@fusion.dev/helix-docs 0.144.0 → 0.146.0

package/content/overlays.mdx

@@ -78,14 +78,16 @@ press `Escape` again.
 
 A modal overlay keeps `Tab` inside itself while it is open, and it returns focus
 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
+you set `modal="false"`. Set `dismissible` on either to draw a close control in
+the corner by the title. The page behind a modal `Dialog` or `Drawer` does not
 scroll while it is open.
 
 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.
+trigger, however it closes, setting `open` included. It does not trap focus
+unless you set `modal`, which keeps `Tab` in the panel until it closes and hides
+the rest of the page from screen readers meanwhile. 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
@@ -98,6 +100,8 @@ 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`.
@@ -107,6 +111,9 @@ 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.
+The pointer can move onto a tooltip's bubble and the bubble stays, so a reader
+can read it under a magnifier. Set `hoverable="false"` to hide it once the
+pointer reaches it.
 
 ## Keep an overlay open
 
@@ -141,9 +148,15 @@ finished. Select on them to draw an entrance or an exit of your own.
 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
+`snap-points` comes to rest at the nearest point, such as half open, and
+`:state(snapped)` holds while it rests short of the whole panel. Moving focus
+with `Tab` to a control past the edge of the window opens it the rest of the
+way, and `snapTo()` moves it from script. 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.
+mouse never swipes, because dragging with a mouse selects text. A `Lightbox`
+with `max-zoom` also zooms: pinch the item, or double click or double tap it,
+and drag it about once zoomed. It swipes only while the item is at its own
+size.
 
 ## Choose an overlay
 

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

package/content/state-and-control.mdx

@@ -106,11 +106,13 @@ 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.
+**A form reset returns to a `value` or `checked` you wrote in markup**, as it
+does on a native control: `<input value="Ada">` and `<helix-input value="Ada">`
+both reset to `Ada`. Where `default-value` or `default-checked` is written, the
+reset returns to that instead. The attribute is read at the reset, and a
+framework that sets `value` as a property writes no attribute, so write the
+starting value of a form control as `default-value`, or `default-checked` for a
+checkbox or a switch, when a reset has to return to it.
 
 ## State is published as a custom state