@fusion.dev/helix-docs 0.215.2 → 0.216.0

package/content/sandbox.mdx

@@ -120,6 +120,26 @@ over a package of the same name. The preview loads its document again when one
 of them changes, because a browser reads an import map only as a document
 starts. A `src` document declares its own import map.
 
+A module pane in TypeScript or JSX is compiled before the frame loads it. The
+compiler runs in a worker, which the preview starts from a `blob:` address, and
+loads from the `cdn`. A page whose Content Security Policy refuses `blob:`
+workers, as `worker-src 'self'` does, serves the worker as a file instead. Copy
+`@fusion.dev/helix/sandbox/compile-worker.js` to the page's own origin, and
+give its address to `registerCompilerWorker` before the first preview compiles:
+
+```js
+import { registerCompilerWorker } from '@fusion.dev/helix/sandbox'
+
+registerCompilerWorker('/sandbox/compile-worker.js')
+```
+
+A copied file does not update with the package. Where a release changes the
+messages the worker and the page exchange, the console warns that the file is
+from another release and names the address to copy it to again.
+
+In both cases the policy's `script-src` names the `cdn`'s host, which the
+compiler and the packages load from.
+
 ## Editing keys
 
 In a source pane, Tab inserts two spaces. Shift+Tab moves focus back, and

package/content/undo.mdx

@@ -0,0 +1,72 @@
+---
+description: Do an action at once and offer to undo it from a toast, in place of asking first.
+section: Essentials
+title: Undo an action from a toast
+---
+
+# Undo an action from a toast
+
+An action a reader can take back does not need a confirmation dialog. Do the
+action at once, then show a toast that offers to undo it. The reader who meant
+it loses no time, and the reader who did not has a few seconds to take it back.
+
+## Show the toast after the action
+
+Call `undoable()` on a `Toast` region after the action, with what to do if the
+reader undoes it:
+
+```js
+const stack = document.querySelector('helix-toast')
+
+archive(file)
+stack.undoable(`Archived ${file.name}`, {
+  undo: () => restore(file),
+})
+```
+
+The message holds an Undo button and shows for 8 seconds. While it shows:
+
+- Command+Z, or Control+Z on Windows and Linux, undoes the newest one, unless
+  focus is in a text field, which keeps the key for its own undo, or the app
+  handled the key first and called `preventDefault()`.
+- A pointer or focus in the stack pauses its timer.
+- A screen reader hears the message and then which keys undo it.
+- The shortcut overlay and its sheet list the key.
+
+An app with an undo of its own on those keys, such as a canvas or an editor,
+sets `undo-keys=""` on the region. The Undo button stays, and the keys stay
+the app's.
+
+## Hold back what cannot be taken back
+
+Where the action cannot be reversed once it has happened, such as deleting a
+record on a server, do it when the message closes. Remove the item from the
+page at once, and pass `commit`:
+
+```js
+row.hidden = true
+const result = await stack.undoable('Deleted 3 files', {
+  commit: () => deleteOnServer(ids),
+  undo: () => (row.hidden = false),
+})
+```
+
+`undoable()` returns a promise that settles to `undone` or `kept`.
+
+A message that never closes is kept as well: `commit` runs when the region
+leaves the page, such as on a route change, and when the page is hidden to be
+closed or reloaded. A browser can end a page without telling it, so a server
+that holds a deletion back should also finish it on a timeout of its own.
+
+## Keep a confirmation where an undo cannot help
+
+| Action | Use |
+|---|---|
+| Archive, move, rename, reorder, or change a setting | Undo toast |
+| Delete to a trash, or delete held back until the message closes | Undo toast |
+| Delete with no way back, such as emptying the trash | Confirmation dialog |
+| Send, publish, invite, or pay | Confirmation dialog |
+
+An action that reaches another person or leaves the app cannot be taken back
+from a toast, because it has already happened somewhere you do not control.
+Ask first with a `Dialog` with `alert`.

package/dist/pages.generated.js

@@ -275,6 +275,12 @@ export const docPages = [
         slug: 'typography',
         title: 'Typography',
     },
+    {
+        description: 'Do an action at once and offer to undo it from a toast, in place of asking first.',
+        section: 'Essentials',
+        slug: 'undo',
+        title: 'Undo an action from a toast',
+    },
     {
         description: 'The rules an agent follows to write Helix code, and the five mistakes that look like Helix bugs.',
         parent: 'coding-agents',