Contributing

Search Web Components is developed on drupal.org, with the code in its GitLab repository and the issues in its issue queue. A change is a merge request against the issue it fixes.

The repository

• lit/: the TypeScript source of the components, their browser tests, Storybook, and the bundle search-web-components.min.js that the Drupal module loads. CI rebuilds the bundle on each push to 1.0.x, so it is never edited by hand.
• src/, config/: the endpoint settings and the event subscriber that sends them in the endpoint's response.
• components/: the single directory components, one per element.
• modules/block/, modules/canvas/, modules/facets/, modules/layout/, modules/spellcheck/: the blocks, the Canvas integration, the facet widgets, the Layout Builder layouts, and the Did You Mean support.
• docs/: this site.

Local environment

The repository is a ddev-drupal-contrib project: the DDEV site lives in the module checkout and symlinks the module into web/modules/custom/search_web_components.

ddev start
ddev poser
ddev install-demo

ddev install-demo installs the Umami demo profile with the module, its submodules, and the demo project, and indexes the content. The site is at https://search-web-components.ddev.site (admin / admin), with the search page at /search and the endpoint at /api/search/content.

The Node work happens on the host, with the Node version in .nvmrc:

cd lit && npm ci

Checks

Every merge request passes these:

Command	What it checks
ddev phpstan	Static analysis at the highest level, with no baseline.
ddev phpcs	The Drupal and DrupalPractice coding standards.
ddev phpunit	The kernel and functional tests.
cd lit && npm run lint	lit-analyzer, ESLint, the type check of the browser tests, and the docs check.
cd lit && npm run wdio	The browser tests of every component, in Chrome against recorded responses.
cd lit && npm run build	The TypeScript compile.

A check is made to pass by fixing the code, never by lowering its level, adding a baseline entry, or ignoring a rule.

Conventions

• A method whose name starts with an underscore, e.g., _getResults(), is an extension point a subclass overrides, not a private method. Its name and signature stay stable. For the hooks, see Extend.
• Each component follows a W3C pattern for its keys, focus, and ARIA attributes, named in the component's class docblock and tested in its browser tests. For the patterns, see W3C references.
• Every attribute has a story that sets it, every class a component renders is documented in its class docblock, and npm run lint:docs checks that the docs and the stories name only what exists.
• The module is in production on many sites. What an attribute, a token, an event, or a configuration key does changes only to fix a bug, and nothing is dropped.