diff --git a/docs/_guide/abilities.md b/docs/_guide/abilities.md new file mode 100644 index 00000000..dabc750b --- /dev/null +++ b/docs/_guide/abilities.md @@ -0,0 +1,50 @@ +--- +chapter: 14 +subtitle: Abilities +hidden: true +--- + +Under the hood Catalyst's controller decorator is comprised of a handful of separate "abilities". Each of these abilities is created with the `createAbility` function. An "ability" is essentially a mixin or perhaps "higher order class". An ability takes a class and returns an extended class that adds additional behaviours. Importantly abilities are idempotent, meaning applying an ability to a class multiple times is safe and the ability is only applied once. By convention all abilities exported by Catalyst are suffixed with `able` which we think is a nice way to denote that something is an ability and should be used as such. Catalyst also exposes all of the tooling to create your own abilities in your own code which we'd encourage if you find yourself repeating patterns within components (if you think you've got a really useful ability, we'd love for you to contribute it)! + +### Using Abilities + +Abilities are fundementally just class decorators, and so can be used just like the `@controller` decorator. For example to add only the `actionable` decorator (which automatically binds events based on `data-action` attributes): + +```typescript +import {actionable} from '@github/catalyst' + +@actionable +class HelloWorld extends HTMLElement { +} +``` + +### Using Marks + +Abilities also come with complementary field decorators which we call "marks" (we give them a distinctive name because they're a more restrictive subset of field decorators). Marks annotate fields which abilities can then extend with custom logic, both [Targets]({{ site.baseurl }}/guide/targets) and [Attrs]({{ site.baseurl }}/guide/attrs) are abilities that use marks. The `targetable` ability includes `target` & `targets` marks, and the `attrable` ability includes the `attr` mark. Marks decorate individual fields, like so: + +```typescript +import {targetable, target, targets} from '@github/catalyst' + +@targetable +class HelloWorldElement extends HTMLElement { + @target name + @targets people +} +``` + +Marks _can_ decorate over fields, get/set functions, or class methods - but individual marks can set their own validation logic, for example enforcing a naming pattern or disallowing application on methods. + +### Built-In Abilities + +Catalyst ships with a set of built in abilities. The `@controller` decorator applies the following built-in abilities: + +- `controllable` - the base ability which other abilities require for functionality. +- `targetable` - the ability to define `@target` and `@targets` properties. See [Targets]({{ site.baseurl }}/guide/targets) for more. +- `actionable` - the ability to automatically bind events based on `data-action` attributes. See [Actions]({{ site.baseurl }}/guide/actions) for more. +- `attrable` - the ability to define `@attr`s. See [Attrs]({{ site.baseurl }}/guide/attrs) for more. + +The `@controller` decorator also applies the `@register` decorator which automatically registers the element in the Custom Element registry, however this decorator isn't an "ability". + +The following abilities are shipped with Catalyst but require manually applying as they aren't considered critical functionality: + + - `providable` - the ability to define `provider` and `consumer` properties. See [Providable]({{ side.baseurl }}/guide/providable) for more. diff --git a/docs/_guide/providable.md b/docs/_guide/providable.md new file mode 100644 index 00000000..91c798f5 --- /dev/null +++ b/docs/_guide/providable.md @@ -0,0 +1,145 @@ +--- +chapter: 15 +subtitle: The Provider pattern +hidden: true +--- + +The [Provider pattern](https://www.patterns.dev/posts/provider-pattern/) allows for deeply nested children to ask ancestors for values. This can be useful for decoupling state inside a component, centralising it higher up in the DOM heirarchy. A top level container component might store values, and many children can consume those values, without having logic duplicated across the app. It's quite an abstract pattern so is better explained with examples... + +Say for example a set of your components are built to perform actions on a user, but need a User ID. One way to handle this is to set the User ID as an attribute on each element, but this can lead to a lot of duplication. Instead these actions can request the ID from a parent component, which can provide the User ID without creating an explicit relationship (which can lead to brittle code). + +The `@providable` ability allows a Catalyst controller to become a provider or consumer (or both) of one or many properties. To provide a property to nested controllers that ask for it, mark a property as `@provide`. To consume a property from a parent, mark a property as `@consume`. Let's try implementing the user actions using `@providable`: + +```typescript +import {providable, consume, provide, controller} from '@github/catalyst' + +@providable +@controller +class BlockUser extends HTMLElement { + // This will request `userId`, and default to '' if not provided. + @consume userId = '' + // This will request `userName`, and default to '' if not provided. + @consume userName = '' + + async handleEvent() { + if (confirm(`Would you like to block ${this.userName}?`)) { + await fetch(`/users/${userId}/delete`) + } + } +} + +@providable +@controller +class FollowUser extends HTMLElement { + // This will request `userId`, and default to '' if not provided. + @consume userId = '' + // This will request `userName`, and default to '' if not provided. + @consume userName = '' + + async handleEvent() { + if (confirm(`Would you like to follow ${this.userName}?`)) { + await fetch(`/users/${userId}/delete`) + } + } +} + +@providable +@controller +class UserRow extends HTMLElement { + // This will provide `userId` as '123' to any nested children that request it. + @provide userId = '123' + // This will provide `userName` as 'Alex' to any nested children that request it. + @provide userId = 'Alex' +} +``` + +```html + +