@fusion.dev/helix-docs 0.142.1 → 0.143.0

package/content/other-frameworks.mdx

@@ -65,9 +65,10 @@ it.
 ## Register the elements
 
 ```ts
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/button'
+import '@fusion.dev/helix/dialog'
 ```
 
-Import it once, anywhere that runs in the browser. The stylesheets are the same
+Import each family you use once, anywhere that runs in the browser. The stylesheets are the same
 in every framework, and they are the part most often left out. See
 [Installation](./installation) for the stylesheets.

package/content/overlays.mdx

@@ -70,13 +70,27 @@ checks focus by walking through the shadow roots.
 Nested overlays work because lifecycle events do not bubble.
 `helix-before-open` and `helix-before-close` do not bubble and are not composed,
 so a menu that closes inside a dialog does not close the dialog. `Escape` closes
-the innermost overlay and leaves the others open.
+the innermost overlay and leaves the others open. The overlay that closes
+cancels the key press, so a `Dialog` or `Drawer` around it stays open until you
+press `Escape` again.
 
 ## Where focus goes
 
 A modal overlay keeps `Tab` inside itself while it is open, and it returns focus
-to the element that opened it. `Dialog` and `Drawer` always do this. `Popover`
-does it only in its modal mode.
+to the element that opened it. `Dialog` does this, and so does `Drawer` unless
+you set `modal="false"`. The page behind a modal `Dialog` or `Drawer` does not
+scroll while it is open.
+
+`Popover` does not trap focus. When focus moves out of its trigger and its
+panel, the popover closes.
+
+The fields with a panel behave the same way:
+
+- `Select` and `Combobox` close their list when `Tab` moves focus out.
+- `Date Input`, `Time Input`, and `Color Input` close their panel when focus
+  leaves the field, and `Escape` returns focus to the field.
+- Opening one of those panels from its trigger, or with `ArrowDown`, moves
+  focus into the panel.
 
 **A tooltip never takes focus.** A tooltip only describes a control, so it
 cannot contain a button. For something with a button in it, use a `Popover`.

package/content/react.mdx

@@ -131,7 +131,9 @@ See [State and control](./state-and-control) for the full model.
 
 ```tsx
 'use client'
-import '@fusion.dev/helix'
+// One line per family you use.
+import '@fusion.dev/helix/button'
+import '@fusion.dev/helix/dialog'
 
 export const HelixElements = () => null
 ```

package/content/sandbox.mdx

@@ -41,20 +41,84 @@ without tracking which element sent each event. A pane named `html` sets the
 preview's markup, and a pane named `css` sets its stylesheet. The sandbox
 ignores a pane with any other name, so that pane only displays its contents.
 
+A pane's text goes in its `value`. The pane renders no children. The sandbox
+also hands each pane's `value` to the preview when it starts, so you write the
+text once, in the pane. A preview given its own `source` keeps it until the
+first edit.
+
 ```html
 <helix-sandbox>
   <helix-sandbox-source
     name="html"
     slot="source"
-  >…</helix-sandbox-source>
+    value="<p>Hello</p>"
+  ></helix-sandbox-source>
   <helix-sandbox-source
     name="css"
     slot="source"
-  >…</helix-sandbox-source>
-  <helix-sandbox-preview slot="preview"></helix-sandbox-preview>
+    value="p { color: teal }"
+  ></helix-sandbox-source>
+  <helix-sandbox-preview
+    slot="preview"
+    src="/frame.html"
+  ></helix-sandbox-preview>
 </helix-sandbox>
 ```
 
+Cancel `helix-before-edit` to refuse an edit. The pane keeps its text, and the
+preview does not receive the refused one.
+
+In a source pane, Tab inserts two spaces. Shift+Tab moves focus back, and
+Escape then Tab moves it forward. The field's description says this to a
+screen reader.
+
+## The frame document
+
+`helix-sandbox-preview` loads `src` into a sandboxed frame. You provide that
+document. It loads the styles and the elements your examples use, and it talks
+to the preview through `postMessage`:
+
+| Message | Sent by | What it carries |
+|---|---|---|
+| `helix-preview-console` | The frame | One console call: `level` (`log`, `info`, `warn` or `error`) and `text` |
+| `helix-preview-press` | The frame | Nothing. Send it on `pointerdown`, so menus outside the frame close |
+| `helix-preview-ready` | The frame | Nothing. Send it once the listener for renders is in place |
+| `helix-preview-render` | The preview | `source`, `styles`, `layout`, `direction` and an optional `colorMode` |
+| `helix-preview-size` | The frame | `size`, the height of the content in CSS pixels |
+
+Each message is an object with a `type` naming it. The preview sends
+`helix-preview-render` once the frame posts `helix-preview-ready` or fires
+`load`, and again after each edit settles. The frame writes `source` into its
+body and `styles` into a stylesheet. The preview accepts a message only from
+its own frame, and only from an opaque origin, so the frame keeps the sandbox
+it was given. The types are exported from `@fusion.dev/helix/sandbox` as
+`PreviewMessage` and its members.
+
+A minimal frame follows. `/helix.css` is the stylesheet from
+`@fusion.dev/helix-styles`, and `/elements.js` is a classic script that
+registers your elements, for the reason under "How the preview is isolated".
+
+```html
+<!doctype html>
+<link
+  href="/helix.css"
+  rel="stylesheet"
+>
+<script
+  defer
+  src="/elements.js"
+></script>
+<style id="example-styles"></style>
+<script defer>
+  addEventListener('message', ({ data }) => {
+    if (data?.type !== 'helix-preview-render') return
+    document.getElementById('example-styles').textContent = data.styles
+    document.body.innerHTML = data.source
+  })
+  parent.postMessage({ type: 'helix-preview-ready' }, '*')
+</script>
+```
+
 ## Console output from the example
 
 Logs from the example appear in the console panel. Logs from the page around it

package/content/server-rendering.mdx

@@ -52,7 +52,7 @@ browser. Load Lit's hydration support before the components:
 
 ```ts
 import '@lit-labs/ssr-client/lit-element-hydrate-support.js'
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/button'
 ```
 
 Hydration assumes the markup already matches the client's first render. If a

package/content/state-and-control.mdx

@@ -106,6 +106,12 @@ current value. The pair comes from the platform. A native input reflects its
 `value` *content attribute* to `defaultValue`, and it keeps a dirty flag. Once a
 user has typed, the flag stops the attribute from changing the value.
 
+**A form reset clears a `value` or `checked` you wrote in markup.** A native
+`<input value="Ada">` resets to `Ada`, and `<helix-input value="Ada">` resets to
+empty, because a Helix control resets to `default-value` and `default-checked`.
+Write the starting value of a form control as `default-value`, or
+`default-checked` for a checkbox or a switch.
+
 ## State is published as a custom state
 
 ```css
@@ -120,7 +126,8 @@ A reflected `value` would carry the password past every session-replay masker
 that masks `.value` and `input[value]`.
 
 Helix publishes the resolved boolean as a custom state, and the attribute keeps
-the value you wrote. There are four custom states:
+the value you wrote. These are the most common, and each component's reference
+page lists the states it publishes:
 
 - `:state(open)`
 - `:state(checked)`

package/content/svelte.mdx

@@ -30,7 +30,7 @@ and you do not need a compiler flag.
 Svelte passes objects and arrays as properties on its own:
 
 ```svelte
-<helix-tabs items={tabs} />
+<helix-data-table label="People" rows={people} />
 ```
 
 Svelte's own attributes are typed on every Helix tag as well, so `onclick`,

package/content/theming.mdx

@@ -158,7 +158,11 @@ Mark the section so the stylesheet derives its own colors there from the
 section's seeds, in the section's mode, and paint it with its page color:
 
 ```html
-<section data-band data-color-mode="dark" data-helix-theme>…</section>
+<section
+  data-band
+  data-color-mode="dark"
+  data-helix-theme
+>…</section>
 ```
 
 ```css

package/content/using-helix-with-an-agent.mdx

@@ -120,7 +120,7 @@ looks enabled while it does not accept input.
 
 ```ts
 import '@fusion.dev/helix-styles/helix.css'
-import '@fusion.dev/helix'
+import '@fusion.dev/helix/button'
 ```
 
 `helix.css` combines four files in the order they must load:

package/content/using-the-elements.mdx

@@ -90,10 +90,12 @@ button.
 ## Import `elements.css` beside the base layer
 
 ```ts
-import '@fusion.dev/helix-styles/base.css'
 import '@fusion.dev/helix-styles/helix.css'
 ```
 
+`helix.css` imports `elements.css` after the primitives, the tokens, and the
+base layer. If you import the layers one at a time, import `elements.css` last.
+
 `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.
@@ -112,6 +114,24 @@ import '@fusion.dev/helix' // ❌ the barrel
 Import one component family per module, so you do not ship the whole library to
 use a button.
 
+## Turn off an attribute that is on by default
+
+A boolean attribute is off until you write it, with four exceptions. These are
+on until you write the string `"false"`:
+
+- `modal` on Drawer
+- `playsinline` on Video
+- `default-pinned` on Chat
+- `tab-indents` on Sandbox Source
+
+```html
+<helix-drawer modal="false"></helix-drawer>
+```
+
+In JSX, `modal={false}` sets the property and does the same. Other features
+that are on by default turn off with an attribute named `no-`, such as
+`no-copy`.
+
 ## Declarative shadow DOM is opt-in
 
 The site ships no declarative shadow DOM (DSD). The shadow styles load with the

package/content/vue.mdx

@@ -42,7 +42,8 @@ That works for every Helix element. A string goes through either path, and an
 array or an object goes through the property.
 
 ```vue
-<helix-tabs :items="items" @helix-before-activate="onActivate" />
+<helix-data-table label="People" :rows="people" />
+<helix-tabs @helix-before-activate="onActivate" />
 ```
 
 `@helix-before-activate` binds with `addEventListener`, so use the event's own