@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/server-rendering.mdx

@@ -1,24 +1,23 @@
 ---
-description: What renders without a DOM, and what has to wait for one.
+description: How components render on a server with no DOM, and what waits for the browser.
 section: Essentials
 title: Server rendering
 ---
 
 # Server rendering
 
-Every component renders on a server with no DOM. If you are only consuming
-Helix, the practical consequence is small: components work in your server
-components and there is nothing to configure. If you are extending one, the
-rules below are the whole contract.
+Every component renders on a server with no DOM. If you only use Helix
+components, they work in your server components with no configuration. If you
+extend a component, follow the rules below. They are the complete set.
 
-## There is no DOM
+## The server has no DOM
 
-Lit's element shim carries attributes. It does not carry a tree. `querySelector`
-is undefined, `this.children` is undefined, and anything that walks the DOM
-throws while rendering.
+Lit's element shim has attributes and no element tree. `querySelector` and
+`this.children` are undefined, and any code that walks the DOM throws during
+rendering.
 
-Two real examples from this library, both found the first time their component
-was given a server spec:
+We found these two examples in Helix the first time each component got a server
+spec:
 
 ```ts
 // Select. `display` is read during render and reached the render root.
@@ -32,70 +31,71 @@ get hasSubmenu(): boolean {
 }
 ```
 
-Before those two guards, neither component could be server-rendered at all. Both
-looked correct in every browser, because the client always has a root and always
-has a tree.
+Before we added those two guards, neither component could render on a server.
+Both worked in every browser, because a browser always has a render root and an
+element tree.
 
-**Anything that inspects the tree reads it through `this.knownChildren`**, in
-`willUpdate` or in a getter the render calls. It is every child on a client and
-none on a server, so the server renders "not known yet" and the client's first
-render already has the answer. Reading after the render instead means two
-renders on every client, which Lit's dev build warns about.
+**Read the element tree through `this.knownChildren`**, in `willUpdate` or in a
+getter that the render calls. On a client it holds every child, and on a server
+it holds none. The server renders the "not known yet" state, and the client's
+first render already has the children. If you read the tree after the render,
+every client renders twice, and Lit's dev build warns about that.
 
-Not known is not empty. `this.childrenKnown` is false on a server, and a list
-there doesn't render its "Nothing to show" over items it can't see.
+`this.childrenKnown` is false on a server, where the children cannot be read. A
+list on a server therefore does not render its "Nothing to show" message over
+items it cannot see.
 
 ## Declarative shadow DOM
 
-If you render with Lit SSR, its declarative shadow DOM hydrates. Load Lit's
-hydration support before the components:
+If you render with Lit SSR, the declarative shadow DOM it writes hydrates in the
+browser. Load Lit's hydration support before the components:
 
 ```ts
 import '@lit-labs/ssr-client/lit-element-hydrate-support.js'
 import '@fusion.dev/helix'
 ```
 
-Hydration assumes the markup already shows the client's first render. A value
-that differs is never written, so the page keeps the server's, and a template
-that differs throws. So while hydrating, a component renders exactly what the
-server did, and anything it could only learn in a browser waits for the update
-after:
+Hydration assumes the markup already matches the client's first render. If a
+value differs, hydration does not write it, and the page keeps the server's
+value. If a template differs, hydration throws. While hydrating, a component
+renders exactly what the server rendered. Anything it can read only in a browser
+waits for the next update:
 
 - `this.hydrating` is true for the render that hydrates.
 - `this.knownChildren` is empty during it, as on the server.
-- `this.finishHydration()`, called from `firstUpdated`, asks for the update that
-  reads what was skipped.
+- `this.finishHydration()`, called from `firstUpdated`, requests the update
+  that reads what was skipped.
 
-Two things the platform does before any script can listen, and how components
-answer them:
+The browser does two things before any script can listen. Components handle
+them this way:
 
 - **A declarative shadow root reports its slots as it is parsed.** A component
-  never learns what's slotted from `slotchange` alone. It reads its children
-  first and uses `slotchange` for later changes.
-- **The parser fetches images.** A `load` or `error` can fire before hydration,
-  so a component asks the image what happened (`this.serverRendered`) and relays
-  the event a task later.
+  does not rely on `slotchange` alone to find what is slotted. It reads its
+  children first and uses `slotchange` for later changes.
+- **The parser fetches images.** A `load` or `error` event can fire before
+  hydration. A component checks the state of the image (`this.serverRendered`)
+  and dispatches the event again a task later.
 
-A component that assigns its slots by hand gets a root that can only assign by
-name, because HTML can't declare manual assignment. On such a root
-(`this.assignsByName`) it writes `slot` onto its children with `this.route()`,
-and only there.
+HTML cannot declare manual slot assignment. A component that assigns its slots
+by hand therefore gets a root that can assign only by name. On such a root
+(`this.assignsByName`), and only there, the component writes `slot` onto its
+children with `this.route()`.
 
-A page's own scripts should run after the definitions load. That's the order
-hydration expects: a property set before hydration is one the server never
-rendered with.
+Run your page's own scripts after the definitions load. Hydration expects that
+order. A property you set before hydration is one the server did not render
+with.
 
 `bun run check:spec:dsd` renders every example with Lit SSR, hydrates it in
 Chromium, and compares it with the same example rendered on a client.
 
-React server components don't use any of this. Their output is replayed through
-DOM APIs, and DSD doesn't activate for nodes a script inserts. See
-[React](./react).
+React server components do not use declarative shadow DOM. Their output is
+replayed through DOM APIs, and declarative shadow DOM does not activate for
+nodes that a script inserts. See [React](./react).
 
 ## Never initialize state in `connectedCallback`
 
-SSR does not call it. Derive from properties, or seed in `willUpdate`, which SSR
-does call.
+SSR does not call `connectedCallback`. Derive state from properties, or set
+initial state in `willUpdate`, which SSR calls.
 
 ## Guard generated ids
 
@@ -105,50 +105,61 @@ if (!this.id) {
 }
 ```
 
-The server writes the id into the HTML; the client sees it present and skips
-generating a new one, so both agree. Without the guard they disagree and the
-association breaks on hydration.
+The server writes the id into the HTML. On the client, the id is already
+present, so the component does not generate a new one, and both ids match.
+Without the guard, the ids differ, and the association breaks on hydration.
 
-## Semantics on the host, presentation in the shadow root
+## Put semantics on the host and presentation in the shadow root
 
 IDREFs do not cross shadow boundaries, so `aria-labelledby` inside a shadow root
-can never resolve to a light-DOM id. Use `ElementInternals`, which writes no
-attribute at all, so the host stays exactly as you wrote it and hydration has
-nothing to disagree about.
-
-**Labels are the case that catches people.** `<label for>` cannot reach into a
-shadow root either, which is why a field's label is rendered *inside* the
-control rather than by anything wrapping it, and why a wrapping "form field"
-component cannot own the label without handing it down as a property. It is also
-why `aria-label` on a host has to be forwarded rather than left where it was
-written. See [Composition](./composition).
-
-Where an id genuinely cannot reach, **element references can**, and they resolve
-outward: an element in a shadow root may point at one in the light DOM.
-`Listbox` uses that for `aria-activedescendant`, because its options are your
-elements and the element that takes focus is in its shadow root. Feature-test
-them: assigning to a property an engine does not implement is a no-op rather
-than an error.
-
-## A child announces itself to its parent
+cannot resolve to a light-DOM id. Use `ElementInternals`. It writes no
+attributes, so the host stays exactly as you wrote it, and hydration finds no
+difference.
+
+Labels have the same problem. `<label for>` cannot reach into a shadow root
+either. For that reason:
+
+- A field's label is rendered *inside* the control, and no wrapping element
+  renders it.
+- A wrapping "form field" component can own the label only by passing it down
+  as a property.
+- `aria-label` on a host has to be forwarded from where you wrote it.
+
+See [Composition](./composition).
+
+Where an id cannot reach, use an element reference. Element references resolve
+outward, so an element in a shadow root can point at an element in the light
+DOM. `Listbox` uses one for `aria-activedescendant`, because its options are
+your elements and the element that takes focus is in its shadow root. Test for
+support before you use element references. Assigning to a property that an
+engine does not implement does nothing and throws no error.
+
+## A child dispatches a ready event to its parent
 
 A parent cannot poll for a child that has not upgraded yet. The child dispatches
-a bubbling ready event and the parent listens.
+a bubbling ready event, and the parent listens for it.
 
-## Writing a server spec
+## Write a server spec
 
-Every component has a `*.ssr.spec.ts`, and there is one rule about them worth
-repeating, because it has produced a false pass twice:
+Every component has a `*.ssr.spec.ts` file. Breaking one rule for these specs
+has produced a false pass twice:
 
 **Never assert structure against the raw SSR string.** Declarative shadow DOM
-inlines the component's stylesheet into the very markup being asserted, and that
-stylesheet names every part, host attribute and token the component uses. So
-`toContain('part="media"')` passes on a *selector*, and
-`not.toContain('data-scrolled')` fails on a `:host([data-scrolled])` *rule*,
-both saying nothing about what rendered.
-
-Use the helpers: `withoutStyles`, `hasPart`, `partTag`, `hostTag`. And match
-attribute bindings with a pattern, since they render across several lines:
+inlines the component's stylesheet into the markup you assert against. That
+stylesheet names every part, host attribute, and token the component uses.
+`toContain('part="media"')` can pass because of a *selector*, and
+`not.toContain('data-scrolled')` can fail because of a `:host([data-scrolled])`
+*rule*. Neither result tells you what rendered.
+
+Use these helpers:
+
+- `withoutStyles`
+- `hasPart`
+- `partTag`
+- `hostTag`
+
+Match attribute bindings with a pattern, because they render across several
+lines:
 
 ```ts
 expect(markup).toMatch(/<a\s+part="button"/) // ✅

package/content/shape-and-borders.mdx

@@ -1,5 +1,5 @@
 ---
-description: Five radii, two widths, and the two tokens that are a policy rather than a value.
+description: The corner radius and border width tokens, and how a theme changes them.
 section: Foundations
 title: Shape and borders
 ---
@@ -20,12 +20,11 @@ title: Shape and borders
 
 [//]: # (/tokens)
 
-`full` is `9999px` rather than `50%`, which matters for anything that is not
-square: a percentage radius on a wide element gives an ellipse, and a pill is
-what you wanted.
+`full` is `9999px`, which gives a pill shape on an element that is not square.
+A percentage radius such as `50%` gives an ellipse on a wide element.
 
-Rounding is the fastest single change to how a system feels, and it is one
-token, but it is the **seed** rather than one of the four above:
+Changing the rounding is the quickest way to change how your interface looks.
+You change it with one token, the seed:
 
 ```css
 :root {
@@ -33,25 +32,32 @@ token, but it is the **seed** rather than one of the four above:
 }
 ```
 
-That makes every card, dialog, input and button squarer at once, because `sm`,
-`md` and `lg` are all derived from it: they become 1px, 2px and 3px. The theme
-engine takes a `radius` intent input for exactly this reason. See [Deriving a
-theme](./theming).
+This makes every card, dialog, input, and button squarer at once, because `sm`,
+`md`, and `lg` are all computed from the seed. With this seed, they become 1px,
+2px, and 3px. The theme engine has a `radius` intent input for the same purpose.
+See [Deriving a theme](./theming).
 
-**Setting `--helix-radii-md` instead moves only what reads `md`**, which is
-neither the buttons, the inputs and the dialogs (`sm`) nor the cards (`lg`).
-The four rungs are siblings derived from the seed, not a chain, so overriding
-one is how you change a single step on purpose rather than how you reshape a
-system.
+Setting `--helix-radii-md` changes only what uses `md`. Buttons, inputs, and
+dialogs use `sm`, and cards use `lg`, so none of them change. Each step is
+computed from the seed on its own, so overriding one step changes only that
+step. To change the rounding everywhere, set the seed.
 
-**Every floating panel takes `sm`.** A dialog, a drawer, a menu, a popover, a
-tooltip, a toast, and the panel any field opens under itself: all the same
-corner, whatever the panel's size. A radius is read against the corner beside it
-rather than against the area behind it.
+**Every floating panel uses `sm`.** This includes:
 
-**A shape that is round rather than softened does not use these.** An avatar, a
-loader and a radio are circles because of what they are, so they say `50%`
-directly and are unaffected by a theme that squares everything else off.
+- dialogs
+- drawers
+- menus
+- popovers
+- tooltips
+- toasts
+- the panel a field opens below itself
+
+They all have the same corner, whatever their size. You compare a radius with
+the corners next to it, so the size of the panel does not matter.
+
+Circles do not use these tokens. An avatar, a loader, and a radio are circles by
+design, so they set `50%` directly. A theme that squares off everything else
+does not change them.
 
 ## Border widths
 
@@ -66,26 +72,27 @@ directly and are unaffected by a theme that squares everything else off.
 
 [//]: # (/tokens)
 
-The first two are values you pick. **The second two are a decision**, and they
-belong to [Surfaces and separation](./surfaces-and-separation): they are what a
-theme sets to zero to go shadow-first, or to a width to go border-first.
+You pick from the first two. The last two are policy tokens, described in
+[Surfaces and separation](./surfaces-and-separation). A theme sets them to zero
+to go shadow-first, or to a width to go border-first.
 
-This distinction is why a component's border width sits behind a per-component
-hook rather than being written inline. A width written inline can be recolored
-by a theme and never removed, and a hardcoded `border: none` can never have one
-added back, so a surface themes perfectly in one direction and not at all in the
-other.
+For this reason, each component reads its border width from its own hook. A
+theme can recolor a width written inline but cannot remove it. A theme also
+cannot add a border back to a component that sets `border: none`. In both
+cases, the surface can be themed in one direction only.
 
-## Corner radius on a group
+## Corners in a group of controls
 
-Adjacent controls in a group flatten the corners between them, so a button group
-reads as one shape rather than three:
+Controls next to each other in a group have flat corners where they meet, so a
+button group looks like one shape:
 
 ```css
 [data-button]:not(:first-child) { border-start-start-radius: 0; }
 ```
 
-The base layer does this for the recipes, and the components do it for
-themselves. If you build your own group: it is the inner corners that go flat,
-not the outer ones, and it is `border-start-start-radius` rather than
-`border-top-left-radius` so it follows the writing direction.
+The base layer does this for the recipes, and each component does it for
+itself. If you build your own group:
+
+- Flatten the inner corners, and keep the outer corners rounded.
+- Use `border-start-start-radius`, which follows the writing direction.
+  `border-top-left-radius` does not.

package/content/size-and-density.mdx

@@ -1,5 +1,5 @@
 ---
-description: Why no control has a size, and what to write instead.
+description: Controls take their height from the density of the region they are in. Set the density once on the region.
 section: Theming
 title: Size and density
 ---
@@ -17,47 +17,46 @@ title: Size and density
 </helix-flex>
 ```
 
-There is no `size` prop on a button, an input, a select or a checkbox. That
-looks like a restriction and is not one.
+Buttons, inputs, selects, and checkboxes have no `size` prop.
 
-## Size does three jobs
+## What size is used for
 
-**Emphasis.** The `emphasis` axis carries it. A filled primary button says "this one
-matters" far louder than eight more pixels ever will.
+Size does three jobs:
 
-**Fit.** This is a fact about the region rather than about the control. A
-toolbar is tight, a hero is spacious, a table row is tighter still. The control
-does not know which it is in; the region does.
+- Emphasis shows which control matters most. The `emphasis` axis sets it. A
+  filled primary button marks the important action much more clearly than eight
+  more pixels of height.
+- Fit depends on the region. A toolbar is tight, a hero is spacious, and a table
+  row is tighter still. The region sets the fit for every control in it.
+- Optical role applies only to things that are not controls. An avatar at 24 in
+  a list and at 96 on a profile are two different pictures. That is why
+  `Avatar`, `Loader`, and `Orb` keep a `size`.
 
-**Optical role.** Real, and only for things that are not controls. An avatar at
-24 in a list and 96 on a profile is a different graphic, not a taller control.
-That is why `size` survives on `Avatar`, `Loader` and `Orb`: those are
-pictures.
+## Can two controls differ in height?
 
-## The test that settles it
+Ask whether two controls placed together can ever differ in height:
 
-*Can two controls sitting together legitimately differ in height?*
+- Save and Cancel
+- An icon button beside a text button
+- An input and its submit button
+- The two halves of a split button
 
-Save and Cancel. An icon button beside a text button. An input and its submit.
-The two halves of a split button. In every case the answer is no.
+In every case the answer is no.
 
-So a per-instance size is only ever used to say something about the **region**,
-one element at a time, which is exactly how a row ends up with one member the
-wrong height. Said once on the region, a ragged row is not discouraged. It is
-unwritable.
+A size on each control describes the **region**, one element at a time, and
+that is how a row ends up with one control at the wrong height. When you set the
+density once on the region, you cannot write a row of mismatched heights.
 
-`Dialog` keeps a `size` by the same test read from the other end. Two dialogs
-never sit together: one is on screen at a time, in the top layer, so it *is* the
-region rather than a control in one.
+`Dialog` keeps a `size` by the same test. Two dialogs never sit together. One is
+on screen at a time, in the top layer, so the dialog is itself the region.
 
-That is also what makes this safe for anything generating code, whether that is
-a person or a model: there is no size to get wrong, and one question to ask per
-region instead of one per element.
+This also helps when you or a model generate code. There is no size to get wrong
+on each element, and you make one choice for each region.
 
-## How to use it
+## Set the density of a region
 
-Put `data-density` on any container. `sm`, `md` or `lg`. `md` is the default and
-is never written.
+Put `data-density` on any container, with a value of `sm`, `md`, or `lg`. `md`
+is the default, so you never write it.
 
 ```html
 <helix-toolbar>
@@ -67,24 +66,30 @@ is never written.
 </helix-toolbar>
 ```
 
-**Containers that are dense by nature declare it themselves.** The app header,
-the toolbar and the announcement all do, so a control put in one is already the
-right height without anybody deciding.
+Containers that are dense by design set their own density. The app header, the
+toolbar, and the announcement all do, so a control inside one of them is already
+the right height.
 
-It works through custom properties (`--helix-size-control`,
-`--helix-size-checkbox`, `--helix-size-switch`, `--helix-size-tag`), which is
-why it costs no component any API and crosses every shadow boundary on its own.
+Density works through these custom properties:
 
-The `-sm` / `-md` / `-lg` tokens are the scale and never move. The unsuffixed
-ones are the current step, and `data-density` is what moves them.
+- `--helix-size-control`
+- `--helix-size-checkbox`
+- `--helix-size-switch`
+- `--helix-size-tag`
 
-## What this is not
+Because of this, density adds no API to any component, and it passes through
+every shadow boundary.
 
-**`data-link-size` stays.** A text link has no control height: its size is
-typography, and it follows the text around it.
+The `-sm`, `-md`, and `-lg` tokens are the scale, and they never change. The
+unsuffixed tokens hold the current step, and `data-density` changes them.
 
-**A control may still declare its own scale.** `--helix-size-switch` is one step
-above `--helix-size-checkbox` at every density, because a switch is a track with
-a thumb inside it and a checkbox is a box with a mark in it. That is the
-component choosing where it sits on the scale, once, for everyone. It is not the
-same thing as a consumer setting a height per instance.
+## Exceptions
+
+`data-link-size` still exists. A text link has no control height. Its size comes
+from typography, and it follows the text around it.
+
+A component can still set its own step on the scale. `--helix-size-switch` is
+one step above `--helix-size-checkbox` at every density, because a switch is a
+track with a thumb inside it and a checkbox is a box with a mark in it. The
+component sets this once, and it applies to every instance. You do not set a
+height on each instance.

package/content/space-and-size.mdx

@@ -1,14 +1,14 @@
 ---
-description: One spacing scale, and why a control's height is not on it.
+description: Use the space scale for gaps and the size tokens for the height of controls.
 section: Foundations
 title: Space and size
 ---
 
 # Space and size
 
-Two scales that look similar and answer different questions. Space is the gaps
-between things. Size is how big a control is. Mixing them is how a layout ends
-up with a button that is one step of padding taller than the input beside it.
+Helix has two scales. The space scale sets the gaps between things. The size
+scale sets how big a control is. If you use one for the other, a button can end
+up one step of padding taller than the input beside it.
 
 ## Space
 
@@ -29,15 +29,16 @@ up with a button that is one step of padding taller than the input beside it.
 
 [//]: # (/tokens)
 
-Nine steps, t-shirt named rather than numbered. A numbered scale invites
-arithmetic (`space-4` is twice `space-2`) which stops being true the moment the
-scale is tuned, and invites a `space-4.5` the first time something does not fit.
+The scale has nine steps, named like t-shirt sizes. Numbered steps suggest
+arithmetic, such as `space-4` being twice `space-2`. That stops being true as
+soon as the scale is tuned, and it leads to a `space-4.5` the first time
+something does not fit.
 
-`--helix-space-control` is the tenth and is different in kind: it is the inset a
-control uses, and it follows the region's density rather than sitting on the
+`--helix-space-control` is a tenth token of a different kind. It is the inset a
+control uses, and it follows the region's density. It is not a step on the
 scale. See [Size and density](./size-and-density).
 
-Use them for gap, padding and margin:
+Use the space tokens for gap, padding, and margin:
 
 ```css
 .toolbar {
@@ -49,24 +50,31 @@ Use them for gap, padding and margin:
 
 ## Size
 
-Forty-one tokens, and almost all of them name a specific thing:
-`--helix-size-control`, `--helix-size-checkbox`, `--helix-size-switch`,
-`--helix-size-avatar`, `--helix-size-icon`, `--helix-size-tag`,
-`--helix-size-header`, `--helix-size-progress`, `--helix-size-meter`.
+The size scale has forty-one tokens, and almost all of them name a specific
+thing:
 
-Most come in a `-sm`, `-md` and `-lg` set beside the unsuffixed one. **The
-unsuffixed token is the live one** and the suffixed ones are the values the
-density axis picks between. The loader is the exception: it has `-sm`, `-md`
-and `-lg` and no unsuffixed token above them, because nothing reads a loader's
-size off the density. So a component reads `--helix-size-control` and the
-region's `[data-density]` decides which of `-sm`, `-md` or `-lg` that resolves
-to.
+- `--helix-size-control`
+- `--helix-size-checkbox`
+- `--helix-size-switch`
+- `--helix-size-avatar`
+- `--helix-size-icon`
+- `--helix-size-tag`
+- `--helix-size-header`
+- `--helix-size-progress`
+- `--helix-size-meter`
 
-That is why a component has no `size` property: the answer is the region's, and
-saying it once there means a ragged row is not merely discouraged, it is
-unwritable.
+Most come in a `-sm`, `-md`, and `-lg` set beside the unsuffixed token. **The
+unsuffixed token is the live one.** The suffixed tokens are the values the
+density axis picks between. A component reads `--helix-size-control`, and the
+region's `[data-density]` sets whether that resolves to `-sm`, `-md`, or `-lg`.
 
-## The focus ring is three tokens
+The loader is the exception. It has `-sm`, `-md`, and `-lg` and no unsuffixed
+token, because nothing reads a loader's size from the density.
+
+This is why a component has no `size` property. The region sets the size once,
+so you cannot write a row of controls with different heights.
+
+## Focus ring tokens
 
 ```
 --helix-size-focus-ring     the ring's own thickness
@@ -74,16 +82,15 @@ unwritable.
 --helix-size-focus-reach    ring plus offset, for reserving room
 ```
 
-The third exists because a ring drawn outside a control needs room, and every
-component that draws one otherwise recomputes the sum. Reserve with `reach`,
-draw with the other two.
+A ring drawn outside a control needs room. `--helix-size-focus-reach` holds that
+sum, so each component that draws a ring does not compute it again. Use `reach`
+to reserve the room, and the other two to draw the ring.
 
 ## What not to do
 
-**Do not use a size token for a gap.** `--helix-size-control` is a height, and a
-layout that uses it as a gap changes meaning the day a density changes under it.
+**Do not use a size token for a gap.** `--helix-size-control` is a height. A gap
+that uses it changes when the region's density changes.
 
-**Do not use a raw value because the scale has no step for it.** If a gap is
-genuinely between `sm` and `md`, say so rather than writing `11px`: it is
-usually a sign the two things being separated belong at different levels of the
-layout.
+**Do not use a raw value when the scale has no step for it.** If a gap really
+falls between `sm` and `md`, note it and do not write `11px`. It usually means
+the two things it separates belong at different levels of the layout.