@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/otp-field.md

@@ -0,0 +1,160 @@
+# OTP Field
+
+> A one-time code input, after Base UI's OTPField: one native `<input>` shown as one slot per character. SMS autofill (`autocomplete="one-time-code"`), paste, Backspace, the arrow keys, `maxlength`, `pattern`, `required` and the form's value are the platform's, without JavaScript too, and assistive technology meets one labelled text field. `<lu-otp-field>`'s 1.5 kB script lays the input over the slots, keeps the code to the allowed characters, and reports completion. `bind:value` keeps a signal in sync.
+
+```ts
+import { OTPField } from "@lumiose/ui"; // or "@lumiose/ui/otp-field"
+import "@lumiose/ui/otp-field.css"; // or "@lumiose/ui/styles.css" for every component
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<OTPField.Root length={6}>
+  <OTPField.Input />
+  <OTPField.Slot />
+  <OTPField.Slot />
+  <OTPField.Separator />
+  <OTPField.Slot />
+</OTPField.Root>
+```
+
+| Part        | Renders                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-otp-field length validation-type>`, with `data-complete`, `data-filled` and `data-focused` from its script               |
+| `Input`     | `<input type="text" autocomplete="one-time-code" inputmode maxlength minlength pattern name>` (`type="password"` with `mask`) |
+| `Slot`      | `<div aria-hidden="true" data-slot>`: the next character (a dot with `mask`), `data-filled`, `data-active` at the caret       |
+| `Separator` | `<div aria-hidden="true" data-orientation>`: a dash or a gap between slots                                                    |
+
+Name the field with a [Field](field.md) (`Field.Label`), a `<label for>` the Root's `id`, or an
+`aria-label` on the `Input`.
+
+## API
+
+### OTPField.Root
+
+| Prop                               | Type                                               | Default           |                                                                                                                                                                                            |
+| ---------------------------------- | -------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `length`                           | `number`                                           |                   | How many characters the code has. Required.                                                                                                                                                |
+| `value`                            | `string`                                           |                   | Shows this code when it changes. Pair it with `onValueChange`.                                                                                                                             |
+| `defaultValue`                     | `string`                                           | `""`              | The code at first; a form reset goes back to it.                                                                                                                                           |
+| `onValueChange`                    | `(value: string) => void`                          |                   | Called as the code changes: typing, a paste, autofill, Backspace.                                                                                                                          |
+| `bind:value`                       | `Signal<string>`                                   |                   | Stands in for `value` and `onValueChange`.                                                                                                                                                 |
+| `onValueComplete`                  | `(value: string) => void`                          |                   | Called when the last character is entered.                                                                                                                                                 |
+| `onValueInvalid`                   | `(value: string) => void`                          |                   | Called with what was entered when it held characters the field does not allow.                                                                                                             |
+| `validationType`                   | `"numeric" \| "alpha" \| "alphanumeric" \| "none"` | `"numeric"`       | The characters the code may hold, ASCII as in Base UI (other scripts' digits and full-width letters are typed as ASCII); spaces are always dropped. Any other value counts as `"numeric"`. |
+| `normalizeValue`                   | `(value: string) => string`                        |                   | Normalizes what is entered before the allowed characters are kept (an island).                                                                                                             |
+| `inputMode`                        | `"numeric" \| "text" \| "tel" \| "none"`           | from the type     | The virtual keyboard: numeric for digits, text otherwise.                                                                                                                                  |
+| `mask`                             | `boolean`                                          | `false`           | The slots show dots, and the input is a password input, so screen readers do not speak the code.                                                                                           |
+| `autoComplete`                     | `string`                                           | `"one-time-code"` | The input's `autocomplete`.                                                                                                                                                                |
+| `autoSubmit`                       | `boolean`                                          | `false`           | Submits the form when the last character is entered.                                                                                                                                       |
+| `name`, `form`                     | `string`                                           |                   | The name the code is submitted under, and the id of its form when it is outside it.                                                                                                        |
+| `id`                               | `string`                                           | generated         | The input's id, for a `<label for>`.                                                                                                                                                       |
+| `required`, `disabled`, `readOnly` | `boolean`                                          | `false`           | As on a native input.                                                                                                                                                                      |
+
+### The other parts
+
+`Input` takes `<input>` props except the code's own (`type`, `value`, `name`, `maxlength`,
+`pattern`, `inputmode`, `autocomplete`, …: the Root's); `placeholder` and `aria-label` pass
+through. `Slot` and `Separator` take `<div>` props. Inside a [Field](field.md), the input takes the
+field's id, name, description and error.
+
+**One input, not one per character.** Base UI renders an input per slot. Here one input holds the
+code: autofill of an SMS code works natively (it fills one field), a paste or Backspace needs no
+script, the browser validates the whole code (`pattern`, `minlength`) and submits it, and a screen
+reader meets one field named once instead of six. The slots are a picture of that input, drawn by
+the script; the input lies over them, transparent, so a press on a slot moves the caret there.
+
+**Differences from Base UI's OTPField.** `Slot` replaces the per-character `Input`s; the
+`Separator` is visual (`aria-hidden`). `normalizeValue` (`(text) => text.toUpperCase()`, say)
+works in an island, where Root hands it to the element: a server page's script cannot receive a
+function. No `inputRef`, no `render`.
+
+## Example
+
+```tsx check
+import { OTPField } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function VerifyCode() {
+  const code = signal("");
+  return (
+    <form method="post">
+      <label for="code">Verification code</label>
+      <OTPField.Root
+        id="code"
+        name="code"
+        length={6}
+        required
+        bind:value={code}
+        class="lu-otp-field"
+      >
+        <OTPField.Input />
+        <OTPField.Slot />
+        <OTPField.Slot />
+        <OTPField.Slot />
+        <OTPField.Separator />
+        <OTPField.Slot />
+        <OTPField.Slot />
+        <OTPField.Slot />
+      </OTPField.Root>
+      <button type="submit" class="lu-button" disabled={code().length < 6}>
+        Verify
+      </button>
+    </form>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-otp-field` on `Root`: a 2.5rem box per character (they shrink
+on narrow screens), the caret's box ringed while the field has focus with a blinking caret in it
+(still where motion is reduced), and a short dash for a separator.
+
+**With your own CSS**, style the slots through `[data-slot]`, `[data-filled]` and `[data-active]`,
+the separator through `[data-orientation]`, and the root through `[data-complete]`,
+`[data-focused]` and `:has(input:disabled)`.
+
+`@lumiose/ui/otp-field.css` (0.2 kB brotli) lays the input over the slots once the script runs
+(`:defined`), its text, caret and selection transparent, and until then shows the input as a plain
+field and hides the slots.
+
+## Keyboard and focus
+
+| Key                | Does                                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| A character        | Fills the caret's slot, typing over its character (the ringed slot), as in Base UI. Refused characters do nothing. |
+| Backspace / Delete | Deletes the character before or after the caret, as in any text field.                                             |
+| Arrow Left / Right | Moves the caret, and the ringed slot, one slot.                                                                    |
+| Home / End         | The first slot, or after the last character.                                                                       |
+| Tab                | Moves on: one tab stop.                                                                                            |
+
+A paste fills every slot from the caret, its spaces and dashes dropped, even past what
+`maxlength` would cut. An IME composition (Chinese, Japanese, full-width digits) shows in the
+slots as it is; only the committed text is kept to the allowed characters, completes the field and
+auto-submits.
+
+## Without JavaScript, and the element's script
+
+The input is a native text field: autofill, typing, paste, `pattern` and `required` validation and
+submission work with no script, and the slots stay hidden. `<lu-otp-field>`'s script (1.5 kB
+brotli) shows the slots, cleans the value as it changes (firing `valueinvalid` for refused input),
+fires `valuecomplete`, auto-submits, and follows a form reset.
+
+A numeric code (`validationType="numeric"`, the default) renders `dir="ltr"` on the Root: its
+slots run left to right in a right-to-left page too, as digits read there. Other codes follow the
+page; pass `dir` to choose.
+
+## Browser support
+
+`autocomplete="one-time-code"`: Safari (iOS, macOS) and Chrome on Android offer received codes;
+elsewhere the field is a plain one. The transparent input over the slots is 16px, so iOS Safari
+does not zoom into it on focus.
+
+## Related
+
+- [Field](field.md): a label, a description and errors for the code.
+- [Input](input.md): a text field without slots.
+- [Form](form.md): submitting the code to a form action.

package/docs/popover.md

@@ -0,0 +1,271 @@
+# Popover
+
+> A popup anchored to its trigger: a native `popover` opened and closed by the trigger's `popovertarget`, placed with CSS anchor positioning, so it works in server HTML with no JavaScript. A 3.3 kB script moves focus into it and back, dismisses it as Base UI does (not on a right-click), keeps `aria-expanded` current and places it in browsers without anchor positioning. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands. A trigger can open it on hover (`openOnHover`), and a `modal` popover is a modal `<dialog>` that makes the page behind it inert.
+
+```ts
+import { Popover } from "@lumiose/ui"; // or "@lumiose/ui/popover"
+import "@lumiose/ui/popover.css"; // places the popup next to its trigger
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Popover.Root>
+  <Popover.Trigger />
+  <Popover.Popup>
+    <Popover.Title />
+    <Popover.Description />
+    <Popover.Close />
+  </Popover.Popup>
+</Popover.Root>
+```
+
+| Part          | Renders                                                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`        | No element. Holds the state and the ids the other parts share.                                                                                                              |
+| `Trigger`     | `<button type="button" popovertarget="…" aria-haspopup="dialog">`, with an `anchor-name` in its `style`.                                                                    |
+| `Popup`       | `<div popover="auto" role="dialog" data-side="…" data-align="…">`, labelled by its `Title` and described by its `Description`; `popover="manual"` once the script opens it. |
+| `Title`       | `<h2>`, which names the popup.                                                                                                                                              |
+| `Description` | `<p>`, which describes it.                                                                                                                                                  |
+| `Close`       | `<button type="button" popovertarget="…" popovertargetaction="hide">`.                                                                                                      |
+
+With `modal`, the `Trigger` is a `<button command="show-modal" commandfor="…">`, the `Popup` a
+`<dialog closedby="any" data-side="…" data-align="…">` and the `Close` a
+`<button command="close" commandfor="…">`.
+
+The popup is a non-modal dialog, as in Base UI: the page around it stays usable (unless `modal`). A popover may
+contain another `Popover.Root`: the inner popup opens on top, and closing the outer one closes
+both.
+
+## API
+
+### Popover.Root
+
+| Prop           | Type                      | Default |                                                                                                                                                                      |
+| -------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Opens or closes the popover when it changes, in the browser. Server HTML always starts closed: a popover opens only from its trigger or script.                      |
+| `onOpenChange` | `(open: boolean) => void` |         | Called after the popover opens or closes, whatever did it: the trigger, a close button, Escape, a click outside, another popover or `open`.                          |
+| `bind:open`    | `Signal<boolean>`         |         | Stands in for `open` and `onOpenChange`.                                                                                                                             |
+| `modal`        | `boolean \| "trap-focus"` | `false` | A modal popover: the page behind it is inert and does not scroll, focus stays inside, and a press outside or Escape closes it. `"trap-focus"` only keeps Tab inside. |
+
+### Popover.Trigger
+
+| Prop          | Type      | Default |                                                                                                                                                          |
+| ------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `openOnHover` | `boolean` | `false` | A mouse or pen resting on the trigger opens the popover too, and it closes once the pointer has left the trigger and the popup. Not for a modal popover. |
+| `delay`       | `number`  | `300`   | With `openOnHover`: how long the pointer rests on the trigger before the popover opens, in ms.                                                           |
+| `closeDelay`  | `number`  | `0`     | With `openOnHover`: how long the popover stays open after the pointer leaves, in ms (at least 100 ms to cross the gap to the popup).                     |
+
+A hover opens the popover without moving focus, and a click on the trigger then keeps it open
+until it is dismissed. Touch and the keyboard open it with a click (a tap, Enter or Space), as
+without `openOnHover`. On the way from the trigger to the popup, the pointer may take its time:
+while it moves inside the triangle from where it left the trigger to the popup's near side (Base
+UI's safe polygon), the popover waits; a stop or a turn away lets it close.
+
+### Popover.Popup
+
+| Prop          | Type                                                                       | Default    |                                                                                                |
+| ------------- | -------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
+| `side`        | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` | The trigger's side the popup goes on. `inline-start` and `inline-end` follow `dir`.            |
+| `align`       | `"start" \| "center" \| "end"`                                             | `"center"` | How the popup lines up with the trigger along that side.                                       |
+| `sideOffset`  | `number`                                                                   | `0`        | The gap between the trigger and the popup, in CSS pixels.                                      |
+| `alignOffset` | `number`                                                                   | `0`        | A shift along the side, in CSS pixels: away from the aligned edge, or right/down when centred. |
+
+The popup flips to the opposite side when it does not fit, and goes below (or above) the trigger
+when a `left` or `right` popup fits on neither side. A popup too tall for the room on both sides shrinks to the room beside its trigger
+(below, or above when below has less than 8rem), and scrolls; without anchor positioning the
+script writes that room as `--lu-available-height`, which the default theme's caps use. It hides while its trigger is
+scrolled out of view, of the page or of a scroller around it (`data-anchor-hidden` on the popup,
+where the script runs), and comes back with it.
+
+### 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`, `role`, `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 trigger points
+at (see [Ids](README.md#ids)), and `popover` and `popovertarget` stay the parts' own. A `style` you pass keeps the anchor name.
+
+- **`Trigger`**: `aria-expanded` comes from the browser for `popovertarget`, and from the client
+  script once it runs.
+- **`Popup`**: native events work as on any popover: `on:toggle` and `on:beforetoggle`. A popup
+  without a `Title` needs an `aria-label`.
+
+## Example
+
+```tsx check
+import { Popover } from "@lumiose/ui";
+
+export function Notifications() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger class="lu-button">Notifications</Popover.Trigger>
+      <Popover.Popup class="lu-popover" align="start">
+        <Popover.Title>Notifications</Popover.Title>
+        <Popover.Description>You are all caught up.</Popover.Description>
+        <footer>
+          <Popover.Close class="lu-button">Close</Popover.Close>
+        </footer>
+      </Popover.Popup>
+    </Popover.Root>
+  );
+}
+```
+
+In an island, bound to a signal: `bind:open={open}` is short for `open={open()}` plus
+`onOpenChange={(next) => open.set(next)}`. A popover opened by the signal still anchors to its
+trigger and treats it as its invoker.
+
+```tsx check
+import { Popover } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function Filters() {
+  const open = signal(false);
+  return (
+    <>
+      <Popover.Root bind:open={open}>
+        <Popover.Trigger class="lu-button">Filters</Popover.Trigger>
+        <Popover.Popup class="lu-popover" side="right" sideOffset={8}>
+          <Popover.Title>Filters</Popover.Title>
+        </Popover.Popup>
+      </Popover.Root>
+      <p>{open() ? "Choosing filters…" : "All items"}</p>
+    </>
+  );
+}
+```
+
+A profile card that opens on hover, and a modal popover with a form:
+
+```tsx check
+import { Popover } from "@lumiose/ui";
+
+export function HoverAndModal() {
+  return (
+    <>
+      <Popover.Root>
+        <Popover.Trigger class="lu-button" openOnHover delay={200}>
+          Ada Lovelace
+        </Popover.Trigger>
+        <Popover.Popup class="lu-popover" sideOffset={8}>
+          <Popover.Title>Ada Lovelace</Popover.Title>
+          <Popover.Description>Wrote the first published program.</Popover.Description>
+        </Popover.Popup>
+      </Popover.Root>
+      <Popover.Root modal>
+        <Popover.Trigger class="lu-button">Rename</Popover.Trigger>
+        <Popover.Popup class="lu-popover" align="start" sideOffset={8}>
+          <Popover.Title>Rename the file</Popover.Title>
+          <label>
+            Name <input class="lu-input" value="report.pdf" />
+          </label>
+          <footer>
+            <Popover.Close class="lu-button">Done</Popover.Close>
+          </footer>
+        </Popover.Popup>
+      </Popover.Root>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-popover` on `Popup`: a surface with the title, the
+description and a `<footer>` styled, a 4px gap to the trigger, and a fade. Its colours come from the
+theme's `--lu-` properties ([UI components](README.md#the-default-theme)).
+
+**With your own CSS**, style the popup through `class` and its state: `:popover-open` (`[open]`
+for a modal popover, whose `::backdrop` is transparent until you style it),
+`[data-side]` and `[data-align]` (the requested placement; a flip does not change them), and the
+trigger through `[aria-expanded]`. Two custom properties set the offsets, and the props override
+them: `--lu-side-offset` and `--lu-align-offset`.
+
+```css
+.popover {
+  --lu-side-offset: 6px;
+  padding: 0.75rem;
+  border: 1px solid #d4d4d8;
+  border-radius: 0.5rem;
+  box-shadow: 0 10px 30px -10px rgb(0 0 0 / 0.35);
+}
+```
+
+`@lumiose/ui/popover.css` holds the placement, in the `lu.core` layer: for each `data-side` and
+`data-align`, the CSS anchor positioning that puts the popup next to its trigger, with flips and
+`position-visibility: anchors-visible`. Tooltip shares it.
+
+## Keyboard and focus
+
+| Key          | Does                                                                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter, Space | On the trigger: opens or closes the popover.                                                                                                                              |
+| Tab          | Moves through the popup, then on to the element after the trigger. When the trigger is the last element, focus leaves the popup.                                          |
+| Shift+Tab    | From the start of the popup, back to the trigger. The popover stays open.                                                                                                 |
+| Escape       | Closes the popover on top. With nested popovers, or a popover in a dialog, one Escape closes one layer. An Escape that ends an input method's composition closes nothing. |
+
+- **On open**, focus moves to the popup's first tab stop (the checked radio of a group, not an
+  item a roving widget takes out of the order), or to the popup itself when it has none. Opened by touch, the popup focuses itself, so no virtual keyboard opens.
+- **On close**, focus returns to the trigger without scrolling, unless a click outside landed on
+  another control, which keeps it. Escape and the close buttons return it too.
+- **Tab past the popup** closes it, so it never covers the control that takes focus; Shift+Tab
+  back to its trigger keeps it open, and so does focus moving into a toast.
+- **Closing it**, whatever closed it (a bound `open` set to false), closes the popovers, menus and
+  dialogs open inside it.
+- **A click outside** closes the popover; a right-click or a second finger does not. A press inside a nested popover does not close its
+  parent, and opening another popover closes the first.
+- Popovers opened from a dialog belong inside its `Popup`: everything outside a modal dialog is
+  inert.
+- **Opened on hover**, the popover leaves focus where it is, and closing it moves none (unless
+  focus had gone into it); it stays open while the pointer is on the trigger or the popup, and
+  Escape closes it without moving the pointer (WCAG 1.4.13).
+- **A modal popover** keeps Tab inside it (the page behind it is inert), and Escape, a press
+  outside or a close button closes it; focus returns to the trigger.
+- **`modal="trap-focus"`** keeps Tab and Shift+Tab going around the popup's tab stops (a radio
+  group is one stop, as a roving toolbar is), and nothing else: the page scrolls, and a press
+  outside lands where it is pressed (and closes the popover).
+
+## Without JavaScript, and the client script
+
+The trigger, the close buttons, Escape, the click outside and the placement are HTML and CSS
+features: a popover in a server-rendered page works before any script loads, and with none. So
+does a modal popover, through invoker commands and `closedby` (where a browser lacks them,
+[Dialog](dialog.md)'s script, which a modal popover loads, stands in). Opening on hover needs the
+script.
+`open`, `onOpenChange` and `bind:open` need the component to run in an island.
+
+A page that renders a `Popover` loads a 3.3 kB (brotli) module once, without the Lumiose runtime;
+islands bundle it. It covers every Popover on the page:
+
+- focus on open (the first focusable element, or the popup) and its return on close;
+- dismissal, shared with [Menu](menu.md) and [Combobox](combobox.md): a trigger's click makes the
+  popup a manual popover, which the script closes on a click outside (main button only, so a
+  right-click or a second finger does not close it, as in Base UI), on Escape and other close
+  requests (the Android back gesture), and when another popover opens outside it. Until the
+  script loads, the browser's light dismiss closes it on any press outside;
+- `aria-expanded` on the triggers;
+- the placement in browsers without CSS anchor positioning, which it keeps current on scroll and
+  resize;
+- opening on hover: the delays, the grace and the safe triangle to cross the gap to the popup,
+  and keeping it open after a click on the trigger;
+- `modal="trap-focus"`'s Tab loop.
+
+No `Backdrop` part: an open popover is in the top layer, so `.lu-popover::backdrop` (or a modal
+popover's `dialog::backdrop`) styles the layer under it, without an element of its own.
+
+## Browser support
+
+- **Popover and `popovertarget`**: every current browser (Baseline 2024).
+- **Invoker commands and `closedby`** (a modal popover): Chrome 135, Firefox 144, Safari 26.2 for
+  commands; Chrome 134 and Firefox 141 for `closedby`. Elsewhere Dialog's script stands in.
+- **CSS anchor positioning**: Chrome and Edge 125, Firefox 147, Safari 26. Elsewhere the client
+  script places the popup; without JavaScript there it opens in the middle of the viewport.
+- Safari and Firefox do not follow a trigger moved by a CSS `transform`.
+
+## Related
+
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Tooltip](tooltip.md): a short tip on hover or focus, with the same placement props.
+- [Dialog](dialog.md): a modal popup.

package/docs/preview-card.md

@@ -0,0 +1,130 @@
+# Preview Card
+
+> A card that previews a link's destination while the pointer or keyboard focus rests on the link, after Base UI's PreviewCard. The trigger is the link itself, which works as a link without JavaScript; the card is a manual popover placed with [Popover](popover.md)'s placement and opened with its hover timing by a 2.8 kB script. It is hoverable, persistent and dismissible (WCAG 1.4.13). `bind:open` keeps a signal in sync.
+
+```ts
+import { PreviewCard } from "@lumiose/ui"; // or "@lumiose/ui/preview-card"
+import "@lumiose/ui/preview-card.css"; // places the card next to its link
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<PreviewCard.Root>
+  <p>
+    … <PreviewCard.Trigger href="…" /> …
+  </p>
+  <PreviewCard.Popup />
+</PreviewCard.Root>
+```
+
+| Part      | Renders                                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------------------- |
+| `Root`    | No element. Holds the ids the other parts share.                                                           |
+| `Trigger` | `<a href data-preview-card="…">`, with an `anchor-name` in its `style`; `data-popup-open` while it is open |
+| `Popup`   | `<div popover="manual" data-side data-align>`, placed next to the link                                     |
+
+The card is a `<div>`: put it after the paragraph that holds the link, not inside it (a `<p>`
+cannot hold a `<div>`), with the Root around both.
+
+## API
+
+### PreviewCard.Root
+
+| Prop           | Type                      | Default |                                                           |
+| -------------- | ------------------------- | ------- | --------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Opens or closes the card when it changes, in the browser. |
+| `onOpenChange` | `(open: boolean) => void` |         | Called after the card opens or closes, whatever did it.   |
+| `bind:open`    | `Signal<boolean>`         |         | Stands in for `open` and `onOpenChange`.                  |
+
+### PreviewCard.Trigger
+
+| Prop         | Type     | Default |                                                                                |
+| ------------ | -------- | ------- | ------------------------------------------------------------------------------ |
+| `delay`      | `number` | `600`   | How long the pointer or focus rests on the link before the card opens, in ms.  |
+| `closeDelay` | `number` | `300`   | How long the card stays after the pointer leaves the link and the card, in ms. |
+
+Every other `<a>` prop passes through: `href`, `target`, `class`, `aria-*`.
+
+### PreviewCard.Popup
+
+`side`, `align`, `sideOffset` and `alignOffset`, as on [Popover.Popup](popover.md#popoverpopup);
+every other `<div>` prop passes through.
+
+**Differences from Base UI's PreviewCard.** No `Portal`, `Positioner` or `Viewport`: the top
+layer and CSS anchor positioning replace them, and the placement props are on `Popup`.
+
+- **No `Backdrop`**: the open card is in the top layer, so `.lu-preview-card::backdrop` styles the
+  layer under it, without an element.
+- **No `Arrow`**, as in Popover and Tooltip: anchor positioning gives no arrow offset when the card
+  shifts to fit. A pointer that follows `data-side` is a `::before` of your CSS.
+- **No detached triggers** (`handle`, `payload`) or `actionsRef`: a card's content is markup
+  rendered with it, so each link has its Root and its card, in server HTML too. In an island, a
+  signal per link does what a payload does.
+
+## Example
+
+```tsx check
+import { PreviewCard } from "@lumiose/ui";
+
+export function SignalsLink() {
+  return (
+    <PreviewCard.Root>
+      <p>
+        Lumiose components update through{" "}
+        <PreviewCard.Trigger href="/docs/concepts/signals">signals</PreviewCard.Trigger>.
+      </p>
+      <PreviewCard.Popup class="lu-preview-card">
+        <strong>Signals</strong>
+        <p>Values that update whatever reads them.</p>
+      </PreviewCard.Popup>
+    </PreviewCard.Root>
+  );
+}
+```
+
+A card is a visual enhancement, as Base UI says: what it shows should also be on the linked page.
+
+## Styling
+
+**With the default theme**, put `lu-preview-card` on `Popup`: a surface like a popover's, 8px from
+the link, with a fade (none where motion is reduced).
+
+**With your own CSS**, style the card through `class`, `:popover-open`, `[data-side]` and
+`[data-align]`, and the link through `[data-popup-open]`. `--lu-side-offset` and
+`--lu-align-offset` set the offsets.
+
+`@lumiose/ui/preview-card.css` is the placement Popover and Tooltip share (placement.css).
+
+## Keyboard and focus
+
+| Key    | Does                                                                                                        |
+| ------ | ----------------------------------------------------------------------------------------------------------- |
+| Tab    | Onto the link: the card opens after the delay, focus stays on the link. Again: into the open card, then on. |
+| Escape | Closes the card without moving the pointer; from inside the card, focus goes back to the link.              |
+| Enter  | Follows the link.                                                                                           |
+
+- **Hover** opens the card after the delay; it stays while the pointer is on the link or the card
+  (it may cross the gap between them) and closes after the close delay once it left both.
+- **Focus** opens it too; it closes when focus leaves the link and the card. The open card follows
+  its link in the focus order (the link is its invoker).
+- **Touch** follows the link: no card opens on a tap.
+- **A press outside** closes it, as Escape does (the dismissal model of Popover and Menu).
+
+## Without JavaScript, and the client script
+
+The link is a plain link and the card never opens. A page that renders a `PreviewCard` loads a
+2.8 kB (brotli) module once (with the hover timing it shares with Popover): hover and focus with
+their delays, dismissal, `data-popup-open`, and the placement in browsers without CSS anchor
+positioning.
+
+## Browser support
+
+Popover and CSS anchor positioning as in [Popover](popover.md#browser-support): the script places
+the card where anchor positioning is missing.
+
+## Related
+
+- [Popover](popover.md): a popup a click opens, or a hover with `openOnHover`.
+- [Tooltip](tooltip.md): a short text tip on hover or focus.