20 |
25 |
--------------------------------------------------------------------------------
/docs/_config.yml:
--------------------------------------------------------------------------------
1 | title: Catalyst
2 |
3 | markdown: CommonMarkGhPages
4 |
5 | commonmark:
6 | extensions: ['autolink', 'table']
7 |
8 | permalink: pretty
9 |
10 | exclude:
11 | - Gemfile
12 | - Gemfile.lock
13 | - node_modules
14 | - vendor
15 |
16 | collections:
17 | guide:
18 | output: true
19 |
20 | defaults:
21 | - scope:
22 | type: guide
23 | values:
24 | layout: guide
25 |
26 | repository: github/catalyst
27 |
28 | plugins:
29 | - 'jekyll-github-metadata'
30 | - 'jekyll-gzip'
31 |
--------------------------------------------------------------------------------
/src/dasherize.ts:
--------------------------------------------------------------------------------
1 | export const dasherize = (str: unknown): string =>
2 | String(typeof str === 'symbol' ? str.description : str)
3 | .replace(/([A-Z]($|[a-z]))/g, '-$1')
4 | .replace(/--/g, '-')
5 | .replace(/^-|-$/, '')
6 | .toLowerCase()
7 |
8 | export const mustDasherize = (str: unknown, type = 'property'): string => {
9 | const dashed = dasherize(str)
10 | if (!dashed.includes('-')) {
11 | throw new DOMException(`${type}: ${String(str)} is not a valid ${type} name`, 'SyntaxError')
12 | }
13 | return dashed
14 | }
15 |
--------------------------------------------------------------------------------
/src/controller.ts:
--------------------------------------------------------------------------------
1 | import {CatalystDelegate} from './core.js'
2 | import type {CustomElementClass} from './custom-element.js'
3 | /**
4 | * Controller is a decorator to be used over a class that extends HTMLElement.
5 | * It will automatically `register()` the component in the customElement
6 | * registry, as well as ensuring `bind(this)` is called on `connectedCallback`,
7 | * wrapping the classes `connectedCallback` method if needed.
8 | */
9 | export function controller(classObject: CustomElementClass): void {
10 | new CatalystDelegate(classObject)
11 | }
12 |
--------------------------------------------------------------------------------
/test/dasherize.ts:
--------------------------------------------------------------------------------
1 | import {expect} from '@open-wc/testing'
2 | import {dasherize} from '../src/dasherize.js'
3 |
4 | describe('dasherize', () => {
5 | const tests: Array<[PropertyKey, string]> = [
6 | ['json', 'json'],
7 | ['fooBar', 'foo-bar'],
8 | ['FooBar', 'foo-bar'],
9 | ['autofocusWhenReady', 'autofocus-when-ready'],
10 | ['URLBar', 'url-bar'],
11 | ['ClipX', 'clip-x'],
12 | [Symbol('helloWorld'), 'hello-world']
13 | ]
14 |
15 | tests.map(([input, output]) =>
16 | it(`transforms ${String(input)} to ${output}`, () => expect(dasherize(input)).to.equal(output))
17 | )
18 | })
19 |
--------------------------------------------------------------------------------
/.github/workflows/nodejs.yml:
--------------------------------------------------------------------------------
1 | name: Build
2 |
3 | on:
4 | pull_request:
5 | push:
6 |
7 | jobs:
8 | test-node:
9 | name: Test on Node.js
10 | runs-on: ubuntu-latest
11 | steps:
12 | - name: Checkout the project
13 | uses: actions/checkout@v3
14 | - name: Use Node.js 16.x (LTS)
15 | uses: actions/setup-node@v3
16 | with:
17 | node-version: 16.x
18 | cache: 'npm'
19 | - run: npm ci
20 | - name: Lint Codebase
21 | run: npm run lint
22 | - name: Run Node.js Tests
23 | run: npm run test
24 | - name: Check Bundle Size
25 | run: npm run size
26 |
--------------------------------------------------------------------------------
/.github/workflows/publish.yml:
--------------------------------------------------------------------------------
1 | name: Publish
2 |
3 | on:
4 | release:
5 | types: [created]
6 |
7 | jobs:
8 | publish-npm:
9 | runs-on: ubuntu-latest
10 | steps:
11 | - name: Checkout the project
12 | uses: actions/checkout@v3
13 | - name: Use Node.js 16.x (LTS)
14 | uses: actions/setup-node@v3
15 | with:
16 | node-version: 16.x
17 | registry-url: https://registry.npmjs.org/
18 | cache: npm
19 | - run: npm ci
20 | - run: npm test
21 | - run: npm version ${TAG_NAME} --git-tag-version=false
22 | env:
23 | TAG_NAME: ${{ github.event.release.tag_name }}
24 | - run: npm whoami; npm publish
25 | env:
26 | NODE_AUTH_TOKEN: ${{secrets.npm_token}}
27 |
--------------------------------------------------------------------------------
/src/ability.ts:
--------------------------------------------------------------------------------
1 | import type {CustomElementClass} from './custom-element.js'
2 |
3 | type Decorator = (Class: CustomElementClass) => unknown
4 | const abilityMarkers = new WeakMap404
21 | 22 |Page not found :(
23 |The requested page could not be found.
24 |
3 |
4 |
10 |
11 |
17 |
--------------------------------------------------------------------------------
/lighthouserc.json:
--------------------------------------------------------------------------------
1 | {
2 | "ci": {
3 | "collect": {
4 | "url": ["http://localhost:4000/?prefers-color-scheme=light", "http://localhost:4000/?prefers-color-scheme=dark"],
5 | "startServerCommand": "cd docs && bundle exec jekyll serve",
6 | "startServerReadyPattern": "Server running..."
7 | },
8 | "assert": {
9 | "preset": "lighthouse:no-pwa",
10 | "assertions": {
11 | "unused-css-rules": "off",
12 | "uses-text-compression": "off",
13 | "render-blocking-resources": "off",
14 | "uses-rel-preload": "off",
15 | "first-contentful-paint": ["error", {"minScore": 0.6}],
16 | "first-meaningful-paint": ["error", {"maxNumericValue": 3000}],
17 | "largest-contentful-paint": ["error", {"maxNumericValue": 3000}],
18 | "deprecations": "off",
19 | "csp-xss": "off"
20 | }
21 | },
22 | "upload": {
23 | "target": "temporary-public-storage"
24 | }
25 | }
26 | }
27 |
--------------------------------------------------------------------------------
/src/register.ts:
--------------------------------------------------------------------------------
1 | import type {CustomElementClass} from './custom-element.js'
2 | import {dasherize} from './dasherize.js'
3 |
4 | /**
5 | * Register the controller as a custom element.
6 | *
7 | * The classname is converted to a appropriate tag name.
8 | *
9 | * Example: HelloController => hello-controller
10 | */
11 | export function register(classObject: CustomElementClass): CustomElementClass {
12 | const name = dasherize(classObject.name).replace(/-element$/, '')
13 |
14 | try {
15 | window.customElements.define(name, classObject)
16 | // eslint-disable-next-line @typescript-eslint/ban-ts-comment
17 | // @ts-ignore
18 | window[classObject.name] = customElements.get(name)
19 | } catch (e: unknown) {
20 | // The only reason for window.customElements.define to throw a `NotSupportedError`
21 | // is if the element has already been defined.
22 | if (!(e instanceof DOMException && e.name === 'NotSupportedError')) throw e
23 | }
24 | return classObject
25 | }
26 |
--------------------------------------------------------------------------------
/.github/workflows/lighthouse.yml:
--------------------------------------------------------------------------------
1 | name: Lighthouse
2 |
3 | on: [pull_request]
4 |
5 | jobs:
6 | lhci:
7 | name: Lighthouse
8 | runs-on: ubuntu-latest
9 | steps:
10 | - name: Checkout the project
11 | uses: actions/checkout@v3
12 |
13 | - name: Use Node.js 16.x (LTS)
14 | uses: actions/setup-node@v3
15 | with:
16 | node-version: 16.x
17 | cache: 'npm'
18 | - run: npm ci
19 |
20 | - name: Use Ruby 2.7.3
21 | uses: ruby/setup-ruby@v1
22 | with:
23 | ruby-version: '2.7.3'
24 | bundler-cache: true
25 | working-directory: docs
26 |
27 | - name: Build docs
28 | run: npm run build:docs
29 | env:
30 | JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
31 |
32 | - name: Run Lighthouse CI
33 | run: npx @lhci/cli@0.9.x autorun
34 | env:
35 | JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
36 | LHCI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
37 |
--------------------------------------------------------------------------------
/docs/_includes/sidebar.html:
--------------------------------------------------------------------------------
1 |
24 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2020 GitHub
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/.devcontainer/devcontainer.json:
--------------------------------------------------------------------------------
1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
2 | // https://github.com/microsoft/vscode-dev-containers/tree/v0.222.0/containers/javascript-node
3 | {
4 | "name": "Node.js",
5 | "build": {
6 | "dockerfile": "Dockerfile",
7 | // Update 'VARIANT' to pick a Node version: 16, 14, 12.
8 | // Append -bullseye or -buster to pin to an OS version.
9 | // Use -bullseye variants on local arm64/Apple Silicon.
10 | "args": { "VARIANT": "16" }
11 | },
12 |
13 | // Set *default* container specific settings.json values on container create.
14 | "settings": {},
15 |
16 | // Add the IDs of extensions you want installed when the container is created.
17 | "extensions": [
18 | "dbaeumer.vscode-eslint"
19 | ],
20 |
21 | // Use 'forwardPorts' to make a list of ports inside the container available locally.
22 | // "forwardPorts": [],
23 |
24 | // Use 'postCreateCommand' to run commands after the container is created.
25 | "postCreateCommand": "npm i && cd docs && sudo bundle install",
26 |
27 | // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
28 | "remoteUser": "node",
29 | "features": {
30 | "git": "latest"
31 | }
32 | }
33 |
--------------------------------------------------------------------------------
/src/target.ts:
--------------------------------------------------------------------------------
1 | import {findTarget, findTargets} from './findtarget.js'
2 | import {meta} from './core.js'
3 |
4 | /**
5 | * Target is a decorator which - when assigned to a property field on the
6 | * class - will override that class field, turning it into a Getter which
7 | * returns a call to `findTarget(this, key)` where `key` is the name of the
8 | * property field. In other words, `@target foo` becomes a getter for
9 | * `findTarget(this, 'foo')`.
10 | */
11 | export function target
12 |
13 | {{ callout }}
14 |
15 |
16 |
21 | {% include sidebar.html %}
22 |
23 |
24 |
51 |
52 |
--------------------------------------------------------------------------------
/docs/_includes/type.html:
--------------------------------------------------------------------------------
1 | {%- capture output %}
2 | {%- case type.type %}
3 | {%- when "intrinsic" %}
4 | {{- }}{{- type.name }}
5 | {%- when "reference" %}
6 | {{- }}{{- type.name }}
7 | {%- when "array" %}
8 | {%- assign type = type.elementType %}
9 | {%- include type.html %}[]
10 | {%- when "union" %}
11 | {%- for type in type.types %}
12 | {%- include type.html %}{% if forloop.last != true %} | {%- endif %}
13 | {%- endfor %}
14 | {%- when "reflection" %}
15 | {%- assign type = type.declaration %}
16 | {%- include type.html %}
17 | {%- when "typeParameter" %}
18 | {%- assign name = type.name %}
19 | {%- assign type = type.constraint %}
20 | {{- ''}}{{ name }}
21 | {%- else %}
22 | {%- if type.signatures %}
23 | {%- assign rootType = type %}
24 | {%- for signature in type.signatures %}
25 | {%- if signature.name != "__call" %}{{ signature.name }}{% endif %}
26 | {{- ''}}(
27 | {%- for parameter in signature.parameters %}
28 | {{- ''}}{%- if parameter.flags.isRest %}...{% endif %}{{ parameter.name }}:
29 | {%- assign type = parameter.type %}
30 | {%- include type.html %}
31 | {%- if forloop.last != true %}, {%- endif %}
32 | {%- endfor %}
33 | {{-''}})
34 | {%- if rootType.name == "__type" %} =>
35 | {%- else %}: {% endif %}
36 | {%- assign type = signature.type %}
37 | {%- include type.html %}
38 | {%- endfor %}
39 | {%- else %}
40 |
25 | {% if page.version == 2 %}
26 |
50 |
27 | You are reading the documentation for the Alpha version of Catalyst. The API and documentation is subject to change.
28 | The documentation for the stable version can be found here.
29 |
30 | {% endif %}
31 |
32 | {{ page.title }}
33 | {{ content }} 34 |
35 |
48 |
49 | {{- type | jsonify }}
41 | {%- endif %}
42 | {%- endcase %}
43 | {%- endcapture %}{{- output | strip_newlines }}
44 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@github/catalyst",
3 | "version": "1.3.0",
4 | "description": "Helpers for creating HTML Elements as Controllers",
5 | "homepage": "https://github.github.io/catalyst",
6 | "bugs": {
7 | "url": "https://github.com/github/catalyst/issues"
8 | },
9 | "repository": {
10 | "type": "git",
11 | "url": "git+https://github.com/github/catalyst.git"
12 | },
13 | "license": "MIT",
14 | "author": "GitHub Inc.",
15 | "contributors": [
16 | "Keith Cirkel (https://keithcirkel.co.uk/)",
17 | "Kristján Oddsson
27 |
29 |
48 | Catalyst
28 |World
30 |
40 | Hello World
41 |
42 | 30 | 31 | Catalyst will automatically convert the classes name so the HTML tag will be `
79 | 80 | -------------------------------------------------------------------------------- /test/ability.ts: -------------------------------------------------------------------------------- 1 | import type {CustomElement} from '../src/custom-element.js' 2 | import {expect, fixture, html} from '@open-wc/testing' 3 | import {restore} from 'sinon' 4 | import {createAbility} from '../src/ability.js' 5 | 6 | describe('ability', () => { 7 | const calls: string[] = [] 8 | const fakeable = createAbility( 9 | Class => 10 | class extends Class { 11 | foo() { 12 | return 'foo!' 13 | } 14 | connectedCallback() { 15 | calls.push('fakeable connectedCallback') 16 | super.connectedCallback?.() 17 | } 18 | disconnectedCallback() { 19 | calls.push('fakeable disconnectedCallback') 20 | super.disconnectedCallback?.() 21 | } 22 | adoptedCallback() { 23 | calls.push('fakeable adoptedCallback') 24 | super.adoptedCallback?.() 25 | } 26 | attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) { 27 | calls.push('fakeable attributeChangedCallback') 28 | super.attributeChangedCallback?.(name, oldValue, newValue) 29 | } 30 | } 31 | ) 32 | const otherfakeable = createAbility( 33 | Class => 34 | class extends Class { 35 | bar() { 36 | return 'bar!' 37 | } 38 | connectedCallback() { 39 | calls.push('otherfakeable connectedCallback') 40 | super.connectedCallback?.() 41 | } 42 | disconnectedCallback() { 43 | calls.push('otherfakeable disconnectedCallback') 44 | super.disconnectedCallback?.() 45 | } 46 | adoptedCallback() { 47 | calls.push('otherfakeable adoptedCallback') 48 | super.adoptedCallback?.() 49 | } 50 | attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) { 51 | calls.push('otherfakeable attributeChangedCallback') 52 | super.attributeChangedCallback?.(name, oldValue, newValue) 53 | } 54 | } 55 | ) 56 | class Element extends HTMLElement { 57 | connectedCallback() {} 58 | disconnectedCallback() {} 59 | adoptedCallback() {} 60 | attributeChangedCallback() {} 61 | } 62 | 63 | afterEach(() => restore()) 64 | 65 | it('creates a function, which creates a subclass of the given class', async () => { 66 | const DElement = fakeable(Element) 67 | expect(DElement).to.have.property('prototype').instanceof(Element) 68 | }) 69 | 70 | it('retains original class name', () => { 71 | const DElement = fakeable(Element) 72 | const D2Element = otherfakeable(Element) 73 | expect(DElement).to.have.property('name', 'Element') 74 | expect(D2Element).to.have.property('name', 'Element') 75 | }) 76 | 77 | it('can be used in decorator position', async () => { 78 | @fakeable 79 | class DElement extends HTMLElement {} 80 | 81 | expect(DElement).to.have.property('prototype').instanceof(HTMLElement) 82 | }) 83 | 84 | it('can be chained with multiple abilities', async () => { 85 | const DElement = fakeable(Element) 86 | expect(Element).to.not.equal(DElement) 87 | const D2Element = otherfakeable(DElement) 88 | expect(DElement).to.not.equal(D2Element) 89 | expect(DElement).to.have.property('prototype').be.instanceof(Element) 90 | expect(D2Element).to.have.property('prototype').be.instanceof(Element) 91 | }) 92 | 93 | it('can be called multiple times, but only applies once', async () => { 94 | const MultipleFakeable = fakeable(fakeable(fakeable(fakeable(fakeable(Element))))) 95 | customElements.define('multiple-fakeable', MultipleFakeable) 96 | const instance: CustomElement = await fixture(html`
29 | 30 | Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. 31 | 32 | By convention Catalyst controllers end in `Element`; Catalyst will omit this when generating a tag name. The `Element` suffix is _not_ required - just convention. All examples in this guide use `Element` suffixed names. 33 | 34 | {% capture callout %} 35 | Remember! A class name _must_ include at least two CamelCased words (not including the `Element` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskElement`, `PagerContainerElement` 36 | {% endcapture %}{% include callout.md %} 37 | 38 | 39 | ### What does `@controller` do? 40 | 41 | The `@controller` decorator ties together the various other decorators within Catalyst, plus a few extra conveniences such as automatically registering the element, which saves you writing some boilerplate that you'd otherwise have to write by hand. Specifically the `@controller` decorator: 42 | 43 | - Derives a tag name based on your class name, removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash. 44 | - Calls `window.customElements.define` with the newly derived tag name and your class. 45 | - Calls `defineObservedAttributes` with the class to add map any `@attr` decorators. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this. 46 | - Injects the following code inside of the `connectedCallback()` function of your class: 47 | - `bind(this)`; ensures that as your element connects it picks up any `data-action` handlers. See [actions]({{ site.baseurl }}/guide/actions) for more on this. 48 | - `autoShadowRoot(this)`; ensures that your element loads any `data-shadowroot` templates. See [rendering]({{ site.baseurl }}/guide/rendering) for more on this. 49 | - `initializeAttrs(this)`; ensures that your element binds any `data-*` attributes to props. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this. 50 | 51 | You can do all of this manually; for example here's the above `HelloWorldElement`, written without the `@controller` annotation: 52 | 53 | ```js 54 | import {bind, autoShadowRoot, initializeAttrs, defineObservedAttributes} from '@github/catalyst' 55 | class HelloWorldElement extends HTMLElement { 56 | connectedCallback() { 57 | autoShadowRoot(this) 58 | initializeAttrs(this) 59 | this.innerHTML = 'Hello World!' 60 | bind(this) 61 | } 62 | } 63 | defineObservedAttributes(HelloWorldElement) 64 | window.customElements.define('hello-world', HelloWorldElement) 65 | ``` 66 | 67 | The `@controller` decorator saves on having to write this boilerplate for each element. 68 | 69 | ### What about without TypeScript Decorators? 70 | 71 | If you don't want to use TypeScript decorators, you can use `controller` as a regular function by passing it to your class: 72 | 73 | ```js 74 | import {controller} from '@github/catalyst' 75 | 76 | controller( 77 | class HelloWorldElement extends HTMLElement { 78 | //... 79 | } 80 | ) 81 | ``` 82 |
83 | -------------------------------------------------------------------------------- /docs/_guide/testing.md: -------------------------------------------------------------------------------- 1 | --- 2 | version: 1 3 | chapter: 14 4 | title: Testing 5 | subtitle: Tips for automated testing 6 | --- 7 | 8 | Catalyst controllers are based on Web Components, and as such need the Web Platform environment to run in, including in tests. It's possible to run these tests in "browser like" environments such as NodeJS or Deno with libraries like jsdom, but it's best to run tests directly in the browser. 9 | 10 | ### Recommended Libraries 11 | 12 | We recommend using [`@web/test-runner`](https://modern-web.dev/docs/test-runner/overview/), which provides the `web-test-runner` command line tool that can run [mocha](https://mochajs.org/) test files in a headless Chromium instance. We also recommend using [`@open-wc/testing`](https://open-wc.org/docs/testing/testing-package/) which provides a set of testing functions, including `expect` from [Chai](https://www.chaijs.com/api/bdd/). If you're using TypeScript, it may be worth also installing [`@web/dev-server-esbuild`](https://modern-web.dev/docs/dev-server/overview/) which can transpile TypeScript to JavaScript, allowing the use of TypeScript within test files themselves. 13 | 14 | With these installed and configured your `package.json` might look something like: 15 | 16 | ```json 17 | { 18 | "name": "my-catalyst-component", 19 | "scripts": { 20 | "test": "web-test-server" 21 | }, 22 | "devDependencies": { 23 | "@web/dev-server-esbuild": "^0.3.0", 24 | "@web/test-runner": "^0.13.27", 25 | "@open-wc/testing": "^3.1.2" 26 | } 27 | } 28 | ``` 29 | 30 | You can configure the `web-test-server` by writing a `web-test-runner.config.js` file, which sets up the esbuild plugin to transpile TypeScript, and configure the directory containing your test files: 31 | 32 | ```typescript 33 | import {esbuildPlugin} from '@web/dev-server-esbuild' 34 | 35 | export default { 36 | files: ['test/*'], 37 | nodeResolve: true, 38 | plugins: [esbuildPlugin({ts: true})] 39 | } 40 | ``` 41 | 42 | #### Example Test File 43 | 44 | With this set-up, the boilerplate for an Element test suite might look something like this: 45 | 46 | ```typescript 47 | // test/my-controller.ts 48 | import {expect, fixture, html} from '@open-wc/testing' 49 | import {MyController} from '../src/my-controller' 50 | 51 | describe('MyController', () => { 52 | let instance 53 | beforeEach(async () => { 54 | instance = await fixture(html`
26 | Hello World 27 |
28 | 29 |
71 | Hello ${ this.name }
72 |
`,
73 | this.shadowRoot!)
74 | }
75 | }
76 | ```
77 |
78 | Here, instead of declaring our template in HTML, we can do so in JS, and achieve exactly the same effect. We aren't using `@targets` in this example, as there is a more direct way to handle the data; relying on `attributeChangedCallback` which will efficiently update only the parts that change.
79 |
80 | The same effect could be achieved without using `@attr` via:
81 |
82 | ```typescript
83 | import { controller } from "@github/catalyst"
84 | import { html, render } from "@github/jtml"
85 |
86 | @controller
87 | class HelloWorldElement extends HTMLElement {
88 |
89 | // Make `name` automatically update when changed
90 | #name = 'World'
91 | get name() {
92 | return this.#name
93 | }
94 | set name(value: string) {
95 | this.#name = value
96 | this.update()
97 | }
98 |
99 | connectedCallback() {
100 | this.attachShadow({mode: 'open'})
101 | this.update()
102 | }
103 |
104 | update() {
105 | render(html`
106 |
107 | Hello ${ this.#name }
108 |
`,
109 | this.shadowRoot!)
110 | }
111 | }
112 | ```
113 |
--------------------------------------------------------------------------------
/docs/_guide/decorators.md:
--------------------------------------------------------------------------------
1 | ---
2 | version: 1
3 | chapter: 3
4 | title: Decorators
5 | subtitle: Using TypeScript for ergonomics
6 | ---
7 |
8 | Decorators are used heavily in Catalyst, because they provide really clean ergonomics and makes using the library a lot easier. Decorators are a special, (currently) non standard, feature of TypeScript. You'll need to turn the `experimentalDecorators` option on inside of your TypeScript project to use them (if you're using `@babel/plugin-proposal-decorators` plugin, you need to use [`legacy` option](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy)).
9 |
10 | You can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:
11 |
12 | Decorators can be used three ways:
13 |
14 | ### Class Decorators
15 |
16 | Catalyst comes with the `@controller` decorator. This gets put on top of the class, like so:
17 |
18 | ```js
19 | @controller
20 | class HelloWorldElement extends HTMLElement {}
21 | ```
22 |
23 | ### Class Field Decorators
24 |
25 | Catalyst comes with the `@target` and `@targets` decorators (for more on these [read the Targets guide section]({{ site.baseurl }}/guide/targets)). These get added on top or to the left of the field name, like so:
26 |
27 | ```js
28 | class HelloWorldElement extends HTMLElement {
29 |
30 | @target something
31 |
32 | // Alternative style
33 | @targets
34 | others
35 |
36 | }
37 | ```
38 | 39 | 40 | Class Field decorators get given the class and the field name so they can add custom functionality to the field. Because they operate on the fields, they must be put on top of or to the left of the field. 41 | 42 | ### Method Decorators 43 | 44 | Method decorators work just like Field Decorators. Put them on top or on the left of the method, like so: 45 | 46 | 47 | ```js 48 | class HelloWorldElement extends HTMLElement { 49 | 50 | @log 51 | submit() { 52 | // ... 53 | } 54 | 55 | // Alternative style 56 | 57 | @log load() { 58 | // ... 59 | } 60 | 61 | } 62 | ``` 63 | 64 | ### Getter/Setter 65 | 66 | Decorators can also be used over a `get` or `set` field. These work just like Field Decorators, but you can put them over one or both the `get` or `set` field. Some decorators might throw an error if you put them over a `get` field, when they expect to be put over a `set` field: 67 | 68 | 69 | ```js 70 | class HelloWorldElement extends HTMLElement { 71 | 72 | @target set something() { 73 | // ... 74 | } 75 | 76 | // Can be used over just one field 77 | @attr get data() { 78 | return {} 79 | } 80 | set data() { 81 | 82 | } 83 | } 84 | ``` 85 | 86 | ### Supporting `strictPropertyInitialization` 87 | 88 | TypeScript comes with various "strict" mode settings, one of which is `strictPropertyInitialization` which lets TypeScript catch potential class properties which might not be assigned during construction of a class. This option conflicts with Catalyst's `@target`/`@targets` decorators, which safely do the assignment but TypeScript's simple heuristics cannot detect this. There are two ways to work around this: 89 | 90 | 1. Use TypeScript's [`declare` modifier](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) to tell TypeScript that the decorated field will still be set up correctly: 91 | 92 | ```typescript 93 | class HelloWorldElement extends HTMLElement { 94 | @target declare something: HTMLElement 95 | @targets declare items: HTMLElement[] 96 | } 97 | ``` 98 | 99 | Note that this only works on TypeScript 3.7+, so if you're on an older version, you can also use the [definite initialization operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#definite-assignment-assertions) to do the same thing. 100 | 101 | 2. You can also disable the compiler option (other strict mode rules can still apply) in your `tsconfig.json` like so: 102 | 103 | ```json 104 | { 105 | "compilerOptions": { 106 | "strict": true, 107 | "strictPropertyInitialization": false 108 | } 109 | } 110 | ``` 111 | 112 | ### Function Calling Decorators 113 | 114 | You might see some decorators that look like function calls, and that's because they are! Some decorators allow for customisation; calling with additional arguments. Decorators that expect to be called are generally not interchangeable with the non-call variant, a decorators documentation should tell you how to use it. 115 | 116 | Catalyst doesn't ship with any decorators that can be called like a function; but an example of one can be found in the `@debounce` decorator in the [`@github/mini-throttle`](https://github.com/github/mini-throttle) package: 117 | 118 | ```js 119 | class HelloWorldElement extends HTMLElement { 120 | 121 | @debounce(100) 122 | handleInput() { 123 | // ... 124 | } 125 | 126 | } 127 | ``` 128 |
129 | -------------------------------------------------------------------------------- /docs/_guide/rendering-2.md: -------------------------------------------------------------------------------- 1 | --- 2 | version: 2 3 | chapter: 11 4 | title: Rendering 5 | subtitle: Rendering HTML subtrees 6 | permalink: /guide-v2/rendering 7 | --- 8 | 9 | Sometimes it's necessary to render an HTML subtree as part of a component. This can be especially useful if a component is driving complex UI that is only interactive with JS. 10 | 11 | {% capture callout %} 12 | Remember to _always_ make your JavaScript progressively enhanced, where possible. Using JS to render large portions of the UI, that could be rendered server-side is an anti-pattern; it can be difficult for users to interact with - especially users who disable JS, or when JS fails to load, or those using assistive technologies. Rendering on the client can also impact the [CLS Web Vital](https://web.dev/cls/). 13 | {% endcapture %}{% include callout.md %} 14 | 15 | By leveraging the native [`ShadowDOM`](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) feature, Catalyst components can render complex sub-trees, fully encapsulated from the rest of the page. 16 | 17 | [Actions]({{ site.baseurl }}/guide/actions) and [Targets]({{ site.baseurl }}/guide/targets) all work within an elements ShadowRoot. 18 | 19 | You can also leverage the [declarative shadow DOM](https://web.dev/declarative-shadow-dom/) and render a template inline to your HTML, which will automatically be attached (this may require a polyfill for browsers which are yet to support this feature). 20 | 21 | ### Example 22 | 23 | ```html 24 |
27 | Hello World 28 |
29 | 30 |69 | Hello World 70 |
` 71 | } 72 | } 73 | ``` 74 | 75 | ### Updating a Template element using JS templates 76 | 77 | Sometimes you wont have a template that is server rendered, and instead want to make a template using JS. Catalyst does not support this out of the box, but it is possible to use another library: `@github/jtml`. This library can be used to write declarative templates using JS. Let's re-work the above example using `@github/jtml`: 78 | 79 | ```typescript 80 | import { attr, controller } from "@github/catalyst" 81 | import { html, render } from "@github/jtml" 82 | 83 | @controller 84 | class HelloWorldElement extends HTMLElement { 85 | @attr name = 'World' 86 | 87 | connectedCallback() { 88 | this.attachShadow({mode: 'open'}) 89 | } 90 | 91 | attributeChangedCallback() { 92 | render(html` 93 |
94 | Hello ${ this.name }
95 |
`,
96 | this.shadowRoot!)
97 | }
98 | }
99 | ```
100 |
101 | Here, instead of declaring our template in HTML, we can do so in JS, and achieve exactly the same effect. We aren't using `@targets` in this example, as there is a more direct way to handle the data; relying on `attributeChangedCallback` which will efficiently update only the parts that change.
102 |
103 | The same effect could be achieved without using `@attr` via:
104 |
105 | ```typescript
106 | import { controller } from "@github/catalyst"
107 | import { html, render } from "@github/jtml"
108 |
109 | @controller
110 | class HelloWorldElement extends HTMLElement {
111 |
112 | // Make `name` automatically update when changed
113 | #name = 'World'
114 | get name() {
115 | return this.#name
116 | }
117 | set name(value: string) {
118 | this.#name = value
119 | this.update()
120 | }
121 |
122 | connectedCallback() {
123 | this.attachShadow({mode: 'open'})
124 | this.update()
125 | }
126 |
127 | update() {
128 | render(html`
129 |
130 | Hello ${ this.#name }
131 |
`,
132 | this.shadowRoot!)
133 | }
134 | }
135 | ```
136 |
137 |
--------------------------------------------------------------------------------
/docs/_guide/decorators-2.md:
--------------------------------------------------------------------------------
1 | ---
2 | version: 2
3 | chapter: 3
4 | title: Decorators
5 | subtitle: Using TypeScript for ergonomics
6 | permalink: /guide-v2/decorators
7 | ---
8 |
9 | Decorators are used heavily in Catalyst, because they provide really clean ergonomics and makes using the library a lot easier. Decorators are a special, (currently) non standard, feature of TypeScript. You'll need to turn the `experimentalDecorators` option on inside of your TypeScript project to use them (if you're using `@babel/plugin-proposal-decorators` plugin, you need to use [`legacy` option](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy)).
10 |
11 | You can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:
12 |
13 | Decorators can be used three ways:
14 |
15 | ### Class Decorators
16 |
17 | Catalyst comes with the `@controller` decorator. This gets put on top of the class, like so:
18 |
19 | ```js
20 | @controller
21 | class HelloWorldElement extends HTMLElement {}
22 | ```
23 |
24 | ### Class Field Decorators
25 |
26 | Catalyst comes with the `@target` and `@targets` decorators (for more on these [read the Targets guide section]({{ site.baseurl }}/guide/targets)). These get added on top or to the left of the field name, like so:
27 |
28 | ```js
29 | class HelloWorldElement extends HTMLElement {
30 |
31 | @target something
32 |
33 | // Alternative style
34 | @targets
35 | others
36 |
37 | }
38 | ```
39 | 40 | 41 | Class Field decorators get given the class and the field name so they can add custom functionality to the field. Because they operate on the fields, they must be put on top of or to the left of the field. 42 | 43 | ### Method Decorators 44 | 45 | Method decorators work just like Field Decorators. Put them on top or on the left of the method, like so: 46 | 47 | 48 | ```js 49 | class HelloWorldElement extends HTMLElement { 50 | 51 | @log 52 | submit() { 53 | // ... 54 | } 55 | 56 | // Alternative style 57 | 58 | @log load() { 59 | // ... 60 | } 61 | 62 | } 63 | ``` 64 | 65 | ### Getter/Setter 66 | 67 | Decorators can also be used over a `get` or `set` field. These work just like Field Decorators, but you can put them over one or both the `get` or `set` field. Some decorators might throw an error if you put them over a `get` field, when they expect to be put over a `set` field: 68 | 69 | 70 | ```js 71 | class HelloWorldElement extends HTMLElement { 72 | 73 | @target set something() { 74 | // ... 75 | } 76 | 77 | // Can be used over just one field 78 | @attr get data() { 79 | return {} 80 | } 81 | set data() { 82 | 83 | } 84 | } 85 | ``` 86 | 87 | ### Supporting `strictPropertyInitialization` 88 | 89 | TypeScript comes with various "strict" mode settings, one of which is `strictPropertyInitialization` which lets TypeScript catch potential class properties which might not be assigned during construction of a class. This option conflicts with Catalyst's `@target`/`@targets` decorators, which safely do the assignment but TypeScript's simple heuristics cannot detect this. There are two ways to work around this: 90 | 91 | 1. Use TypeScript's [`declare` modifier](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) to tell TypeScript that the decorated field will still be set up correctly: 92 | 93 | ```typescript 94 | class HelloWorldElement extends HTMLElement { 95 | @target declare something: HTMLElement 96 | @targets declare items: HTMLElement[] 97 | } 98 | ``` 99 | 100 | Note that this only works on TypeScript 3.7+, so if you're on an older version, you can also use the [definite initialization operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#definite-assignment-assertions) to do the same thing. 101 | 102 | 2. You can also disable the compiler option (other strict mode rules can still apply) in your `tsconfig.json` like so: 103 | 104 | ```json 105 | { 106 | "compilerOptions": { 107 | "strict": true, 108 | "strictPropertyInitialization": false 109 | } 110 | } 111 | ``` 112 | 113 | ### Function Calling Decorators 114 | 115 | You might see some decorators that look like function calls, and that's because they are! Some decorators allow for customisation; calling with additional arguments. Decorators that expect to be called are generally not interchangeable with the non-call variant, a decorators documentation should tell you how to use it. 116 | 117 | Catalyst doesn't ship with any decorators that can be called like a function; but an example of one can be found in the `@debounce` decorator in the [`@github/mini-throttle`](https://github.com/github/mini-throttle) package: 118 | 119 | ```js 120 | class HelloWorldElement extends HTMLElement { 121 | 122 | @debounce(100) 123 | handleInput() { 124 | // ... 125 | } 126 | 127 | } 128 | ``` 129 |
130 | -------------------------------------------------------------------------------- /docs/github-syntax.css: -------------------------------------------------------------------------------- 1 | /* Shared */ 2 | :root { 3 | --color-syntax-markup-deleted-text: #b31d28; 4 | --color-syntax-markup-deleted-bg: #ffeef0; 5 | --color-syntax-markup-inserted-text: #22863a; 6 | --color-syntax-markup-inserted-bg: #f0fff4; 7 | } 8 | 9 | /* No preference or prefers light */ 10 | :root:not([data-prefers-color-scheme=dark]), 11 | html[data-prefers-color-scheme=light] { 12 | --color-syntax-text-primary: #24292e; 13 | --color-syntax-highlight: #ffffcc; 14 | --color-syntax-comment: #6a737d; 15 | --color-syntax-brackethighlighter-unmatched: #b31d28; 16 | --color-syntax-keyword: #24292e; /* upstream: #d73a49 */ 17 | --color-syntax-string: #032f62; 18 | --color-syntax-constant: #005cc5; 19 | --color-syntax-entity-tag: #22863a; 20 | --color-syntax-entity: #6f42c1; 21 | } 22 | /* Prefers dark */ 23 | html[data-prefers-color-scheme=dark] { 24 | --color-syntax-text-primary: #c9d1d9; 25 | --color-syntax-highlight: #ffffcc; 26 | --color-syntax-comment: #959da5; 27 | --color-syntax-brackethighlighter-unmatched: #d73a49; 28 | --color-syntax-keyword: #c9d1d9; /* upstream: #ea4a5a */ 29 | --color-syntax-string: #79b8ff; 30 | --color-syntax-constant: #c8e1ff; 31 | --color-syntax-entity-tag: #7bcc72; 32 | --color-syntax-entity: #b392f0; 33 | } 34 | @media (prefers-color-scheme: dark) { 35 | :root:not([data-prefers-color-scheme=light]) { 36 | --color-syntax-text-primary: #c9d1d9; 37 | --color-syntax-highlight: #ffffcc; 38 | --color-syntax-comment: #959da5; 39 | --color-syntax-brackethighlighter-unmatched: #d73a49; 40 | --color-syntax-keyword: #c9d1d9; /* upstream: #ea4a5a */ 41 | --color-syntax-string: #79b8ff; 42 | --color-syntax-constant: #c8e1ff; 43 | --color-syntax-entity-tag: #7bcc72; 44 | --color-syntax-entity: #b392f0; 45 | } 46 | } 47 | 48 | .highlight .hll { background-color: var(--color-syntax-highlight) } 49 | 50 | .highlight .nx, 51 | .highlight .p { color: var(--color-syntax-primary); } 52 | 53 | /* Comment, Comment.Multiline, Comment.Single */ 54 | .highlight .c, 55 | .highlight .cm, 56 | .highlight .c1 { color: var(--color-syntax-comment); font-style: italic } 57 | 58 | /* Comment.Preproc, Comment.Special */ 59 | .highlight .cp, 60 | .highlight .cs { color: var(--color-syntax-comment); font-weight: bold; font-style: italic } 61 | 62 | /* Error */ 63 | .highlight .err { color: var(--color-syntax-brackethighlighter-unmatched) } 64 | 65 | /* Generic.Error, Generic.Traceback */ 66 | .highlight .gr, 67 | .highlight .gt { color: var(--color-syntax-brackethighlighter-unmatched) } 68 | 69 | /* Keyword, Keyword.Constant, Keyword.Declaration, Keyword.Namespace, Keyword.Pseudo, Keyword.Reserved, Keyword.Type */ 70 | .highlight .k, 71 | .highlight .kc, 72 | .highlight .kd, 73 | .highlight .kn, 74 | .highlight .kp, 75 | .highlight .kr, 76 | .highlight .kt { color: var(--color-syntax-keyword); font-weight: bold } 77 | 78 | /* Literal.Number, Literal.String, Literal.Number.Float, Literal.Number.Hex, Literal.Number.Integer, Literal.Number.Oct, Literal.String.Backtick, Literal.String.Char, Literal.String.Doc, Literal.String.Double, Literal.String.Escape, Literal.String.Heredoc, Literal.String.Interpol, Literal.String.Other, Literal.String.Regex, Literal.String.Single, Literal.String.Symbol, Literal.Number.Integer.Long */ 79 | .highlight .m, 80 | .highlight .s, 81 | .highlight .mf, 82 | .highlight .mh, 83 | .highlight .mi, 84 | .highlight .mo, 85 | .highlight .sb, 86 | .highlight .sc, 87 | .highlight .sd, 88 | .highlight .s2, 89 | .highlight .se, 90 | .highlight .sh, 91 | .highlight .si, 92 | .highlight .sx, 93 | .highlight .sr, 94 | .highlight .s1, 95 | .highlight .ss, 96 | .highlight .dl, 97 | .highlight .il { color: var(--color-syntax-string) } 98 | 99 | /* Name.Attribute, Name.Constant, Name.Variable, Name.Variable.Class, Name.Variable.Global, Name.Variable.Instance */ 100 | .highlight .na, 101 | .highlight .no, 102 | .highlight .nv, 103 | .highlight .vc, 104 | .highlight .vg, 105 | .highlight .vi { color: var(--color-syntax-constant) } 106 | 107 | /* Name.Decorator, Name.Builtin, Name.Namespace, Name.Builtin.Pseudo */ 108 | .highlight .nd, 109 | .highlight .nb, 110 | .highlight .nn, 111 | .highlight .bp { color: var(--color-syntax-constant); font-weight: bold; } 112 | 113 | /* Name.Tag */ 114 | .highlight .nt { color: var(--color-syntax-entity-tag) } 115 | 116 | /* Name.Entity */ 117 | .highlight .ni { color: var(--color-syntax-entity) } 118 | 119 | /* Name.Class, Name.Exception, Name.Function, Name.Label */ 120 | .highlight .nc, 121 | .highlight .ne, 122 | .highlight .nf, 123 | .highlight .nl { color: var(--color-syntax-entity); font-weight: bold } 124 | 125 | /* Generic.Strong */ 126 | .highlight .gs { font-weight: bold } 127 | 128 | /* Generic.Deleted */ 129 | .highlight .gd { color: var(--color-syntax-markup-deleted-text); background-color: var(--color-syntax-markup-deleted-bg) } 130 | 131 | /* Generic.Inserted */ 132 | .highlight .gi { color: var(--color-syntax-markup-inserted-text); background-color: var(--color-syntax-markup-inserted-bg) } 133 | 134 | /* Operator, Operator.Word */ 135 | .highlight .o, 136 | .highlight .ow { color: var(--color-syntax-text-primary); font-weight: bold } 137 | 138 | /* Text.Whitespace */ 139 | .highlight .w { color: var(--color-syntax-text-primary) } 140 | 141 | /* Generic.Heading, Generic.Output, Generic.Prompt, Generic.Subheading */ 142 | .highlight .gh, 143 | .highlight .go, 144 | .highlight .gp, 145 | .highlight .gu { color: var(--color-syntax-text-primary) } 146 | 147 | /* Generic.Emph */ 148 | .highlight .ge { color: var(--color-syntax-text-primary); font-style: italic } 149 | -------------------------------------------------------------------------------- /src/providable.ts: -------------------------------------------------------------------------------- 1 | import type {CustomElementClass, CustomElement} from './custom-element.js' 2 | import {createMark} from './mark.js' 3 | import {createAbility} from './ability.js' 4 | 5 | export interface Context
6 |
15 |
16 | Web Components made easy
7 |-
8 |
- 9 | 10 | Read the Guide 11 | 12 | 13 |
20 |
54 | Catalyse your Web Components
21 |Catalyse your Web Components
22 |
23 |
53 |
24 | {% highlight html %}
25 |
26 |
27 |
28 |
31 |
32 |
33 |
34 |
35 | {% endhighlight %}
36 |
37 |
38 | {% highlight js %}
39 | import { controller, target } from "@github/catalyst"
40 |
41 | @controller
42 | class HelloWorldElement extends HTMLElement {
43 | @target name: HTMLElement
44 | @target output: HTMLElement
45 |
46 | greet() {
47 | this.output.textContent = `Hello, ${this.name.value}!`
48 | }
49 | }
50 | {% endhighlight %}
51 |
52 |
17 |
52 |
53 | ### Target Syntax
54 |
55 | The target syntax follows a pattern of `controller.target`.
56 |
57 | - `controller` must be the name of a controller ascendant to the element.
58 | - `.` is the required delimiter between `controller` and `target`.
59 | - `target` must be the name matching that of a `@target` (or `@targets`) annotated field within the Controller code.
60 |
61 | ### Multiple Targets
62 |
63 | {% capture callout %}
64 | Remember! There are two decorators available, `@target` which fetches only one `data-target` element, and `@targets` which fetches multiple `data-targets` elements!
65 | {% endcapture %}{% include callout.md %}
66 |
67 | The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost the same, but returns an Array of elements, and it searches the `data-targets` attribute (not `data-target`).
68 |
69 | Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
70 |
71 |
76 |
77 | ```html
78 |
18 |
21 |
22 | ```html
23 |
24 |
26 |
27 |
28 | ```
29 |
30 |
31 |
32 |
33 |
36 |
37 | ```js
38 | import { controller, target } from "@github/catalyst"
39 |
40 | @controller
41 | class HelloWorldElement extends HTMLElement {
42 | @target output: HTMLElement
43 |
44 | greet() {
45 | this.output.textContent = `Hello, world!`
46 | }
47 | }
48 | ```
49 |
50 |
51 | 93 | 94 | 99 | 100 | ```js 101 | import { controller, target, targets } from "@github/catalyst" 102 | 103 | @controller 104 | class UserSettingsElement extends HTMLElement { 105 | @target read: HTMLInputElement 106 | @target write: HTMLInputElement 107 | 108 | valid() { 109 | // At least one checkbox must be checked! 110 | return this.read.checked || this.write.checked 111 | } 112 | } 113 | 114 | @controller 115 | class UserListElement extends HTMLElement { 116 | @targets users: HTMLElement[] 117 | 118 | valid() { 119 | // Every user must be valid! 120 | return this.users.every(user => user.valid()) 121 | } 122 | } 123 | ``` 124 | 125 | ### Target Vs Targets 126 | 127 | To clarify the difference between `@target` and `@targets` here is a handy table: 128 | 129 | | Decorator | Equivalent Native Method | Selector | Returns | 130 | |:-----------|:-------------------------|:-------------------|:-----------------| 131 | | `@target` | `querySelector` | `data-target="*"` | `Element` | 132 | | `@targets` | `querySelectorAll` | `data-targets="*"` | `Array
18 |
53 |
54 | ### Target Syntax
55 |
56 | The target syntax follows a pattern of `controller.target`.
57 |
58 | - `controller` must be the name of a controller ascendant to the element.
59 | - `target` must be the name matching that of a `@target` (or `@targets`) annotated field within the Controller code.
60 |
61 | ### Multiple Targets
62 |
63 | {% capture callout %}
64 | Remember! There are two decorators available, `@target` which fetches only one `data-target` element, and `@targets` which fetches multiple `data-targets` elements!
65 | {% endcapture %}{% include callout.md %}
66 |
67 | The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost the same, but returns an Array of elements, and it searches the `data-targets` attribute (not `data-target`).
68 |
69 | Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
70 |
71 |
76 |
77 | ```html
78 |
19 |
22 |
23 | ```html
24 |
25 |
27 |
28 |
29 | ```
30 |
31 |
32 |
33 |
34 |
37 |
38 | ```js
39 | import { controller, target } from "@github/catalyst"
40 |
41 | @controller
42 | class HelloWorldElement extends HTMLElement {
43 | @target output: HTMLElement
44 |
45 | greet() {
46 | this.output.textContent = `Hello, world!`
47 | }
48 | }
49 | ```
50 |
51 |
52 | 93 | 94 | 99 | 100 | ```js 101 | import { controller, target, targets } from "@github/catalyst" 102 | 103 | @controller 104 | class UserSettingsElement extends HTMLElement { 105 | @target read: HTMLInputElement 106 | @target write: HTMLInputElement 107 | 108 | valid() { 109 | // At least one checkbox must be checked! 110 | return this.read.checked || this.write.checked 111 | } 112 | } 113 | 114 | @controller 115 | class UserListElement extends HTMLElement { 116 | @targets users: HTMLElement[] 117 | 118 | valid() { 119 | // Every user must be valid! 120 | return this.users.every(user => user.valid()) 121 | } 122 | } 123 | ``` 124 | 125 | ### Target Vs Targets 126 | 127 | To clarify the difference between `@target` and `@targets` here is a handy table: 128 | 129 | | Decorator | Equivalent Native Method | Selector | Returns | 130 | |:-----------|:-------------------------|:-------------------|:-----------------| 131 | | `@target` | `querySelector` | `data-target="*"` | `Element` | 132 | | `@targets` | `querySelectorAll` | `data-targets="*"` | `Array
18 |
66 |
67 | ### Actions Syntax
68 |
69 | The actions syntax follows a pattern of `event:controller#method`.
70 |
71 | - `event` must be the name of a [_DOM Event_](https://developer.mozilla.org/en-US/docs/Web/Events), e.g. `click`.
72 | - `controller` must be the name of a controller ascendant to the element.
73 | - `method` (optional) must be a _public_ _method_ attached to a controller's prototype. Static methods will not work.
74 |
75 | If method is not supplied, it will default to `handleEvent`.
76 |
77 | Some examples of Actions Syntax:
78 |
79 | - `click:my-element#foo` -> `click` events will call `foo` on `my-element` elements.
80 | - `submit:my-element#foo` -> `submit` events will call `foo` on `my-element` elements.
81 | - `click:user-list` -> `click` events will call `handleEvent` on `user-list` elements.
82 | - `click:user-list#` -> `click` events will call `handleEvent` on `user-list` elements.
83 | - `click:top-header-user-profile#` -> `click` events will call `handleEvent` on `top-header-user-profile` elements.
84 | - `nav:keydown:user-list` -> `navigation:keydown` events will call `handleEvent` on `user-list` elements.
85 |
86 | ### Multiple Actions
87 |
88 | Multiple actions can be bound to multiple events, methods, and controllers. For example:
89 |
90 |
93 |
94 | ```html
95 |
19 |
20 |
23 |
24 | ```html
25 |
26 |
30 |
31 |
35 |
36 |
38 |
39 |
40 | ```
41 |
42 |
43 |
44 |
45 |
48 |
49 | ```js
50 | import { controller, target } from "@github/catalyst"
51 |
52 | @controller
53 | class HelloWorldElement extends HTMLElement {
54 | @target name: HTMLElement
55 | @target output: HTMLElement
56 |
57 | greetSomeone() {
58 | this.output.textContent =
59 | `Hello, ${this.name.value}!`
60 | }
61 | }
62 | ```
63 |
64 |
65 |