@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/toggle.md

@@ -0,0 +1,94 @@
+# Toggle
+
+> A two-state button (bold, mute, pin), after Base UI's Toggle: a native `<button type="button" aria-pressed>`. Its label stays the same; `aria-pressed` tells pressed from not. On its own the component presses it, in an island, and `bind:pressed` keeps a signal in sync; inside a [Toggle Group](toggle-group.md) the group presses it, on server pages too.
+
+```ts
+import { Toggle } from "@lumiose/ui"; // or "@lumiose/ui/toggle"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Toggle aria-label="Bold">B</Toggle>
+```
+
+| Part     | Renders                                                     |
+| -------- | ----------------------------------------------------------- |
+| `Toggle` | `<button type="button" aria-pressed="true">` (or `"false"`) |
+
+## API
+
+### Toggle
+
+| Prop              | Type                         | Default |                                                                         |
+| ----------------- | ---------------------------- | ------- | ----------------------------------------------------------------------- |
+| `pressed`         | `boolean`                    |         | Presses or releases it when it changes. Pair it with `onPressedChange`. |
+| `defaultPressed`  | `boolean`                    | `false` | Whether it starts pressed.                                              |
+| `onPressedChange` | `(pressed: boolean) => void` |         | Called after the user presses or releases it.                           |
+| `bind:pressed`    | `Signal<boolean>`            |         | Stands in for `pressed` and `onPressedChange`.                          |
+| `value`           | `string`                     |         | Its identity in a Toggle Group's `value`.                               |
+
+Every other native button prop passes through: `disabled`, `id`, `class`, `aria-label`, `aria-*`,
+`onClick` (`type` is always `"button"`).
+
+**Differences from Base UI's Toggle.** No `nativeButton` or `render`. `onPressedChange` gets the new
+state only; in a group, a `pressedchange` listener can cancel the press with
+`event.preventDefault()`.
+
+## Example
+
+```tsx check
+import { Toggle } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function PinToggle() {
+  const pinned = signal(false);
+  return (
+    <p>
+      <Toggle bind:pressed={pinned} class="lu-toggle">
+        Pin
+      </Toggle>{" "}
+      {pinned() ? "Pinned to the top." : "Not pinned."}
+    </p>
+  );
+}
+```
+
+Give an icon-only toggle an `aria-label` that names the action ("Bold"), not its state.
+
+## Styling
+
+**With the default theme**, put `lu-toggle` on it: a bordered 36px button that, pressed, takes a
+filled surface and a bar along its bottom edge, so the state shows by shape and not by colour alone.
+
+**With your own CSS**, style the button and its state: `[aria-pressed="true"]`, `:hover`,
+`:focus-visible`, `:disabled`.
+
+Toggle ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key           | Does                         |
+| ------------- | ---------------------------- |
+| Enter / Space | Presses or releases it.      |
+| Tab           | Moves on: one tab stop each. |
+
+In a Toggle Group, the group's arrow keys move between the toggles instead.
+
+## Without JavaScript
+
+A native button with its state in `aria-pressed` from the server. On its own, a Toggle is pressed
+by the component, so it needs an island (its state is for your code anyway); in a Toggle Group the
+group's script presses it on server pages too. For a value a form submits, use a
+[Checkbox](checkbox.md) or a [Switch](switch.md).
+
+## Browser support
+
+`aria-pressed` on a native button: every browser and screen reader.
+
+## Related
+
+- [Toggle Group](toggle-group.md): toggles that share one value, one or several pressed.
+- [Switch](switch.md): an on/off setting submitted with a form.
+- [Button](button.md): a plain button.

package/docs/toolbar.md

@@ -0,0 +1,138 @@
+# Toolbar
+
+> A set of controls with one tab stop, after Base UI's Toolbar and the APG toolbar pattern: `<lu-toolbar role="toolbar">` moves focus between its items with the arrow keys, Home and End, following the orientation and the text direction. Its items are native: buttons that stay focusable when disabled, links, inputs, and the toggles of a [Toggle Group](toggle-group.md) inside it. In the server HTML every item is a tab stop, so each is reachable without JavaScript; a 1.1 kB script makes them one tab stop and moves it.
+
+```ts
+import { Toolbar } from "@lumiose/ui"; // or "@lumiose/ui/toolbar"
+import "@lumiose/ui/toolbar.css"; // or "@lumiose/ui/styles.css" for every component
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Toolbar.Root>
+  <Toolbar.Button />
+  <Toolbar.Link />
+  <Toolbar.Separator />
+  <Toolbar.Group>
+    <Toolbar.Button />
+  </Toolbar.Group>
+  <Toolbar.Input />
+</Toolbar.Root>
+```
+
+| Part        | Renders                                                                                            |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-toolbar role="toolbar" aria-orientation data-orientation>`                                    |
+| `Button`    | A [Button](button.md): `<button type="button">`, `aria-disabled` when disabled (still focusable)   |
+| `Link`      | `<a>`                                                                                              |
+| `Input`     | `<input>`, `aria-disabled` and read-only when disabled (still focusable)                           |
+| `Group`     | `<div role="group">`                                                                               |
+| `Separator` | A [Separator](separator.md), `<hr>`, across the toolbar: vertical in a row, horizontal in a column |
+
+Every item gets `data-orientation`; the script gives the tab stop `tabindex="0"` and the other
+items `"-1"`. Name the toolbar with `aria-label` or `aria-labelledby`.
+
+## API
+
+### Toolbar.Root
+
+| Prop          | Type                         | Default        |                                                                        |
+| ------------- | ---------------------------- | -------------- | ---------------------------------------------------------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | A row moved through with Left and Right, or a column with Up and Down. |
+| `loopFocus`   | `boolean`                    | `true`         | The arrow keys go from the last item to the first, and back.           |
+| `disabled`    | `boolean`                    | `false`        | Disables every item but links; they stay focusable.                    |
+
+### Toolbar.Button, Toolbar.Input and Toolbar.Group
+
+| Prop                    | Type      | Default |                                                                    |
+| ----------------------- | --------- | ------- | ------------------------------------------------------------------ |
+| `disabled`              | `boolean` | `false` | Disables the item (a Group: its items).                            |
+| `focusableWhenDisabled` | `boolean` | `true`  | Button and Input: disabled, they stay focusable (`aria-disabled`). |
+
+Every other native prop passes through. A `ToggleGroup` inside a toolbar keeps pressing its
+toggles but leaves the arrow keys and the tab stop to the toolbar; a Menu or Popover trigger inside
+it is an item too. A disabled Root or Group reaches them: its toggles and triggers render
+`aria-disabled="true"` and stay focusable, but press and open nothing, without JavaScript too (the
+triggers lose `popovertarget`). A Menu in a vertical toolbar opens beside it, at its inline end, as
+in a vertical [Menubar](menubar.md). What a Menu's or a Popover's popup holds is not the toolbar's:
+its toggles and triggers keep their own tab stops.
+
+**Differences from Base UI's Toolbar.** No `render` or `nativeButton`: put other triggers
+(`Menu.Trigger`, `Popover.Trigger`) in the toolbar directly. Disabled items are `aria-disabled`
+rather than `data-disabled` and `data-focusable`.
+
+## Example
+
+```tsx check
+import { Toggle, ToggleGroup, Toolbar } from "@lumiose/ui";
+
+export function FormattingToolbar() {
+  return (
+    <Toolbar.Root aria-label="Formatting" class="lu-toolbar">
+      <ToggleGroup aria-label="Text style" multiple class="lu-toggle-group">
+        <Toggle value="bold" class="lu-toggle">
+          Bold
+        </Toggle>
+        <Toggle value="italic" class="lu-toggle">
+          Italic
+        </Toggle>
+      </ToggleGroup>
+      <Toolbar.Separator />
+      <Toolbar.Button class="lu-button">Undo</Toolbar.Button>
+      <Toolbar.Button class="lu-button" disabled>
+        Redo
+      </Toolbar.Button>
+      <Toolbar.Link href="/help">Help</Toolbar.Link>
+    </Toolbar.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-toolbar` on `Root`: a bordered row (a column when vertical)
+that wraps on narrow screens, groups in rows, separators as 1px lines across it, links as tall as
+the buttons. Style the items with their own classes (`lu-button`, `lu-toggle`, `lu-input`).
+
+**With your own CSS**, style the parts through `class`, `[data-orientation]`, `[role="group"]`,
+`hr` and the items' `[aria-disabled="true"]` and `:focus-visible`.
+
+`@lumiose/ui/toolbar.css` makes `<lu-toolbar>` a block box, as Base UI's `<div>`.
+
+## Keyboard and focus
+
+| Key                      | Does                                                                             |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| Tab                      | Into the toolbar on the last focused item (at first, the first), and out of it.  |
+| Arrow Right / Arrow Left | In a row: the next or previous item (swapped right to left), looping.            |
+| Arrow Down / Arrow Up    | In a column: the next or previous item, looping.                                 |
+| Home / End               | The first or last item.                                                          |
+| Enter / Space            | Acts on the item: presses a button or a toggle, follows a link.                  |
+| Arrow Right              | In a column, on a Menu's trigger: opens the menu beside it (Left right to left). |
+
+Natively disabled controls are skipped. When the item with the tab stop is removed, disabled or
+hidden, the first item takes it. A key an item handles itself (a Menu trigger's) moves nothing. A
+control keeps the keys it needs: a text field its
+caret's Left and Right (focus moves on at its start or end; with Shift they select) and Home and
+End, a number field or a slider its arrows, a select Up and Down. A text field the arrows reach has
+its text selected, as in Base UI. Base UI advises at most one input, last.
+
+## Without JavaScript, and the element's script
+
+The server HTML is a labelled toolbar whose items are all tab stops, so Tab reaches each one
+without JavaScript or before the script runs. `<lu-toolbar>`'s script (1.1 kB brotli with Button's)
+makes the toolbar one tab stop, moves focus with the keys and keeps the tab stop on the last focused
+item.
+
+## Browser support
+
+Custom elements and `role="toolbar"`: every supported browser and screen reader.
+
+## Related
+
+- [Toggle Group](toggle-group.md): toggles that share a value, in or out of a toolbar.
+- [Button](button.md): the items' button, focusable when disabled.
+- [Separator](separator.md): the line between groups.
+- [Menu](menu.md): a menu opened from a toolbar button.

package/docs/tooltip.md

@@ -0,0 +1,128 @@
+# Tooltip
+
+> A short tip next to its trigger, on hover or keyboard focus: a native `popover="hint"` with `role="tooltip"`, placed with CSS anchor positioning. The trigger is described by the tip in server HTML, so screen readers announce it without hovering; a 2.0 kB script opens and closes it as Base UI's tooltip does. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+
+```ts
+import { Tooltip } from "@lumiose/ui"; // or "@lumiose/ui/tooltip"
+import "@lumiose/ui/tooltip.css"; // places the tip next to its trigger
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Tooltip.Root>
+  <Tooltip.Trigger />
+  <Tooltip.Popup />
+</Tooltip.Root>
+```
+
+| Part      | Renders                                                                                                     |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `Root`    | No element. Holds the ids the parts share.                                                                  |
+| `Trigger` | `<button type="button" aria-describedby="…">`, with an `anchor-name` in its `style`.                        |
+| `Popup`   | `<span popover="hint" role="tooltip" data-side="…" data-align="…">`: a `<span>`, so it fits in a paragraph. |
+
+**Accessibility model.** The tooltip follows the
+[WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/): the tip is the
+trigger's description, always, not only while it shows. It is not its name: give an icon-only
+trigger an `aria-label` (Base UI asks the same).
+
+## API
+
+### Tooltip.Root
+
+| Prop                    | Type                      | Default |                                                                                                                                                                                                      |
+| ----------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`                  | `boolean`                 |         | Opens or closes the tip when it changes, in the browser.                                                                                                                                             |
+| `onOpenChange`          | `(open: boolean) => void` |         | Called after the tip opens or closes, whatever did it: hover, focus, Escape, `open`.                                                                                                                 |
+| `bind:open`             | `Signal<boolean>`         |         | Stands in for `open` and `onOpenChange`.                                                                                                                                                             |
+| `disabled`              | `boolean`                 | `false` | Hover and focus do not open the tip; `open` still does.                                                                                                                                              |
+| `disableHoverablePopup` | `boolean`                 | `false` | Closes the tip as soon as the pointer leaves the trigger, instead of letting it move onto the tip. WCAG 1.4.13 asks for hoverable content: use it only for tips that cover something the user needs. |
+
+### Tooltip.Trigger
+
+| Prop           | Type      | Default |                                                                        |
+| -------------- | --------- | ------- | ---------------------------------------------------------------------- |
+| `delay`        | `number`  | `600`   | How long the pointer rests on the trigger before the tip opens, in ms. |
+| `closeDelay`   | `number`  | `0`     | How long the tip stays after the pointer leaves, in ms.                |
+| `closeOnClick` | `boolean` | `true`  | A click (or Enter, or Space) on the trigger closes the tip.            |
+
+The trigger takes a `<button>`'s props too; an `aria-describedby` you pass is kept, after the tip.
+These props reach the client script as attributes of the trigger: `data-delay`,
+`data-close-delay`, `data-close-on-click="false"`, and `data-trigger-disabled` from `Root`'s
+`disabled`.
+
+### Tooltip.Popup
+
+The placement props of [Popover.Popup](popover.md#popoverpopup): `side` (default `"top"`),
+`align`, `sideOffset` and `alignOffset`.
+
+## Example
+
+```tsx check
+import { Tooltip } from "@lumiose/ui";
+
+export function BoldButton() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger class="lu-button" aria-label="Bold">
+        B
+      </Tooltip.Trigger>
+      <Tooltip.Popup class="lu-tooltip">Bold (Ctrl+B)</Tooltip.Popup>
+    </Tooltip.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-tooltip` on `Popup`: inverted colours, a 6px gap and a fade.
+
+**With your own CSS**, style the tip through `class`, `:popover-open`, `[data-side]` and
+`[data-align]`, and the offsets through `--lu-side-offset` and `--lu-align-offset`, as for
+[Popover](popover.md#styling). `@lumiose/ui/tooltip.css` holds the placement both share.
+
+## Keyboard and focus
+
+The [WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/), with Base UI's
+and Zag's opening rules:
+
+| Key          | Does                                                                             |
+| ------------ | -------------------------------------------------------------------------------- |
+| Tab          | Focusing the trigger from the keyboard opens the tip at once; leaving closes it. |
+| Escape       | Closes the tip, and only the tip: a dialog or popover around it stays open.      |
+| Enter, Space | Activate the trigger and close the tip, unless `closeOnClick={false}`.           |
+
+- **Opens** after `delay` of hover with a mouse or a pen, or at once on keyboard focus
+  (`:focus-visible`). A touch never opens it, and neither does the focus a mouse click gives.
+- **One at a time.** Within 400 ms of another tooltip closing, or while one is open, the next one
+  opens without delay, so moving along a toolbar reads each tip.
+- **A press before the delay** cancels the opening.
+- **Closes** on Escape (only the tip: a dialog or popover around it stays open), on a press, on a
+  click of the trigger (unless `closeOnClick={false}`), on blur, and when something around the
+  trigger scrolls.
+- **Hoverable** (WCAG 1.4.13): the pointer can move from the trigger onto the tip, across the gap,
+  and the tip stays; it closes `closeDelay` after the pointer leaves both.
+
+A tooltip inside a popover keeps the popover open, and one inside a dialog belongs inside its
+`Popup` (everything outside a modal dialog is inert).
+
+## Without JavaScript, and the client script
+
+Without JavaScript the tip never shows, but the trigger keeps its description: screen readers
+announce it. A page that renders a `Tooltip` loads a 2.0 kB (brotli) module once, without the
+Lumiose runtime; islands bundle it. It opens and closes every tooltip on the page, and places them
+in browsers without CSS anchor positioning.
+
+## Browser support
+
+- **`popover="hint"`**: Chrome and Edge from 133 (complete in 151), Firefox from 149 (complete in
+  153). Safari reads it as `popover="manual"`: the client script does the same work there.
+- **CSS anchor positioning**: Chrome and Edge 125, Firefox 147, Safari 26. Elsewhere the client
+  script places the tip.
+
+## Related
+
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Popover](popover.md): a popup with interactive content, opened by a click.

package/package.json

@@ -1,6 +1,105 @@
 {
   "name": "@lumiose/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Accessible, unstyled UI primitives for Lumiose: native elements first (dialog, popover, invoker commands, anchor positioning), light-DOM custom elements only where the platform falls short.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsjavi/lumiose.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css",
+    "**/*.script.ts"
+  ],
+  "exports": {
+    ".": "./dist/index.ts",
+    "./dialog": "./dist/dialog/dialog.tsx",
+    "./styles.css": "./dist/styles.css",
+    "./dialog.css": "./dist/dialog/dialog.css",
+    "./popover": "./dist/popover/popover.tsx",
+    "./popover.css": "./dist/popover/popover.css",
+    "./tooltip": "./dist/tooltip/tooltip.tsx",
+    "./tooltip.css": "./dist/tooltip/tooltip.css",
+    "./tabs": "./dist/tabs/tabs.tsx",
+    "./tabs.css": "./dist/tabs/tabs.css",
+    "./menu": "./dist/menu/menu.tsx",
+    "./menu.css": "./dist/menu/menu.css",
+    "./combobox": "./dist/combobox/combobox.tsx",
+    "./combobox.css": "./dist/combobox/combobox.css",
+    "./select": "./dist/select/select.tsx",
+    "./select.css": "./dist/select/select.css",
+    "./field": "./dist/field/field.tsx",
+    "./field.css": "./dist/field/field.css",
+    "./fieldset": "./dist/fieldset/fieldset.tsx",
+    "./form": "./dist/form/form.tsx",
+    "./input": "./dist/input/input.tsx",
+    "./checkbox": "./dist/checkbox/checkbox.tsx",
+    "./checkbox-group": "./dist/checkbox-group/checkbox-group.tsx",
+    "./radio-group": "./dist/radio-group/radio-group.tsx",
+    "./switch": "./dist/switch/switch.tsx",
+    "./collapsible": "./dist/collapsible/collapsible.tsx",
+    "./collapsible.css": "./dist/collapsible/collapsible.css",
+    "./accordion": "./dist/accordion/accordion.tsx",
+    "./accordion.css": "./dist/accordion/accordion.css",
+    "./toast": "./dist/toast/toast.tsx",
+    "./toast.css": "./dist/toast/toast.css",
+    "./button": "./dist/button/button.tsx",
+    "./toggle": "./dist/toggle/toggle.tsx",
+    "./toggle-group": "./dist/toggle-group/toggle-group.tsx",
+    "./progress": "./dist/progress/progress.tsx",
+    "./meter": "./dist/meter/meter.tsx",
+    "./slider": "./dist/slider/slider.tsx",
+    "./slider.css": "./dist/slider/slider.css",
+    "./context-menu": "./dist/context-menu/context-menu.tsx",
+    "./context-menu.css": "./dist/context-menu/context-menu.css",
+    "./drawer": "./dist/drawer/drawer.tsx",
+    "./drawer.css": "./dist/drawer/drawer.css",
+    "./number-field": "./dist/number-field/number-field.tsx",
+    "./number-field.css": "./dist/number-field/number-field.css",
+    "./autocomplete": "./dist/autocomplete/autocomplete.tsx",
+    "./autocomplete.css": "./dist/combobox/combobox.css",
+    "./separator": "./dist/separator/separator.tsx",
+    "./separator.css": "./dist/separator/separator.css",
+    "./avatar": "./dist/avatar/avatar.tsx",
+    "./avatar.css": "./dist/avatar/avatar.css",
+    "./otp-field": "./dist/otp-field/otp-field.tsx",
+    "./otp-field.css": "./dist/otp-field/otp-field.css",
+    "./preview-card": "./dist/preview-card/preview-card.tsx",
+    "./preview-card.css": "./dist/preview-card/preview-card.css",
+    "./toolbar": "./dist/toolbar/toolbar.tsx",
+    "./toolbar.css": "./dist/toolbar/toolbar.css",
+    "./scroll-area": "./dist/scroll-area/scroll-area.tsx",
+    "./scroll-area.css": "./dist/scroll-area/scroll-area.css",
+    "./menubar": "./dist/menubar/menubar.tsx",
+    "./menubar.css": "./dist/menubar/menubar.css",
+    "./navigation-menu": "./dist/navigation-menu/navigation-menu.tsx",
+    "./navigation-menu.css": "./dist/navigation-menu/navigation-menu.css",
+    "./themes/default.css": "./dist/themes/default.css",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@lumiose/compiler": "0.6.0",
+    "@lumiose/vite": "0.6.0",
+    "@types/node": "^24.0.0",
+    "happy-dom": "^20.14.5",
+    "lumiose": "0.6.0",
+    "vite": "^8.3.4"
+  },
+  "peerDependencies": {
+    "lumiose": "^0.6.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "size": "node scripts/size.ts",
+    "docs:gen": "node scripts/gen-llms.ts",
+    "docs:check": "node scripts/gen-llms.ts --check",
+    "build": "node scripts/build.ts"
+  }
 }