@fusion.dev/helix-docs 0.0.0-dev

package/content/overriding-a-component.mdx

@@ -0,0 +1,160 @@
+---
+description: The three ways in past a shadow root, and which one to reach for.
+section: Theming
+title: Overriding a component
+---
+
+# Overriding a component
+
+Every Helix component draws inside a shadow root, so your stylesheet cannot
+reach in. That is the point: a rule you write can never accidentally break a
+component's internals, and a component can be rewritten without breaking your
+page.
+
+Three doors are open, and they are in the order you should try them.
+
+## 1. Tokens
+
+```css
+:root {
+  --helix-radii-md: 2px;
+}
+```
+
+If every card, dialog and button should be squarer, that is a token change and
+you are done. Tokens cross shadow boundaries on their own, because custom
+properties inherit, so one declaration reaches every component at once.
+
+Reach for this first. Most requests that arrive as "can I restyle the button"
+are really "our brand has less rounding than yours", and the token is both the
+smaller change and the one that stays consistent.
+
+See [Tokens](./tokens) and [Deriving a theme](./theming).
+
+## 2. Per-component hooks
+
+```css
+helix-card {
+  --card-padding: var(--helix-space-lg);
+}
+
+helix-accordion {
+  --accordion-border-color: var(--helix-color-border);
+}
+```
+
+A hook is a custom property a component publishes and reads. It defaults to a
+semantic token, so leaving it alone gets you the themed value, and setting it
+changes that component and nothing else.
+
+**They are API, not tokens**, and the distinction is enforced. A hook is named
+after the component (`--card-padding`, `--drawer-radius`) and a token is named
+`--helix-*`. Every documented hook is held to a rule that actually reads it, in
+both directions: declared and never read is a promise with nothing behind it,
+and read and never declared is a working feature nobody is told about. Three of
+`Button`'s four hooks were inert for a refactor's worth of time while the
+reference went on listing them, which is how that check came
+to exist.
+
+Each component's page lists its hooks under Custom properties.
+
+## 3. Parts
+
+```css
+helix-select::part(trigger) {
+  font-variant-numeric: tabular-nums;
+}
+
+helix-dialog::part(dialog) {
+  max-inline-size: 40rem;
+}
+```
+
+`::part()` reaches a named element inside the shadow root and lets you write any
+declaration you like on it. It is the most powerful door and the one to try
+last, because it is the one that couples your stylesheet to a component's
+internal structure.
+
+**A published part is a promise**, held both ways:
+a documented part that nothing renders, and a rendered part nobody was told
+about. The second is the worse of the two, because a `::part()` that resolves to
+nothing is valid CSS that matches nothing and reports nothing. `Breadcrumbs`
+published a `nav` part the family does not render; `Checkbox` renders the
+`field` part the whole styled appearance is built on and never declared it.
+
+Each component's page lists its parts.
+
+### A composed component forwards what it renders
+
+`::part()` reaches one shadow boundary and stops, so a component that renders
+another would hide that child's whole part surface. Every one of them forwards
+it instead, and the forwarded name is prefixed with the role the child plays:
+
+```css
+helix-date-input::part(picker-cell) { … }
+helix-select::part(listbox-items) { … }
+helix-video::part(overflow-header) { … }
+```
+
+`<helix-date-input>` renders a date picker as its `picker`, so the picker's
+`cell` is `picker-cell` here. Where the child's part is already the role, the
+role stands alone: the tooltip inside `<helix-copy-button>` is `tooltip`, and
+its arrow is `tooltip-arrow`.
+
+**The prefix is not decoration.** Two levels can agree on a word, and did:
+`Command` forwarded the listbox's `search-field` under a name it also rendered
+itself, so `::part(search-field)` matched two elements at once.
+
+This is checked in both directions. `check:parts` holds a published part and a
+rendered one to each other, and `check:exportparts` holds a composition to
+forwarding everything its child publishes, under one prefix, colliding with
+nothing. Before it existed, 148 published child parts were unreachable: all
+sixteen of the color picker's from inside a color input, all thirteen of the
+date picker's from inside a date input.
+
+If you still find a part you cannot reach, that is worth reporting rather than
+working around: the missing part is the bug.
+
+### Words that name a position mean one thing
+
+A part that names a *role* rather than a thing draws from a fixed vocabulary, so
+you learn it once instead of per component:
+
+| Part | What it is |
+|---|---|
+| `box` | The drawn control, where the host is not it. |
+| `container` | An element's own outer box. |
+| `content` | A region you fill. |
+| `panel` | A region switched between, or a sheet anchored to an edge. |
+| `surface` | A floating panel drawn over the page. |
+| `viewport` | A scrollport the component reads the position of. |
+
+Anything naming a thing the component actually has, a `thumb`, a `swatch`, a
+`weekday`, is that component's own word and is on its page.
+
+## What not to do
+
+**Do not raise specificity to fight a component.** `helix-button.thing.thing` is
+still outside the shadow root, so it wins nothing it was not already winning.
+Selector weight is not what is stopping you.
+
+**Do not restyle through `!important` on the host.** Some properties inherit
+into a shadow root and most do not, so this works for `color` and `font-family`
+and fails silently for everything else, which is a worse outcome than failing
+loudly.
+
+**Do not fork the component to change a color.** The headless tier exists for
+the case where you want none of our styling, and it is a different decision from
+overriding one value. See [Tiers](./tiers).
+
+## When you want all of it
+
+```ts
+import '@fusion.dev/helix-headless'
+```
+
+The headless tier is structure, accessibility, state and form participation with
+no CSS at all. You write the entire appearance. That is the honest answer when
+the design is genuinely not ours, and it is a supported tier rather than an
+escape hatch: `helix-headless-select` is a registered element, not an abstract
+class.

package/content/react.mdx

@@ -0,0 +1,144 @@
+---
+description: The typings, the hydration bridge, and how state moves.
+parent: installation
+section: Getting started
+title: React
+---
+
+# React
+
+There is no React package. The elements are custom elements and React renders
+them directly. What ships for React is a `jsx.d.ts` that types every tag and a
+runtime bridge in `@fusion.dev/helix-core` that repairs two React behaviors.
+
+```ts
+import '@fusion.dev/helix/jsx'
+```
+
+A types-only import, once, anywhere TypeScript will see it. After that
+`<helix-button>` is a typed element with its real props, and a value the
+component does not accept is a compile error rather than a runtime shrug.
+
+## Bind events with `onhelix-*`
+
+```tsx
+<helix-accordion-item onhelix-before-open={(event) => track(event.detail.open)} />
+```
+
+The prop is `on` and the event name, verbatim. Not `onHelixOpen`, not `onOpen`.
+React 19 forwards an unknown `on*` prop to `addEventListener` using the name as
+written, so the casing is the event's own.
+
+## The bridge
+
+React skips everything it would have to apply imperatively while hydrating. That
+is two things, and `HelixElement` repairs both.
+
+**Event handlers** attached during hydration are stashed on the DOM node but
+never bound, so an event fired before the next render finds nothing listening.
+The element reads React's own stash off the node and binds what it finds, so a
+handler works from the first paint rather than from the first re-render.
+
+**Object and function properties** are dropped on both sides: React's server
+renderer writes nothing for a prop whose value is an object, and the hydrate path
+never applies one. An array prop therefore arrives by no route at all, and
+because both halves agree, nothing warns. The element assigns them itself once it
+upgrades, which is what lets a data table take its rows as a plain prop:
+
+```tsx
+<helix-data-table label="People" rows={rows}>
+  <helix-table-column field="name" sortable>Name</helix-table-column>
+  <helix-table-column field="team" sortable>Team</helix-table-column>
+  <helix-table-column field="location">Location</helix-table-column>
+</helix-data-table>
+```
+
+Only properties the component declares, and only values an attribute could not
+have carried, so a string is left to the channel that already works. A `null` is
+left alone too, and the component's own default stands.
+
+The columns are elements rather than a config array for the same reason: `field`,
+`sortable` and `width` are strings and booleans, so they cross to the server
+intact, and `cell` and `compare` are functions on an element that can repair its
+own props. Nested inside a `columns` array they would be unreachable.
+
+**The cell values still do not server-render**, which is a separate limit and not
+this one. Reading a cell needs the columns, and the columns are markup children
+the server render does not hand the table, so the first paint is a labeled shell
+either way. Use `helix-table` where the content has to be in the served HTML.
+
+That is runtime code you already have, in `@fusion.dev/helix-core`, and nothing to
+configure. One thing to know about it: it reads a React
+internal, the per-page key React stores props under. If a React release renames
+that key the bridge stops repairing and your handlers go back to needing a
+commit before they fire. Helix pins the React version it was measured against
+and fails its own build when React moves past it, so this cannot go unnoticed.
+
+## A declared property is a claim of ownership
+
+This is the one thing about Helix that surprises people coming from React, and
+it is a compile error rather than a surprise at runtime:
+
+```tsx
+// Does not compile.
+<helix-input label="Name" value="Ada" />
+```
+
+In React, `value` on a native `<input>` without `onChange` renders a read-only
+field and warns. **A Helix element is not read-only**: `value` is a seed and the
+element goes on applying its own changes, so the markup below works and needs no
+handler beside it.
+
+```tsx
+// Seeded: the element owns it from there.
+<helix-input default-value="Ada" label="Name" />
+
+// Mirrored: bind the notification and let the element apply.
+<helix-input label="Name" onChange={(event) => setName(event.currentTarget.value)} />
+
+// Refused: you take the decision for this one change.
+<helix-input
+  label="Name"
+  onhelix-before-change={(event) => {
+    event.preventDefault()
+    setName(clean(event.detail.value))
+  }}
+  value={name}
+/>
+```
+
+**The one habit to unlearn is refusing by not answering.** React force-restores
+a native `<input>` whose state did not move and does not do this for a custom
+element, so a handler that declines to call `setState` leaves the element
+holding the new value. `preventDefault()` is the refusal.
+
+*Until 26 Aug 2026 this page described the opposite, and the typings enforced
+it: writing `value` was a claim of ownership, the element applied nothing until
+told, and `<helix-input value="Ada" />` was a compile error without an answering
+handler. The constraint is deleted along with the mode.*
+
+See [State and control](./state-and-control) for the whole of it.
+
+## Register in a client component
+
+```tsx
+'use client'
+import '@fusion.dev/helix'
+
+export const HelixElements = () => null
+```
+
+Render it once in your layout. **Your pages stay server components.** An
+unregistered tag is an unknown element in the HTML that upgrades when the
+definition lands, so nothing about a server component needs to change.
+
+## There is no declarative shadow DOM
+
+A server component's output is replayed from the flight payload through DOM APIs
+rather than parsed as HTML, and declarative shadow DOM cannot activate for
+script-inserted nodes. This is why `elements.css` exists: it styles the
+un-upgraded markup so the interval before hydration looks like the finished page
+rather than like unstyled boxes.
+
+[Server rendering](./server-rendering) has the whole contract, and
+[Using the elements](./using-the-elements) has the rest of the binding rules.

package/content/recipes.mdx

@@ -0,0 +1,131 @@
+---
+description: Helix styling for markup this library does not render, with no JavaScript.
+section: Foundations
+title: Recipes
+---
+
+# Recipes
+
+`@fusion.dev/helix-styles` carries recipes for markup the components do not render: your
+own anchors, your own buttons, a card you built yourself, prose out of a CMS.
+They are `data-` attributes, they need no JavaScript, and they read the same
+tokens the components do.
+
+This is what lets a page look like Helix without a single custom element on it.
+
+## Buttons
+
+```html
+<button
+  data-button="solid"
+  data-button-tone="primary"
+>Save</button>
+<a
+  data-button="ghost"
+  href="/settings"
+>Settings</a>
+```
+
+Two axes: `data-button` is how much ink it claims (`solid`, `outlined`, `ghost`,
+`subtle`) and `data-button-tone` is what it means (`primary`, `accent`,
+`neutral`, `danger`). `data-button-width` takes `auto`, `standard` or `full`.
+
+**This exists for elements this library does not render**, which is the case an
+`<a>` styled as a button falls into. When you want a button, use `helix-button`:
+the recipe has no loading state, no pressed state and no `type="submit"`
+handling.
+
+## Links
+
+```html
+<a
+  data-link
+  href="/pricing"
+>Pricing</a>
+<a
+  data-link
+  data-link-underline="quiet"
+  href="/docs"
+>Docs</a>
+```
+
+`data-link-size` and `data-link-underline` are the modifiers. `quiet` is for
+navigation, where a line under every row would be noise. A link that opens a new
+context says so on its own, rather than surprising the reader.
+
+## Surfaces and layout
+
+```html
+<div data-card>…</div>
+<li data-list-item>…</li>
+<div data-dock="bottom-end">…</div>
+```
+
+`data-dock` pins something to a corner, which is a fact about the page rather
+than about the control: `data-dock-within` scopes it to the nearest positioned
+ancestor instead of the window.
+
+## Surface axes
+
+Two of the [visual axes](./visual-axes) describe a surface rather than a control,
+and these are how a plain element reaches them:
+
+```html
+<section data-material="glass">…</section>
+<div data-separation="elevated">…</div>
+```
+
+`data-material` takes `glass`, `frosted` and `transparent`, and `data-separation`
+takes `elevated`, `filled`, `outlined` and `plain`. The values are the axes' own,
+so one word means the same thing here as it does on a component: a `<section>`
+that is `glass` and a component that is `material="glass"` are asking for the
+same optical treatment. See [Elevation and
+material](./elevation-and-material).
+
+**Blur is the expensive one.** `glass` and `frosted` both carry a
+`backdrop-filter`, which makes the compositor re-read what is behind the element
+on every frame it moves, so a full-width band that stays on screen through a
+scroll pays continuously. Where the effect is about depth rather than texture,
+`data-separation` is the cheaper axis.
+
+## Prose
+
+```html
+<article data-prose>
+  <h2>From a CMS</h2>
+  <p>Styled without being rewritten.</p>
+</article>
+```
+
+Headings take the type scale, paragraphs take the measure and leading, lists and
+links and inline code all follow. See [Typography](./typography).
+
+## Region axes
+
+These two are API rather than styling, and they are the reason the base layer is
+worth importing even in an app that uses only components:
+
+```html
+<div data-density="sm">…</div>
+<div data-color-mode="dark">…</div>
+```
+
+`data-density` sets how big the controls in a region are, and it works through
+custom properties so it crosses every shadow boundary on its own.
+`data-color-mode` sets the color mode for a subtree. See [Size and
+density](./size-and-density) and [Color modes](./color-modes).
+
+## Utilities
+
+```html
+<span data-hidden-visually>Sorting by</span>
+```
+
+Clipped rather than `display: none`, so it stays in the accessibility tree. See
+[Accessibility](./accessibility).
+
+## When a recipe is the wrong tool
+
+A recipe has appearance and no behavior. It cannot manage state, cannot
+participate in a form, cannot trap focus and has no keyboard handling. If you
+find yourself adding script to a recipe, the component is what you wanted.

package/content/routing.mdx

@@ -0,0 +1,208 @@
+---
+description: Why a component renders its own anchor, and how to keep a router.
+section: Essentials
+title: Routing and navigation
+---
+
+# Routing and navigation
+
+Some components navigate. A tree used as a sidebar, a button that goes
+somewhere, a tab that is really a page. Those all want to be links, and a link
+inside a shadow root is where web components and framework routers disagree.
+
+## A component that navigates renders its own anchor
+
+`Tree.Item` and `Button` both take an `href`, and when they have one the thing
+you press *is* an `<a>`:
+
+```html
+<helix-tree-item
+  href="/design/components/button"
+  value="button"
+>
+  Button
+</helix-tree-item>
+```
+
+That is not a detail of the implementation. What it buys is a list of things no
+amount of JavaScript reproduces:
+
+- the whole row is the target, not just the words
+- Enter works, because a focused anchor is a thing Enter activates
+- middle-click and Command-click open a tab
+- the destination appears in the status bar on hover
+- right-click offers Copy Link Address
+- a crawler follows it
+
+Before `href` existed, the docs sidebar put a `<Link>` inside each row. The
+anchor was 57px of a 240px row, so five sixths of every row did nothing, and
+Enter did nothing at all: the tree announced a selection and no anchor heard it.
+
+## `href` and a framework's `<Link>`
+
+You cannot give a component's internal anchor to `next/link`. `<Link>` renders
+*its own* `<a>` and attaches its own handlers to it, and there is no way to hand
+that to an element that renders one inside a shadow root.
+
+So it is one or the other.
+
+## Wrapping the component in a `<Link>` is not the third option
+
+It looks like it should work, and it half does:
+
+```tsx
+{/* Don't. */}
+<Link href="/design/components/button">
+  <helix-tree-item value="button">Button</helix-tree-item>
+</Link>
+```
+
+The tree still finds its items, because it collects them with a descendant
+query rather than by looking at its children. What it costs:
+
+- **Two focus stops per row.** The anchor is focusable and so is the treeitem
+  inside it. A tree owns a single roving tab stop, and this adds a second one it
+  does not control.
+- **A `treeitem` nested inside a `link`.** Anything reading the semantics meets
+  both, in that order, for one thing.
+- **Nothing at all for a branch.** A branch contains its children, so wrapping
+  one puts every descendant anchor inside an ancestor anchor. That is invalid,
+  and browsers rearrange it.
+
+## Some roles cannot contain a link
+
+`treeitem` and `tab` are the two in this library. You cannot nest an anchor in
+either, and the answer is not to give up the anchor.
+
+For a tree, the role moves *onto* the anchor and the group becomes its sibling:
+
+```html
+<!-- What Tree.Item renders when it has an href -->
+<div
+  part="item"
+  role="none"
+>
+  <a
+    aria-expanded="true"
+    href="/x"
+    part="row"
+    role="treeitem"
+  >Name</a>
+  <div
+    part="group"
+    role="group"
+  >…</div>
+</div>
+```
+
+That is the navigation flavor of the tree pattern, and it is why `href` changes
+the shape of the markup rather than only adding an attribute. Without an `href`
+nothing moves: the wrapper stays the `treeitem` and holds its group, which is
+what an `<li>` holding a `<ul>` is.
+
+Tabs have no equivalent published pattern. Web Awesome hit the same wall and
+answered it the other way, telling consumers to drop the anchor and navigate in
+JavaScript. That works, and it costs every item in the list above.
+
+## Getting client-side routing back
+
+Real anchors do a full page load, because a framework only intercepts anchors it
+rendered itself. If you want its router, put it back on top rather than giving
+up the anchors:
+
+```tsx
+'use client'
+const router = useRouter()
+
+const navigate = (event) => {
+  // A modified or middle press is exactly the gesture that wants the browser's
+  // own behavior. Taking it back is taking back the reason for real anchors.
+  if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+    return
+  }
+  // The anchor is inside a shadow root, so by the time the event gets here it
+  // has retargeted to the host: `event.target` is the custom element.
+  const link = event.nativeEvent
+    .composedPath()
+    .find((node) => node instanceof HTMLAnchorElement)
+  if (!link || link.target !== '' || new URL(link.href).origin !== location.origin) {
+    return
+  }
+  event.preventDefault()
+  router.push(new URL(link.href).pathname)
+}
+
+return <nav onClick={navigate} onPointerOver={warm}>{/* … */}</nav>
+```
+
+One listener on the container covers every row, and nothing has to be rebound as
+rows come and go.
+
+### Prefetch on approach, not on sight
+
+`<Link>` prefetches when a link enters the viewport. For a sidebar of seventy
+that is seventy requests for one navigation. Prefetching on `pointerover` and
+`focus` instead costs one, and a reader points at a row well before they press
+it:
+
+```tsx
+const warmed = useRef(new Set())
+const warm = (event) => {
+  const path = pathOf(event)
+  if (path && !warmed.current.has(path)) {
+    warmed.current.add(path)
+    router.prefetch(path)
+  }
+}
+```
+
+Prefetching is production-only in Next, so this does nothing in development. It
+is not broken.
+
+## Which components take an `href` today
+
+| Component | Notes |
+|---|---|
+| `Button` | Renders an `<a>` styled as a button. |
+| `Tree.Item` | Changes the ARIA shape, as above. A linked branch navigates from its row and opens from its chevron. |
+| `Menu.Item` | The row becomes the anchor and carries `menuitem`. Takes `target`, `rel` and `download`. |
+
+Anything else that should navigate is a gap. Slot a link into it, and press the
+row rather than the words: `Tree.Item` follows a slotted anchor from anywhere in
+the row and from the keyboard, which covers the case without an `href`.
+
+## `Option` cannot take one
+
+The obvious place to want a link in a list is a command palette, whose entries
+are usually half commands and half destinations. It is the one place this
+library cannot offer an `href`.
+
+**A listbox cannot move focus to its options.** A combobox keeps focus in its
+text field while the arrows walk the list, so the pattern it is obliged to use
+is `aria-activedescendant`: focus stays put and an attribute says which option
+is current. A menu is the opposite, and that is what makes `Menu.Item` easy:
+focus really moves to the row, so the row can be an anchor with `menuitem` on
+it.
+
+**That reference reaches the option's host and nothing inside it.** IDREFs do
+not cross shadow boundaries at all, so `Listbox` uses the element-reference
+form. Measured in Chromium: assigning `ariaActiveDescendantElement` an element
+inside a *sibling* shadow root reads back `null`, while assigning the option's
+host reads back the host. So `role="option"` is pinned to the host, since the
+host is the only element the listbox can point at.
+
+**And a `role="option"` with an anchor inside it is broken.** Measured in the
+same browser, the accessibility tree for `<div role="option"><a href>Open
+settings</a></div>` inside a listbox is an option with *no accessible name*, and
+the link exposed as a child of it. The sibling option with plain text is named
+correctly. So the manoeuvre that works for `treeitem` and `menuitem`, moving the
+role onto the anchor, is exactly the one thing that cannot be done here.
+
+Two constraints pointing opposite ways, and no arrangement satisfies both.
+
+**So a palette routes through its event.** Listen for `helix-select` on
+`helix-command` and call the router. That is what a palette is for, entries
+being commands and "go to Settings" being a command that navigates, and it is
+what every palette a reader has used already does. What it costs is the gestures
+only a real anchor has: middle-click, a modified click, and the destination in
+the status bar.