[ { "path": ".devcontainer/Dockerfile", "content": "# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.222.0/containers/javascript-node/.devcontainer/base.Dockerfile\n\n# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 16, 14, 12, 16-bullseye, 14-bullseye, 12-bullseye, 16-buster, 14-buster, 12-buster\nARG VARIANT=\"24\"\nFROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}\n\nRUN apt-get update && export DEBIAN_FRONTEND=noninteractive \\\n && apt-get -y install --no-install-recommends bundler\n\n# [Optional] Uncomment if you want to install an additional version of node using nvm\n# ARG EXTRA_NODE_VERSION=10\n# RUN su node -c \"source/usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}\"\n\n# [Optional] Uncomment if you want to install more global node modules\n# RUN su node -c \"npm install -g \" \n" }, { "path": ".devcontainer/devcontainer.json", "content": "// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:\n// https://github.com/microsoft/vscode-dev-containers/tree/v0.222.0/containers/javascript-node\n{\n\t\"name\": \"Node.js\",\n\t\"build\": {\n\t\t\"dockerfile\": \"Dockerfile\",\n\t\t// Update 'VARIANT' to pick a Node version: 16, 14, 12.\n\t\t// Append -bullseye or -buster to pin to an OS version.\n\t\t// Use -bullseye variants on local arm64/Apple Silicon.\n\t\t\"args\": { \"VARIANT\": \"24\" }\n\t},\n\n\t// Set *default* container specific settings.json values on container create.\n\t\"settings\": {},\n\n\t// Add the IDs of extensions you want installed when the container is created.\n\t\"extensions\": [\n\t\t\"dbaeumer.vscode-eslint\"\n\t],\n\n\t// Use 'forwardPorts' to make a list of ports inside the container available locally.\n\t// \"forwardPorts\": [],\n\n\t// Use 'postCreateCommand' to run commands after the container is created.\n\t\"postCreateCommand\": \"npm i && cd docs && sudo bundle install\",\n\n\t// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.\n\t\"remoteUser\": \"node\",\n\t\"features\": {\n\t\t\"git\": \"latest\"\n\t}\n}\n" }, { "path": ".eslintrc.json", "content": "{\n \"root\": true,\n \"plugins\": [\"github\"],\n \"extends\": [\"plugin:github/recommended\", \"plugin:github/typescript\", \"plugin:github/browser\"],\n \"rules\": {\n \"import/no-unresolved\": \"off\",\n \"github/no-inner-html\": \"off\",\n \"i18n-text/no-en\": \"off\",\n \"import/extensions\": [\"error\", \"ignorePackages\"],\n \"@typescript-eslint/consistent-type-imports\": [\"error\", {\"prefer\": \"type-imports\"}]\n },\n \"overrides\": [\n {\n \"files\": \"test/*\",\n \"rules\": {\n \"@typescript-eslint/no-empty-function\": \"off\"\n },\n \"globals\": {\n \"chai\": false,\n \"expect\": false\n },\n \"env\": {\n \"mocha\": true\n }\n },\n {\n \"files\": \"*.cjs\",\n \"rules\": {\n \"import/no-commonjs\": \"off\"\n },\n \"env\": {\n \"node\": true\n }\n }\n ]\n}\n" }, { "path": ".github/workflows/lighthouse.yml", "content": "name: Lighthouse\npermissions:\n contents: read\n\non: [pull_request]\n\njobs:\n lhci:\n name: Lighthouse\n runs-on: ubuntu-latest\n steps:\n - name: Checkout the project\n uses: actions/checkout@v3\n\n - name: Use Node.js 24.x (LTS)\n uses: actions/setup-node@v3\n with:\n node-version: 24.x\n cache: 'npm'\n - run: npm ci\n\n - name: Use Ruby 2.7.3\n uses: ruby/setup-ruby@v1\n with:\n ruby-version: '2.7.3'\n bundler-cache: true\n working-directory: docs\n\n - name: Build docs\n run: npm run build:docs\n env:\n JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Run Lighthouse CI\n run: npx @lhci/cli@0.9.x autorun\n env:\n JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n LHCI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/nodejs.yml", "content": "name: Build\npermissions:\n contents: read\n\non:\n pull_request:\n push:\n\njobs:\n test-node:\n name: Test on Node.js\n runs-on: ubuntu-latest\n steps:\n - name: Checkout the project\n uses: actions/checkout@v3\n - name: Use Node.js 24.x (LTS)\n uses: actions/setup-node@v3\n with:\n node-version: 24.x\n cache: 'npm'\n - run: npm ci\n - name: Lint Codebase\n run: npm run lint\n - name: Run Node.js Tests\n run: npm run test\n - name: Check Bundle Size\n run: npm run size\n" }, { "path": ".github/workflows/publish.yml", "content": "name: Publish\n\non:\n release:\n types: [created]\n\npermissions:\n contents: read\n id-token: write # for provenance and publish access\n\njobs:\n publish-npm:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout the project\n uses: actions/checkout@v3\n - name: Use Node.js 24.x (LTS)\n uses: actions/setup-node@v3\n with:\n node-version: 24.x\n registry-url: https://registry.npmjs.org/\n cache: npm\n - run: npm ci\n - run: npm test\n - run: npm version ${TAG_NAME} --git-tag-version=false\n env:\n TAG_NAME: ${{ github.event.release.tag_name }}\n - run: npm publish --provenance\n" }, { "path": ".gitignore", "content": "node_modules\n_site\n*.tsbuildinfo\nlib/\n.jekyll-cache\n.lighthouseci\ncoverage\n" }, { "path": ".nvmrc", "content": "13.11.0\n" }, { "path": "CODEOWNERS", "content": "* @github/primer-reviewers @koddsson\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as\ncontributors and maintainers pledge to making participation in our project and\nour community a harassment-free experience for everyone, regardless of age, body\nsize, disability, ethnicity, sex characteristics, gender identity and expression,\nlevel of experience, education, socio-economic status, nationality, personal\nappearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment\ninclude:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or\n advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic\n address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable\nbehavior and are expected to take appropriate and fair corrective action in\nresponse to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or\nreject comments, commits, code, wiki edits, issues, and other contributions\nthat are not aligned to this Code of Conduct, or to ban temporarily or\npermanently any contributor for other behaviors that they deem inappropriate,\nthreatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces\nwhen an individual is representing the project or its community. Examples of\nrepresenting a project or community include using an official project e-mail\naddress, posting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event. Representation of a project may be\nfurther defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported by contacting the project team at opensource@github.com. All\ncomplaints will be reviewed and investigated and will result in a response that\nis deemed necessary and appropriate to the circumstances. The project team is\nobligated to maintain confidentiality with regard to the reporter of an incident.\nFurther details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good\nfaith may face temporary or permanent repercussions as determined by other\nmembers of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,\navailable at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see\nhttps://www.contributor-covenant.org/faq\n" }, { "path": "CONTRIBUTING.md", "content": "## Contributing\n\n[fork]: https://github.com/github/catalyst/fork\n[pr]: https://github.com/github/catalyst/compare\n[style]: https://github.com/styleguide/ruby\n[code-of-conduct]: CODE_OF_CONDUCT.md\n\nHi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.\n\nContributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.md).\n\nPlease note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.\n\n## Submitting a pull request\n\n0. [Fork][fork] and clone the repository\n0. Configure and install the dependencies: `npm i`\n0. Make sure the tests pass on your machine: `npm t`\n0. Create a new branch: `git checkout -b my-branch-name`\n0. Make your change, add tests, and make sure the tests still pass\n0. Push to your fork and [submit a pull request][pr]\n0. Pat your self on the back and wait for your pull request to be reviewed and merged.\n\nHere are a few things you can do that will increase the likelihood of your pull request being accepted:\n\n- Follow the [style guide][style].\n- Write tests.\n- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.\n- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).\n\n## Resources\n\n- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)\n- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)\n- [GitHub Help](https://help.github.com)\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2020 GitHub\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# Catalyst\n\nCatalyst is a set of patterns and techniques for developing components within a complex application. At its core, Catalyst simply provides a small library of functions to make developing [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) easier.\n\nFor more see the [Catalyst Website](https://github.github.io/catalyst/) which includes a [Guide To using Catalyst](https://github.github.io/catalyst/guide/introduction).\n" }, { "path": "SECURITY.md", "content": "If you discover a security issue in this repository, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github).\n" }, { "path": "docs/404.html", "content": "---\nlayout: default\n---\n\n\n\n
\n

404

\n\n

Page not found :(

\n

The requested page could not be found.

\n
\n" }, { "path": "docs/Gemfile", "content": "# frozen_string_literal: true\n\nsource 'https://rubygems.org'\n\ngem 'jekyll'\n\ngroup :jekyll_plugins do\n gem 'jekyll-commonmark-ghpages'\n gem 'jekyll-github-metadata'\n gem 'jekyll-gzip'\nend\n" }, { "path": "docs/_config.yml", "content": "title: Catalyst\n\nmarkdown: CommonMarkGhPages\n\ncommonmark:\n extensions: ['autolink', 'table']\n\npermalink: pretty\n\nexclude:\n - Gemfile\n - Gemfile.lock\n - node_modules\n - vendor\n\ncollections:\n guide:\n output: true\n\ndefaults:\n - scope:\n type: guide\n values:\n layout: guide\n\nrepository: github/catalyst\n\nplugins:\n - 'jekyll-github-metadata'\n - 'jekyll-gzip'\n" }, { "path": "docs/_guide/abilities.md", "content": "---\nversion: 2\nchapter: 4\ntitle: Abilities\nsubtitle: Abilities\npermalink: /guide-v2/abilities\n---\n\nUnder the hood Catalyst's controller decorator is comprised of a handful of separate \"abilities\". 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. 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.\n\n### Using Abilities\n\nAbilities 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):\n\n```typescript\nimport {actionable} from '@github/catalyst'\n\n@actionable\nclass HelloWorld extends HTMLElement {\n}\n```\n\n### Using Marks\n\nAbilities 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:\n\n```typescript\nimport {targetable, target, targets} from '@github/catalyst'\n\n@targetable\nclass HelloWorldElement extends HTMLElement {\n @target name\n @targets people\n}\n```\n\nMarks _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.\n\n### Built-In Abilities\n\nCatalyst ships with a set of built in abilities. The `@controller` decorator applies the following built-in abilities:\n\n- `controllable` - the base ability which other abilities require for functionality.\n- `targetable` - the ability to define `@target` and `@targets` properties. See [Targets]({{ site.baseurl }}/guide/targets) for more.\n- `actionable` - the ability to automatically bind events based on `data-action` attributes. See [Actions]({{ site.baseurl }}/guide/actions) for more.\n- `attrable` - the ability to define `@attr`s. See [Attrs]({{ site.baseurl }}/guide/attrs) for more.\n\nThe `@controller` decorator also applies the `@register` decorator which automatically registers the element in the Custom Element registry, however this decorator isn't an \"ability\".\n\nThe following abilities are shipped with Catalyst but require manually applying as they aren't considered critical functionality:\n\n - `providable` - the ability to define `provider` and `consumer` properties. See [Providable]({{ site.baseurl }}/guide/providable) for more.\n\nIn addition to the provided abilities, Catalyst provides all of the tooling to create your own custom abilities. Take a look at the [Create Ability]({{ site.baseurl }}/guide/create-ability) documentation for more!\n" }, { "path": "docs/_guide/actions-2.md", "content": "---\nversion: 2\nchapter: 6\ntitle: Actionable\nsubtitle: Binding Events\npermalink: /guide-v2/actions\n---\n\nCatalyst Components automatically bind actions upon instantiation. Automatically as part of the `connectedCallback`, a component will search for any children with the `data-action` attribute, and bind events based on the value of this attribute. Any _public method_ on a Controller can be bound to via `data-action`.\n\n{% capture callout %}\nRemember! Actions are _automatically_ bound using the `@controller` decorator. There's no extra JavaScript code needed.\n{% endcapture %}{% include callout.md %}\n\n### Example\n\n
\n
\n\n\n\n```html\n\n \n\n \n Greet Someone\n \n\n \n \n\n```\n\n
\n
\n\n\n\n```js\nimport { controller, target } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @target name: HTMLElement\n @target output: HTMLElement\n\n greetSomeone() {\n this.output.textContent =\n `Hello, ${this.name.value}!`\n }\n}\n```\n\n
\n
\n\n### Actions Syntax\n\nThe actions syntax follows a pattern of `event:controller#method`.\n\n - `event` must be the name of a [_DOM Event_](https://developer.mozilla.org/en-US/docs/Web/Events), e.g. `click`.\n - `controller` must be the name of a controller ascendant to the element.\n - `method` (optional) must be a _public_ _method_ attached to a controller's prototype. Static methods will not work.\n\nIf method is not supplied, it will default to `handleEvent`.\n\nSome examples of Actions Syntax:\n\n- `click:my-element#foo` -> `click` events will call `foo` on `my-element` elements.\n- `submit:my-element#foo` -> `submit` events will call `foo` on `my-element` elements.\n- `click:user-list` -> `click` events will call `handleEvent` on `user-list` elements.\n- `click:user-list#` -> `click` events will call `handleEvent` on `user-list` elements.\n- `click:top-header-user-profile#` -> `click` events will call `handleEvent` on `top-header-user-profile` elements.\n- `nav:keydown:user-list` -> `navigation:keydown` events will call `handleEvent` on `user-list` elements.\n\n### Multiple Actions\n\nMultiple actions can be bound to multiple events, methods, and controllers. For example:\n\n\n\n```html\n\n \n \n\n \n Greet Someone\n \n \n\n```\n\n### Custom Events\n\nA Controller may emit custom events, which may be listened to by other Controllers using the same Actions Syntax. There is no extra syntax needed for this. For example a `lazy-loader` Controller might dispatch a `loaded` event, once its contents are loaded, and other controllers can listen to this event:\n\n\n\n```html\n\n \n \n \n\n```\n\n\n\n```js\nimport {controller} from '@github/catalyst'\n\n@controller\nclass LazyLoader extends HTMLElement {\n\n connectedCallback() {\n this.innerHTML = await (await fetch(this.dataset.url)).text()\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n\n}\n\n@controller\nclass HoverCard extends HTMLElement {\n\n enable() {\n this.disabled = false\n }\n\n}\n```\n\n### Targets and \"ShadowRoots\"\n\nCustom elements can create encapsulated DOM trees known as \"Shadow\" DOM. Catalyst actions support Shadow DOM by traversing the `shadowRoot`, if present, and also automatically watching shadowRoots for changes; auto-binding new elements as they are added.\n\n### What about without Decorators?\n\nIf you're using decorators, then the `@controller` decorator automatically handles binding of actions to a Controller.\n\nIf you're not using decorators, then you'll need to call `bind(this)` somewhere inside of `connectedCallback()`.\n\n```js\nimport {bind} from '@github/catalyst'\n\nclass HelloWorldElement extends HTMLElement {\n connectedCallback() {\n bind(this)\n }\n}\n```\n\n### Binding dynamically added actions\n\nCatalyst automatically listens for elements that are dynamically injected into the DOM, and will bind any element's `data-action` attributes. It does this by calling `listenForBind(controller.ownerDocument)`. If for some reason you need to observe other documents (such as mutations within an iframe), then you can call the `listenForBind` manually, passing a `Node` to listen to DOM mutations on.\n\n```js\nimport {listenForBind} from '@github/catalyst'\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @target iframe: HTMLIFrameElement\n\n connectedCallback() {\n // listenForBind(this.ownerDocument) is automatically called.\n\n listenForBind(this.iframe.document.body)\n }\n}\n```\n" }, { "path": "docs/_guide/actions.md", "content": "---\nversion: 1\nchapter: 5\ntitle: Actions\nsubtitle: Binding Events\n---\n\nCatalyst Components automatically bind actions upon instantiation. Automatically as part of the `connectedCallback`, a component will search for any children with the `data-action` attribute, and bind events based on the value of this attribute. Any _public method_ on a Controller can be bound to via `data-action`.\n\n{% capture callout %}\nRemember! Actions are _automatically_ bound using the `@controller` decorator. There's no extra JavaScript code needed.\n{% endcapture %}{% include callout.md %}\n\n### Example\n\n
\n
\n\n\n\n```html\n\n \n\n \n Greet Someone\n \n\n \n \n\n```\n\n
\n
\n\n\n\n```js\nimport { controller, target } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @target name: HTMLElement\n @target output: HTMLElement\n\n greetSomeone() {\n this.output.textContent =\n `Hello, ${this.name.value}!`\n }\n}\n```\n\n
\n
\n\n### Actions Syntax\n\nThe actions syntax follows a pattern of `event:controller#method`.\n\n - `event` must be the name of a [_DOM Event_](https://developer.mozilla.org/en-US/docs/Web/Events), e.g. `click`.\n - `:` is the required delimiter between the `event` and `controller`.\n - `controller` must be the name of a controller ascendant to the element.\n - `#` is the required delimieter between the `controller` and `method`.\n - `method` (optional) must be a _public_ _method_ attached to a controller's prototype. Static methods will not work.\n\nIf method is not supplied, it will default to `handleEvent`.\n\nSome examples of Actions Syntax:\n\n- `click:my-element#foo` -> `click` events will call `foo` on `my-element` elements.\n- `submit:my-element#foo` -> `submit` events will call `foo` on `my-element` elements.\n- `click:user-list` -> `click` events will call `handleEvent` on `user-list` elements.\n- `click:user-list#` -> `click` events will call `handleEvent` on `user-list` elements.\n- `click:top-header-user-profile#` -> `click` events will call `handleEvent` on `top-header-user-profile` elements.\n- `nav:keydown:user-list` -> `navigation:keydown` events will call `handleEvent` on `user-list` elements.\n\n### Multiple Actions\n\nMultiple actions can be bound to multiple events, methods, and controllers. For example:\n\n\n\n```html\n\n \n \n\n \n Greet Someone\n \n \n\n```\n\n### Custom Events\n\nA Controller may emit custom events, which may be listened to by other Controllers using the same Actions Syntax. There is no extra syntax needed for this. For example a `lazy-loader` Controller might dispatch a `loaded` event, once its contents are loaded, and other controllers can listen to this event:\n\n\n\n```html\n\n \n \n \n\n```\n\n\n\n```js\nimport {controller} from '@github/catalyst'\n\n@controller\nclass LazyLoader extends HTMLElement {\n\n connectedCallback() {\n this.innerHTML = await (await fetch(this.dataset.url)).text()\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n\n}\n\n@controller\nclass HoverCard extends HTMLElement {\n\n enable() {\n this.disabled = false\n }\n\n}\n```\n\n### Targets and \"ShadowRoots\"\n\nCustom elements can create encapsulated DOM trees known as \"Shadow\" DOM. Catalyst actions support Shadow DOM by traversing the `shadowRoot`, if present, and also automatically watching shadowRoots for changes; auto-binding new elements as they are added.\n\n### What about without Decorators?\n\nIf you're using decorators, then the `@controller` decorator automatically handles binding of actions to a Controller.\n\nIf you're not using decorators, then you'll need to call `bind(this)` somewhere inside of `connectedCallback()`.\n\n```js\nimport {bind} from '@github/catalyst'\n\nclass HelloWorldElement extends HTMLElement {\n connectedCallback() {\n bind(this)\n }\n}\n```\n\n### Binding dynamically added actions\n\nCatalyst automatically listens for elements that are dynamically injected into the DOM, and will bind any element's `data-action` attributes. It does this by calling `listenForBind(controller.ownerDocument)`. If for some reason you need to observe other documents (such as mutations within an iframe), then you can call the `listenForBind` manually, passing a `Node` to listen to DOM mutations on.\n\n```js\nimport {listenForBind} from '@github/catalyst'\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @target iframe: HTMLIFrameElement\n\n connectedCallback() {\n // listenForBind(this.ownerDocument) is automatically called.\n\n listenForBind(this.iframe.document.body)\n }\n}\n```\n" }, { "path": "docs/_guide/anti-patterns-2.md", "content": "---\nversion: 2\nchapter: 15\ntitle: Anti Patterns\nsubtitle: Things to avoid building components\npermalink: /guide-v2/anti-patterns\n---\n\n{% capture octx %}{% endcapture %}\n{% capture octick %}{% endcapture %}\n{% capture discouraged %}

{{ octx }} Discouraged

{% endcapture %}\n{% capture encouraged %}

{{ octick }} Encouraged

{% endcapture %}\n\nHere are a few common anti-patterns which we've discovered as developers have used Catalyst. We consider these anti-patterns as they're best avoided, because of surprising edge-cases, or simply because there are easier ways to achieve the same goals.\n\n### Avoid doing any initialisation in the constructor\n\nWith conventional classes, it is expected that initialisation will be done in the `constructor()` method. Custom Elements are slightly different, because the `constructor` is called _before_ the element has been put into the Document, which means any initialisation that expects to be connected to a DOM will fail. \n\n{{ discouraged }}\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n constructor() {\n // This will fire before DOM is connected, so will never bubble!\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n}\n```\n\n{{ encouraged }}\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n connectedCallback() {\n // This will fire _after_ DOM is connected, so will bubble up as expected\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n}\n```\n\n\n### Avoid interacting with parents, use Events where possible\n\nSometimes it's necessary to let ancestors know about the state of a child element, for example when an element loads or needs the parent to change somehow. Sometimes it can be tempting to use methods like `this.closest()` to get a reference to the parent element and interact with it directly, but this creates a fragile coupling to elements and is best avoided. Events can used here, instead:\n\n{{ discouraged }}\n\n
\n
\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserSettingsElement extends HTMLElement {\n loading() {\n // While this is loading we need to disable\n // the whole User if `user-profile` ever\n // changes, this code will break!\n this\n .closest('user-profile')\n .disable()\n }\n}\n```\n\n
\n\n```html\n\n \n\n```\n\n
\n
\n\nInstead of interacting with the parent's API directly in JS, you can use `Events` which can be listened to with `data-action`, this moves any coupling into the HTML which already has the association, and so subsequent refactors will have far less risk of breaking the code:\n\n{{ encouraged }}\n\n
\n
\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserSettingsElement extends HTMLElement {\n loading() {\n this.dispatchEvent(\n new CustomEvent('loading')\n )\n }\n}\n```\n\n
\n\n```html\n\n \n \n\n```\n\n
\n
\n\n### Avoid shadowing method names\n\nWhen naming a method, you should avoid naming it something that already exists on the `HTMLElement` prototype; as doing so can lead to surprising behaviors. Test out the form below to see what method names are allowed or not:\n\n
\n \n \n \n \n \n
\n\n### Avoid naming methods after events, e.g. `onClick`\n\nWhen you have a method which is only called as an event, it is tempting to name that method based off of the event, e.g. `onClick`, `onInputFocus`, and so on. This name implies a coupling between the event and method, which later refactorings may break. Also names like `onClick` are very close to `onclick` which is already [part of the Element's API](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onclick). Instead we recommend naming the method after what it does, not how it is called, for example `resetForm`:\n\n{{ discouraged }}\n\n
\n
\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserLoginElement extends HTMLElement {\n\n // `onClick` is not clear\n onClick() {\n // Log the user in\n }\n}\n```\n\n
\n
\n\n```html\n\n \n \n \n Log In\n \n\n```\n\n
\n
\n\n{{ encouraged }}\n\n
\n
\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserLoginElement extends HTMLElement {\n\n login() {\n // Log the user in\n }\n}\n```\n\n
\n
\n\n```html\n\n \n \n Log In\n \n\n```\n\n
\n
\n\n### Avoid querying against your element, use `@target` or `@targets`\n\nWe find it very common for developers to return to habits and use `querySelector[All]` when needing to get elements. The `@target` and `@targets` decorators were designed to simplify `querySelector[All]` and avoid certain bugs with them (such as nesting issues, and unnecessary coupling) so it's a good idea to use them as much as possible:\n\n{{ discouraged }}\n\n```typescript\nclass UserListElement extends HTMLElement {\n showAdmins() {\n // Just need to get admins here...\n for (const user of this.querySelector('[data-is-admin]')) {\n user.hidden = false\n }\n }\n}\n```\n\n{{ encouraged }}\n\n```typescript\nclass UserList {\n @targets admins: HTMLElement[]\n\n showAdmins() {\n // Just need to get admins here...\n for (const user of this.admins) {\n user.hidden = false\n }\n }\n}\n```\n\n\n### Avoid filtering `@targets`, use another `@target` or `@targets`\n\n\nSometimes you might need to get a subset of elements from a `@targets` selector. When doing this, simply use another `@target` or `@targets` attribute, it's okay to have many of these! Adding getters which simply return a `@targets` subset has various drawbacks which make it an anti pattern.\n\nFor example let's say we have a list of filter checkboxes and checking the \"all\" checkbox unchecks all other checkboxes:\n\n{{ discouraged }}\n\n```typescript\n@controller\nclass UserFilter {\n @targets filters: HTMLInputElement[]\n\n get allFilter() {\n return this.filters.find(el => el.matches('[data-filter=\"all\"]'))\n }\n\n filter(event: Event) {\n if (event.target === this.allFilter) {\n for(const filter of this.filters) {\n if (filter !== this.allFilter) filter.checked = false\n }\n }\n // ...\n }\n\n}\n```\n\n```html\n\n \n \n \n \n\n```\n\nWhile this works well, it could be more easily solved with targets:\n\n{{ encouraged }}\n\n```typescript\n@controller\nclass UserFilter {\n @targets filters: HTMLInputElement[]\n @target allFilter: HTMLInputElement\n\n filter(event: Event) {\n if (event.target === this.allFilter) {\n for (const filter of this.filters) {\n if (filter !== this.allFilter) filter.checked = false\n }\n }\n // ...\n }\n\n}\n```\n\n```html\n\n \n \n \n \n\n```\n" }, { "path": "docs/_guide/anti-patterns.md", "content": "---\nversion: 1\nchapter: 11\ntitle: Anti Patterns\nsubtitle: Things to avoid building components\n---\n\n{% capture octx %}{% endcapture %}\n{% capture octick %}{% endcapture %}\n{% capture discouraged %}

{{ octx }} Discouraged

{% endcapture %}\n{% capture encouraged %}

{{ octick }} Encouraged

{% endcapture %}\n\nHere are a few common anti-patterns which we've discovered as developers have used Catalyst. We consider these anti-patterns as they're best avoided, because of surprising edge-cases, or simply because there are easier ways to achieve the same goals.\n\n### Avoid doing any initialisation in the constructor\n\nWith conventional classes, it is expected that initialisation will be done in the `constructor()` method. Custom Elements are slightly different, because the `constructor` is called _before_ the element has been put into the Document, which means any initialisation that expects to be connected to a DOM will fail. \n\n{{ discouraged }}\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n constructor() {\n // This will fire before DOM is connected, so will never bubble!\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n}\n```\n\n{{ encouraged }}\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n connectedCallback() {\n // This will fire _after_ DOM is connected, so will bubble up as expected\n this.dispatchEvent(new CustomEvent('loaded'))\n }\n}\n```\n\n\n### Avoid interacting with parents, use Events where possible\n\nSometimes it's necessary to let ancestors know about the state of a child element, for example when an element loads or needs the parent to change somehow. Sometimes it can be tempting to use methods like `this.closest()` to get a reference to the parent element and interact with it directly, but this creates a fragile coupling to elements and is best avoided. Events can used here, instead:\n\n{{ discouraged }}\n\n
\n
\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserSettingsElement extends HTMLElement {\n loading() {\n // While this is loading we need to disable\n // the whole User if `user-profile` ever\n // changes, this code will break!\n this\n .closest('user-profile')\n .disable()\n }\n}\n```\n\n
\n\n```html\n\n \n\n```\n\n
\n
\n\nInstead of interacting with the parent's API directly in JS, you can use `Events` which can be listened to with `data-action`, this moves any coupling into the HTML which already has the association, and so subsequent refactors will have far less risk of breaking the code:\n\n{{ encouraged }}\n\n
\n
\n\n```typescript\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserSettingsElement extends HTMLElement {\n loading() {\n this.dispatchEvent(\n new CustomEvent('loading')\n )\n }\n}\n```\n\n
\n\n```html\n\n \n \n\n```\n\n
\n
\n\n### Avoid shadowing method names\n\nWhen naming a method, you should avoid naming it something that already exists on the `HTMLElement` prototype; as doing so can lead to surprising behaviors. Test out the form below to see what method names are allowed or not:\n\n
\n \n \n \n \n \n
\n\n### Avoid naming methods after events, e.g. `onClick`\n\nWhen you have a method which is only called as an event, it is tempting to name that method based off of the event, e.g. `onClick`, `onInputFocus`, and so on. This name implies a coupling between the event and method, which later refactorings may break. Also names like `onClick` are very close to `onclick` which is already [part of the Element's API](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onclick). Instead we recommend naming the method after what it does, not how it is called, for example `resetForm`:\n\n{{ discouraged }}\n\n
\n
\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserLoginElement extends HTMLElement {\n\n // `onClick` is not clear\n onClick() {\n // Log the user in\n }\n}\n```\n\n
\n
\n\n```html\n\n \n \n \n Log In\n \n\n```\n\n
\n
\n\n{{ encouraged }}\n\n
\n
\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass UserLoginElement extends HTMLElement {\n\n login() {\n // Log the user in\n }\n}\n```\n\n
\n
\n\n```html\n\n \n \n Log In\n \n\n```\n\n
\n
\n\n### Avoid querying against your element, use `@target` or `@targets`\n\nWe find it very common for developers to return to habits and use `querySelector[All]` when needing to get elements. The `@target` and `@targets` decorators were designed to simplify `querySelector[All]` and avoid certain bugs with them (such as nesting issues, and unnecessary coupling) so it's a good idea to use them as much as possible:\n\n{{ discouraged }}\n\n```typescript\nclass UserListElement extends HTMLElement {\n showAdmins() {\n // Just need to get admins here...\n for (const user of this.querySelector('[data-is-admin]')) {\n user.hidden = false\n }\n }\n}\n```\n\n{{ encouraged }}\n\n```typescript\nclass UserList {\n @targets admins: HTMLElement[]\n\n showAdmins() {\n // Just need to get admins here...\n for (const user of this.admins) {\n user.hidden = false\n }\n }\n}\n```\n\n\n### Avoid filtering `@targets`, use another `@target` or `@targets`\n\n\nSometimes you might need to get a subset of elements from a `@targets` selector. When doing this, simply use another `@target` or `@targets` attribute, it's okay to have many of these! Adding getters which simply return a `@targets` subset has various drawbacks which make it an anti pattern.\n\nFor example let's say we have a list of filter checkboxes and checking the \"all\" checkbox unchecks all other checkboxes:\n\n{{ discouraged }}\n\n```typescript\n@controller\nclass UserFilter {\n @targets filters: HTMLInputElement[]\n\n get allFilter() {\n return this.filters.find(el => el.matches('[data-filter=\"all\"]'))\n }\n\n filter(event: Event) {\n if (event.target === this.allFilter) {\n for(const filter of this.filters) {\n if (filter !== this.allFilter) filter.checked = false\n }\n }\n // ...\n }\n\n}\n```\n\n```html\n\n \n \n \n \n\n```\n\nWhile this works well, it could be more easily solved with targets:\n\n{{ encouraged }}\n\n```typescript\n@controller\nclass UserFilter {\n @targets filters: HTMLInputElement[]\n @target allFilter: HTMLInputElement\n\n filter(event: Event) {\n if (event.target === this.allFilter) {\n for (const filter of this.filters) {\n if (filter !== this.allFilter) filter.checked = false\n }\n }\n // ...\n }\n\n}\n```\n\n```html\n\n \n \n \n \n\n```\n" }, { "path": "docs/_guide/attrs-2.md", "content": "---\nversion: 2\nchapter: 7\ntitle: Attrable\nsubtitle: Using attributes as configuration\npermalink: /guide-v2/attrs\n---\n\nComponents may sometimes manage state, or configuration. We encourage the use of DOM as state, rather than maintaining a separate state. One way to maintain state in the DOM is via [Attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).\n\nAs Catalyst elements are really just Web Components, they have the `hasAttribute`, `getAttribute`, `setAttribute`, `toggleAttribute`, and `removeAttribute` set of methods available, as well as [`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset), but these can be a little tedious to use; requiring null checking code with each call.\n\nCatalyst includes the `@attr` decorator which provides nice syntax sugar to simplify, standardise, and encourage use of attributes. `@attr` has the following benefits over the basic `*Attribute` methods:\n\n - It dasherizes a property name, making it safe for HTML serialization without conflicting with [built-in global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes). This works the same as the class name, so for example `@attr pathName` will be `path-name` in HTML, `@attr srcURL` will be `src-url` in HTML.\n - An `@attr` property automatically casts based on the initial value - if the initial value is a `string`, `boolean`, or `number` - it will never be `null` or `undefined`. No more null checking!\n - It is automatically synced with the HTML attribute. This means setting the class property will update the HTML attribute, and setting the HTML attribute will update the class property!\n - Assigning a value in the class description will make that value the _default_ value so if the HTML attribute isn't set, or is set but later removed the _default_ value will apply.\n\nThis behaves similarly to existing HTML elements where the class field is synced with the html attribute, for example the `` element's `type` field:\n\n```ts\nconst input = document.createElement('input')\nconsole.assert(input.type === 'text') // default value\nconsole.assert(input.hasAttribute('type') === false) // no attribute to override\ninput.setAttribute('type', 'number')\nconsole.assert(input.type === 'number') // overrides based on attribute\ninput.removeAttribute('type')\nconsole.assert(input.type === 'text') // back to default value\n```\n\n{% capture callout %} \nAn important part of `@attr`s is that they _must_ comprise of two words, so that they get a dash when serialised to HTML. This is intentional, to avoid conflicting with [built-in global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes). To see how JavaScript property names convert to HTML dasherized names, try typing the name of an `@attr` below:\n{% endcapture %}{% include callout.md %}\n\n
\n \n \n \n \n
\n\nTo use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching dasherized HTML attribute.\n\n### Example\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr fooBar = 'hello'\n}\n```\n\nThis is somewhat equivalent to:\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n get fooBar(): string {\n return this.getAttribute('foo-bar') || ''\n }\n\n set fooBar(value: string): void {\n return this.setAttribute('foo-bar', value)\n }\n\n connectedCallback() {\n if (!this.hasAttribute('foo-bar')) this.fooBar = 'Hello'\n }\n\n}\n```\n\n### Attribute Types\n\nThe _type_ of an attribute is automatically inferred based on the type it is first set to. This means once a value is initially set it cannot change type; if it is set a `string` it will never be anything but a `string`. An attribute can only be one of either a `string`, `number`, or `boolean`. The types have small differences in how they behave in the DOM.\n\nBelow is a handy reference for the small differences, this is all explained in more detail below that. \n\n| Type | When `get` is called | When `set` is called |\n|:----------|----------------------|:---------------------|\n| `string` | `getAttribute` | `setAttribute` |\n| `number` | `getAttribute` | `setAttribute` |\n| `boolean` | `hasAttribute` | `toggleAttribute` |\n\n#### String Attributes\n\nIf an attribute is first set to a `string`, then it can only ever be a `string` during the lifetime of an element. The property will revert to the initial value if the attribute doesn't exist, and trying to set it to something that isn't a string will turn it into one before assignment.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr fooBar = 'Hello'\n\n connectedCallback() {\n console.assert(this.fooBar === 'Hello')\n this.fooBar = 'Goodbye'\n console.assert(this.fooBar === 'Goodbye'')\n console.assert(this.getAttribute('foo-bar') === 'Goodbye')\n\n this.removeAttribute('foo-bar')\n // If the attribute doesn't exist, it'll output the initial value!\n console.assert(this.fooBar === 'Hello') \n }\n}\n```\n\n#### Boolean Attributes\n\nIf an attribute is first set to a boolean, then it can only ever be a boolean during the lifetime of an element. Boolean properties check for _presence_ of an attribute, sort of like how [`required`, `disabled` & `readonly` attributes work on forms](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes) The property will return `false` if the attribute doesn't exist, and `true` if it does, regardless of the value. If the property is set to `false` then `removeAttribute` is called, whereas `setAttribute(name, '')` is called when setting to a truthy value.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr fooBar = false\n\n connectedCallback() {\n console.assert(this.hasAttribute('foo-bar') === false)\n this.fooBar = true\n console.assert(this.hasAttribute('foo-bar') === true)\n this.setAttribute('foo-bar', 'this value doesnt matter!')\n console.assert(this.fooBar === true)\n }\n}\n```\n\n#### Number Attributes\n\nIf an attribute is first set to a number, then it can only ever be a number during the lifetime of an element. This is sort of like the [`maxlength` attribute on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength). The property will return the initial value if the attribute doesn't exist, and will be coerced to `Number` if it does - this means it is _possible_ to get back `NaN`. Negative numbers and floats are also valid.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr fooBar = 1\n\n connectedCallback() {\n this.fooBar = 2\n console.assert(this.getAttribute('foo-bar') === '2')\n this.setAttribute('foo-bar', 'not a number')\n console.assert(Number.isNaN(this.fooBar))\n this.fooBar = -3.14\n console.assert(this.getAttribute('foo-bar') === '-3.14')\n }\n}\n```\n\n### Default Values\n\nWhen an element gets connected to the DOM, the attr is initialized. During this phase Catalyst will determine if the default value should be applied. The default value is defined in the class property. The basic rules are as such:\n\n - If the class property has a value, that is the _default_\n - When connected, if the element _does not_ have a matching attribute, the _default is_ applied.\n - When connected, if the element _does_ have a matching attribute, the default _is not_ applied, the property will be assigned to the value of the attribute instead.\n\n{% capture callout %}\nRemember! The values defined in the class field are the _default_. They won't be set if the element is created and its attribute set to a custom value!\n{% endcapture %}{% include callout.md %}\n\nThe following example illustrates this behavior:\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr dataName = 'World'\n connectedCallback() {\n this.textContent = `Hello ${this.dataName}`\n }\n}\n```\n\n\n\n```html\n\n// This will render `Hello World`\n\n\n// This will render `Hello Catalyst`\n\n\n// This will render `Hello `\n```\n\n### Advanced usage\n\n#### Determining when an @attr changes value\n\nTo be notified when an `@attr` changes value, you can use the decorator over\n\"setter\" method instead, and the method will be called with the new value\nwhenever it is re-assigned, either through HTML or JavaScript:\n\n```typescript\nimport { controller, attr } from \"@github/catalyst\"\n@controller\nclass HelloWorldElement extends HTMLElement {\n\n @attr get dataName() {\n return 'World' // Used to get the intial value\n }\n // Called whenever `name` changes\n set dataName(newValue: string) {\n this.textContent = `Hello ${newValue}`\n }\n}\n```\n\n### What about without Decorators?\n\nIf you're not using decorators, then the `@attr` decorator has an escape hatch: You can define a static class field using the `[attr.static]` computed property, as an array of key names. Like so:\n\n```js\nimport {controller, attr} from '@github/catalyst'\n\ncontroller(\nclass HelloWorldElement extends HTMLElement {\n // Same as @attr fooBar\n [attr.static] = ['fooBar']\n\n // Field can still be defined\n fooBar = 1\n}\n)\n```\n\nThis example is functionally identical to:\n\n```js\nimport {controller, attr} from '@github/catalyst'\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr fooBar = 1\n}\n```\n\n" }, { "path": "docs/_guide/attrs.md", "content": "---\nversion: 1\nchapter: 6\ntitle: Attrs\nsubtitle: Using attributes as configuration\n---\n\nComponents may sometimes manage state, or configuration. We encourage the use of DOM as state, rather than maintaining a separate state. One way to maintain state in the DOM is via [Attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).\n\nAs Catalyst elements are really just Web Components, they have the `hasAttribute`, `getAttribute`, `setAttribute`, `toggleAttribute`, and `removeAttribute` set of methods available, as well as [`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset), but these can be a little tedious to use; requiring null checking code with each call.\n\nCatalyst includes the `@attr` decorator, which provides nice syntax sugar to simplify, standardise, and encourage use of attributes. `@attr` has the following benefits over the basic `*Attribute` methods:\n\n - It maps whatever the property name is to `data-*`, [similar to how `dataset` does](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset#name_conversion), but with more intuitive naming (e.g. `URL` maps to `data-url` not `data--u-r-l`).\n - An `@attr` property is limited to `string`, `boolean`, or `number`, it will never be `null` or `undefined` - instead it has an \"empty\" value. No more null checking!\n - The attribute name is automatically [observed, meaning `attributeChangedCallback` will fire when it changes](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks).\n - Assigning a value in the class description will make that value the _default_ value, so when the element is connected that value is set (unless the element has the attribute defined already).\n\nTo use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching `data-*` attribute.\n\n### Example\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr foo = 'hello'\n}\n```\n\nThis is the equivalent to:\n\n```js\nimport { controller } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n get foo(): string {\n return this.getAttribute('data-foo') || ''\n }\n\n set foo(value: string): void {\n return this.setAttribute('data-foo', value)\n }\n\n connectedCallback() {\n if (!this.hasAttribute('data-foo')) this.foo = 'Hello'\n }\n\n static observedAttributes = ['data-foo']\n}\n```\n\n### Attribute Types\n\nThe _type_ of an attribute is automatically inferred based on the type it is first set to. This means once a value is set it cannot change type; if it is set a `string` it will never be anything but a `string`. An attribute can only be one of either a `string`, `number`, or `boolean`. The types have small differences in how they behave in the DOM.\n\nBelow is a handy reference for the small differences, this is all explained in more detail below that. \n\n| Type | \"Empty\" value | When `get` is called | When `set` is called |\n|:----------|:--------------|----------------------|:---------------------|\n| `string` | `''` | `getAttribute` | `setAttribute` |\n| `number` | `0` | `getAttribute` | `setAttribute` |\n| `boolean` | `false` | `hasAttribute` | `toggleAttribute` |\n\n#### String Attributes\n\nIf an attribute is first set to a `string`, then it can only ever be a `string` during the lifetime of an element. The property will return an empty string (`''`) if the attribute doesn't exist, and trying to set it to something that isn't a string will turn it into one before assignment.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr foo = 'Hello'\n\n connectedCallback() {\n console.assert(this.foo === 'Hello')\n this.foo = null // TypeScript won't like this!\n console.assert(this.foo === 'null')\n delete this.dataset.foo // Removes the attribute\n console.assert(this.foo === '') // If the attribute doesn't exist, its an empty string!\n }\n}\n```\n\n#### Boolean Attributes\n\nIf an attribute is first set to a boolean, then it can only ever be a boolean during the lifetime of an element. Boolean properties check for _presence_ of an attribute, sort of like how [`required`, `disabled` & `readonly` attributes work on forms](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes) The property will return `false` if the attribute doesn't exist, and `true` if it does, regardless of the value. If the property is set to `false` then `removeAttribute` is called, whereas `setAttribute(name, '')` is called when setting to a truthy value.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr foo = false\n\n connectedCallback() {\n console.assert(this.hasAttribute('data-foo') === false)\n this.foo = true\n console.assert(this.hasAttribute('data-foo') === true)\n this.setAttribute('data-foo', 'this value doesnt matter!')\n console.assert(this.foo === true)\n }\n}\n```\n\n#### Number Attributes\n\nIf an attribute is first set to a number, then it can only ever be a number during the lifetime of an element. This is sort of like the [`maxlength` attribute on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength). The property will return `0` if the attribute doesn't exist, and will be coerced to `Number` if it does - this means it is _possible_ to get back `NaN`. Negative numbers and floats are also valid.\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr foo = 1\n\n connectedCallback() {\n console.assert(this.getAttribute('data-foo') === '1')\n this.setAttribute('data-foo', 'not a number')\n console.assert(Number.isNaN(this.foo))\n this.foo = -3.14\n console.assert(this.getAttribute('data-foo') === '-3.14')\n }\n}\n```\n\n### Default Values\n\nWhen an element gets connected to the DOM, the attr is initialized. During this phase Catalyst will determine if the default value should be applied. The default value is defined in the class property. The basic rules are as such:\n\n - If the class property has a value, that is the _default_\n - When connected, if the element _does not_ have a matching attribute, the default _is_ applied.\n - When connected, if the element _does_ have a matching attribute, the default _is not_ applied, the property will be assigned to the value of the attribute instead.\n\n{% capture callout %}\nRemember! The values defined in the class field are the _default_. They won't be set if the element is created and its attribute set to a custom value!\n{% endcapture %}{% include callout.md %}\n\nThe following example illustrates this behavior:\n\n\n\n```js\nimport { controller, attr } from \"@github/catalyst\"\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr name = 'World'\n connectedCallback() {\n this.textContent = `Hello ${this.name}`\n }\n}\n```\n\n\n\n```html\n\n// This will render `Hello World`\n\n\n// This will render `Hello Catalyst`\n\n\n// This will render `Hello `\n```\n\n### What about without Decorators?\n\nIf you're not using decorators, then you won't be able to use the `@attr` decorator, but there is still a way to achieve the same result. Under the hood `@attr` simply tags a field, but `initializeAttrs` and `defineObservedAttributes` do all of the logic.\n\nCalling `initializeAttrs` in your connected callback, with the list of properties you'd like to initialize, and calling `defineObservedAttributes` with the class, can achieve the same result as `@attr`. The class fields can still be defined in your class, and they'll be overridden as described above. For example:\n\n```js\nimport {initializeAttrs, defineObservedAttributes} from '@github/catalyst'\n\nclass HelloWorldElement extends HTMLElement {\n foo = 1\n\n connectedCallback() {\n initializeAttrs(this, ['foo'])\n }\n\n}\ndefineObservedAttributes(HelloWorldElement, ['foo'])\n```\n\nThis example is functionally identical to:\n\n```js\nimport {controller, attr} from '@github/catalyst'\n\n@controller\nclass HelloWorldElement extends HTMLElement {\n @attr foo = 1\n}\n```\n" }, { "path": "docs/_guide/conventions-2.md", "content": "---\nversion: 2\nchapter: 13\ntitle: Conventions\nsubtitle: Common naming and patterns\npermalink: /guide-v2/conventions\n---\n\nCatalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code:\n\n### Suffix your controllers consistently, for symmetry\n\nCatalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that framework.\n\n```typescript\n@controller\nclass UserListElement extends HTMLElement {} // ``\n```\n\n```typescript\n@controller\nclass UserListComponent extends HTMLElement {} // ``\n```\n\n### The best class-names are two word descriptions\n\nCustom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of at least two CamelCased words. The element name should describe what it does succinctly in two words. Some examples:\n\n - `theme-picker` (`class ThemePickerElement`)\n - `markdown-toolbar` (`class MarkdownToolbarElement`)\n - `user-list` (`class UserListElement`)\n - `content-pager` (`class ContentPagerElement`)\n - `image-gallery` (`class ImageGalleryElement`)\n\nIf you're struggling to come up with two words, think about one word being the \"what\" (what does it do?) and another being the \"how\" (how does it do it?).\n\n### Keep class-names short (but not too short)\n\nBrevity is good, element names are likely to be typed out a lot, especially throughout HTML in as tag names, and `data-target`, `data-action` attributes. A good rule of thumb is to try to keep element names down to less than 15 characters (excluding the `Element` suffix), and ideally less than 10. Also, longer words are generally harder to spell, which means mistakes might creep into your code.\n\nBe careful not to go too short! We'd recommend avoiding contracting words such as using `Img` to mean `Image`. It can create confusion, especially if there are inconsistencies across your code!\n\n### Method names should describe what they do\n\nA good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given most names, you should avoid names that conflict with existing methods on the `HTMLElement` prototype (more on that in [anti-patterns]({{ site.baseurl }}/guide/anti-patterns#avoid-shadowing-method-names)). Names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask \"how\" and \"what\", so for example `showAdmins`, `filterUsers`, `updateURL`.\n\n### `@target` should use singular naming, while `@targets` should use plural\n\nTo help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).\n\n" }, { "path": "docs/_guide/conventions.md", "content": "---\nversion: 1\nchapter: 9\ntitle: Conventions\nsubtitle: Common naming and patterns\n---\n\nCatalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code:\n\n### Use `Element` to suffix your controller class\n\nBuilt in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components should be no different, they should behave as closely to the built-ins as possible.\n\n```typescript\n@controller\nclass UserListElement extends HTMLElement {}\n```\n\n### The best class-names are two word descriptions\n\nCustom elements are required to have a `-` inside the tag name. Catalyst's `@controller` will derive the tag name from the class name - and so as such the class name needs to have at least two capital letters, or to put it another way, it needs to consist of at least two CamelCased words. The element name should describe what it does succinctly in two words. Some examples:\n\n - `theme-picker` (`class ThemePickerElement`)\n - `markdown-toolbar` (`class MarkdownToolbarElement`)\n - `user-list` (`class UserListElement`)\n - `content-pager` (`class ContentPagerElement`)\n - `image-gallery` (`class ImageGalleryElement`)\n\nIf you're struggling to come up with two words, think about one word being the \"what\" (what does it do?) and another being the \"how\" (how does it do it?).\n\n### Keep class-names short (but not too short)\n\nBrevity is good, element names are likely to be typed out a lot, especially throughout HTML in as tag names, and `data-target`, `data-action` attributes. A good rule of thumb is to try to keep element names down to less than 15 characters (excluding the `Element` suffix), and ideally less than 10. Also, longer words are generally harder to spell, which means mistakes might creep into your code.\n\nBe careful not to go too short! We'd recommend avoiding contracting words such as using `Img` to mean `Image`. It can create confusion, especially if there are inconsistencies across your code!\n\n### Method names should describe what they do\n\nA good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given most names, you should avoid names that conflict with existing methods on the `HTMLElement` prototype (more on that in [anti-patterns]({{ site.baseurl }}/guide/anti-patterns#avoid-shadowing-method-names)). Names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask \"how\" and \"what\", so for example `showAdmins`, `filterUsers`, `updateURL`.\n\n### `@target` should use singular naming, while `@targets` should use plural\n\nTo help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).\n" }, { "path": "docs/_guide/create-ability.md", "content": "---\nversion: 2\nchapter: 9\ntitle: Create Ability\nsubtitle: Create your own abilities\npermalink: /guide-v2/create-ability\n---\n\nCatalyst provides the functionality to create your own abilities, with a few helper methods and a `controllable` base-level ability. These are explained in detail below, but for a quick summary they are:\n\n - `createAbility` - a helper function to make new abilities (class decorators).\n - `createMark` - a helper function to generate class field & method decorators.\n - `tag-observer` - a set of helper functions to watch for tagged children in an element's subtree.\n - `controllable` - the base ability which allows interacting with semi-private parts of an element.\n\n## createAbility\n\nThis function allows you to make your own [Ability]({{ site.baseurl }}/guide/abilities). Abilities are really Class Decorators, but there's a couple of things that `createAbility` provides to simplify the ergonomics of Class Decorators:\n\n - TypeScript can be a little tricky when working with Class Decorators. `createAbility` simplifies this a bit.\n - JavaScript does not copy over the `name` property when extending a class (e.g. via a decorator), and it can be a little cumbersome to do this, so `createAbility` does this for you.\n - Abilities are [idempotent](https://en.wikipedia.org/wiki/Idempotence). Class decorators are not idempotent by default, which means applying a decorator multiple times can cause issues. `createAbility` mitigates this by memoizing the classes it has applied to, meaning applying an ability multiple times has no effect past the first application.\n\nThe above three features of `createAbility` make it really useful when creating mixins for web components, and makes them much easier for developers as they can trust an ability to not be sensitive to these problems.\n\nTo create an ability, call the `createAbility` method and pass in a callback function which takes a `CustomElementClass` and returns a new class. You can also provide extra types if your returned class adds new methods or fields. Here's an example, using TypeScript:\n\n\n```typescript\nimport type {CustomElementClass} from '@github/catalyst'\nimport {createAbility} from '@github/catalyst'\n\n// by convention, abilities end in \"able\"\ninterface Fooable {\n foo(): void // This interface has additional methods on top of `CustomElementClass`!\n}\n\n// Fooable: automatically calls `foo()` on `connectedCallback`\nexport const fooable = createAbility(\n // ↓ Notice the `& { new (): Fooable }`\n (Class: T): T & { new (): Fooable } =>\n class extends Class {\n connectedCallback() {\n this.foo()\n }\n\n foo() {\n console.log('Foo was called!')\n }\n }\n)\n```\n\nInside the `class extends Class` block, you can author custom element logic that you might want to make reusable across a multitude of elements. You can also adjust the input type to subclass `CustomElementClass`, which can be useful for setting up a contract between your Ability and the classes that rely on it:\n\n```typescript\nimport type {CustomElementClass} from '@github/catalyst'\nimport {createAbility} from '@github/catalyst'\n\n// by convention, abilities end in \"able\"\ninterface Fooable {\n foo(): void // This interface has additional methods on top of `CustomElementClass`!\n}\n\ninterface FooableClass {\n new(...args: any[]): Fooable\n}\n\n// Fooable: automatically calls `foo()` on `connectedCallback`\nexport const fooable = createAbility(\n // ↓ Notice the `& FooableClass`\n (Class: T): T =>\n class extends Class {\n // TypeScript will expect the constructor to be defined for a mixin\n constructor(...args: any[]) {\n super(...args)\n }\n\n connectedCallback() {\n // Classes that apply this ability _must_ implement `foo()`.\n super.foo()\n }\n }\n```\n\nIf you're interested in some advanced examples, you can take a look at the Catalyst source code - every feature of Catalyst is an Ability!\n\n## createMark\n\nThis function allows you to make annotations for fields (like `@attr` and `@target`). Marks are really Field/Method Decorators, but with simpler ergonomics:\n\n - Marks are only initialized on instances, which makes them easier to reason about.\n - Marks are not configurable, which keeps them simple.\n - They are built to ease a transition between TypeScript decorators and ECMAScript decorators, which will help as decorators become standardised.\n\n`createMark` can be called with a `validate` and an `init` function, and gives back a tuple of 3 functions: the decorator itself, a function to get a list of marks that an instance has, and a function that will initialise the marks on an instance. It can be used like so:\n\n```typescript\n\n// Makes the @prop decorator\nconst [prop, getProps, initProps] = createMark(\n ({name, kind}) => {\n // Validate the name and kind that a mark can have.\n // Name will be the PropertyKey that was decorated, and `kind` will be one of:\n // \"method\", \"field\", \"getter\", \"setter\".\n if (kind === \"method\") {\n throw new Error(`@prop cannot be used to mark a method`)\n }\n },\n (instance: CustomElement, {name, kind, access}) => {\n // Put field initialization logic here.\n // Return a property descriptor to define a field's functionality:\n let value = kind === 'field' ? access.value : access.get?.call(instance)\n return {\n get() { return value }\n set(newValue) {\n value = newValue\n instance.propChanged(name, newValue)\n }\n }\n }\n)\n```\n\nIf you want to find some examples of how marks work, take a look at the Catalyst source code! All field decorators (`@attr`, `@target`, `@provide`, `@consume` and so on) use `createMark`.\n\n## tag-observer\n\nTag Observer provides a set of functions to observe elements marked with well-known attributes across the DOM, allowing classes to be reactive to DOM mutations. These functions operate over a `MutationObserver` set up to detect new elements coming into the page that have a registered attribute. To call register a new tag you can use the `registerTag` function which takes an attribute name to observe, a parse function (that parses the attribute value), and a found function (which is called for each element that has the attribute):\n\n```typescript\nregisterTag(\n `data-foo`,\n (value: string) => value.split('.'),\n (el: Element, controller: Element | ShadowRoot, ...meta: string[]) => {\n // ...\n }\n)\n```\n\nTag Observer also provides a `observeElementForTags` function, which can be called on an element to adopt it into observation. A good place to use this is in your Abilities `connectedCallback`. This function can also take a `shadowRoot` if you're interested in observing tags within the shadow DOM (recommended). This function will find the root element (`ownerDocument`) and begin observing it.\n\n```typescript\nexport const fooable = createAbility(\n (Class: T): T =>\n class extends Class {\n connectedCallback() {\n observeElementForTags(this) // This elements ownerDocument will now look out for new tags\n }\n }\n```\n\nWhenever an element appears on the page with the matching attribute (e.g. `data-foo`), the value is extracted, split by whitespace, and each substring is then given to `parse` to turn into an array of strings. The first value in the array that the parse function returns must be a parent selector, which is then used to find the controller this attribute could pertain to. If the element is a child of the given controller selector, then the found function is called with the element, the controller, and any additional metadata that the parse function extracted. Let's see an example for how this might work, given the above registered tag:\n\n```html\n\n
\n\n```\n\n- Our `data-foo` attribute is found in the DOM, belonging to the `div` element.\n- The value is extracted and split by whitespace.\n- Our parse function gets called twice, firstly with `my-element.foo.bar`\n - The parse function splits this by `.` which gets us `['my-element', 'foo', 'bar']`.\n - Tag observer uses `my-element` as the parent selector and calls `div.closest('my-element')`,\n - The `` controller is found.\n - Our found function is called with `(
, , ['foo', 'bar'])`\n- The parse function is also called with `other-element.baz.bing`.\n - The parse function splits this by `.` which gets us `['other-element', 'baz', 'bing']`.\n - Tag observer uses `other-element` as the parent selector and calls `div.closest('other-element')`,\n - No parent element is found, so the found function is not called.\n\nTo take a look at how Tag Observer is used in Catalyst, you can look at [`data-action` (the Actionable ability)]({{ site.baseurl }}/guide/actions) or [`data-target` & `data-targets` (the Targetable ability)]({{ site.baseurl }}/guide/targets).\n\n## controllable\n\n`controllable` is a basic ability which other abilities can use to simplify connecting to a custom elements private state. This ability isn't _required_ to be used when creating your own abilities, but it's very useful for abilities which expect to use either the [ShadowDOM](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) or [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals).\n\nYou can create an ability that itself uses the `controllable` ability like so:\n\n```typescript\nimport type {CustomElementClass} from '@github/catalyst'\nimport {createAbility, controllable} from '@github/catalyst'\n\ncreateAbility((Class: CustomElementClass) => class extends controllable(Class) {\n // Your behaviour goes here!\n}\n```\n\nThe `controllable` ability provides 2 _custom_ callbacks which allow you to safely & robustly intercept the attachment of a ShadowRoot, and the attachment of ElementInternals. Let's look at each:\n\n### `[attachShadowCallback](shadowRoot: ShadowRoot)`\n\n```typescript\nimport type {CustomElementClass} from '@github/catalyst'\nimport {createAbility, attachShadowCallback, controllable} from '@github/catalyst'\n\ncreateAbility((Class: CustomElementClass) => class extends controllable(Class) {\n [attachShadowCallback](shadowRoot: ShadowRoot) {\n super[attachShadowCallback](shadowRoot)\n // Do stuff with the `shadowRoot`.\n }\n}\n```\n\n`attachShadowCallback` is a special `Symbol()` which allows you to make a method mostly hidden from other classes. `controllable` will call this symbol method whenever a ShadowRoot is attached to the element, which can be attached in 2 different ways:\n\n - During the constructor, where the element might recieve a declarative ShadowDOM root (closed or open).\n - Any time the `attachShadow()` function is called.\n\nThis method is _usually_ called zero or once, but may be called twice if the element recieves a Declarative ShadowDOM root, and overrides this with another call to `attachShadow()`.\n\nSimply overriding `this.attachShadow` or trying to access `this.shadowRoot` can be a little tricky (if an element has a closed declarative shadow root this can be especially difficult to access within mixins), so this callback can be especially useful for working around the various ways a shadowRoot can be created.\n\n### `[attachInternalsCallback](internals: ElementInternals)`\n\n```typescript\nimport type {CustomElementClass} from '@github/catalyst'\nimport {createAbility, attachInternalsCallback, controllable} from '@github/catalyst'\n\ncreateAbility((Class: CustomElementClass) => class extends controllable(Class) {\n [attachInternalsCallback](internals: ElementInternals) {\n super[attachInternalsCallback](internals)\n // Do stuff with the `internals`.\n }\n}\n```\n\n`attachInternalsCallback` is a special `Symbol()` which allows you to make a method mostly hidden from other classes. `controllable` will call this symbol method whenever an element is constructed, giving it the element's `ElementInternals`. This enables custom enablies [Abilities]({{ site.baseurl }}/guide/abilities) to also have access to `ElementInternals`. It does so while also preserving the ability for `attachInternals()` to be called again (usually `attachInternals()` will error if called twice).\n\nIf you need access to the internals, then the `attachInternalsCallback` can be very useful as it protects you from calling `attachInternals` in a way which the concrete classes will then fail.\n" }, { "path": "docs/_guide/decorators-2.md", "content": "---\nversion: 2\nchapter: 3\ntitle: Decorators\nsubtitle: Using TypeScript for ergonomics\npermalink: /guide-v2/decorators\n---\n\nDecorators 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)).\n\nYou can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:\n\nDecorators can be used three ways:\n\n### Class Decorators\n\nCatalyst comes with the `@controller` decorator. This gets put on top of the class, like so:\n\n```js\n@controller\nclass HelloWorldElement extends HTMLElement {}\n```\n\n### Class Field Decorators\n\nCatalyst 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:\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @target something\n \n // Alternative style\n @targets\n others\n\n}\n```\n
\n\nClass 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.\n\n### Method Decorators\n\nMethod decorators work just like Field Decorators. Put them on top or on the left of the method, like so:\n\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @log\n submit() {\n // ...\n }\n\n // Alternative style\n\n @log load() {\n // ...\n }\n\n}\n```\n\n### Getter/Setter \n\nDecorators 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:\n\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @target set something() {\n // ...\n }\n\n // Can be used over just one field\n @attr get data() {\n return {}\n }\n set data() {\n\n }\n}\n```\n\n### Supporting `strictPropertyInitialization`\n\nTypeScript 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:\n\n1. 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:\n\n ```typescript\n class HelloWorldElement extends HTMLElement {\n @target declare something: HTMLElement\n @targets declare items: HTMLElement[]\n }\n ```\n \n 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.\n\n2. You can also disable the compiler option (other strict mode rules can still apply) in your `tsconfig.json` like so:\n\n ```json\n {\n \"compilerOptions\": {\n \"strict\": true,\n \"strictPropertyInitialization\": false\n }\n }\n ```\n\n### Function Calling Decorators\n\nYou 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.\n\nCatalyst 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:\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @debounce(100)\n handleInput() {\n // ...\n }\n\n}\n```\n
\n" }, { "path": "docs/_guide/decorators.md", "content": "---\nversion: 1\nchapter: 3\ntitle: Decorators\nsubtitle: Using TypeScript for ergonomics\n---\n\nDecorators 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)).\n\nYou can read more about [decorators in the TypeScript handbook](https://www.typescriptlang.org/docs/handbook/decorators.html), but here's quick guide:\n\nDecorators can be used three ways:\n\n### Class Decorators\n\nCatalyst comes with the `@controller` decorator. This gets put on top of the class, like so:\n\n```js\n@controller\nclass HelloWorldElement extends HTMLElement {}\n```\n\n### Class Field Decorators\n\nCatalyst 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:\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @target something\n \n // Alternative style\n @targets\n others\n\n}\n```\n
\n\nClass 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.\n\n### Method Decorators\n\nMethod decorators work just like Field Decorators. Put them on top or on the left of the method, like so:\n\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @log\n submit() {\n // ...\n }\n\n // Alternative style\n\n @log load() {\n // ...\n }\n\n}\n```\n\n### Getter/Setter \n\nDecorators 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:\n\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @target set something() {\n // ...\n }\n\n // Can be used over just one field\n @attr get data() {\n return {}\n }\n set data() {\n\n }\n}\n```\n\n### Supporting `strictPropertyInitialization`\n\nTypeScript 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:\n\n1. 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:\n\n ```typescript\n class HelloWorldElement extends HTMLElement {\n @target declare something: HTMLElement\n @targets declare items: HTMLElement[]\n }\n ```\n \n 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.\n\n2. You can also disable the compiler option (other strict mode rules can still apply) in your `tsconfig.json` like so:\n\n ```json\n {\n \"compilerOptions\": {\n \"strict\": true,\n \"strictPropertyInitialization\": false\n }\n }\n ```\n\n### Function Calling Decorators\n\nYou 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.\n\nCatalyst 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:\n\n```js\nclass HelloWorldElement extends HTMLElement {\n\n @debounce(100)\n handleInput() {\n // ...\n }\n\n}\n```\n
\n" }, { "path": "docs/_guide/introduction-2.md", "content": "---\nversion: 2\nchapter: 1\ntitle: Introduction\nsubtitle: Origins & Concepts\npermalink: /guide-v2/introduction\n---\n\nCatalyst is a set of patterns and techniques for developing _components_ within a complex application. At its core, Catalyst simply provides a small library of functions to make developing [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) easier. The library is an implementation detail, though. The concepts are what we're most interested in.\n\n## How did we get here?\n\nGitHub's first page interactions were written using jQuery, which was widely used at the time. Eventually, as browser compatibility increased and jQuery patterns such as the Selector Pattern & easy class manipulation became standard, [GitHub moved away from jQuery](https://github.blog/2018-09-06-removing-jquery-from-github-frontend/).\n\nRather than moving to entirely new paradigms, GitHub continued to use the same concepts within jQuery. Event Delegation was still heavily used, as well as querySelector. The event delegation concept was also extended to \"element delegation\" - discovering when Elements were added to the DOM, using the [Selector Observer](https://github.com/josh/selector-observer) library.\n\nThese patterns were reduced to first principles: _Observing_ elements on the page, _listening_ to the events these elements or their children emit, and _querying_ the children of an element to mutate or extend them.\n\nThe Web Systems team at GitHub explored other tools that adopt these set of patterns and principles. The closest match to those goals was [Stimulus](https://stimulusjs.org/) (from which Catalyst is heavily inspired), but ultimately the desire to leverage technology that engineers at GitHub were already familiar with was the motivation to create Catalyst.\n\n## Three core concepts: Observe, Listen, Query\n\nCatalyst takes these three core concepts and delivers them in the lightest possible way they can be delivered.\n\n - **Observability** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Your First Component]({{ site.baseurl }}/guide/your-first-component).\n\n - **Listening** Event Delegation makes a great deal of sense when observing events \"high up the tree\" - registering global event listeners on the Window element - but Custom Elements sit much closer to their children within the tree, and so Direct Event binding is preferred. Catalyst solves this by binding event listeners to any descendants with `data-action` attributes. Read more about this in the Guide Section entitled [Actions]({{ site.baseurl }}/guide/actions).\n\n - **Querying** Custom Elements largely solve querying, by simply calling `querySelector` - however CSS selectors are loosely disciplined and can create unnecessary coupling to the DOM structure (e.g. by querying tag names). Catalyst extends the `data-action` concept by also using `data-target` to declare descendants that the Custom Element is interested in querying. Read more about this in the Guide Section entitled [Targets]({{ site.baseurl }}/guide/targets).\n" }, { "path": "docs/_guide/introduction.md", "content": "---\nversion: 1\nchapter: 1\ntitle: Introduction\nsubtitle: Origins & Concepts\n---\n\nCatalyst is a set of patterns and techniques for developing _components_ within a complex application. At its core, Catalyst simply provides a small library of functions to make developing [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) easier. The library is an implementation detail, though. The concepts are what we're most interested in.\n\n## How did we get here?\n\nGitHub's first page interactions were written using jQuery, which was widely used at the time. Eventually, as browser compatibility increased and jQuery patterns such as the Selector Pattern & easy class manipulation became standard, [GitHub moved away from jQuery](https://github.blog/2018-09-06-removing-jquery-from-github-frontend/).\n\nRather than moving to entirely new paradigms, GitHub continued to use the same concepts within jQuery. Event Delegation was still heavily used, as well as querySelector. The event delegation concept was also extended to \"element delegation\" - discovering when Elements were added to the DOM, using the [Selector Observer](https://github.com/josh/selector-observer) library.\n\nThese patterns were reduced to first principles: _Observing_ elements on the page, _listening_ to the events these elements or their children emit, and _querying_ the children of an element to mutate or extend them.\n\nThe Web Systems team at GitHub explored other tools that adopt these set of patterns and principles. The closest match to those goals was [Stimulus](https://stimulusjs.org/) (from which Catalyst is heavily inspired), but ultimately the desire to leverage technology that engineers at GitHub were already familiar with was the motivation to create Catalyst.\n\n## Three core concepts: Observe, Listen, Query\n\nCatalyst takes these three core concepts and delivers them in the lightest possible way they can be delivered.\n\n - **Observability** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Your First Component]({{ site.baseurl }}/guide/your-first-component).\n\n - **Listening** Event Delegation makes a great deal of sense when observing events \"high up the tree\" - registering global event listeners on the Window element - but Custom Elements sit much closer to their children within the tree, and so Direct Event binding is preferred. Catalyst solves this by binding event listeners to any descendants with `data-action` attributes. Read more about this in the Guide Section entitled [Actions]({{ site.baseurl }}/guide/actions).\n\n - **Querying** Custom Elements largely solve querying, by simply calling `querySelector` - however CSS selectors are loosely disciplined and can create unnecessary coupling to the DOM structure (e.g. by querying tag names). Catalyst extends the `data-action` concept by also using `data-target` to declare descendants that the Custom Element is interested in querying. Read more about this in the Guide Section entitled [Targets]({{ site.baseurl }}/guide/targets).\n" }, { "path": "docs/_guide/lazy-elements-2.md", "content": "---\nversion: 2\nchapter: 16\ntitle: Lazy Elements\nsubtitle: Dynamically load elements just in time\npermalink: /guide-v2/lazy-elements\n---\n\nA common practice in modern web development is to combine all JavaScript code into JS \"bundles\". By bundling the code together we avoid the network overhead of fetching each file. However the trade-off of bundling is that we might deliver JS code that will never run in the browser.\n\n![A screenshot from Chrome Devtools showing the Coverage panel. The panel has multiple request to JS assets and it shows that most of them have large chunks that are unused.](/catalyst/guide/devtools-coverage.png)\n\nAn alternative solution to bundling is to load JavaScript just in time. Downloding the JavaScript for Catalyst controllers when the browser first encounters them can be done with the `lazyDefine` function.\n\n```typescript\nimport {lazyDefine} from '@github/catalyst'\n\n// Dynamically import the Catalyst controller when the `` tag is seen.\nlazyDefine('user-avatar', () => import('./components/user-avatar'))\n```\n\nServing this file allows us to defer loading of the component code until it's actually needed by the web page. The tradeoff of deferring loading is that the elements will be inert until the dynamic import of the component code resolves. Consider what your UI might look like while these components are resolving. Consider providing a loading indicator and disabling controls as the default state. The smaller the component, the faster it will resolve which means that your users might not notice a inert state. A good rule of thumb is that a component should load within 100ms on a \"Fast 3G\" connection.\n\nGenerally we think it's a good idea to `lazyDefine` all elements and then prioritize eager loading of ciritical elements as needed. You might consider using code-generation to generate a file lazy defining all your components.\n\nBy default the component will be loaded when the element is present in the document and the document has finished loading. This can happen before sub-resources such as scripts, images, stylesheets and frames have finished loading. It is possible to defer loading even later by adding a `data-load-on` attribute on your element. The value of which must be one of the following prefefined values:\n\n- `` (default)\n\t- The element is loaded when the document has finished loading. This listens for changes to `document.readyState` and triggers when it's no longer loading.\n- `` \n\t- This element is loaded on the first user interaction with the page. This listens for `mousedown`, `touchstart`, `pointerdown` and `keydown` events on `document`.\n- ``\n\t- This element is loaded when it's close to being visible. Similar to `` . The functionality is driven by an `IntersectionObserver`.\n\nThis functionality is similar to the [\"Lazy Custom Element Definitions\" spec proposal](https://github.com/WICG/webcomponents/issues/782) and as this proposal matures we see Catalyst conforming to the spec and leveraging this new API to lazy load elements.\n" }, { "path": "docs/_guide/lazy-elements.md", "content": "---\nversion: 1\nchapter: 13\ntitle: Lazy Elements\nsubtitle: Dynamically load elements just in time\n---\n\nA common practice in modern web development is to combine all JavaScript code into JS \"bundles\". By bundling the code together we avoid the network overhead of fetching each file. However the trade-off of bundling is that we might deliver JS code that will never run in the browser.\n\n![A screenshot from Chrome Devtools showing the Coverage panel. The panel has multiple request to JS assets and it shows that most of them have large chunks that are unused.](/catalyst/guide/devtools-coverage.png)\n\nAn alternative solution to bundling is to load JavaScript just in time. Downloding the JavaScript for Catalyst controllers when the browser first encounters them can be done with the `lazyDefine` function.\n\n```typescript\nimport {lazyDefine} from '@github/catalyst'\n\n// Dynamically import the Catalyst controller when the `` tag is seen.\nlazyDefine('user-avatar', () => import('./components/user-avatar'))\n```\n\nServing this file allows us to defer loading of the component code until it's actually needed by the web page. The tradeoff of deferring loading is that the elements will be inert until the dynamic import of the component code resolves. Consider what your UI might look like while these components are resolving. Consider providing a loading indicator and disabling controls as the default state. The smaller the component, the faster it will resolve which means that your users might not notice a inert state. A good rule of thumb is that a component should load within 100ms on a \"Fast 3G\" connection.\n\nGenerally we think it's a good idea to `lazyDefine` all elements and then prioritize eager loading of ciritical elements as needed. You might consider using code-generation to generate a file lazy defining all your components.\n\nBy default the component will be loaded when the element is present in the document and the document has finished loading. This can happen before sub-resources such as scripts, images, stylesheets and frames have finished loading. It is possible to defer loading even later by adding a `data-load-on` attribute on your element. The value of which must be one of the following prefefined values:\n\n- `` (default)\n\t- The element is loaded when the document has finished loading. This listens for changes to `document.readyState` and triggers when it's no longer loading.\n- `` \n\t- This element is loaded on the first user interaction with the page. This listens for `mousedown`, `touchstart`, `pointerdown` and `keydown` events on `document`.\n- ``\n\t- This element is loaded when it's close to being visible. Similar to `` . The functionality is driven by an `IntersectionObserver`.\n\nThis functionality is similar to the [\"Lazy Custom Element Definitions\" spec proposal](https://github.com/WICG/webcomponents/issues/782) and as this proposal matures we see Catalyst conforming to the spec and leveraging this new API to lazy load elements.\n" }, { "path": "docs/_guide/lifecycle-hooks-2.md", "content": "---\nversion: 2\nchapter: 10\ntitle: Lifecycle Hooks\nsubtitle: Observing the life cycle of an element\npermalink: /guide-v2/lifecycle-hooks\n---\n\nCatalyst Controllers - like many other frameworks - have several \"well known\" method names which are called periodically through the life cycle of the element, and let you observe when an element changes in various ways. Here is a comprehensive list of all life-cycle callbacks. Each one is suffixed `Callback`, to denote that it will be called by the framework.\n\n### `connectedCallback()`\n\nThe [`connectedCallback()` is part of Custom Elements][ce-callbacks], and gets fired as soon as your element is _appended_ to the DOM. This callback is a good time to initialize any variables, perhaps add some global event listeners, or start making any early network requests.\n\nJavaScript traditionally uses the `constructor()` callback to listen for class creation. While this still works for Custom Elements, it is best avoided as the element won't be in the DOM when `constructor()` is fired, limiting its utility.\n\n#### Things to remember\n\nThe `connectedCallback` is called _as soon as_ the element is attached to a `document`. This _may_ occur _before_ an element has any children appended to it, so you should be careful not expect an element to have children during a `connectedCallback` call. This means avoiding checking any `target`s or using other methods like `querySelector`. Instead use this function to initialize itself and avoid doing initialization work which depend on children existing.\n\nIf your element depends heavily on its children existing, consider adding a [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) in the `connectedCallback` to track when your elements children change.\n\n### `attributeChangedCallback()`\n\nThe [`attributeChangedCallback()` is part of Custom Elements][ce-callbacks], and gets fired when _observed attributes_ are added, changed, or removed from your element. It required you set a `static observedAttributes` array on your class, the values of which will be any attributes that will be observed for mutations. This is given a set of arguments, the signature of your function should be:\n\n```typescript\nattributeChangedCallback(name: string, oldValue: string|null, newValue: string|null): void {}\n```\n\n#### Things to remember\n\nThe `attributeChangedCallback` will fire whenever `setAttribute` is called with an observed attribute, even if the _new_ value is the same as the _old_ value. In other words, it is possible for `attributeChangedCallback` to be called when `oldValue === newValue`. In most cases this really won't matter much, and in some cases this is very helpful; but sometimes this can bite, especially if you have [non-idempotent](https://en.wikipedia.org/wiki/Idempotence#Computer_science_examples) code inside your `attributeChangedCallback`. Try to make sure operations inside `attributeChangedCallback` are idempotent, or perhaps consider adding a check to ensure `oldValue !== newValue` before performing operations which may be sensitive to this.\n\n### `disconnectedCallback()`\n\nThe [`disconnectedCallback()` is part of Custom Elements][ce-callbacks], and gets fired as soon as your element is _removed_ from the DOM. Event listeners will automatically be cleaned up, and memory will be freed automatically from JavaScript, so you're unlikely to need this callback for much.\n\n### `adoptedCallback()`\n\nThe [`adoptedCallback()` is part of Custom Elements][ce-callbacks], and gets called when your element moves from one `document` to another (such as an iframe). It's very unlikely to occur, you'll almost never need this.\n\n[ce-callbacks]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks\n" }, { "path": "docs/_guide/lifecycle-hooks.md", "content": "---\nversion: 1\nchapter: 7\ntitle: Lifecycle Hooks\nsubtitle: Observing the life cycle of an element\n---\n\nCatalyst Controllers - like many other frameworks - have several \"well known\" method names which are called periodically through the life cycle of the element, and let you observe when an element changes in various ways. Here is a comprehensive list of all life-cycle callbacks. Each one is suffixed `Callback`, to denote that it will be called by the framework.\n\n### `connectedCallback()`\n\nThe [`connectedCallback()` is part of Custom Elements][ce-callbacks], and gets fired as soon as your element is _appended_ to the DOM. This callback is a good time to initialize any variables, perhaps add some global event listeners, or start making any early network requests.\n\nJavaScript traditionally uses the `constructor()` callback to listen for class creation. While this still works for Custom Elements, it is best avoided as the element won't be in the DOM when `constructor()` is fired, limiting its utility.\n\n#### Things to remember\n\nThe `connectedCallback` is called _as soon as_ the element is attached to a `document`. This _may_ occur _before_ an element has any children appended to it, so you should be careful not expect an element to have children during a `connectedCallback` call. This means avoiding checking any `target`s or using other methods like `querySelector`. Instead use this function to initialize itself and avoid doing initialization work which depend on children existing.\n\nIf your element depends heavily on its children existing, consider adding a [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) in the `connectedCallback` to track when your elements children change.\n\n### `attributeChangedCallback()`\n\nThe [`attributeChangedCallback()` is part of Custom Elements][ce-callbacks], and gets fired when _observed attributes_ are added, changed, or removed from your element. It required you set a `static observedAttributes` array on your class, the values of which will be any attributes that will be observed for mutations. This is given a set of arguments, the signature of your function should be:\n\n```typescript\nattributeChangedCallback(name: string, oldValue: string|null, newValue: string|null): void {}\n```\n\n#### Things to remember\n\nThe `attributeChangedCallback` will fire whenever `setAttribute` is called with an observed attribute, even if the _new_ value is the same as the _old_ value. In other words, it is possible for `attributeChangedCallback` to be called when `oldValue === newValue`. In most cases this really won't matter much, and in some cases this is very helpful; but sometimes this can bite, especially if you have [non-idempotent](https://en.wikipedia.org/wiki/Idempotence#Computer_science_examples) code inside your `attributeChangedCallback`. Try to make sure operations inside `attributeChangedCallback` are idempotent, or perhaps consider adding a check to ensure `oldValue !== newValue` before performing operations which may be sensitive to this.\n\n### `disconnectedCallback()`\n\nThe [`disconnectedCallback()` is part of Custom Elements][ce-callbacks], and gets fired as soon as your element is _removed_ from the DOM. Event listeners will automatically be cleaned up, and memory will be freed automatically from JavaScript, so you're unlikely to need this callback for much.\n\n### `adoptedCallback()`\n\nThe [`adoptedCallback()` is part of Custom Elements][ce-callbacks], and gets called when your element moves from one `document` to another (such as an iframe). It's very unlikely to occur, you'll almost never need this.\n\n[ce-callbacks]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks\n" }, { "path": "docs/_guide/patterns-2.md", "content": "---\nversion: 2\nchapter: 14\ntitle: Patterns\nsubtitle: Best Practices for behaviours\npermalink: /guide-v2/patterns\n---\n\nAn aim of Catalyst is to be as light weight as possible, and so we often avoid including helper functions for otherwise fine code. We also want to keep Catalyst focussed, and so where some helper functions might be reasonable, we recommend judicious use of other small libraries.\n\nHere are a few common patterns which we've avoided introducing into the Catalyst code base, and instead encourage you to take the example code and run with that:\n\n### Debouncing or Throttling events\n\nOften times you'll want to do something computationally intensive (or network intensive) based on a user event. It's worth throttling the amount of times a function can be called for these events, to prevent saturation of the CPU or network. For this we can use the \"debounce\" or \"throttle\" patterns. We recommend using the [`@github/mini-throttle`](https://github.com/github/mini-throttle) library for this, which provides throttling decorators for methods:\n\n```typescript\nimport {controller} from '@github/catalyst'\nimport {debounce} from '@github/mini-throttle/decorators'\n\n@controller\nclass FuzzySearchElement extends HTMLElement {\n\n // Adding `@debounce(100)` here means this method will only be called once in a 100ms period.\n @debounce(100)\n search(event: Event) {\n const value = event.currentTarget.value\n // This function is very computationally intensive, so we should run it as little as possible\n this.filterAllItemsWithValue(value)\n }\n\n}\n```\n\nAlternatively, if you'd like more precise control over the exact way debouncing happens (for example you'd like to make the debounce timeout dynamic, or sometimes call _without_ debouncing), you can have two methods following the pattern of `foo`/`fooNow` or `foo`/`fooSync`, where the non-suffixed method dispatches asynchronously to the `Now`/`Sync` suffixed method, a little like this:\n\n```typescript\nimport {controller} from '@github/catalyst'\n\n@controller\nclass FuzzySearchElement extends HTMLElement {\n\n #searchAnimationFrame = 0\n search(event: Event) {\n clearAnimationFrame(this.#searchAnimationFrame)\n this.#searchAnimationFrame = requestAnimationFrame(() => this.searchNow(event: Event))\n }\n \n searchNow(event: Event) {\n const value = event.currentTarget.value\n // This function is very computationally intensive, so we should run it as little as possible\n this.filterAllItemsWithValue(value)\n }\n\n}\n```\n\n### Aborting Network Requests\n\nWhen making network requests using `fetch`, based on user input, you can cancel old requests as new ones come in. This is useful for performance as well as UI responsiveness, as old requests that aren't cancelled might complete later than newer ones, and causing the UI to jump around. Aborting network requests requires you to use [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) (a web platform feature).\n\n```typescript\n@controller\nclass RemoveSearchElement extends HTMLElement {\n\n #remoteSearchController: AbortController|null\n\n async search(event: Event) {\n // Abort the old Request\n this.#remoteSearchController?.abort()\n\n // To start making a new request, construct an AbortController\n const {signal} = (this.#remoteSearchController = new AbortController())\n\n try {\n const res = await fetch(myUrl, {signal})\n\n // ... Add logic here with the completed network response\n } catch (e) {\n\n // ... Add logic here if you need to report a failed network request.\n // Do not rethrow for network errors!\n\n }\n\n if (signal.aborted) {\n // Here you can add logic for if the request was cancelled, but\n // usually what you want to do is just return early to avoid\n // cleaning up the loading UI (bear in mind if the request is\n // cancelled then another one will be in its place).\n return\n }\n\n // ... Add cleanup logic here, such as removing `loading` classes.\n\n }\n}\n```\n\n### Registering global or many event listeners\n\nGenerally speaking, you'll want to use [\"Actions\"]({{ site.baseurl }}/guide/actions) to register event listeners with your Controller, but Actions only work for components nested within your Controller. It may also be necessary to listen for events on the Document, Window, or across well-known adjacent elements. We can manually call `addEventListener` for these types, including during the `connectedCallback` phase. Cleanup for `addEventListener` can be a bit error prone, but [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) can be useful here to pass a signal that the element is cleaning up. AbortControllers should be created once per `connectedCallback`, as they are not re-usable, while Controllers _can_ be reused.\n\n\n```typescript\n@controller\nclass UnsavedChangesElement extends HTMLElement {\n\n #eventAbortController: AbortController|null = null\n\n connectedCallback(event: Event) {\n // Create the new AbortController and get the new signal\n const {signal} = (this.#eventAbortController = new AbortController())\n \n // You can `signal` as an option to any `addEventListener` call:\n window.addEventListener('hashchange', this, { signal })\n window.addEventListener('blur', this, { signal })\n window.addEventListener('popstate', this, { signal })\n window.addEventListener('pagehide', this, { signal })\n }\n \n disconnectedCallback() {\n // This will clean up any `addEventListener` calls which were given the `signal`\n this.#eventAbortController?.abort()\n }\n \n handleEvent(event) {\n // `handleEvent` will be called when each one of the event listeners\n // defined in `connectedCallback` is dispatched.\n }\n}\n```\n" }, { "path": "docs/_guide/patterns.md", "content": "---\nversion: 1\nchapter: 10\ntitle: Patterns\nsubtitle: Best Practices for behaviours\n---\n\nAn aim of Catalyst is to be as light weight as possible, and so we often avoid including helper functions for otherwise fine code. We also want to keep Catalyst focussed, and so where some helper functions might be reasonable, we recommend judicious use of other small libraries.\n\nHere are a few common patterns which we've avoided introducing into the Catalyst code base, and instead encourage you to take the example code and run with that:\n\n### Debouncing or Throttling events\n\nOften times you'll want to do something computationally intensive (or network intensive) based on a user event. It's worth throttling the amount of times a function can be called for these events, to prevent saturation of the CPU or network. For this we can use the \"debounce\" or \"throttle\" patterns. We recommend using the [`@github/mini-throttle`](https://github.com/github/mini-throttle) library for this, which provides throttling decorators for methods:\n\n```typescript\nimport {controller} from '@github/catalyst'\nimport {debounce} from '@github/mini-throttle/decorators'\n\n@controller\nclass FuzzySearchElement extends HTMLElement {\n\n // Adding `@debounce(100)` here means this method will only be called once in a 100ms period.\n @debounce(100)\n search(event: Event) {\n const value = event.currentTarget.value\n // This function is very computationally intensive, so we should run it as little as possible\n this.filterAllItemsWithValue(value)\n }\n\n}\n```\n\nAlternatively, if you'd like more precise control over the exact way debouncing happens (for example you'd like to make the debounce timeout dynamic, or sometimes call _without_ debouncing), you can have two methods following the pattern of `foo`/`fooNow` or `foo`/`fooSync`, where the non-suffixed method dispatches asynchronously to the `Now`/`Sync` suffixed method, a little like this:\n\n```typescript\nimport {controller} from '@github/catalyst'\n\n@controller\nclass FuzzySearchElement extends HTMLElement {\n\n #searchAnimationFrame = 0\n search(event: Event) {\n clearAnimationFrame(this.#searchAnimationFrame)\n this.#searchAnimationFrame = requestAnimationFrame(() => this.searchNow(event: Event))\n }\n \n searchNow(event: Event) {\n const value = event.currentTarget.value\n // This function is very computationally intensive, so we should run it as little as possible\n this.filterAllItemsWithValue(value)\n }\n\n}\n```\n\n### Aborting Network Requests\n\nWhen making network requests using `fetch`, based on user input, you can cancel old requests as new ones come in. This is useful for performance as well as UI responsiveness, as old requests that aren't cancelled might complete later than newer ones, and causing the UI to jump around. Aborting network requests requires you to use [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) (a web platform feature).\n\n```typescript\n@controller\nclass RemoveSearchElement extends HTMLElement {\n\n #remoteSearchController: AbortController|null\n\n async search(event: Event) {\n // Abort the old Request\n this.#remoteSearchController?.abort()\n\n // To start making a new request, construct an AbortController\n const {signal} = (this.#remoteSearchController = new AbortController())\n\n try {\n const res = await fetch(myUrl, {signal})\n\n // ... Add logic here with the completed network response\n } catch (e) {\n\n // ... Add logic here if you need to report a failed network request.\n // Do not rethrow for network errors!\n\n }\n\n if (signal.aborted) {\n // Here you can add logic for if the request was cancelled, but\n // usually what you want to do is just return early to avoid\n // cleaning up the loading UI (bear in mind if the request is\n // cancelled then another one will be in its place).\n return\n }\n\n // ... Add cleanup logic here, such as removing `loading` classes.\n\n }\n}\n```\n\n### Registering global or many event listeners\n\nGenerally speaking, you'll want to use [\"Actions\"]({{ site.baseurl }}/guide/actions) to register event listeners with your Controller, but Actions only work for components nested within your Controller. It may also be necessary to listen for events on the Document, Window, or across well-known adjacent elements. We can manually call `addEventListener` for these types, including during the `connectedCallback` phase. Cleanup for `addEventListener` can be a bit error prone, but [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) can be useful here to pass a signal that the element is cleaning up. AbortControllers should be created once per `connectedCallback`, as they are not re-usable, while Controllers _can_ be reused.\n\n\n```typescript\n@controller\nclass UnsavedChangesElement extends HTMLElement {\n\n #eventAbortController: AbortController|null = null\n\n connectedCallback(event: Event) {\n // Create the new AbortController and get the new signal\n const {signal} = (this.#eventAbortController = new AbortController())\n \n // You can `signal` as an option to any `addEventListener` call:\n window.addEventListener('hashchange', this, { signal })\n window.addEventListener('blur', this, { signal })\n window.addEventListener('popstate', this, { signal })\n window.addEventListener('pagehide', this, { signal })\n }\n \n disconnectedCallback() {\n // This will clean up any `addEventListener` calls which were given the `signal`\n this.#eventAbortController?.abort()\n }\n \n handleEvent(event) {\n // `handleEvent` will be called when each one of the event listeners\n // defined in `connectedCallback` is dispatched.\n }\n}\n```\n" }, { "path": "docs/_guide/providable.md", "content": "---\nversion: 2\nchapter: 8\ntitle: Providable\nsubtitle: The Provider pattern\npermalink: /guide-v2/providable\n---\n\nThe [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...\n\nSay 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).\n\nThe `@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` or `@provideAsync`. To consume a property from a parent, mark a property as `@consume`. Let's try implementing the user actions using `@providable`:\n\n```typescript\nimport {providable, consume, provide, controller} from '@github/catalyst'\n\n@controller\n@providable\nclass BlockUser extends HTMLElement {\n // This will request `userId`, and default to '' if not provided.\n @consume userId = ''\n // This will request `userName`, and default to '' if not provided.\n @consume userName = ''\n\n async handleEvent() {\n if (confirm(`Would you like to block ${this.userName}?`)) {\n await fetch(`/users/${userId}/delete`)\n }\n }\n}\n\n@controller\n@providable\nclass FollowUser extends HTMLElement {\n // This will request `userId`, and default to '' if not provided.\n @consume userId = ''\n // This will request `userName`, and default to '' if not provided.\n @consume userName = ''\n\n async handleEvent() {\n if (confirm(`Would you like to follow ${this.userName}?`)) {\n await fetch(`/users/${userId}/delete`)\n }\n }\n}\n\n@controller\n@providable\nclass UserRow extends HTMLElement {\n // This will provide `userId` as '123' to any nested children that request it.\n @provide userId = '123'\n // This will provide `userName` as 'Alex' to any nested children that request it.\n @provide userName = 'Alex'\n}\n```\n\n```html\n\n