@fusion.dev/helix-docs 0.23.0 → 0.24.1

package/content/react.mdx

@@ -132,7 +132,7 @@ 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
+## 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

package/content/recipes.mdx

@@ -100,6 +100,17 @@ scroll pays continuously. Where the effect is about depth rather than texture,
 Headings take the type scale, paragraphs take the measure and leading, lists and
 links and inline code all follow. See [Typography](./typography).
 
+If you own the markdown renderer, map two things to components, because markup
+can't carry 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.
+- **Alerts** such as `> [!WARNING]` to `helix-callout`. A `<blockquote>` has no
+  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.
+
 ## Region axes
 
 These two are API rather than styling, and they are the reason the base layer is

package/content/server-rendering.mdx

@@ -36,8 +36,61 @@ 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.
 
-**Anything that inspects the tree runs in `firstUpdated` or later**, and is
-therefore a client-side enhancement by definition.
+**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.
+
+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.
+
+## Declarative shadow DOM
+
+If you render with Lit SSR, its declarative shadow DOM hydrates. 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:
+
+- `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.
+
+Two things the platform does before any script can listen, and how components
+answer them:
+
+- **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.
+
+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.
+
+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.
+
+`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).
 
 ## Never initialize state in `connectedCallback`
 

package/content/using-the-elements.mdx

@@ -110,12 +110,12 @@ import '@fusion.dev/helix' // ❌ the barrel
 
 One family per module, so you are not shipping the library to use a button.
 
-## There is no declarative shadow DOM
+## Declarative shadow DOM is opt-in
 
-Components render on the server through Lit SSR in our own tests, but the app
-ships no DSD, and the shadow styles arrive with the definition rather than in
-the markup. You do not need to configure anything for this; it is here so the
-absence is not mistaken for something missing.
+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
+[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

package/content/visual-axes.mdx

@@ -11,7 +11,7 @@ vocabularies. You cannot invent a value, and a component may take a subset.
 
 | Axis | Values |
 |---|---|
-| `emphasis` | `ghost`, `outlined`, `solid`, `subtle` |
+| `emphasis` | `ghost`, `muted`, `outlined`, `solid`, `subtle` |
 | `material` | `frosted`, `glass`, `transparent` |
 | `separation` | `elevated`, `filled`, `outlined`, `plain` |
 | `tone` | The status and intent words: `primary`, `accent`, `neutral`, `danger`, and so on |