@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/dialog.md

@@ -0,0 +1,256 @@
+# Dialog
+
+> A modal dialog, or an alert dialog that needs an answer: a native `<dialog>` opened and closed by invoker commands, so it works in server HTML with no JavaScript, and a 1.5 kB script closes the native element's gaps where JavaScript runs. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+
+```ts
+import { Dialog } from "@lumiose/ui"; // or "@lumiose/ui/dialog"
+import "@lumiose/ui/dialog.css"; // locks the page's scroll behind a modal dialog
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger />
+  <Dialog.Popup>
+    <Dialog.Title />
+    <Dialog.Description />
+    <Dialog.Close />
+  </Dialog.Popup>
+</Dialog.Root>
+```
+
+| Part          | Renders                                                                                                                       |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Root`        | No element. Holds the state and the ids the other parts share.                                                                |
+| `Trigger`     | `<button type="button" command="show-modal" commandfor="…" aria-haspopup="dialog" aria-expanded="…">`                         |
+| `Popup`       | `<dialog closedby="…">`, labelled by its `Title` and described by its `Description`; `role="alertdialog"` for an alert dialog |
+| `Title`       | `<h2>`, which names the dialog.                                                                                               |
+| `Description` | `<p>`, which describes it.                                                                                                    |
+| `Close`       | `<button type="button" command="close" commandfor="…">`: its `value` becomes the dialog's `returnValue`.                      |
+
+The trigger can sit anywhere inside `Root`, and a popup may have several close buttons. `Title` and
+`Description` go inside `Popup`. A dialog may contain another `Dialog.Root`: the inner dialog
+opens on top of the outer one.
+
+## API
+
+### Dialog.Root
+
+| Prop           | Type                        | Default    |                                                                                                                                                   |
+| -------------- | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`         | `boolean`                   |            | Opens or closes the dialog when it changes, in the browser. Server HTML always starts closed: a modal dialog opens only from a trigger or script. |
+| `onOpenChange` | `(open: boolean) => void`   |            | Called after the dialog opens or closes, whatever did it: the trigger, a close button, Escape, a click outside or `open`.                         |
+| `bind:open`    | `Signal<boolean>`           |            | Stands in for `open` and `onOpenChange`: the signal opens and closes the dialog, and follows it.                                                  |
+| `role`         | `"dialog" \| "alertdialog"` | `"dialog"` | `"alertdialog"` for a confirmation that needs an answer: a click outside does not close it.                                                       |
+
+Without `open`, `onOpenChange` or `bind:open` the dialog keeps its own state.
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through. Your props override the defaults (`type`,
+`aria-haspopup`, `aria-expanded`, `closedby`, `aria-labelledby`, `aria-describedby`). A `Title`'s or
+a `Description`'s `id` names it, and the popup points at it; the `Popup` keeps its own `id`, which
+its triggers point at (see [Ids](README.md#ids)), and `command` and `commandfor` stay the parts' own.
+
+- **`Trigger`**: `aria-expanded` follows the dialog in the browser. In server HTML it stays
+  `"false"`, which is never wrong where assistive technology can reach it: while the modal dialog
+  is open, the trigger is inert.
+- **`Popup`**: `closedby` is `"any"` for a dialog (Escape or a click outside closes it) and
+  `"closerequest"` for an alert dialog (Escape only); pass `closedby="none"` to allow neither. Native
+  events work as on a `<dialog>`: `on:close` runs after any close, and
+  `event.currentTarget.returnValue` holds the value of the `Close` that closed it (it is unchanged
+  after Escape). To keep a dialog open (unsaved changes, say), use `closedby="none"` while it must
+  stay, not `preventDefault()` on its `cancel` event: browsers let a page cancel only the first of
+  repeated close requests, so a second Escape closes it anyway.
+- **`Title`** and **`Description`**: the popup's `aria-labelledby` and `aria-describedby` point at
+  the ones it renders, and only those; in an island they follow parts that appear or go away. A
+  dialog without a `Title` needs an `aria-label` on `Popup`.
+
+## Example
+
+A confirmation in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Dialog } from "@lumiose/ui";
+
+export function DeleteProject() {
+  return (
+    <Dialog.Root role="alertdialog">
+      <Dialog.Trigger class="lu-button">Delete project…</Dialog.Trigger>
+      <Dialog.Popup class="lu-dialog">
+        <Dialog.Title>Delete project?</Dialog.Title>
+        <Dialog.Description>This removes the project and its deployments.</Dialog.Description>
+        <footer>
+          <Dialog.Close class="lu-button" value="cancel">
+            Cancel
+          </Dialog.Close>
+          <Dialog.Close class="lu-button" data-variant="destructive" value="delete">
+            Delete
+          </Dialog.Close>
+        </footer>
+      </Dialog.Popup>
+    </Dialog.Root>
+  );
+}
+```
+
+In an island, bound to a signal: the button outside opens it, and the signal follows whatever
+closes it. `bind:open={open}` is short for `open={open()}` plus
+`onOpenChange={(next) => open.set(next)}`.
+
+```tsx check
+import { Dialog } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function EditProfile() {
+  const open = signal(false);
+  const saved = signal("");
+  return (
+    <>
+      <button type="button" class="lu-button" onClick={() => open.set(true)}>
+        Edit profile
+      </button>
+      <Dialog.Root bind:open={open}>
+        <Dialog.Popup
+          class="lu-dialog"
+          on:close={(event) => saved.set(event.currentTarget.returnValue)}
+        >
+          <Dialog.Title>Edit profile</Dialog.Title>
+          <Dialog.Description>Your name as others see it.</Dialog.Description>
+          <footer>
+            <Dialog.Close class="lu-button" data-variant="primary" value="save">
+              Save
+            </Dialog.Close>
+          </footer>
+        </Dialog.Popup>
+      </Dialog.Root>
+      <p>{open() ? "Editing…" : `Last answer: ${saved() || "none"}`}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-dialog` on `Popup` and `lu-button` on the buttons
+(`data-variant="primary"` or `"destructive"` for filled ones). `lu-dialog` also styles the backdrop,
+the title, the description and a `<footer>` for the buttons, and fades and zooms the dialog in and
+out. Its colours come from the theme's `--lu-` properties ([UI components](README.md#the-default-theme)).
+
+**With your own CSS**, style the parts through `class` and the dialog's native state: `dialog[open]`,
+`:modal`, `::backdrop` and `[role="alertdialog"]`. Where the client script runs, a dialog with open
+dialogs inside also gets `data-nested-dialog-open` and `--lu-nested-dialogs` (how many are open inside
+it), as in Base UI; `dialog:has(dialog[open])` matches the same dialogs without the script. A starting point, with a fade that keeps the dialog in the top layer while it
+closes:
+
+```css
+.dialog {
+  inline-size: min(28rem, 100vw - 2rem);
+  padding: 1.25rem;
+  border: 1px solid #d4d4d8;
+  border-radius: 0.75rem;
+  box-shadow: 0 10px 30px -10px rgb(0 0 0 / 0.35);
+}
+.dialog::backdrop {
+  background: rgb(0 0 0 / 0.45);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .dialog,
+  .dialog::backdrop {
+    transition:
+      opacity 150ms ease-out,
+      overlay 150ms allow-discrete,
+      display 150ms allow-discrete;
+  }
+  .dialog:not([open]),
+  .dialog:not([open])::backdrop {
+    opacity: 0;
+  }
+  @starting-style {
+    .dialog[open],
+    .dialog[open]::backdrop {
+      opacity: 0;
+    }
+  }
+}
+```
+
+`@lumiose/ui/dialog.css` holds the scroll lock, in the `lu.core` layer: the page behind any modal
+`<dialog>` does not scroll (`:root:has(dialog:modal) { overflow: hidden }`). A page that overflows
+keeps its scrollbar's space (`scrollbar-gutter: stable`), so with classic scrollbars (Windows,
+Linux) its layout does not shift. A page that fits the window gets no gutter, which would leave an
+empty strip of about 15px at its inline end. The client script measures the page before the dialog
+opens; without it, a scroll timeline in the stylesheet tells the two apart (decision-79), and a
+browser without scroll timelines keeps the gutter on a page that fits too
+([Browser support](#browser-support)). Leave the stylesheet out, or override the rule, to let the
+page scroll.
+
+## Keyboard and focus
+
+The browser's modal dialog provides the
+[WAI-ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/):
+
+| Key            | Does                                                                                                                                                                   |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter, Space   | On the trigger: opens the dialog.                                                                                                                                      |
+| Tab, Shift+Tab | Move between the focusable elements of the dialog. The page behind is inert: focus never reaches it.                                                                   |
+| Escape         | Closes the dialog on top, alert dialogs included. With nested dialogs, one Escape closes one dialog. An Escape that ends an input method's composition closes nothing. |
+
+- **On open**, focus moves to the element with `autofocus`, or else the first tab stop inside,
+  or else the dialog, as in Base UI and the same in every browser: not a scroller before it, nor a
+  `tabindex="-1"` title (where the script runs). Opened by touch, the dialog focuses itself
+  instead, so no virtual keyboard opens over it (an `autofocus` element still gets focus).
+- **On close**, focus returns to the element that had it before: the trigger, or the button that
+  set the signal. If that element is gone, focus goes to another trigger of the dialog, without
+  scrolling the page. The popovers, menus and dialogs open inside it close with it.
+- **A click outside** closes a dialog, not an alert dialog, and only the dialog on top. A press
+  that starts inside and ends outside, such as selecting text, does not count, and neither does a
+  right-click or a second finger.
+- Popups opened from a dialog (a menu, a select) belong inside its `Popup`: everything outside a
+  modal dialog is inert.
+
+## Without JavaScript, and the client script
+
+The trigger, the close buttons, Escape and the click outside are HTML features: a dialog in a
+server-rendered page works before any script loads, and with none. `open`, `onOpenChange`,
+`bind:open` and a live `aria-expanded` need the component to run in the browser, in an island.
+
+Where the native element falls short of Base UI's dialog, a small script closes the gap: a page
+that renders a `Dialog` loads it once, as a 1.5 kB (brotli) module without the Lumiose runtime, and
+islands bundle it. It covers every `<dialog>` on the page:
+
+- a right-click or a second finger outside does not close the dialog;
+- `data-nested-dialog-open` and `--lu-nested-dialogs` on a dialog with open dialogs inside;
+- the first tab stop takes focus on open, in every browser, and a dialog opened by touch focuses
+  itself;
+- focus returns without scrolling, to the opener or, if it is gone, another trigger (WebKit, which
+  does not focus a clicked button, would otherwise leave focus on the page);
+- the click outside where the browser lacks `closedby` (Safari), and the invoker commands where it
+  lacks them.
+
+Until the script loads (or without JavaScript) the dialog behaves as the browser's own.
+
+## Browser support
+
+- **Invoker commands** (`command`, `commandfor`) open and close the dialog: Chrome and Edge 135,
+  Firefox 144, Safari 26.2. In older browsers the client script stands in for them; without
+  JavaScript the trigger and the close buttons do nothing there.
+- **`closedby`**: Chrome 134 and Firefox 141; Safari only in Technology Preview. Elsewhere the
+  client script closes the dialog on a click outside; without JavaScript only Escape does.
+- **Exit animations** that keep the dialog in the top layer (`overlay`) are Chromium-only.
+  Elsewhere the dialog leaves the top layer as soon as it starts closing.
+- **Scroll timelines** (`animation-timeline: scroll()`) keep the scroll lock's gutter off a page
+  that fits the window without JavaScript: Chrome and Edge 115, Safari 26. In Firefox, until the
+  client script runs or without JavaScript, such a page keeps the gutter while a dialog is open:
+  with classic scrollbars, an empty strip at its inline end.
+
+## Related
+
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Islands](https://itsjavi.com/lumiose/docs/concepts/islands/): running a component in the browser, for `open` and
+  `onOpenChange`.
+- [JSX](https://itsjavi.com/lumiose/docs/concepts/jsx/): native events with `on:` and `ref`.

package/docs/drawer.md

@@ -0,0 +1,204 @@
+# Drawer
+
+> A panel that slides in from an edge of the window and that a swipe toward that edge closes: a Dialog (a native modal `<dialog>` opened by an invoker command, so it works in server HTML with no JavaScript) against the edge its `swipeDirection` names. A 1 kB script adds the swipe, with the close buttons, Escape and a click on the backdrop as its alternatives. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+
+```ts
+import { Drawer } from "@lumiose/ui"; // or "@lumiose/ui/drawer"
+import "@lumiose/ui/drawer.css"; // puts the dialog against its edge; locks the page's scroll
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Drawer.Root>
+  <Drawer.Trigger />
+  <Drawer.Popup>
+    <Drawer.Title />
+    <Drawer.Description />
+    <Drawer.Content />
+    <Drawer.Close />
+  </Drawer.Popup>
+</Drawer.Root>
+```
+
+| Part          | Renders                                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `Root`        | No element. Holds the state and the ids the other parts share, as `Dialog.Root`.                                    |
+| `Trigger`     | `<button type="button" command="show-modal" commandfor="…" aria-haspopup="dialog" aria-expanded="…">`, as Dialog's. |
+| `Popup`       | `<dialog closedby="any" data-swipe-direction="…">`, labelled by its `Title` and described by its `Description`.     |
+| `Content`     | `<div>` around the drawer's content, which may scroll.                                                              |
+| `Title`       | `<h2>`, which names the drawer.                                                                                     |
+| `Description` | `<p>`, which describes it.                                                                                          |
+| `Close`       | `<button type="button" command="close" commandfor="…">`, as Dialog's.                                               |
+
+`Trigger`, `Title`, `Description` and `Close` are [Dialog's](dialog.md#anatomy). A drawer is
+modal: the page behind it is inert, and focus stays inside.
+
+## API
+
+### Drawer.Root
+
+| Prop             | Type                                  | Default  |                                                                                                                                                   |
+| ---------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`           | `boolean`                             |          | Opens or closes the drawer when it changes, in the browser. Server HTML always starts closed: a modal dialog opens only from a trigger or script. |
+| `onOpenChange`   | `(open: boolean) => void`             |          | Called after the drawer opens or closes, whatever did it: the trigger, a close button, Escape, a click outside, a swipe or `open`.                |
+| `bind:open`      | `Signal<boolean>`                     |          | Stands in for `open` and `onOpenChange`.                                                                                                          |
+| `swipeDirection` | `"down" \| "up" \| "left" \| "right"` | `"down"` | The direction a swipe closes the drawer in, and the window's edge it sits against: `"down"` is a bottom sheet.                                    |
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through, as Dialog's do ([Dialog: API](dialog.md#api)): `closedby`
+on `Popup` (`"closerequest"` keeps a click outside from closing it), `on:close` and the close
+buttons' `value`.
+
+- **`Content`**: a swipe that starts in content that can still scroll toward the drawer's edge
+  scrolls it instead, until it reaches its end. When it scrolls, make it focusable for the
+  keyboard: `tabindex={0}` with `role="region"` and an `aria-label`.
+- **`[data-swipe-ignore]`** on any element inside keeps swipes from starting on it, as on buttons,
+  links and fields. The toasts' region has it, so a toast's swipe never swipes a drawer it sits in.
+- A swipe starts only in the drawer's box: a drag that starts on the backdrop does nothing. A
+  mouse or pen drag in `Content` selects its text and never swipes (a touch swipe still does).
+
+## Example
+
+A bottom sheet in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Drawer } from "@lumiose/ui";
+
+export function FiltersSheet() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger class="lu-button">Filters</Drawer.Trigger>
+      <Drawer.Popup class="lu-drawer">
+        <Drawer.Title>Filters</Drawer.Title>
+        <Drawer.Description>Swipe down, or press Done, to close.</Drawer.Description>
+        <footer>
+          <Drawer.Close class="lu-button" data-variant="primary">
+            Done
+          </Drawer.Close>
+        </footer>
+      </Drawer.Popup>
+    </Drawer.Root>
+  );
+}
+```
+
+In an island, a side drawer bound to a signal: `bind:open={open}` is short for `open={open()}`
+plus `onOpenChange={(next) => open.set(next)}`, and the signal follows a swipe too.
+
+```tsx check
+import { Drawer } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function NavigationDrawer() {
+  const open = signal(false);
+  return (
+    <>
+      <button type="button" class="lu-button" onClick={() => open.set(true)}>
+        Menu
+      </button>
+      <Drawer.Root bind:open={open} swipeDirection="left">
+        <Drawer.Popup class="lu-drawer">
+          <Drawer.Title>Menu</Drawer.Title>
+          <Drawer.Description>Swipe left to close.</Drawer.Description>
+          <Drawer.Close class="lu-button">Close</Drawer.Close>
+        </Drawer.Popup>
+      </Drawer.Root>
+      <p>{open() ? "The menu is open" : "The menu is closed"}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-drawer` on `Popup`: a surface against its edge, rounded on the
+inside, with a handle on a bottom sheet, the title, the description and a `<footer>` styled. It
+slides in and out from its edge, follows a swipe, and leaves from where the swipe let go; the
+backdrop fades with it.
+
+**With your own CSS**, style the drawer through `class`, `[data-swipe-direction]`, `dialog[open]`
+and `::backdrop`, and the swipe through the script's state, named as in Base UI:
+
+- `[data-swiping]` while a swipe runs, with `--lu-drawer-swipe-movement-x` or
+  `--lu-drawer-swipe-movement-y` (pixels, toward the edge) and `--lu-drawer-swipe-progress` (0 to 1,
+  for the backdrop);
+- `[data-swipe-dismiss]` (the direction) when a swipe closed it, until it has left.
+
+```css
+.drawer {
+  translate: var(--lu-drawer-swipe-movement-x, 0) var(--lu-drawer-swipe-movement-y, 0);
+  transition:
+    translate 250ms ease-out,
+    overlay 250ms allow-discrete,
+    display 250ms allow-discrete;
+}
+.drawer[data-swiping] {
+  transition: none;
+}
+.drawer[data-swipe-direction="down"]:not([open]) {
+  translate: 0 100%;
+}
+@starting-style {
+  .drawer[data-swipe-direction="down"][open] {
+    translate: 0 100%;
+  }
+}
+```
+
+`@lumiose/ui/drawer.css` holds Dialog's scroll lock and, in the `lu.core` layer, puts each
+`dialog[data-swipe-direction]` against its edge, across that edge's length, instead of the
+browser's centred box; a swiped drawer selects no text.
+
+With classic scrollbars (Windows, Linux), the scroll lock keeps the scrollbar's space on a page
+that overflows, so the page does not shift: a drawer across the window stops at that gutter, as
+the page does. On a page that fits the window there is no gutter, and the drawer spans it all
+([Dialog's scroll lock](dialog.md#styling); without JavaScript in Firefox, the gutter stays).
+
+## Keyboard and focus
+
+| Key            | Does                                                                         |
+| -------------- | ---------------------------------------------------------------------------- |
+| Enter, Space   | On the trigger: opens the drawer.                                            |
+| Tab, Shift+Tab | Move between the focusable elements of the drawer; the page behind is inert. |
+| Escape         | Closes the drawer on top.                                                    |
+
+- **Focus** moves into the drawer on open and returns to the trigger on close, a swipe included, as
+  with [Dialog](dialog.md#keyboard-and-focus): on open, to the element with `autofocus`, or else the
+  first tab stop, or else the drawer. Base UI's Drawer focuses the drawer itself; give the drawer
+  `autofocus` (`<Drawer.Popup autofocus>`) for that, where the script runs. Opened by touch, it
+  focuses itself already.
+- **A swipe** is a dragging movement: the close buttons, Escape and a click on the backdrop close
+  the drawer without one (WCAG 2.5.7). Give a drawer a visible close button.
+- **The swipe** needs to travel 40% of the drawer's size toward its edge, or to be a quick flick;
+  shorter, the drawer springs back. It never starts on a button, link or field.
+
+## Without JavaScript, and the client script
+
+The trigger, the close buttons, Escape and the click outside are HTML features, as for Dialog: a
+drawer in a server-rendered page works before any script loads, and with none, against its edge.
+`open`, `onOpenChange` and `bind:open` need the component to run in an island.
+
+A page that renders a `Drawer` loads Dialog's script and a 1 kB (brotli) one of its own (2.5 kB
+together), without the Lumiose runtime; islands bundle them. The drawer's script handles the
+swipe, with the mouse and pen through pointer events and on touch screens through touch events,
+taking the gesture from scrolling only once it is a swipe.
+
+Not in this Drawer, next to Base UI's: snap points, a swipe area that opens the drawer from the
+edge, indented backgrounds, the virtual keyboard provider, detached triggers (`createHandle`), and
+non-modal drawers.
+
+## Browser support
+
+- **`<dialog>`, invoker commands, `closedby` and scroll timelines**: as for
+  [Dialog](dialog.md#browser-support).
+- **Exit animations** that keep the drawer in the top layer (`overlay`) are Chromium-only.
+  Elsewhere it leaves the top layer as soon as it starts closing.
+
+## Related
+
+- [Dialog](dialog.md): the same parts, centred.
+- [UI components](README.md): the approach, styling and the other components.