[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/haxtheweb/webcomponents/badge)](https://securityscorecards.dev/viewer/?uri=github.com/haxtheweb/webcomponents) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16207/badge)](https://www.bestpractices.dev/projects/16207) [![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](/SUPPORT.md) [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](/CODE_OF_CONDUCT.md) [![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/aCGxmRHEJP) [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/) [![Lit](https://img.shields.io/badge/-Lit-324fff?style=flat&logo=data:image/svg%2bxml;base64,PHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMTYwIDIwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJtMTYwIDgwdjgwbC00MC00MHptLTQwIDQwdjgwbDQwLTQwem0wLTgwdjgwbC00MC00MHptLTQwIDQwdjgwbDQwLTQwem0tNDAtNDB2ODBsNDAtNDB6bTQwLTQwdjgwbC00MC00MHptLTQwIDEyMHY4MGwtNDAtNDB6bS00MC00MHY4MGw0MC00MHoiLz48L3N2Zz4%3D)](https://lit.dev/) [![#HAXTheWeb](https://img.shields.io/badge/-HAXTheWeb-999999FF?style=flat&logo=data:image/svg%2bxml;base64,PHN2ZyBpZD0iZmVhMTExZTAtMjEwZC00Y2QwLWJhMWQtZGZmOTQyODc0Njg1IiBkYXRhLW5hbWU9IkxheWVyIDEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDE4NC40IDEzNS45NyI+PGRlZnM+PHN0eWxlPi5lMWJjMjAyNS0xODAwLTRkYzItODc4NS1jNDZlZDEwM2Y0OTJ7ZmlsbDojMjMxZjIwO308L3N0eWxlPjwvZGVmcz48cGF0aCBjbGFzcz0iZTFiYzIwMjUtMTgwMC00ZGMyLTg3ODUtYzQ2ZWQxMDNmNDkyIiBkPSJNNzguMDcsODMuNDVWNTVIODYuMnY4LjEzaDE2LjI2djQuMDdoNC4wN1Y4My40NUg5OC40VjY3LjE5SDg2LjJWODMuNDVaIi8+PHBvbHlnb24gcG9pbnRzPSIxNTMuMTMgNjMuNyAxNTMuMTMgNTEuMzkgMTQwLjU0IDUxLjM5IDE0MC41NCAzOS4wOSAxMjcuOTUgMzkuMDkgMTI3Ljk1IDI2Ljc5IDEwMi43OCAyNi43OSAxMDIuNzggMzkuMDkgMTE1LjM2IDM5LjA5IDExNS4zNiA1MS4zOSAxMjcuOTUgNTEuMzkgMTI3Ljk1IDYzLjcgMTQwLjU0IDYzLjcgMTQwLjU0IDc2IDEyNy4zNiA3NiAxMjcuMzYgODguMyAxMTQuNzggODguMyAxMTQuNzggMTAwLjYxIDEwMi4xOSAxMDAuNjEgMTAyLjE5IDExMi45MSAxMjcuMzYgMTEyLjkxIDEyNy4zNiAxMDAuNjEgMTM5Ljk1IDEwMC42MSAxMzkuOTUgODguMyAxNTIuNTQgODguMyAxNTIuNTQgNzYgMTY1LjcyIDc2IDE2NS43MiA2My43IDE1My4xMyA2My43Ii8+PHBvbHlnb24gcG9pbnRzPSIzMy4xMyA2My43IDMzLjEzIDUxLjM5IDQ1LjcyIDUxLjM5IDQ1LjcyIDM5LjA5IDU4LjMxIDM5LjA5IDU4LjMxIDI2Ljc5IDgzLjQ4IDI2Ljc5IDgzLjQ4IDM5LjA5IDcwLjg5IDM5LjA5IDcwLjg5IDUxLjM5IDU4LjMxIDUxLjM5IDU4LjMxIDYzLjcgNDUuNzIgNjMuNyA0NS43MiA3NiA1OC44OSA3NiA1OC44OSA4OC4zIDcxLjQ4IDg4LjMgNzEuNDggMTAwLjYxIDg0LjA3IDEwMC42MSA4NC4wNyAxMTIuOTEgNTguODkgMTEyLjkxIDU4Ljg5IDEwMC42MSA0Ni4zMSAxMDAuNjEgNDYuMzEgODguMyAzMy43MiA4OC4zIDMzLjcyIDc2IDIwLjU0IDc2IDIwLjU0IDYzLjcgMzMuMTMgNjMuNyIvPjwvc3ZnPg==)](https://haxtheweb.org/) [![Published on npm](https://img.shields.io/npm/v/@haxtheweb/h-a-x?style=flat)](https://www.npmjs.com/search?q=@haxtheweb) [![build](https://github.com/haxtheweb/webcomponents/workflows/build/badge.svg?branch=master)](https://github.com/haxtheweb/webcomponents/actions?query=branch%3Amaster) [![X](https://img.shields.io/twitter/follow/haxtheweb.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=haxtheweb) # Welcome to the HaxTheWeb project! Web components that can work in just about anything, are very small (Vanila or Lit based) and have full on authoring solutions if you dig deeper; Enjoy! ## Onboarding New to the HAX ecosystem? **[Start here](https://github.com/haxtheweb/issues/blob/master/CONTRIBUTING.md)** — the single onboarding guide covers prerequisites, cloning the core repos, installing, and running each project locally. ## Who this is for - **Web component developers** — build and maintain the 250+ LitElement components, themes, and the DDD design system. - **Site builders and course designers** — the accessible, standards-based building blocks every HAX site and course page is authored from. - **Campus IT and adopters** — published packages under the `@haxtheweb` npm org, usable in any stack. - **Accessibility contributors** — the component library is the front line of WCAG alignment for the whole HAX ecosystem. ## Getting Started ### Quick install: Dev Containers (as a core dev, forks preferrable) HAXTheWeb is dedicated to making contribution an accessible and simple experience. Follow the step-by-step guide below to explore our curated development environment: ### Prerequisites * On **Windows**: Update **WSL 2** * There are two methods available: * Open **WSL 2** in the [Microsoft Store](https://aka.ms/wslstorepage), select **Install/Update** * Open **PowerShell**, run the command: `wsl --update` * Why: Certain Windows editions are bundled with an outdated **WSL 2** version. * On macOS or Linux: None --- ### Guide 1. Install **Docker Desktop** * [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) * Select the **WSL 2 Backend** option * **Restart** after installing * [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) * [Linux](https://docs.docker.com/desktop/setup/install/linux/) * **Docker Desktop** must remain open for **VS Code** to connect with it. 2. Install [GitHub Desktop](https://desktop.github.com/download/) (optional) 3. Clone the repository with **Git** * Using **GitHub Desktop**: select **Clone Repository**, then select the **URL** option. * Enter the link to your repository: `https://github.com/haxtheweb/webcomponents` 4. Open the repository in **VS Code** * Using **GitHub Desktop**: simply select **Open in VS Code** 5. Some alerts with pop up in the **bottom right** corner of **VS Code**: * Select **Install Recommended Extensions** * Select **Reopen in Container** Wait a few minutes for your **Dev Container** to be built, then you're ready to go! Try the following command to open a demo HAXsite: ```bash yarn run haxsite ``` ### Alternative installs If you're interested in other installation methods, visit our [Contributing Docs](CONTRIBUTING.md#getting-started)! We provide native Bash and PowerShell scripts, in addition to manual instructions. ----------------------------------------------- ## What is HAX The authoring experience of HAX and the ability to make fast, static file backed websites rapidly. Get all the details you want on [HAX docs](https://haxtheweb.org/)! HAX seeks to be the smallest possible back-end CMS to make HAX work and be able to build websites with it. Leveraging JSON Outline Schema, HAX is able to author multiple pages, which it then writes onto the file system. This way a slim server layer is just for basic authentication, knowing how to save files, and placing them in version control. Watch and Learn more about HAX here: - Try Hax: https://hax.cloud - HAXCellence https://haxtheweb.org/what-is-hax - Youtube channel - https://www.youtube.com/@haxtheweb ### Issues / Support / Community - Discord Channel - https://discord.gg/aCGxmRHEJP - Unified issue queue - https://github.com/haxtheweb/issues/issues - Using Merlin directly in any HAX spaces and type "Issue" to jump start a report! ### Related links and tech - [HAXcms (NodeJS)](https://github.com/haxtheweb/haxcms-nodejs) - [HAXcms (PHP)](https://github.com/haxtheweb/haxcms-php) - [Storybook docs](https://open-apis.hax.cloud/) - [HAX [dot] PSU](https://hax.psu.edu) - [HAX doc site](https://haxtheweb.org/) - [HAX + 11ty](https://github.com/haxtheweb/hax11ty) ## To work on any element in our repo ```bash cd elements/ELEMENTNAME yarn start ``` Edit files in `lib/`, `src/`, `locales/` and `demo/` in order to modify the element to contribute back to us via PR. In `locales/`, change only the English (`*.en.json`) files; other languages arrive in the rolling `chore/nightly-translations` PR (an optional AI-assisted scheduled task, not part of CI), and the `locale-guard` check warns on PRs that change them. ## Scripts - `hax webcomponent my-element --y` - Run HAX CLI to create a new web component - `yarn test` - Run tests on ALL webcomponents. - `yarn run build` - Run build on ALL webcomponents. - `yarn run gallery` - Run component gallery (replaces storybook) - `yarn run build-gallery` - Build component gallery for deployment - `yarn run elements-readme` - Regenerate [elements/README.md](elements/README.md) (the index of every element) from each element's `package.json` description. Runs as part of `yarn run ubiquity`; add `--check` to fail when it's stale. ## Web Component development Because this is a monorepo, each web component will need to be independently built in order to actively work on and preview the changes. Every web component has its own Gulp file and Yarn/NPM script. While still running `yarn start` in one terminal window (which runs the local server), you will need to open another terminal window, drill into the directory of the web component you'd like to work on, and execute the `yarn run dev` command. This command will use gulp tasks to watch the files within that web component directory and will automatically re-run the build command and refresh the browser when you make changes to the web component. ### Working on elements (new-element) Run `hax webcomponent` to make a new element. Go to the new element following the directions generated at the end of the element's creation. To work on the new-element run `yarn start` from it's directory. If you are pulling in another element to use, run `yarn add projectname --save` or edit the `package.json` file local to the element you are working on. **ALWAYS INSTALL FROM THE REPO ROOT, NOT THE ELEMENT YOU ARE WORKING ON** ### Example development on a web component ```bash cd /Sites/webcomponents yarn start # SHIFT + CTRL + T to open a new tab in Terminal cd elements your-card # or any other web component yarn run dev ``` Make a change to the web component and save. The gulpfile will handle transpiling the element down to ES5 and will bring in the HTML and Sass into the template in the web component. ## Test To test all webcomponents, run `yarn test` from the root of the repo. If you only want to test the web component you're working on: ```bash cd elements/your-card yarn test ``` Also, if your tests are failing and you want access to a live browser to investigate why, the following flag will keep the browser open. ```bash yarn test -- -p ``` Then open the URL that will be printed in the terminal. It looks something like this: `http://localhost:8081/components/@@haxtheweb/haxtheweb/generated-index.html?cli_browser_id=0`. ### Keyboard-flow tests Automated audits (axe) catch only part of what blocks keyboard users, so the core authoring and learning flows also have scripted keyboard tests. They live next to each element as `test/*keyboard-flow.test.js`, drive real key presses in Chromium (`sendKeys` from `@web/test-runner-commands`), and run as part of the normal, blocking suite (`yarn test:all` and each element's `yarn test`). The invariant they protect: a keyboard-only user can complete the flow, and at every focus stop - the focused control shows a visible focus indicator (a computed outline or box-shadow on it or on the host that draws its ring), - focus never lands on something hidden, zero-size, off screen, `inert` or inside `aria-hidden`, - no positive `tabindex` changes the tab order. | Flow | Test file | | --- | --- | | Shared HAX UI dialog (`simple-modal`): focus moves in, Tab/Shift+Tab trapped, Escape closes, focus returns to the opener | `elements/simple-modal/test/simple-modal-keyboard-flow.test.js` | | HAXcms editor top bar + hax-tray panels (View source, Page outline, Add block, Configure block) and the shortcut registry (every binding has an action and description, no collisions, every `Ctrl⇧` shortcut shown in the bar is registered) | `elements/haxcms-elements/test/haxcms-editor-keyboard-flow.test.js` | | Merlin (`super-daemon`): open with its shortcut, type, arrow to a result, Enter runs it, Escape closes and restores focus | `elements/super-daemon/test/super-daemon-keyboard-flow.test.js` | | `outline-designer`: arrow navigation, Alt+arrows move/indent/outdent, Delete marks and restores, row actions menu | `elements/outline-designer/test/outline-designer-keyboard-flow.test.js` | | `video-player` / `audio-player`: play/pause, seek, captions, transcript cues, fullscreen, settings | `elements/{video,audio}-player/test/*-keyboard-flow.test.js` (shared flow in `scripts/test-setup/keyboard-flow-media.js`) | | Question types: select, submit, result announced, try again | `elements/multiple-choice/test/question-keyboard-flow.test.js` | | `a11y-collapse` accordion and `a11y-tabs` | `elements/a11y-collapse/test/`, `elements/a11y-tabs/test/` | Run one locally from the element folder, e.g. `cd elements/simple-modal && yarn test`. Shared helpers (`press`, `expectGoodFocusStop`, `expectFocusOn`, `positiveTabindexIn`) are in `scripts/test-setup/keyboard-flow.js`. When a flow finds a real keyboard bug that is not fixed in the same PR, keep the rest of the flow running and record the bug instead of loosening the check: add an `it.skip("KNOWN BUG: ...")` test that asserts the fixed behavior, with a comment naming the file and the cause, and, if other steps of the flow pass through the broken stop, a `knownBugs` entry (`{ match(el), reason }`) passed to `expectGoodFocusStop`. Fixing the bug means un-skipping that test and deleting the entry. ## Component Gallery We've replaced [Storybook](https://storybook.js.org/) with our own **Component Gallery** to preview and document our web components. The Component Gallery provides a better integrated experience with HAX design system and build tools. To run the component gallery locally ```bash yarn run gallery ``` This will build the gallery and start a web server. Navigate to the URL shown in the terminal to see the Component Gallery in action. The gallery will automatically rebuild when components change. To build the component gallery for deployment ```bash yarn run build-gallery ``` This generates the component gallery as a single HTML file: `index.html`, so it's served automatically at the root of any static host (e.g. a Vercel preview deployment). ### Component Gallery Features - **HAX Integration**: Built-in support for HAX-enabled components - **DDD Design System**: Uses our Design, Develop, Deliver design tokens - **Live Demos**: Interactive component demonstrations - **CodePen Export**: Direct export to CodePen for experimentation - **Search & Filter**: Easy component discovery - **Mobile Responsive**: Works on all device sizes ## Tech Stack **Client:** JavaScript, LitElement, Lit(https://lit.dev/) **Server:** Node.js ## Contributing Contributions are always welcome! ## Active contributors - [@btopro](https://www.github.com/btopro) ## Additional contributions Past contributors, student and larger community, can be found here: https://github.com/haxtheweb/webcomponents/graphs/contributors ![HAX Future Traveler](https://raw.githubusercontent.com/haxtheweb/art/refs/heads/main/haxtheweb/hax-future-traveler.jpg)