@fusion.dev/helix-docs 0.104.1 → 0.106.0

package/content/using-the-elements.mdx

@@ -1,5 +1,5 @@
 ---
-description: Binding events, registering elements, and the traps in both.
+description: Bind events, register the elements, and import the styles in a React app.
 pinned: true
 section: Essentials
 title: Using the elements
@@ -7,8 +7,8 @@ title: Using the elements
 
 # Using the elements
 
-Write `<helix-card>` in your JSX. They are plain custom elements: no wrapper, no
-patched React, and no React package: there is not one.
+Write `<helix-card>` in your JSX. The elements are plain custom elements. There
+is no wrapper component, no patched React, and no React package.
 
 ```tsx
 export default function Page() {
@@ -21,8 +21,7 @@ export default function Page() {
 }
 ```
 
-Everything below is a trap that has actually cost time, rather than general
-advice.
+Each section below covers a problem that has cost us time in practice.
 
 ## Bind Helix events with `onhelix-*`
 
@@ -30,46 +29,48 @@ advice.
 <helix-tabs onhelix-before-activate={(event) => setPane(event.detail.value)} />
 ```
 
-There is a real bug underneath this, and the elements work around it for you.
-**React attaches no custom element listener while hydrating**, so on a
-server-rendered page every one of these props is dead until React commits an
-update for some other reason, at which point it silently starts working. Nothing
-is logged. It is
-[facebook/react#35446](https://github.com/facebook/react/issues/35446), open and
-unfixed.
+React attaches no custom element listeners while it hydrates. On a
+server-rendered page, these props do nothing until React commits an update for
+some other reason. Then they start working, and nothing is logged either way.
+The bug is [facebook/react#35446](https://github.com/facebook/react/issues/35446),
+and it is still open. The elements work around it for you.
 
-Every Helix element binds the handler itself, immediately before it announces
-anything, using the function React is already holding for it. Measured in Chrome
-against React 19.2.8: on a hydrated page the first event reaches the handler,
-and it is never delivered twice once React binds its own listener.
+Every Helix element binds the handler itself, just before it dispatches any
+event, using the function React already holds for it. We measured this in
+Chrome against React 19.2.8. On a hydrated page, the first event reaches the
+handler. After React binds its own listener, no event is delivered twice.
 
-Nothing is required of you, and nothing changes once React fixes it.
+You do not need to do anything, and nothing changes when React fixes the bug.
 
-React's own events are unaffected where they bubble. `onClick` on a
-`<helix-button>` goes through the synthetic system, which hydration does set up.
+React's own events work when they bubble. `onClick` on a `<helix-button>` goes
+through React's synthetic event system, which hydration sets up.
 
-A few of ours are native events relayed from inside the component, and the ones
-that do not bubble (`load` and `error` on Avatar, `ended`, `play` and `pause` on
-Video) reach nothing React sets up. The elements bind those for you, so
-`onError` on a `<helix-avatar>` works like the rest.
+A few Helix events are native events relayed from inside the component. The ones
+that do not bubble never reach React's listeners:
 
-## The prop is `on` plus the event name
+- `load` and `error` on Avatar
+- `ended`, `play`, and `pause` on Video
 
-React slices `on` off the prop and listens for exactly what is left, without
-inspecting it.
+The elements bind these for you, so `onError` on a `<helix-avatar>` works like
+any other handler.
+
+## Write the prop as `on` plus the event name
+
+React removes `on` from the prop name and listens for exactly the rest, as
+written.
 
 - `onhelix-before-open` reaches `helix-before-open`. ✅
 - `onhelix-sample-start` reaches `helix-sample-start`. ✅
-- `onHelixOpen` binds an event called `HelixOpen`, which nobody dispatches. ❌
+- `onHelixOpen` binds an event called `HelixOpen`, which is never dispatched. ❌
 
-The number of hyphens does not matter, measured in Chrome against React 19.2.8.
+The number of hyphens does not matter. We measured this in Chrome against React
+19.2.8.
 
-## Register once, in a client component
+## Register the elements in one client component
 
-A custom element registers as a side effect of importing its module, and that
-import has to be in the client graph to ever run. A server component's imports
-do not ship to the browser. So one client component holds every element import
-and renders `null`:
+A custom element registers when you import its module. That import runs only if
+it is in the client graph, and a server component's imports do not ship to the
+browser. Put every element import in one client component that renders `null`:
 
 ```tsx
 'use client'
@@ -82,9 +83,9 @@ export function HelixElements(): null {
 ```
 
 Render it once in your layout. **Your pages stay server components.** An
-unregistered tag is just an unknown element in the HTML that upgrades when the
-definition lands. Asking you to mark every page `'use client'` to use a button
-would not be a design system.
+unregistered tag is an unknown element in the HTML, and it upgrades when the
+definition loads. You do not need to mark any page `'use client'` to use a
+button.
 
 ## Import `elements.css` beside the base layer
 
@@ -93,13 +94,13 @@ import '@fusion.dev/helix-styles/base.css'
 import '@fusion.dev/helix-styles/helix.css'
 ```
 
-It hides each tag with `:not(:defined)` until it upgrades, using `visibility` so
-the page does not reflow. Without it a card arrives as a run of unstyled text
-and then snaps into a card.
+`elements.css` hides each tag with `:not(:defined)` until the element upgrades.
+It uses `visibility`, so the page does not reflow. Without it, a card appears as
+unstyled text and then jumps into its card layout.
 
-It is generated from the element sources and enumerates the tags, because CSS
-cannot select "any custom element" and a bare `:not(:defined)` would also catch
-your framework's dev overlay.
+We generate the file from the element sources, and it lists every tag by name.
+CSS has no selector for any custom element, and a bare `:not(:defined)` would
+also hide your framework's development overlay.
 
 ## Import from subpaths
 
@@ -108,16 +109,20 @@ import '@fusion.dev/helix/card' // ✅ one family
 import '@fusion.dev/helix' // ❌ the barrel
 ```
 
-One family per module, so you are not shipping the library to use a button.
+Import one component family per module, so you do not ship the whole library to
+use a button.
 
 ## Declarative shadow DOM is opt-in
 
-The site ships no DSD, and the shadow styles arrive with the definition rather
-than in the markup. You don't need to configure anything for that. If you render
-with Lit SSR yourself, its declarative shadow DOM hydrates: see
+The site ships no declarative shadow DOM (DSD). The shadow styles load with the
+element definition. You do not need to configure anything. If you render with
+Lit SSR yourself, its declarative shadow DOM hydrates. See
 [Server rendering](./server-rendering).
 
-The short version of why: DSD cannot activate for script-inserted nodes, a
-server component's output is replayed from the flight payload through DOM APIs
-rather than re-run, and the patch that made it work hooked webpack, which
-Turbopack ignores, silently.
+The site ships no DSD for three reasons:
+
+- DSD cannot activate for nodes inserted by script.
+- React inserts a server component's output by replaying the flight payload
+  through DOM APIs, without running the component again.
+- The patch that made DSD work hooked into webpack, and Turbopack ignores that
+  hook without an error.

package/content/versioning.mdx

@@ -1,5 +1,5 @@
 ---
-description: What a version number means here, and which packages move together.
+description: What a Helix version number means, and which packages are released together.
 order: 6
 section: Getting started
 title: Versioning
@@ -8,65 +8,72 @@ title: Versioning
 # Versioning
 
 **Every Helix package shares one version.** `@fusion.dev/helix@1.4.0` works with
-`@fusion.dev/helix-headless@1.4.0` and with `@fusion.dev/helix-styles@1.4.0`, and that is a
-guarantee rather than a coincidence: they are released together, always, from
-one tag.
+`@fusion.dev/helix-headless@1.4.0` and with `@fusion.dev/helix-styles@1.4.0`.
+This is guaranteed, because we always release them together, from one tag.
 
 ```sh
 bun add @fusion.dev/helix@1.4.0 @fusion.dev/helix-styles@1.4.0
 ```
 
-Pin them to the same number or pin none of them. A range that lets one drift
-ahead of another is the one configuration this scheme does not defend against.
+Pin every Helix package to the same version, or pin none of them. The one setup
+this versioning does not protect you from is a range that lets one package move
+ahead of another.
 
-## Why lockstep
+## Why Helix packages share one version
 
-Cortex moves independently. Full-repo lockstep would be wrong here because the
-documentation packages carry the version of what they document: publishing a
-Cortex fix would bump `@fusion.dev/helix-docs` to a version in which nothing about Helix
-changed.
+Cortex has its own version. We did not give every package in the repository one
+version, because the documentation packages carry the version of what they
+document. With one version for everything, a Cortex fix would publish a new
+version of `@fusion.dev/helix-docs` in which nothing about Helix changed.
 
-Per-domain lockstep keeps the property that matters, which is that two Helix
-packages of the same version are the pair that was tested together.
+One version for Helix keeps the property that matters. Two Helix packages with
+the same version were tested together.
 
-## The version lives in the tag
+## The version number comes from the Git tag
 
-Every manifest in the repository holds `0.0.0-dev`. The real number is stamped
-in CI, seconds before packing.
+Every manifest in the repository has the version `0.0.0-dev`. CI writes the real
+number into each manifest seconds before packing.
 
-If you read the source: a manifest saying `0.0.0-dev` is not an unreleased
-package, it is every package. Committing the number back
-would need a bot whose push access outranks branch protection, to record
-something `git tag` already holds.
+If you read the source, you will see `0.0.0-dev` on every package, including
+released ones. We do not commit the real number back. That would need a bot
+with push access that overrides branch protection, and `git tag` already records
+the number.
 
-Two tag shapes, and the second is the useful one:
+Releases use two kinds of tag:
 
 | Tag | Means |
 |---|---|
 | `helix-v1.4.0` | A release that promoted |
 | `helix-attempt-v1.4.0` | A number that was spent and did not ship |
 
-Version computation reads both, so a failed release burns a number rather than
-poisoning the next one. If you see 1.4.0 skipped, that is what happened.
+The next version is computed from both kinds of tag. A failed release uses up
+its number, and the next release gets a new one. If you see that 1.4.0 was
+skipped, a release with that number failed.
 
 ## Documentation is versioned with the code
 
-`@fusion.dev/helix-docs@1.4.0` documents Helix 1.4.0. There is no version axis inside
-the package and no version switcher in it: the package version *is* the version,
-because every package in the domain moves together.
+`@fusion.dev/helix-docs@1.4.0` documents Helix 1.4.0. The package documents one
+version and has no version switcher. Its version number is the Helix version it
+documents, because every Helix package shares one version.
 
-A site serving several versions installs several versions, which is the
-mechanism npm already provides and the only one that cannot drift.
+To serve documentation for several versions, install several versions of the
+package. npm already supports this, and it is the only approach that cannot fall
+out of step with the code.
 
 ## Stability
 
-Components carry a `status` in the manifest and on their page: `experimental`,
-`stable`, or `deprecated`. Most of the library is experimental today and says
-so. That label is the honest one and it will not be softened to make the set
-look more finished than it is.
+Each component has a `status` in the manifest and on its page. The status is
+one of:
+
+- `experimental`
+- `stable`
+- `deprecated`
+
+Most components are experimental today, and their status says so. We will not
+change a status to make the library look more finished than it is.
 
 ## Release notes
 
-On GitHub, generated from the tags. There is no changelog file in this package,
-because a second copy of the release notes is a second thing to keep in step and
-the one that goes stale is the one nobody is reading that week.
+Release notes are on GitHub, generated from the tags. Helix has no changelog
+file. A second copy of the release notes would have to be kept in step
+with the first, and the copy nobody reads that week is the one that goes stale.