Catalyst is a set of patterns and techniques for developing components within a complex application.
MIT License
Mostly documentation changes, but also now lazyDefine
will observe @controller
shadowroots. It does not patch attachShadow
and so if you want it to observe non-catalyst controller shadowroots, you will need to do so manually:
import {observe} from '@github/catalyst/lib/lazy-define.js'
observe(shadowRoot)
Full Changelog: https://github.com/github/catalyst/compare/v1.6.0...v1.6.1
Published by keithamus about 2 years ago
We've added a new lazyDefine
function, which allows for lazy loading of controllers. See more about lazyDefine in the guide.
lazyDefine
components by @koddsson in https://github.com/github/catalyst/pull/268
Full Changelog: https://github.com/github/catalyst/compare/v1.5.0...v1.6.0
Published by keithamus over 2 years ago
This change lays a bunch of groundwork for 2.0, mostly for things which are not related to production code, so very little has changed from 1.4.2 to 1.5.0.
The key new feature here is a temporary feature to help migration to 2.0: @attr
by default comes with a data-
prefix, this is being dropped in 2.0, and 1.5.0 now observed a classes attrPrefix
static property (which defaults to data-
). To enable an easier migration to 2.0, you can use this to refactor your code and drop the data-
attr prefix:
class HelloWorldController extends HTMLElement {
static attrPrefix = '' // defaults to 'data-'
}
use-delegates
. by @koddsson in https://github.com/github/catalyst/pull/228
@providable
decorator in docs by @keithamus in https://github.com/github/catalyst/pull/248
Full Changelog: https://github.com/github/catalyst/compare/v1.4.2...v1.5.0
Published by keithamus over 2 years ago
This is an early pre-release of Catalyst 2.0, released in order to test for bugs. You should not consider this production ready.
2.0 is a almost-from-the-ground-up rewrite of the core behaviours to make things a bit more consistent and also to allow for more flexibility throughout 2.0. We've also improved the ergonomics and usability of some of the features.
There are many changes and subtle improvements, so we'd recommend sitting down with your favourite beverage and re-reading the guide (NOTE: for pre-releases you'll need to read the v2 branch source. Sorry). Here are some of our favourite new features though:
@attr
and @target
can now be setters, meaning you can trigger behaviour when they change.@attr
, @target
, and class names now all have consistent dasherized versions for within HTML.@attr
drop the data-
prefix for better ergonomics.@loadable
and @providable
. See the guide for more.Here's a summary of breaking changes in order of "you'll definitely need to change this" down to "this probably wont effect you".
@attr
is no longer prefixed with data-
in HTMLThe @attr
decorator used to dasherize a JS property name and then prefix it with data-
for use in HTML, so in other words @attr fooBar
in JS would result in data-foo-bar=
in HTML. This is now no longer the case, and instead @attr fooBar
will result in an HTML attribute name of foo-bar=
. We decided to do this as it is more ergonomic, and less surprising. @attr
names now work like class names: they get dasherized, no surprising prefixes.
The easiest way to handle this change is to prefix your JS properties with data
, so @attr fooBar
becomes @attr dataFooBar
. No changes will need to be made to your HTML, and if you reference the HTML value in your JS (e.g. hasAttribute('data-foo-bar')
) then this will also not need to change.
Drop the data-
prefix from your HTML attributes, as this will be more ergonomic. You might also need to drop the data-
prefix in any JS where you reference the literal HTML value in your JS (e.g. hasAttribute('data-foo-bar')
should be hasAttribute('foo-bar')
).
@attr
s must consist of 2 words (camelcased)In order to drop the data-
prefix, we decided a good trade-off would be to require @attr
s to consist of 2 words - in other words the HTML attribute name must have a dash. Names like @attr foo
will need to be refactored to include 2 words (or one uppercase character), so for example @attr fooBar
is acceptable.
The easiest way to handle this change is to prefix your JS properties with data
which will also get around the dropping of the data
prefix, so @attr foo
becomes @attr dataFoo
. No changes will need to be made to your HTML, and if you reference the HTML value in your JS (e.g. hasAttribute('data-foo-bar')
) then this will also not need to change.
If you have @attr
properties that are one word, you'll need to think of a name for them that consists of two words. Here are some examples to give you some inspiration:
@attr path
-> @attr pathName
@attr valid
-> @attr isValid
@attr changed
-> @attr hasChanged
@attr error
-> @attr errorMessage
@attr src
-> @attr srcURL
@attr content
-> @attr contentText
@attr json
-> Literally anything else π.@attr
no longer sets observedAttributes
, so attributeChangedCallback
won't be fired.We've changed how @attr
updates its attributes, to use a mutationobserver under the hood - instead of attributeChangedCallback
. There are many reasons for this change; it was surprising to users to see attributeChangedCallback
being called for stuff that isn't in observedAttributes
, also attributeChangedCallback
didn't correctly coerce values - it's only called with string
types. With Catalyst 2.0 you can instead add @attr
to a setter, and have that respond to changes to the attribute.
If you don't have an attributeChangedCallback
in your code, forget about it. If you do, then the easiest fix is to manually add observedAttributes
to your class, to reflect all of the @attr
decorated fields. So e.g. @attr fooBar
would need static observedAttributes = ['foo-bar']
.
Refactor your attributeChangedCallback
to remove checks for your @attr
decorated attributes, and use setters instead. For example:
@attr
no longer sets the html in the connectedCallbackIt was surprising to see attributes sprouting onto an element when it gets connected, and it isn't inline with how built-in elements behave. @attr
s now do not set the html attribute value based on the initial value, instead the the html attribute value is used to override the default property value. This works more like built-in HTML elements:
const input = document.createElement('input')
console.assert(input.type === 'text') // default value
console.assert(input.hasAttribute('type') === false) // no attribute to override
input.setAttribute('type', 'number')
console.assert(input.type === 'number') // overrides based on attribute
input.removeAttribute('type')
console.assert(input.type === 'text') // back to default value
You probably won't need to do anything. If your code depends on the html attribute existing during connectedCallback
, then a quick fix is to set the value to itself in your connectedCallback
. e.g. if you have an @attr fooBar = 'hello'
then in your connectedCallback
add the line this.fooBar = this.fooBar
.
If your code depends on the html attribute existing during connectedCallback
, then you should refactor your code. Strategies around this vary, but generally you should refer to the property name rather than the html literal value, alternatively if you still need to access the html literal value you can use a logical OR operator with the @attr
default value, for example for an @attr fooBar = 'hello'
you could use this.getAttribute('foo-bar') || 'hello'
.
@controller
s now will drop the Controller
/Element
/Component
suffixWe've had feedback that Element
is a fine suffix to drop, but it'd be nice to have symmetry with other frameworks and drop more suffixes - so in 2.0 we're also dropping Controller
and Component
suffixes. This means for an element named something like FooBarController
in 1.x would be <foo-bar-controller />
, it'll be <foo-bar />
in 2.x. Similarly FooBarComponent
will also be <foo-bar />
.
We audited all open source Catalyst components (and the closed source ones we had access to) and couldn't find any that end in Component
or Controller
, so we think it's really unlikely that this will be a problem.
Nevertheless, there's only one type of fix for this - and that's to drop the suffix from your HTML.
use-delegates
. by @koddsson in https://github.com/github/catalyst/pull/228
@providable
decorator in docs by @keithamus in https://github.com/github/catalyst/pull/248
Full Changelog: https://github.com/github/catalyst/compare/v1.4.2...v2.0.0-alpha1
Published by keithamus over 2 years ago
This release fixes a bad v1.4.0 build! Please see the release notes for v1.4.0
Published by keithamus over 2 years ago
This release fixes a bad v1.4.0 build! Please see the release notes for v1.4.0
Published by keithamus over 2 years ago
This release allows for safe custom element redefinition, which enables the use of HMR plugins with Catalyst controllers. Releases prior to this would first check if the element is already registered, and skip registration. Instead, in 1.4.0, elements will try to register and catch redefinition errors if theyβre thrown - which means HMR plugins that override customElements.define
will now work.
Published by koddsson over 2 years ago
Full Changelog: https://github.com/github/catalyst/compare/v1.3.1...v1.3.2
Published by koddsson over 2 years ago
Full Changelog: https://github.com/github/catalyst/compare/v1.3.0...v1.3.1
Published by koddsson over 2 years ago
connectedCallback
by @koddsson in https://github.com/github/catalyst/pull/181
Full Changelog: https://github.com/github/catalyst/compare/v1.2.1...v1.3.0
Published by koddsson over 2 years ago
src/core
by @keithamus in https://github.com/github/catalyst/pull/165
Full Changelog: https://github.com/github/catalyst/compare/v1.2.0...v1.2.1
Published by keithamus over 2 years ago
This release brings a new feature: data-action method names are optional, and omitting it will default to the handleEvent
method. For more see https://github.github.io/catalyst/guide/actions/. We've updated some documentation, and some developer dependencies.
aa425d6 Merge pull request #164 from github/bind-handleevent-default
36946da Merge pull request #177 from github/dependabot/npm_and_yarn/y18n-4.0.3
7f608c0 chore(deps): bump y18n from 4.0.0 to 4.0.3
47a3390 Merge pull request #175 from github/dependabot/npm_and_yarn/hosted-git-info-2.8.9
5da9d06 Merge branch 'main' into dependabot/npm_and_yarn/hosted-git-info-2.8.9
074b237 Merge pull request #176 from github/dependabot/npm_and_yarn/underscore-1.13.2
a3c6c8d chore(deps): bump underscore from 1.12.0 to 1.13.2
88d6b94 chore(deps): bump hosted-git-info from 2.8.8 to 2.8.9
5862b88 Merge pull request #173 from github/dependabot/npm_and_yarn/glob-parent-5.1.2
4c85b11 Merge branch 'main' into dependabot/npm_and_yarn/glob-parent-5.1.2
bd74001 Merge pull request #174 from github/dependabot/npm_and_yarn/normalize-url-4.5.1
8ebbc7f chore(deps): bump glob-parent from 5.1.1 to 5.1.2
9211261 Merge branch 'main' into dependabot/npm_and_yarn/normalize-url-4.5.1
c5bde99 Merge pull request #172 from github/dependabot/npm_and_yarn/path-parse-1.0.7
1453238 chore(deps): bump normalize-url from 4.5.0 to 4.5.1
1423fcb Merge branch 'main' into dependabot/npm_and_yarn/path-parse-1.0.7
e8e2c20 Merge pull request #169 from github/dependabot/npm_and_yarn/engine.io-4.1.2
9ae9c59 chore(deps): bump path-parse from 1.0.6 to 1.0.7
db0f232 Merge branch 'main' into dependabot/npm_and_yarn/engine.io-4.1.2
efe15f1 Merge pull request #171 from github/dependabot/npm_and_yarn/lodash-4.17.21
e727c76 Merge branch 'main' into dependabot/npm_and_yarn/engine.io-4.1.2
7dbc959 chore(deps): bump lodash from 4.17.20 to 4.17.21
c9e2bf3 Merge pull request #167 from github/dependabot/npm_and_yarn/log4js-6.4.1
7530fcc chore(deps): bump log4js from 6.3.0 to 6.4.1
This small release brings you fixes to documentation, our build system and some developer dependency updates. Additionally, we've made sure to export functions needed for non-decorator users and inherited attrs
are defined.
<pre>
element is displayed protruding. by @yamanoku in https://github.com/github/catalyst/pull/140
This release fixes a regression, which was introduced between 1.0.2, which changed the call order of bind
and connectedCallback
so that shadowRoots
were bound. In fixing this bug we introduced a new one where sometimes an element which dispatched an event inside it's connectedCallback
could not be observed by other elements, in their connectedCallback
s. This release fixes the regression, but maintains the fix to ensure shadowRoots
are correctly bound. In other words dispatchEvent
and attachShadow
inside a connectedCallback
should do the expected thing with data-action
.
This release changes the import statements in the compiled code to include an extension, which allows this library to be used without module bundlers, or with bundlers which strictly follow ESM module identifier rules, for example Deno or WebPack v5. Fixes https://github.com/github/catalyst/issues/119. Thanks goes out to @heynan0 and @vmsp!
This release changes the @target
/@targets
decorators such that they work using Babel's legacy decorators transform, without TypeScript. TypeScript is still encouraged to be used with Catalyst, but this makes it possible to use Babel instead.
If you're not using Babel, or are transforming with TypeScript ahead of using Babel then this release won't make a difference to your usage.
Published by keithamus over 3 years ago
This release predominantly adds the new @attr
decorator. See the full @attr guide on the website for more information. https://github.com/github/catalyst/pull/103.
This release also optimizes memory usage for bind
. There is no change to the APIs here, but it should use less memory per-controller. See https://github.com/github/catalyst/pull/106 for more details.
Published by koddsson almost 4 years ago
This release adds the following:
npm
as well as GitHub Packages (#84).This release is marked as v1.0
as we consider Catalyst stable for production! It has been in GitHub production for around 8 months now and we consider it to be battle tested enough to cut the first Stable Release!
This release has a few new features. Chiefly, support for ShadowDOM!
listenForBind
is now automatically called on the ownerDocument
s of connected elements. No need to call it manually. (https://github.com/github/catalyst/pull/75)data-target[s]
and data-action
now work inside the ShadowDOM, exactly as you'd expect them to. ShadowDOM targets take precedence over regular DOM. (https://github.com/github/catalyst/pull/73)template[data-shadowroot]
element, it will automatically clone it and attach it as a ShadowDOM. (https://github.com/github/catalyst/pull/74)Plus a few minor docs improvements:
Future releases will adhere to SemVer 2.0; now that Catalyst is 1.0 any changes that break existing API will be released as new major versions.