@fusion.dev/helix-docs 0.143.0 → 0.145.0

package/content/overlays.mdx

@@ -81,8 +81,15 @@ 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.
+Opening a `Popover` moves focus to the first control in its panel, or to the
+panel where it holds none, and closing it from inside gives focus back to the
+trigger. It does not trap focus unless you set `modal`, which keeps `Tab` in the
+panel until it closes. When focus moves out of its trigger and its panel, the
+popover closes.
+
+Press F8 to move focus to the `Toast` stack, and press it again to go back.
+Set `hotkey` on the stack to use another key. The stack's name says which key
+it is.
 
 The fields with a panel behave the same way:
 
@@ -91,10 +98,18 @@ The fields with a panel behave the same way:
   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.
+- Inside one of those panels, `Tab` moves between the panel's controls and
+  does not leave 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`.
 
+A tooltip describes its trigger by itself, whether it wraps the trigger or
+names it with `for`. A Helix trigger is described as soon as it has rendered.
+A plain element in your markup is described the first time a reader points at
+it or focuses it, so the link is never written into markup your server sent.
+Write `aria-describedby` yourself to have the link in the server's markup.
+
 ## Keep an overlay open
 
 An overlay sends `helix-before-close` before it closes. Cancel the event to keep
@@ -118,6 +133,20 @@ on the `overlay` and `display` properties, which allows an exit animation on an
 element the browser is about to remove from the top layer. Every overlay
 responds to `prefers-reduced-motion`.
 
+`Dialog` and `Drawer` also say where they are in the journey:
+`:state(entering)` holds from the moment they open until their entrance has
+finished, and `:state(exiting)` from the moment they close until their exit has
+finished. Select on them to draw an entrance or an exit of your own.
+
+## Swiping an overlay away
+
+A touch or a pen swipes a `Drawer` toward the edge it came from, and a `Toast`
+message toward the end of the line. A swipe past halfway, or a quick one, closes
+it through the same cancelable request as its close control. A `Drawer` with
+`snap-points` comes to rest at the nearest point, such as half open. In a
+`Lightbox`, a swipe across the viewer shows the next or the previous item. A
+mouse never swipes, because dragging with a mouse selects text.
+
 ## Choose an overlay
 
 | Component | Use it for |

package/content/recipes.mdx

@@ -62,6 +62,30 @@ loading state, no pressed state, and no `type="submit"` handling.
 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.
 
+## Navigation items
+
+```html
+<helix-navigation label="Sections">
+  <a
+    aria-current="page"
+    href="/guide"
+  >Guide</a>
+  <a href="/api">API</a>
+</helix-navigation>
+<button data-navigation-item>Menu</button>
+```
+
+A link inside `helix-navigation` is styled by the page's stylesheet, because the
+page's styles reach a slotted link before the component's do.
+`data-navigation-item` gives the same look to an element outside a navigation
+bar. Two custom properties set the text color:
+
+- `--navigation-item-color` colors every destination except the current one.
+- `--navigation-item-current-color` colors the destination marked
+  `aria-current="page"`.
+
+Set them on `helix-navigation` or on any element that contains it.
+
 ## Surfaces and layout
 
 ```html

package/content/sandbox.mdx

@@ -72,6 +72,15 @@ 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.
 
+Each request has a notification once it is applied: `helix-edit` after
+`helix-before-edit`, `helix-split` after `helix-before-split`, and
+`helix-panel-resize` after `helix-before-panel-resize`. Listen for these to
+store the arrangement or the source.
+
+Set `controls` on `helix-sandbox-terminal` for a clear button and a level
+filter above the log. Without them, `clear()` empties the log, and `level`
+hides the quieter lines.
+
 ## The frame document
 
 `helix-sandbox-preview` loads `src` into a sandboxed frame. You provide that
@@ -94,9 +103,13 @@ 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".
+`servePreview` from `@fusion.dev/helix/sandbox` is that protocol, written for
+you. Call it once in the frame document, after your elements are defined. It
+writes each render into `#preview-root`, runs the example's scripts, relays
+its console, reports its height and its presses, and adds the rules for the
+four layouts. A frame follows. `/helix.css` is the stylesheet from
+`@fusion.dev/helix-styles`, and `/frame.js` is a classic script you bundle,
+for the reason under "How the preview is isolated":
 
 ```html
 <!doctype html>
@@ -104,21 +117,24 @@ registers your elements, for the reason under "How the preview is isolated".
   href="/helix.css"
   rel="stylesheet"
 >
+<div id="preview-root"></div>
 <script
   defer
-  src="/elements.js"
+  src="/frame.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>
 ```
 
+```ts
+// frame.ts, bundled to /frame.js as a classic script
+import '@fusion.dev/helix' // registers every family, because an example can use any of them
+import { servePreview } from '@fusion.dev/helix/sandbox'
+
+servePreview()
+```
+
+Pass `onReplace` to take down what an example mounted before the next one
+replaces it, and `onRender` to act after each render, such as mounting a map.
+
 ## Console output from the example
 
 Logs from the example appear in the console panel. Logs from the page around it