catalyst

Catalyst is a set of patterns and techniques for developing components within a complex application.

MIT License

Downloads
275.2K
Stars
1.3K
Committers
34
View Code on GitHub Visit Website
Ecosystems: GitHub
catalyst - v1.6.1 Latest Release

Published by keithamus over 1 year ago

What's Changed

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)

New Contributors

Full Changelog: https://github.com/github/catalyst/compare/v1.6.0...v1.6.1

catalyst - v1.6.0

Published by keithamus about 2 years ago

New Features

We've added a new lazyDefine function, which allows for lazy loading of controllers. See more about lazyDefine in the guide.

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.5.0...v1.6.0

catalyst - v1.5.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-'
}

What's Changed

New Contributors

Full Changelog: https://github.com/github/catalyst/compare/v1.4.2...v1.5.0

catalyst - v2.0.0-alpha1

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.

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.
  • The html literal versions of @attr drop the data- prefix for better ergonomics.
  • Actions and Targets can now listen to closed shadowroots.
  • We've added a new system for Abilities. We'll be adding two new abilities in the 2.0 release: @loadable and @providable. See the guide for more.
  • You can create your own abilities for shared functionality!

Breaking Changes

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 HTML

The @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.

What's the easiest fix?

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.

What's a better fix?

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')).

πŸ”΄ @attrs must consist of 2 words (camelcased)

In order to drop the data- prefix, we decided a good trade-off would be to require @attrs 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.

What's the easiest fix?

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.

What's a better fix?

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.

What's the easiest fix?

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'].

What's a better fix?

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 connectedCallback

It was surprising to see attributes sprouting onto an element when it gets connected, and it isn't inline with how built-in elements behave. @attrs 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

What's the easiest fix?

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.

What's a better fix?

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'.

🟑 @controllers now will drop the Controller/Element/Component suffix

We'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 />.

What's the easiest fix?

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.

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.4.2...v2.0.0-alpha1

catalyst - v1.4.2

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

catalyst - v1.4.1

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

catalyst - 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.

catalyst - v1.3.2

Published by koddsson over 2 years ago

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.3.1...v1.3.2

catalyst - v1.3.1

Published by koddsson over 2 years ago

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.3.0...v1.3.1

catalyst - v1.3.0

Published by koddsson over 2 years ago

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.2.1...v1.3.0

catalyst - v1.2.1

Published by koddsson over 2 years ago

What's Changed

Full Changelog: https://github.com/github/catalyst/compare/v1.2.0...v1.2.1

catalyst - v1.2.0

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.

What's Changed

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

New Contributors

https://github.com/github/catalyst/compare/v1.1.4...v1.2.0

catalyst -

Published by koddsson about 3 years ago

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.

What's Changed

New Contributors

https://github.com/github/catalyst/compare/v1.1.3...v1.1.4

catalyst -

Published by keithamus over 3 years ago

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 connectedCallbacks. 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.

catalyst -

Published by keithamus over 3 years ago

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!

catalyst -

Published by keithamus over 3 years ago

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.

catalyst - v1.1.0

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.

catalyst -

Published by keithamus almost 4 years ago

This release fixes a bug where shadowRoots in the connectedCallback were not automatically scanned for data-action elements. Now bind() runs after connectedCallback, meaning the shadowRoot can be created in connectedCallback and will be scanned.

catalyst - v1.0.1

Published by koddsson almost 4 years ago

This release adds the following:

  • Publish to npm as well as GitHub Packages (#84).
  • Update docs to link to ShadowDom docs (#79).
catalyst -

Published by keithamus almost 4 years ago

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!

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.

Package Rankings
Top 1.56% on Npmjs.org