@lumiose/ui 0.0.0-stage → 0.1.0

package/dist/tooltip/tooltip.script.ts

@@ -0,0 +1,222 @@
+// Tooltip's client script (decision-62, decision-63): what opens and closes a tooltip, for every
+// Tooltip on the page. A trigger is an element whose `aria-describedby` names a
+// `[popover][role=tooltip]`; the innermost one under the pointer wins. It follows Base UI and Zag
+// (doc-9, section 4):
+//
+// - Opens after the trigger's `data-delay` (600 ms) of hover by a mouse or pen, never by touch, or
+//   at once on keyboard focus (`:focus-visible`). Within 400 ms of another tooltip, it opens at
+//   once. Only one tooltip is open at a time.
+// - A press before the delay cancels it. Closes on Escape (only the tooltip: the keydown is
+//   cancelled, so a dialog around it stays open), on a press, on a click of its trigger (unless
+//   `data-close-on-click="false"`), on blur, and when an ancestor of the trigger scrolls.
+// - Hoverable (WCAG 1.4.13): it stays open while the pointer moves onto it, unless the popup has
+//   `data-disable-hoverable-popup`, and closes `data-close-delay` (0 ms) after the pointer leaves.
+// - Placement where CSS anchor positioning is missing (placement/place.ts).
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+import { anchoring, place } from "../placement/place.ts";
+
+/** After a tooltip closes, how long the next one opens without delay (Base UI's Provider). */
+const GROUP = 400;
+/** How long a hoverable tooltip waits for the pointer to cross the gap from its trigger. */
+const GRACE = 100;
+
+let current: { trigger: HTMLElement; popup: HTMLElement } | undefined;
+let pending: { trigger: HTMLElement; timer: ReturnType<typeof setTimeout> } | undefined;
+let closing: ReturnType<typeof setTimeout> | undefined;
+let closedAt = Number.NEGATIVE_INFINITY;
+/** A trigger whose tooltip a click closed: it stays closed until the pointer or focus leaves. */
+let suppressed: HTMLElement | undefined;
+
+function on<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  options: AddEventListenerOptions = {},
+) {
+  document.addEventListener(type, listener, { capture: true, ...options });
+}
+
+/** The tooltip that describes `trigger`, if any. */
+function tipOf(trigger: Element): HTMLElement | undefined {
+  for (const id of (trigger.getAttribute("aria-describedby") ?? "").split(/\s+/)) {
+    const tip = id ? document.getElementById(id) : null;
+    if (tip?.matches("[popover][role=tooltip]")) return tip;
+  }
+  return undefined;
+}
+
+/** The innermost tooltip trigger at or around `node`. */
+function triggerAt(node: EventTarget | null): HTMLElement | undefined {
+  let element = node instanceof Element ? node.closest("[aria-describedby]") : null;
+  while (element) {
+    if (element instanceof HTMLElement && tipOf(element)) return element;
+    element = element.parentElement?.closest("[aria-describedby]") ?? null;
+  }
+  return undefined;
+}
+
+const ms = (trigger: HTMLElement, name: string, fallback: number) => {
+  const value = Number(trigger.getAttribute(name) ?? Number.NaN);
+  return Number.isFinite(value) ? value : fallback;
+};
+
+const hoverable = (popup: HTMLElement) => !popup.hasAttribute("data-disable-hoverable-popup");
+
+function cancel() {
+  clearTimeout(pending?.timer);
+  clearTimeout(closing);
+  pending = undefined;
+  closing = undefined;
+}
+
+function show(trigger: HTMLElement) {
+  cancel();
+  const popup = tipOf(trigger);
+  if (!popup) return;
+  if (current && current.popup !== popup) hide();
+  current = { trigger, popup };
+  if (!popup.matches(":popover-open")) {
+    // `source` makes the trigger the tooltip's invoker: a tooltip inside a popover keeps it open.
+    (popup.showPopover as (options?: { source?: HTMLElement }) => void)({ source: trigger });
+  }
+  if (!anchoring) place(popup, trigger);
+}
+
+function hide() {
+  cancel();
+  const popup = current?.popup;
+  current = undefined;
+  closedAt = performance.now();
+  if (popup?.matches(":popover-open")) popup.hidePopover();
+}
+
+/** Opens `trigger`'s tooltip after its delay, or at once within the group window. */
+function schedule(trigger: HTMLElement) {
+  if (trigger.hasAttribute("data-trigger-disabled") || trigger === suppressed) return;
+  if (current?.trigger === trigger) {
+    clearTimeout(closing);
+    return;
+  }
+  if (pending?.trigger === trigger) return;
+  clearTimeout(pending?.timer);
+  const warm = current !== undefined || performance.now() - closedAt < GROUP;
+  const delay = warm ? 0 : ms(trigger, "data-delay", 600);
+  if (delay === 0) show(trigger);
+  else pending = { trigger, timer: setTimeout(() => show(trigger), delay) };
+}
+
+on("pointerover", (event) => {
+  if (event.pointerType === "touch") return;
+  const target = event.target as Node;
+  if (current && hoverable(current.popup) && current.popup.contains(target)) {
+    clearTimeout(closing);
+    return;
+  }
+  const trigger = triggerAt(target);
+  if (trigger) schedule(trigger);
+});
+
+on("pointerout", (event) => {
+  if (event.pointerType === "touch") return;
+  const from = event.target as Node;
+  const to = event.relatedTarget as Node | null;
+  const left = (element: HTMLElement) => element.contains(from) && !element.contains(to);
+  if (pending && left(pending.trigger)) cancel();
+  if (suppressed && left(suppressed)) suppressed = undefined;
+  if (!current) return;
+  const { trigger, popup } = current;
+  const inside = (node: Node | null) =>
+    trigger.contains(node) || (hoverable(popup) && popup.contains(node));
+  if (inside(from) && !inside(to)) {
+    clearTimeout(closing);
+    const delay = ms(trigger, "data-close-delay", 0);
+    closing = setTimeout(hide, hoverable(popup) ? Math.max(delay, GRACE) : delay);
+  }
+});
+
+on("pointerdown", (event) => {
+  const target = event.target as Node;
+  clearTimeout(pending?.timer);
+  pending = undefined;
+  if (!current || current.popup.contains(target)) return;
+  const { trigger } = current;
+  if (trigger.contains(target)) {
+    if (trigger.getAttribute("data-close-on-click") === "false") return;
+    suppressed = trigger;
+  }
+  hide();
+});
+
+// A click on the trigger, from the keyboard (Enter or Space) too.
+on("click", (event) => {
+  if (!current || !current.trigger.contains(event.target as Node)) return;
+  if (current.trigger.getAttribute("data-close-on-click") === "false") {
+    // The browser light-dismisses a hint on a press outside it, its trigger included: undo it.
+    if (!current.popup.matches(":popover-open")) show(current.trigger);
+    return;
+  }
+  suppressed = current.trigger;
+  hide();
+});
+
+on("focusin", (event) => {
+  const target = event.target as HTMLElement;
+  const trigger = triggerAt(target);
+  if (!trigger || trigger.hasAttribute("data-trigger-disabled")) return;
+  if (target.matches(":focus-visible")) show(trigger);
+});
+
+on("focusout", (event) => {
+  const target = event.target as Node;
+  const to = event.relatedTarget as Node | null;
+  if (suppressed?.contains(target) && !suppressed.contains(to)) suppressed = undefined;
+  if (current?.trigger.contains(target) && !current.trigger.contains(to)) hide();
+});
+
+on("keydown", (event) => {
+  if (event.key !== "Escape" || !current?.popup.matches(":popover-open")) return;
+  // Only the tooltip closes: a cancelled keydown is no close request for a dialog around it.
+  event.preventDefault();
+  hide();
+});
+
+on(
+  "scroll",
+  (event) => {
+    const scroller = event.target;
+    if (current && scroller instanceof Node && scroller.contains(current.trigger)) hide();
+  },
+  { passive: true },
+);
+
+// Opened or closed another way: the `open` prop, or the browser's light dismiss of a hint.
+on("toggle", (event) => {
+  const popup = event.target;
+  if (!(popup instanceof HTMLElement) || !popup.matches("[popover][role=tooltip]")) return;
+  if (event.newState === "closed") {
+    if (current?.popup === popup) {
+      current = undefined;
+      closedAt = performance.now();
+    }
+    return;
+  }
+  if (current?.popup === popup) return;
+  const trigger = document.querySelector<HTMLElement>(
+    `[aria-describedby~="${CSS.escape(popup.id)}"]`,
+  );
+  if (!trigger) return;
+  if (current) hide();
+  current = { trigger, popup };
+  if (!anchoring) place(popup, trigger);
+});
+
+// Opened by the `open` prop: placed in the frame it first paints in.
+on("beforetoggle", (event) => {
+  const popup = event.target;
+  if (anchoring || event.newState !== "open" || !(popup instanceof HTMLElement)) return;
+  if (!popup.matches("[popover][role=tooltip]")) return;
+  requestAnimationFrame(() => {
+    const trigger = current?.popup === popup ? current.trigger : undefined;
+    if (trigger && popup.matches(":popover-open")) place(popup, trigger);
+  });
+});

package/dist/tooltip/tooltip.tsx

@@ -0,0 +1,149 @@
+// Tooltip (decision-62, TASK-356): a native `popover="hint"` (`manual` where the browser lacks
+// hint popovers) with `role="tooltip"`, placed next to its trigger with CSS anchor positioning
+// (placement.css). The trigger is described by it (`aria-describedby`), in server HTML too, so
+// assistive technology reads the tip without hovering, as the APG tooltip pattern asks; the
+// trigger still needs its own name. Hover and keyboard focus open it through the client script,
+// which reads the trigger's delays from its attributes. Ported from Timeless's approach
+// (https://timeless.build).
+import { createContext, effect, ref, useContext, useId } from "lumiose";
+import { anchorName, placement, withStyle, type PlacementProps } from "../placement/placement.ts";
+import tooltipScript from "./tooltip.script.ts?client";
+
+/**
+ * `Tooltip.Root` renders no element: it holds the ids its parts share. `bind:open={signal}`
+ * stands in for `open` and `onOpenChange`.
+ */
+export interface TooltipRootProps {
+  /**
+   * Opens (`true`) or closes (`false`) the tooltip when it changes, in the browser. Pair it with
+   * `onOpenChange` to keep a signal in sync; leave both out and hover and focus drive it.
+   */
+  open?: boolean;
+  /** Called after the tooltip opens or closes, whatever opened or closed it. */
+  onOpenChange?: (open: boolean) => void;
+  /** Hover and focus do not open the tooltip. The `open` prop still does. */
+  disabled?: boolean;
+  /**
+   * The tooltip closes as soon as the pointer leaves the trigger, instead of staying open while
+   * the pointer moves onto it. Default `false`: WCAG 1.4.13 asks for hoverable content.
+   */
+  disableHoverablePopup?: boolean;
+  /** The other parts: the `Tooltip.Trigger` and the `Tooltip.Popup`. */
+  children?: JSX.Element;
+}
+
+/**
+ * A `<button>` described by the tip (`aria-describedby`); its delays reach the client script as
+ * `data-` attributes.
+ */
+export type TooltipTriggerProps = JSX.IntrinsicElements["button"] & {
+  /** How long the pointer rests on the trigger before the tooltip opens, in ms. Default 600. */
+  delay?: number;
+  /** How long the tooltip stays after the pointer leaves, in ms. Default 0. */
+  closeDelay?: number;
+  /** Clicking the trigger closes the tooltip. Default `true`. */
+  closeOnClick?: boolean;
+};
+/**
+ * The tip: a `<span popover role="tooltip">`, placed next to the trigger. A `<span>`, so it may sit
+ * next to a trigger inside a paragraph.
+ */
+export type TooltipPopupProps = JSX.IntrinsicElements["span"] & PlacementProps;
+
+interface TooltipContextValue {
+  id: string;
+  popupId: string;
+  popup: JSX.Ref<HTMLSpanElement>;
+  props: TooltipRootProps;
+}
+
+const TooltipContext = createContext<TooltipContextValue>();
+
+function useTooltip(): TooltipContextValue {
+  const context = useContext(TooltipContext);
+  if (!context) throw new Error("Tooltip parts must be inside <Tooltip.Root>.");
+  return context;
+}
+
+function Root(props: TooltipRootProps) {
+  // Opens and closes tooltips on hover and focus, and places them without anchor positioning;
+  // the page loads it once (decision-63).
+  tooltipScript();
+  const id = useId();
+  const popup = ref<HTMLSpanElement>();
+  const context: TooltipContextValue = { id, popupId: `${id}-popup`, popup, props };
+
+  // The `open` prop drives the native state; the popup's `toggle` event reports back.
+  effect(() => {
+    const element = popup();
+    const wanted = props.open;
+    if (!element?.isConnected || wanted === undefined) return;
+    const shown = element.matches(":popover-open");
+    if (wanted && !shown) element.showPopover();
+    else if (!wanted && shown) element.hidePopover();
+  });
+
+  return <TooltipContext value={context}>{props.children}</TooltipContext>;
+}
+
+function Trigger({ children, delay, closeDelay, closeOnClick, ...rest }: TooltipTriggerProps) {
+  const tooltip = useTooltip();
+  const described = () =>
+    [tooltip.popupId, rest["aria-describedby"]].filter(Boolean).join(" ") || undefined;
+  return (
+    <button
+      type="button"
+      {...rest}
+      aria-describedby={described()}
+      style={withStyle(rest.style, { "anchor-name": anchorName(tooltip.id) })}
+      data-delay={delay}
+      data-close-delay={closeDelay}
+      data-close-on-click={closeOnClick === false ? "false" : undefined}
+      data-trigger-disabled={tooltip.props.disabled ? "" : undefined}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Popup({
+  children,
+  ref: forwarded,
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  ...rest
+}: TooltipPopupProps) {
+  const tooltip = useTooltip();
+  return (
+    <span
+      role="tooltip"
+      {...rest}
+      {...placement({ side, align, sideOffset, alignOffset, style: rest.style }, tooltip.id, "top")}
+      data-disable-hoverable-popup={tooltip.props.disableHoverablePopup ? "" : undefined}
+      ref={(element: HTMLSpanElement) => {
+        tooltip.popup(element);
+        forwarded?.(element);
+      }}
+      id={tooltip.popupId}
+      popover="hint"
+      on:toggle={(event: ToggleEvent) => tooltip.props.onOpenChange?.(event.newState === "open")}
+    >
+      {children}
+    </span>
+  );
+}
+
+/**
+ * A short tip next to its trigger, on hover or keyboard focus. The trigger is described by it, in
+ * server HTML too; give an icon-only trigger its own `aria-label`. Unstyled: style the parts
+ * through `class` and native state (`:popover-open`, `[data-side]`).
+ *
+ * @example
+ * <Tooltip.Root>
+ *   <Tooltip.Trigger aria-label="Bold">B</Tooltip.Trigger>
+ *   <Tooltip.Popup sideOffset={6}>Bold (⌘B)</Tooltip.Popup>
+ * </Tooltip.Root>
+ */
+export const Tooltip = { Root, Trigger, Popup };

package/docs/README.md

@@ -0,0 +1,174 @@
+# UI components
+
+> `@lumiose/ui`: accessible, unstyled UI primitives built on native elements (`<dialog>`, popover, invoker commands, CSS anchor positioning), server-rendered without hydration. Style them with your own CSS or the optional default theme.
+
+**Status:** in development. `@lumiose/ui` keeps its own 0.x versions, apart from the version all
+other Lumiose packages share, and is not on npm yet: today it is used from this repository's
+workspace. The goal for its 1.0 is parity with [Base UI](https://base-ui.com)'s components; the
+table below lists them as they land.
+
+These pages ship in the package, in `node_modules/@lumiose/ui/docs`, so they match the installed
+version, and the Lumiose site renders them with a live demo of each example at
+[itsjavi.com/lumiose/ui](https://itsjavi.com/lumiose/ui/). Start with [Installation](installation.md)
+and [Theming](theming.md). For coding agents, `llms.txt` indexes them and `llms-full.txt` holds them all;
+`lumiose docs ui` and `lumiose docs dialog` print them; the MCP server's `ui_components` tool lists
+every component's parts, props, events and styling hooks; and `lumiose agents init` adds a UI
+section to `AGENTS.md` and the `lumiose-ui` skill. Every component page has the same sections:
+Anatomy, API, Example, Styling, Keyboard and focus, Without JavaScript, Browser support and Related.
+
+## Approach
+
+- **Native first.** A component renders the element the platform already has for the job: a
+  `<dialog>` opened by an invoker command, a popover, a `<button>`. Those work in server HTML
+  before any script loads, and keep the browser's own keyboard handling and focus management.
+- **Custom elements only where the platform falls short.** Keyboard navigation in a menu or the
+  filtering of a combobox need script: those components render a light-DOM custom element with a
+  `lu-` tag (`lu-menu`, `lu-combobox`) that upgrades the server HTML in place. A page is meant to
+  load only the definitions of the elements it renders, and no island runtime for them (in
+  development, with those components).
+- **Small scripts for native gaps.** Where a native element falls short of Base UI's behaviour, a
+  small script closes the gap, such as Dialog's right-click and touch handling. The component
+  still works without it; a page that renders the component loads it once, without the island
+  runtime.
+- **Parts.** Each component is a set of parts named as in Base UI (`Dialog.Root`,
+  `Dialog.Trigger`, `Dialog.Popup`, …). Every part that renders an element takes that element's
+  props (`class`, `style`, `aria-*`, events) and passes them through.
+- **Signals.** A component's state is a prop and a callback: `open` with `onOpenChange`, `checked`
+  with `onCheckedChange`, `value` with `onValueChange`. Pass a signal's value and write it back in
+  the callback to keep both in sync, or leave both out and the element keeps its own state. Custom
+  elements report changes with lowercase DOM events, like native ones: `openchange`,
+  `checkedchange` and `change`.
+- **Keyboard contracts.** Every component follows its WAI-ARIA Authoring Practices pattern, and
+  its end-to-end tests check the keyboard paths.
+- **WCAG 2.2 AA.** Every component meets it: the components own semantics, keyboard and
+  behaviour, and the default theme owns the visual criteria (contrast, non-text contrast, focus
+  visible, target size). Each component's end-to-end tests run axe with the WCAG A and AA rules,
+  closed and open, in light and dark, and check reflow at 320 CSS pixels and text spacing.
+
+This is the approach of [Timeless](https://timeless.build), ported to Lumiose.
+
+## Styling
+
+`@lumiose/ui` is **unstyled**: its stylesheets hold only what a component needs to work (display,
+positioning and anchoring, the top layer, the CSS variables a component sets), in the `lu.core`
+cascade layer. A look is opt-in: the default theme, or your own CSS. [Installation](installation.md)
+shows the imports, and [Theming](theming.md) the layers, the theme's classes and custom properties,
+and how to style the parts yourself.
+
+### The default theme
+
+`@lumiose/ui/themes/default.css` is a ready look for demos, prototypes and getting started: neutral
+surfaces, a blue primary, light and dark. Its classes (`lu-button`, `lu-dialog`, …) and its `--lu-`
+custom properties, named as in shadcn/ui, are listed in [Theming](theming.md#the-default-theme).
+
+## Components
+
+| Component                             | Status                                                                                    |
+| ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [Dialog, alert dialog](dialog.md)     | Available: native `<dialog>`, works without JavaScript                                    |
+| [Popover](popover.md)                 | Available: native popover, works without JavaScript                                       |
+| [Tooltip](tooltip.md)                 | Available: native hint popover, opened by its script                                      |
+| [Menu](menu.md)                       | Available: popover menu, opens without JavaScript                                         |
+| [Combobox](combobox.md)               | Available: `<lu-combobox>`, a form control that filters its options                       |
+| [Select](select.md)                   | Available: native `<select>`, customizable where supported, no script                     |
+| [Tabs](tabs.md)                       | Available: server HTML with the full state, `<lu-tabs>` adds the keys                     |
+| [Field](field.md)                     | Available: label, description, errors; native validation in the field                     |
+| [Fieldset](fieldset.md)               | Available: native `<fieldset>` and `<legend>`, no script                                  |
+| [Form](form.md)                       | Available: native `<form>`, a form action's errors in its fields                          |
+| [Input](input.md)                     | Available: native `<input>`, no script                                                    |
+| [Checkbox](checkbox.md)               | Available: native checkbox, indeterminate and read-only                                   |
+| [Checkbox Group](checkbox-group.md)   | Available: checkboxes with one value and a parent checkbox                                |
+| [Radio](radio-group.md)               | Available: native radios in a radiogroup fieldset                                         |
+| [Switch](switch.md)                   | Available: native checkbox with the switch role                                           |
+| [Collapsible](collapsible.md)         | Available: native `<details>`, works without JavaScript                                   |
+| [Accordion](accordion.md)             | Available: native `<details>` items, `<lu-accordion>` adds the keys                       |
+| [Toast](toast.md)                     | Available: server-rendered or from a manager, `<lu-toast-viewport>` times and closes them |
+| [Button](button.md)                   | Available: native `<button>`, focusable when disabled                                     |
+| [Toggle](toggle.md)                   | Available: `<button aria-pressed>`, pressed by the component in an island                 |
+| [Toggle Group](toggle-group.md)       | Available: `<lu-toggle-group>` presses its toggles and moves focus                        |
+| [Progress](progress.md)               | Available: native `<progress>`, indeterminate when unknown, no script                     |
+| [Meter](meter.md)                     | Available: native `<meter>`, no script                                                    |
+| [Slider](slider.md)                   | Available: native range inputs, `<lu-slider>` adds ranges and Page Up and Page Down       |
+| [Number Field](number-field.md)       | Available: native number input, or a formatted spinbutton; press-and-hold buttons         |
+| [Autocomplete](autocomplete.md)       | Available: free text with suggestions, on Combobox's `<lu-combobox>`                      |
+| [OTP Field](otp-field.md)             | Available: one native input under visual slots; autofill, paste, validation natively      |
+| [Preview Card](preview-card.md)       | Available: a link whose hover or focus opens a card; the link works without JavaScript    |
+| [Toolbar](toolbar.md)                 | Available: `<lu-toolbar>`, one tab stop across buttons, links, inputs and toggles         |
+| [Scroll Area](scroll-area.md)         | Available: native scrolling, custom scrollbars from `<lu-scroll-area>`                    |
+| [Context Menu](context-menu.md)       | Available: Menu at the pointer, opened by its script (right-click, long press, keys)      |
+| [Drawer](drawer.md)                   | Available: a Dialog against an edge, works without JavaScript; its script adds the swipe  |
+| [Separator](separator.md)             | Available: native `<hr>`, horizontal or vertical, no script                               |
+| [Avatar](avatar.md)                   | Available: an image over its fallback, `<lu-avatar>` follows its loading status           |
+| [Menubar](menubar.md)                 | Available: Menus in a `role="menubar"`, `<lu-menubar>` moves between them                 |
+| [Navigation Menu](navigation-menu.md) | Available: a `<nav>` whose triggers open panels of links, works without JavaScript        |
+
+## Ids
+
+The parts connect themselves by id (`for`, `aria-labelledby`, `aria-controls`, `popovertarget`,
+`commandfor`), which they generate. A server renders a page once, in order: a part can take an
+`id` of yours only where nothing before it in the page points at it, and the parts after it then
+point at yours.
+
+- **Your `id` names it**: the triggers of Accordion, Collapsible, Menu (and submenus) and Navigation
+  Menu; Tabs' tabs; Combobox's `Label` and `Item`s; the `Title` and `Description` of a Dialog,
+  Drawer or Popover (the popup renders them before its own attributes); a Toast's `Root`; the
+  `Label` of a Slider, Progress or Meter; and the elements that nothing points at (a Slider's
+  `Root`, a Tabs or Accordion `Root`, a Toolbar, a Tooltip's trigger).
+- **It keeps its generated id**, because a part before it points at it: the popups of Dialog,
+  Drawer, Popover, Tooltip, Preview Card and Menu; Navigation Menu's `Content`; the panels of Tabs,
+  Accordion and Collapsible; Combobox's `Input`, `List` and `Popup`; a Slider's thumbs and the
+  tracks of Progress and Meter (their `Label` points at them); a Field's control (`Field.Label`).
+  Combobox's and Field's `Root` keep theirs too: their scripts find the parts by it. A Number
+  Field or an OTP Field takes the input's `id` on its `Root`.
+
+To reach a popup or a panel from elsewhere (a `commandfor`, a `#hash` link), point at a part that
+takes your `id`, such as a tab, or read the generated id from the rendered page.
+
+## Right to left
+
+There is no direction provider: every component reads the direction from the page, the `dir`
+attribute on `<html>` or on any container around it, when it acts (TASK-385). Right to left:
+
+- **Arrow keys** that move along a row swap: Tabs, Toggle Group, Toolbar, Menubar, Navigation
+  Menu, Accordion's and Menu's submenu keys, a Radio group (the browser's), Slider and Number
+  Field's scrub area (leftward goes up).
+- **Placement** follows logical sides and alignment: `inline-start` and `inline-end` sides, and
+  `align="start"` or `"end"`, mirror; `left` and `right` sides stay physical, as in Base UI.
+- **Sliders and scrollbars** run from the right: a Slider's track and Indicator, a Scroll Area's
+  horizontal thumb, a Progress or Meter bar (the indeterminate segment slides leftward).
+- **Swipes** are physical: a Toast or a Drawer swiped right goes right in either direction.
+- **The theme** uses logical properties (`inset-inline-*`, `margin-inline-*`, `border-inline-*`),
+  so it mirrors with no extra rule. A numeric OTP Field keeps its slots left to right, as digits
+  read in right-to-left scripts too.
+
+The theme avoids `:dir()`, so it also mirrors in a project whose own `build.cssTarget` predates
+`:dir()`: Lightning CSS, which minifies production CSS, then lowers it to a list of `:lang()`
+selectors that misses a `dir` attribute. It uses `[dir="rtl"]` around the component instead, or
+logical properties.
+
+## Localisation
+
+Labels and messages come from your markup, with four English defaults to override for another
+language (TASK-456):
+
+| Default                | Where                                                     | Override                          |
+| ---------------------- | --------------------------------------------------------- | --------------------------------- |
+| "Notifications (F6)"   | [Toast](toast.md)`.Viewport`, the landmark's name         | `aria-label` on `Toast.Viewport`  |
+| "Remove"               | [Combobox](combobox.md)`.Chips`, before each chip's label | `removeLabel` on `Combobox.Chips` |
+| "Increase", "Decrease" | [Number Field](number-field.md)'s step buttons            | `aria-label` on each button       |
+
+Validation messages are the browser's, in its language; a Field's `validate` and a form action's
+errors are yours.
+
+## Size
+
+`@lumiose/ui` is opt-in, so its size is reported apart from the runtime's caps:
+`pnpm --filter @lumiose/ui size` prints, per component, the JavaScript a server-rendered page loads
+for its custom elements, the JavaScript an island that uses it loads, and its CSS (minified, gzip
+and brotli).
+
+## Related
+
+- [Web components](https://itsjavi.com/lumiose/docs/guides/web-components/): custom elements in Lumiose pages and islands.
+- [Islands](https://itsjavi.com/lumiose/docs/concepts/islands/): where components run in the browser.
+- [JSX](https://itsjavi.com/lumiose/docs/concepts/jsx/): `class`, events and `on:`.