@fusion.dev/helix-docs 0.104.0 → 0.105.0

package/content/react.mdx

@@ -1,5 +1,5 @@
 ---
-description: The typings, the hydration bridge, and how state moves.
+description: The React typings, the hydration bridge, and how state moves between React and the elements.
 parent: installation
 section: Getting started
 title: React
@@ -7,17 +7,17 @@ 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.
+The elements are custom elements, and React renders them directly, so there is
+no React package. For React, we ship a `jsx.d.ts` file 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.
+Add this types-only import once, anywhere TypeScript sees it. `<helix-button>`
+then has typed props, and a value the component does not accept is a compile
+error.
 
 ## Bind events with `onhelix-*`
 
@@ -25,25 +25,30 @@ component does not accept is a compile error rather than a runtime shrug.
 <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 prop is `on` followed by the exact event name. `onHelixOpen` and `onOpen` do
+not work. React 19 passes an unknown `on*` prop to `addEventListener` with the
+name as written, so use the event's own casing.
 
-## The bridge
+## The hydration bridge
 
-React skips everything it would have to apply imperatively while hydrating. That
-is two things, and `HelixElement` repairs both.
+While React hydrates, it skips everything it would have to apply imperatively.
+That affects 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.
+### Event handlers
 
-**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:
+React stores the event handlers it sees during hydration on the DOM node, but it
+does not bind them. An event fired before the next render reaches no listener.
+The element reads the handlers React stored on the node and binds them, so a
+handler works from the first paint.
+
+### Object and function properties
+
+React drops object and function properties on both sides. The server renderer
+writes nothing for a prop whose value is an object, and hydration never applies
+one. An array prop therefore never reaches the element, and because the server
+and the client agree, React shows no warning. The element assigns these
+properties itself once it upgrades, so a data table can take its rows as a plain
+prop:
 
 ```tsx
 <helix-data-table label="People" rows={rows}>
@@ -53,41 +58,43 @@ upgrades, which is what lets a data table take its rows as a plain prop:
 </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 element assigns only properties the component declares, and only values an
+attribute cannot carry. Strings still go through attributes, which already work.
+The element also leaves a `null` alone, so the component keeps its default.
+
+The columns are elements for the same reason. `field`, `sortable`, and `width`
+are strings and booleans, so they pass through server rendering intact. `cell`
+and `compare` are functions, set on an element that repairs its own props.
+Inside a `columns` array, the bridge could not reach them.
 
-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 render on the server. That is a separate limit.
+Reading a cell needs the columns, and the server render does not pass the table
+its markup children. The first paint shows a labeled table with no data in
+either case. Use `helix-table` when the content must be in the served HTML.
 
-**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.
+### The React version
 
-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.
+The bridge is runtime code in `@fusion.dev/helix-core`, which you already have,
+and it needs no configuration. It reads a React internal: the per-page key that
+React stores props under. If a React release renames that key, the bridge stops
+repairing, and your handlers again need a commit before they fire. We pin the
+React version we measured the bridge against, and our build fails when React
+moves past it, so a rename cannot go unnoticed.
 
-## A declared property is a claim of ownership
+## Seed, mirror, or refuse a value
 
-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:
+Helix differs from React in one way that surprises people. This markup
+compiles, and the field stays editable:
 
 ```tsx
-// Does not compile.
+// Compiles, and the field stays editable.
 <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.
+field and logs a warning. On a Helix element, `value` is a seed. The element
+starts with that value and keeps applying its own changes, so the markup below
+works without a handler.
 
 ```tsx
 // Seeded: the element owns it from there.
@@ -107,17 +114,18 @@ handler beside it.
 />
 ```
 
-**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.
+**To refuse a change, call `preventDefault()`.** Skipping `setState` does not
+refuse it. React restores a native `<input>` whose state did not change, and it
+does not do this for a custom element. A handler that does not call `setState`
+leaves the element with the new value.
 
-*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.*
+*Until August 26, 2026, this page described the opposite behavior, and the typings
+enforced it. Writing `value` made you the owner of the state. The element
+applied no change until you set the value, and `<helix-input value="Ada" />`
+without a handler was a compile error. We removed that mode and its
+constraint.*
 
-See [State and control](./state-and-control) for the whole of it.
+See [State and control](./state-and-control) for the full model.
 
 ## Register in a client component
 
@@ -129,16 +137,16 @@ 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.
+unregistered tag is an unknown element in the HTML, and it upgrades when the
+definition loads. Your server components need no changes.
 
 ## Server components get 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.
+React inserts a server component's output by replaying the flight payload
+through DOM APIs. The browser does not parse that output as HTML, and
+declarative shadow DOM cannot activate for nodes inserted by script.
+`elements.css` exists for this case. It styles the markup before the elements
+upgrade, so the page looks finished before hydration.
 
-[Server rendering](./server-rendering) has the whole contract, and
-[Using the elements](./using-the-elements) has the rest of the binding rules.
+[Server rendering](./server-rendering) covers server rendering in full, and
+[Using the elements](./using-the-elements) covers the other binding rules.

package/content/recipes.mdx

@@ -1,17 +1,22 @@
 ---
-description: Helix styling for markup this library does not render, with no JavaScript.
+description: Style your own HTML with Helix data attributes and 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.
+`@fusion.dev/helix-styles` includes recipes for markup that the components do
+not render, such as:
 
-This is what lets a page look like Helix without a single custom element on it.
+- your own anchors
+- your own buttons
+- a card you built yourself
+- prose from a CMS
+
+Recipes are `data-` attributes. They need no JavaScript, and they use the same
+tokens as the components. With recipes, your page can look like Helix without
+any custom elements.
 
 ## Buttons
 
@@ -26,14 +31,18 @@ This is what lets a page look like Helix without a single custom element on it.
 >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`.
+A button recipe has two axes:
+
+- `data-button` sets the button's emphasis: `solid`, `outlined`, `ghost`, or
+  `subtle`.
+- `data-button-tone` sets what the button means: `primary`, `accent`,
+  `neutral`, or `danger`.
 
-**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.
+`data-button-width` takes `auto`, `standard`, or `full`.
+
+**Use the button recipe only on elements that Helix does not render**, such as
+an `<a>` styled as a button. For a button, use `helix-button`. The recipe has no
+loading state, no pressed state, and no `type="submit"` handling.
 
 ## Links
 
@@ -50,8 +59,8 @@ handling.
 ```
 
 `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.
+navigation, where an underline on every row would distract. If a link opens a
+new tab or window, say so in the link text, so it does not surprise your users.
 
 ## Surfaces and layout
 
@@ -61,32 +70,30 @@ context says so on its own, rather than surprising the reader.
 <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.
+`data-dock` pins an element to a corner of the window. `data-dock-within` pins it
+to a corner of the nearest positioned ancestor.
 
 ## 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:
+Two of the [visual axes](./visual-axes) describe a surface. Use these attributes
+to apply them to a plain element:
 
 ```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).
+`data-material` takes `glass`, `frosted`, and `transparent`. `data-separation`
+takes `elevated`, `filled`, `outlined`, and `plain`. The values are the same as
+the axes' values, so each word means the same thing here as on a component. A
+`<section>` that is `glass` and a component with `material="glass"` get the same
+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.
+**Blur costs the most to render.** `glass` and `frosted` both use a
+`backdrop-filter`. The compositor re-reads what is behind the element on every
+frame in which the element moves. A full-width band that stays on screen while
+you scroll pays that cost the whole time. To show depth, use `data-separation`,
+which costs less.
 
 ## Prose
 
@@ -97,11 +104,16 @@ scroll pays continuously. Where the effect is about depth rather than texture,
 </article>
 ```
 
-Headings take the type scale, paragraphs take the measure and leading, lists and
-links and inline code all follow. See [Typography](./typography).
+In prose:
+
+- Headings use the type scale.
+- Paragraphs use the measure and leading.
+- Lists, links, and inline code follow the same styles.
 
-If you own the markdown renderer, map two things to components, because markup
-can't carry what they need:
+See [Typography](./typography).
+
+If you control the Markdown renderer, map two elements to components, because
+HTML alone cannot hold what they need:
 
 - **Fenced code** to `helix-code-block`, with the fence's language as its `label`.
   A `<pre>` has no label or copy button.
@@ -109,21 +121,21 @@ can't carry what they need:
   tone. `NOTE` and `IMPORTANT` become `tone="info"`, `TIP` becomes `success`,
   `WARNING` becomes `warning`, and `CAUTION` becomes `danger`.
 
-Prose spaces each one the same as the element it replaces.
+Prose spaces each component the same as the element it replaces.
 
 ## 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:
+These two attributes are API. Import the base layer for them, 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
+`data-density` sets the size of the controls in a region. It works through
+custom properties, so it crosses every shadow boundary. `data-color-mode` sets
+the color mode for a subtree. See [Size and
 density](./size-and-density) and [Color modes](./color-modes).
 
 ## Utilities
@@ -132,11 +144,16 @@ density](./size-and-density) and [Color modes](./color-modes).
 <span data-hidden-visually>Sorting by</span>
 ```
 
-Clipped rather than `display: none`, so it stays in the accessibility tree. See
-[Accessibility](./accessibility).
+`data-hidden-visually` clips the element, so it stays in the accessibility tree.
+`display: none` would remove it. See [Accessibility](./accessibility).
+
+## When to use a component
+
+A recipe sets appearance and has no behavior. A recipe cannot:
 
-## When a recipe is the wrong tool
+- manage state
+- take part in a form
+- trap focus
+- handle the keyboard
 
-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.
+If you need to add a script to a recipe, use the component.