wings-plugin-sdk 0.2.0 → 0.4.0

package/README.md

@@ -106,7 +106,8 @@ the page out edge to edge with no padding, for a page that scrolls on its own, l
 You don't write the page's HTML. For `src/sidebar.tsx` that calls one of these, `wings-plugin build` writes
 `sidebar.html` with a mount point, its CSS and its script, titled like the manifest's page. A `sidebar.html` you
 write yourself wins: the build only writes a page that's missing or that it wrote before (it carries a
-`Generated by wings-plugin build` line). A page that builds its DOM itself, without React, gets the same shell
+`Generated by wings-plugin build` line). A popover's page takes its sidebar's title, the name Wings gives the
+popover too. A page that builds its DOM itself, without React, gets the same shell
 from `mountShell(place, options)` in `wings-plugin-sdk/shell`, which returns the element to fill.
 
 ### Talking to main
@@ -119,28 +120,41 @@ component mounts, so main answers with what it has. `useBroadcast(listener)` get
 
 | Component | Props | Renders |
 |---|---|---|
-| `Row`, `Stack` | `gap` (`none`, `xs`, `s`, `m`, `l`), `grow`; `Row` also `align`, `justify`, `wrap`; `as` | Children side by side or one under the other |
+| `Row`, `Stack` | `gap` (`none`, `xs`, `s`, `m`, `l`), `grow`; `Row` also `align`, `justify`, `wrap`; `as` (`form`, `ul`, `ol` too) | Children side by side or one under the other; as a `ul` or `ol`, a list with no bullets. With `as`, the props and handlers are the element's: `<Row as="form" onSubmit={(e) => e.currentTarget.requestSubmit()}>` has a `HTMLFormElement` |
 | `Text` | `tone` (`muted`, `info`, `success`, `warn`, `danger`), `size` (`small`, `tiny`), `weight` (`medium`, `strong`), `mono`, `numeric`, `truncate`, `clamp`, `grow`, `as` | A span, or the element in `as` |
-| `Heading` | `actions` | A section heading, `h2`, with chips or a button on its right |
-| `Card` | `compact` | A card |
+| `Title` | `as` (`h1`, `h2`, `h3`), `size` (`large`), `truncate` | A page's or a card's title, like a sprint's name or a setup step's question |
+| `Heading` | `level` (2, 3, 4), `actions` | A small section heading, `h2` by default, with chips or a button on its right |
+| `Card` | `compact`, `as` (`form`, `ul`, `ol` too) | A card, a card that's a form, or a list. Typed for its `as` element like `Row` and `Stack` |
 | `Gauge`, `Meter` | `label`, `percent`, `note`, `tone` or `levels` | A labelled bar with its percentage, or the bar alone, with the meter role |
 | `Stats` | `items: { label, value, tone? }[]` | Small figures side by side, label over value |
 | `Properties` | `items: { label, value }[]` | Label and value pairs |
 | `List`, `ListItem`, `ListButton` | `ordered` and `compact` on `List`, `align` on the rows | A list of rows; a `ListButton` in a `ListItem` makes the row a button |
-| `Dot`, `Spinner` | `tone`, `size`, `label` | A status dot or a spinner, announced only with a `label` |
+| `Dot`, `Spinner` | `tone`, `size`, `label`; `Dot` also `color` | A status dot or a spinner, announced only with a `label`. A dot's `color` comes from your data, like a work item type's `#cc293d` |
 | `Pill`, `Tag` | `tone` | A filled pill, or an outlined tag like a branch |
 | `Loading`, `Empty` | `Empty`: `title`, `detail` | Before the first data, and nothing to show |
-| `Button` | `variant` (`primary`, `ghost`, `danger`), `size` (`small`) | A button, `type="button"` |
-| `Chip`, `Chips` | `pressed`; `Chips`: `label`, `options`, `value`, `onChange` | A small quiet button, and a group of them that picks one, with `aria-pressed` |
+| `Button` | `variant` (`primary`, `ghost`, `danger`), `size` (`small`), `busy` | A button, `type="button"`; `busy` shows a spinner and ignores clicks, keeping focus |
+| `Chip`, `Chips` | `pressed`; `Chips`: `label`, `options`, `value`, `onChange` | A small quiet button, and a group of them that picks one, with `aria-pressed`. An option's other props, like `id`, go to its chip |
 | `Tabs` | `label`, `items`, `value`, `onChange`, `children` | Tabs with arrow keys, Home and End, over their panel |
-| `Field` | `label`, `hint`, `error` | A labelled field that names and describes the input in it |
+| `Field` | `label`, `hint`, `error`, `id`, `inline` | A labelled field that names and describes the input in it. `id` becomes the input's, for a page that puts focus back by id; `inline` puts the label beside it |
+| `FieldGroup` | `label`, `hint`, `error` | Several controls under one label, like checkboxes: a `fieldset` with its `legend`, described by the hint; an error marks each checkbox invalid |
 | `TextInput`, `SearchField`, `Select` | `label`; `Select`: `options`, `value`, `onChange` | Inputs Wings styles; outside a `Field`, `label` names them |
 | `Checkbox` | `checked`, `onChange`, `children` | A checkbox with its label |
+| `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) |
+| `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
 | `Disclosure` | `summary` | More behind a line that opens it |
 
 Every component passes other props, like `id`, `title`, `className`, `onClick` and `aria-*`, to its element.
 `TextInput` and `SearchField` pass `ref` to the input on React 19.
 
+A button that's working on something is `busy`: it shows a spinner, ignores clicks and says so with `aria-busy`
+and `aria-disabled`, and unlike `disabled` it keeps the keyboard focus:
+
+```tsx
+<Button variant="primary" busy={saving} onClick={save}>
+  Save
+</Button>
+```
+
 ### Ours or your own
 
 The components are there for a page that looks like the rest of Wings without effort, not a rule. Write your
@@ -157,6 +171,7 @@ page has:
 | `--wings-primary`, `--wings-primary-fg` | The primary button, and its text |
 | `--wings-info`, `--wings-success`, `--wings-warning`, `--wings-danger` | Tones |
 | `--wings-radius` | A card's corners |
+| `--wings-menu-bg`, `--wings-menu-ring`, `--wings-menu-active`, `--wings-shadow` | A raised layer like a menu or a list of suggestions, as Wings' own menus draw it: its opaque background, its edge, the highlighted option and its shadow |
 | `--wings-font`, `--wings-mono` | Fonts |
 
 ```tsx
@@ -179,33 +194,40 @@ function Banner({ children }: { children: string }) {
 ```
 
 Wings' base styles cover plain elements (buttons, inputs, selects and the page's font and colours), the `w-*`
-classes and two older helpers, `.muted` and `.card`; nothing else, so your other classes are yours. Your CSS loads after Wings', so it wins where you
-style a component, like `.my-list .w-list-button { height: 24px; }`.
+classes and two older helpers, `.muted` and `.card`; nothing else, so your other classes are yours. Your CSS
+loads after Wings', so it wins where you style a component, like `.my-list .w-list-button { height: 24px; }`.
 
 ### The class contract
 
 The components render plain elements with `w-*` class names and data attributes, like
 `<div class="w-card" data-size="compact">`, and no styles of their own. Wings styles them in its
 `plugin-ui.css`, which ships with the app, so a Wings update restyles every plugin. The names are a versioned
-public contract: `--wings-ui` on the page's root is its version, `1` now, and a version only adds classes.
-`Meter` sets `--w-value`, how full it is, which is data rather than a style.
+public contract: `--wings-ui` on the page's root is its version, `2` now, and a version only adds classes and
+rules. `Meter` sets `--w-value`, how full it is, and a `Dot` with a `color` sets `--w-color`; both are data
+rather than styles.
 
 `w-shell` with `data-place` (`sidebar`, `popover`, `view`, `tab`, `settings`) and `data-fill`; `w-row`,
 `w-stack` with `data-gap`, `data-align`, `data-justify`, `data-wrap`, `data-grow`; `w-text` with `data-tone`,
 `data-size`, `data-weight`, `data-mono`, `data-numeric`, `data-truncate`, `data-clamp`, `data-grow`;
-`w-heading`, `w-heading-row`; `w-card` with `data-size`; `w-gauge`, `w-gauge-label`, `w-gauge-value`,
+`w-title` with `data-size`; `w-heading`, `w-heading-row`; `w-card` with `data-size`; `w-gauge`, `w-gauge-label`, `w-gauge-value`,
 `w-gauge-note`, `w-meter` with `data-tone`, `w-meter-fill`; `w-stats`, `w-stat-label`, `w-stat-value`;
 `w-props`, `w-prop`, `w-prop-label`, `w-prop-value`; `w-list` with `data-density`, `w-list-item`,
-`w-list-button` with `data-align`; `w-dot`, `w-pill`, `w-tag` with `data-tone`; `w-spinner` with `data-size`;
-`w-loading`, `w-empty`, `w-empty-detail`; `w-button` with `data-variant`, `data-size`; `w-chips`, `w-chip`;
-`w-tabs`, `w-tab`; `w-field`, `w-field-label`, `w-field-hint`, `w-input`, `w-search`, `w-select`, `w-check`;
-`w-disclosure`.
+`w-list-button` with `data-align`; `w-dot` with `data-tone` or `data-color`; `w-pill`, `w-tag` with `data-tone`; `w-spinner` with `data-size`;
+`w-loading`, `w-empty`, `w-empty-detail`; `w-button` with `data-variant`, `data-size`, `aria-disabled`; `w-chips`, `w-chip`;
+`w-tabs`, `w-tab`; `w-field` with `data-layout`, `w-field-row`, `w-field-label`, `w-field-hint`,
+`w-field-group`, `w-input`, `w-search`, `w-select`, `w-check`; `w-combobox`, `w-listbox`, `w-option`,
+`w-option-label`, `w-option-detail`, `w-option-empty`; `w-menu-root`, `w-menu` with `data-align`, `w-menu-item`
+with `data-tone`; `w-disclosure`. A `ul` or `ol` with `w-row`, `w-stack` or `w-card` loses its bullets.
+
+Version 2 added `w-title`, `Heading`'s levels, `w-field-group`, `w-field-row`, the combobox and menu classes,
+`data-color` on `w-dot`, busy buttons (`aria-disabled` on `w-button`), lists as rows, stacks and cards, and the four raised-layer variables.
 
 ### Older Wings
 
-Wings before 0.1.15 has no `w-*` styles. A page built with `wings-plugin-sdk/ui` checks `--wings-ui` when it
-mounts, and on a Wings without it, or with an older version, adds the same styles from the package, before
-your CSS. So a plugin works on older Wings without a `minWingsVersion`, and on a current Wings it always gets
+Wings before 0.1.15 has no `w-*` styles, and a Wings with `--wings-ui: 1` lacks version 2's. A page built with
+`wings-plugin-sdk/ui` checks `--wings-ui` when it mounts, and on a Wings without it, or with an older version,
+adds the package's own copy of the styles, before Wings' and your CSS. Since a version only adds rules, the old
+ones Wings has and the new ones from the package fit together. So a plugin works on older Wings without a `minWingsVersion`, and on a current Wings it always gets
 Wings' own styles.
 
 ### A linked SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Types, React hooks, UI components and a build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
     }
   },
   "scripts": {
-    "test": "node --test"
+    "test": "tsc -p tsconfig.json && node --test"
   },
   "bin": {
     "wings-plugin": "bin.mjs"
@@ -68,5 +68,12 @@
     "react-dom": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "jsdom": "^30.1.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "~6.0.3"
   }
 }

package/ui-css.js

@@ -2,12 +2,21 @@
 // in plugin-ui.css wins whenever it's there, so a Wings update restyles every plugin. Keep both the same.
 
 /** The version of the classes this package renders. Wings' plugin-ui.css sets it as `--wings-ui`. */
-export const UI_VERSION = 1;
+export const UI_VERSION = 2;
 
-export const fallbackCss = `/* wings-ui 1 start
+export const fallbackCss = `/* wings-ui 2 start
    The classes wings-plugin-sdk/ui renders, a public contract: the names and data attributes stay, and Wings may
    restyle them. wings-plugin-sdk carries a copy of this block for older Wings without --wings-ui, so keep the
-   two the same (apps/desktop/src/lib/plugin-ui.test.ts checks). Bump --wings-ui when a class is added. */
+   two the same (apps/desktop/src/lib/plugin-ui.test.ts checks). Bump --wings-ui when a class is added, and only add
+   rules: on an older Wings the SDK's copy loads before Wings' own, so a changed rule would lose to the old one. */
+
+/* Raised layers, like a list of suggestions or a menu, as Wings' own menus draw them. */
+:root {
+  --wings-menu-bg: rgb(32 29 35);
+  --wings-menu-ring: rgb(236 233 228 / 0.1);
+  --wings-menu-active: rgb(255 255 255 / 0.08);
+  --wings-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+}
 
 /* The page's place: a sidebar, popover, view (modal, window or tab) or settings page. */
 .w-shell {
@@ -44,6 +53,13 @@ export const fallbackCss = `/* wings-ui 1 start
   gap: 8px;
   min-width: 0;
 }
+:is(ul, ol):is(.w-row, .w-stack, .w-card) {
+  margin: 0;
+  list-style: none;
+}
+:is(ul, ol):is(.w-row, .w-stack) {
+  padding: 0;
+}
 :is(.w-row, .w-stack)[data-gap="none"] {
   gap: 0;
 }
@@ -126,6 +142,26 @@ export const fallbackCss = `/* wings-ui 1 start
   min-width: 0;
 }
 
+/* A page's or a card's title. */
+.w-title {
+  font-size: 14px;
+  font-weight: 600;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+.w-title[data-size="large"] {
+  font-size: 15px;
+}
+/* A title cut to one line with an ellipsis, like Text truncate. */
+.w-title[data-truncate] {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+:is(.w-row, .w-list-item, .w-list-button) > .w-title[data-truncate] {
+  min-width: 0;
+}
+
 /* A section heading, with its controls on the right. */
 .w-heading {
   margin-top: 6px;
@@ -330,6 +366,10 @@ export const fallbackCss = `/* wings-ui 1 start
 .w-dot[data-tone="danger"] {
   background: var(--wings-danger);
 }
+/* A colour from the plugin's data, like a work item type's, in --w-color. */
+.w-dot[data-color] {
+  background: var(--w-color);
+}
 .w-spinner {
   flex: none;
   width: 10px;
@@ -440,11 +480,24 @@ export const fallbackCss = `/* wings-ui 1 start
 .w-button[data-variant="ghost"]:hover {
   background: var(--wings-hover);
 }
+/* Busy: it keeps focus, unlike a disabled button, and looks like one. */
+.w-button[aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: default;
+}
+.w-button[aria-disabled="true"]:active {
+  transform: none;
+}
 .w-button[data-size="small"] {
   height: 24px;
   padding: 0 8px;
   font-size: 12px;
 }
+/* A busy button's spinner takes the button's text colour, so it shows on primary, danger, ghost and default alike. */
+.w-button .w-spinner {
+  border-color: color-mix(in srgb, currentColor 25%, transparent);
+  border-top-color: currentColor;
+}
 
 /* Chips: small quiet buttons, and a group of them that filters what shows. */
 .w-chips {
@@ -508,6 +561,28 @@ export const fallbackCss = `/* wings-ui 1 start
   font-size: 12px;
   font-weight: 500;
 }
+.w-field[data-layout="inline"] > .w-field-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.w-field-row > .w-field-label {
+  flex: none;
+}
+.w-field-group {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.w-field-group > legend {
+  margin-bottom: 4px;
+  padding: 0;
+}
 .w-field-hint {
   font-size: 12px;
   color: var(--wings-muted);
@@ -530,6 +605,93 @@ export const fallbackCss = `/* wings-ui 1 start
   margin: 0;
 }
 
+/* A field with suggestions under it, and a menu under a button: raised lists of options. */
+.w-combobox,
+.w-menu-root {
+  position: relative;
+  min-width: 0;
+}
+.w-menu-root {
+  display: inline-block;
+}
+.w-listbox,
+.w-menu {
+  position: absolute;
+  z-index: 10;
+  top: calc(100% + 4px);
+  left: 0;
+  max-height: 240px;
+  margin: 0;
+  padding: 4px;
+  overflow: auto;
+  list-style: none;
+  border-radius: var(--wings-radius);
+  background: var(--wings-menu-bg);
+  box-shadow:
+    0 0 0 1px var(--wings-menu-ring),
+    var(--wings-shadow);
+}
+.w-listbox {
+  right: 0;
+}
+.w-listbox > ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.w-menu {
+  min-width: 100%;
+  width: max-content;
+}
+.w-menu[data-align="end"] {
+  left: auto;
+  right: 0;
+}
+.w-listbox[hidden],
+.w-menu[hidden] {
+  display: none;
+}
+.w-option,
+.w-menu-item {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 4px 6px;
+  border-radius: 8px;
+  cursor: default;
+}
+.w-option[aria-selected="true"],
+.w-menu-item:focus {
+  background: var(--wings-menu-active);
+}
+/* Like Wings' own menus, the highlight shows where focus is. */
+.w-menu-item:focus-visible {
+  outline: none;
+}
+.w-menu-item[data-tone="danger"] {
+  color: var(--wings-danger);
+}
+.w-option-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.w-option-detail {
+  flex: none;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  color: var(--wings-muted);
+}
+.w-option-empty {
+  padding: 4px 6px;
+  color: var(--wings-muted);
+}
+
 /* More behind a summary line. */
 .w-disclosure > summary {
   padding: 4px 6px;
@@ -543,5 +705,5 @@ export const fallbackCss = `/* wings-ui 1 start
     animation: none;
   }
 }
-/* wings-ui 1 end */
+/* wings-ui 2 end */
 `;

package/ui.d.ts

@@ -37,15 +37,24 @@ export function useMainState<T extends { type: string }>(type: T["type"], hello?
 export type Tone = "muted" | "info" | "success" | "warn" | "danger";
 type Props<Tag extends keyof JSX.IntrinsicElements> = ComponentPropsWithoutRef<Tag>;
 type As = "div" | "span" | "p" | "section" | "header" | "footer" | "strong" | "time" | "label" | "li";
+/** The elements `Row` and `Stack` can be. */
+type BoxAs = As | "form" | "ul" | "ol";
+/** The elements `Card` can be. */
+type CardAs = As | "form" | "article" | "ul" | "ol";
+/** The props of element `E`, with `own` on top: where they share a name, `own` wins. */
+type Own<E extends keyof JSX.IntrinsicElements, own> = Omit<Props<E>, keyof own> & own;
 /** Spacing between children: none, xs (2px), s (4px), m (8px, the default) or l (12px), set by Wings. */
 export type Gap = "none" | "xs" | "s" | "m" | "l";
 
 // ---------- layout and text ----------
 
-/** Children side by side, centred. */
-export function Row(props: Props<"div"> & { as?: As; gap?: Gap; align?: "start" | "baseline"; justify?: "end" | "between"; wrap?: boolean; grow?: boolean }): ReactElement;
-/** Children one under the other. */
-export function Stack(props: Props<"div"> & { as?: As; gap?: Gap; grow?: boolean }): ReactElement;
+/**
+ * Children side by side, centred. `as` picks the element, like a `form` or a `ul`; the props and handlers are the
+ * element's, so `<Row as="form" onSubmit={(e) => e.currentTarget.requestSubmit()}>` has a `HTMLFormElement`.
+ */
+export function Row<E extends BoxAs = "div">(props: Own<E, { as?: E; gap?: Gap; align?: "start" | "baseline"; justify?: "end" | "between"; wrap?: boolean; grow?: boolean }>): ReactElement;
+/** Children one under the other. As a `ul` or `ol` it's a list with no bullets, of `li` children. `as` types the props like `Row`'s. */
+export function Stack<E extends BoxAs = "div">(props: Own<E, { as?: E; gap?: Gap; grow?: boolean }>): ReactElement;
 /** Text with a tone and size, that can `grow` to fill a row or `truncate` with an ellipsis. */
 export function Text(
   props: Props<"span"> & {
@@ -65,9 +74,12 @@ export function Text(
   },
 ): ReactElement;
 /** A section heading, an `h2`, with `actions` like chips or a button on its right. */
-export function Heading(props: Props<"h2"> & { actions?: ReactNode }): ReactElement;
-/** A card. `compact` for a summary line. */
-export function Card(props: Props<"div"> & { as?: As; compact?: boolean }): ReactElement;
+export function Heading(props: Props<"h2"> & { level?: 2 | 3 | 4; actions?: ReactNode }): ReactElement;
+/** A page's or a card's title, like a sprint's name or a setup step's question: an `h1` unless `as` says otherwise. */
+/** `truncate` cuts a title that's too long for its place to one line, with an ellipsis. */
+export function Title(props: Props<"h1"> & { as?: "h1" | "h2" | "h3"; size?: "large"; truncate?: boolean }): ReactElement;
+/** A card. `compact` for a summary line. As a `form` it holds a form; as a `ul` or `ol`, a list of `li`. `as` types the props like `Row`'s. */
+export function Card<E extends CardAs = "div">(props: Own<E, { as?: E; compact?: boolean }>): ReactElement;
 
 // ---------- figures ----------
 
@@ -98,7 +110,14 @@ export function ListButton(props: Props<"button"> & { align?: "baseline" }): Rea
 // ---------- status ----------
 
 /** A status dot, green unless `tone` says otherwise. With a `label` it's announced; otherwise it's decoration. */
-export function Dot(props: Props<"span"> & { tone?: Exclude<Tone, "success">; label?: string }): ReactElement;
+export function Dot(
+  props: Props<"span"> & {
+    tone?: Exclude<Tone, "success">;
+    /** A colour from your data, like a work item type's `#cc293d`, set as `--w-color`. Wins over `tone`. */
+    color?: string;
+    label?: string;
+  },
+): ReactElement;
 /** A spinner. With a `label` it's announced; otherwise it's decoration. */
 export function Spinner(props: Props<"span"> & { size?: "large"; label?: string }): ReactElement;
 /** A filled pill, like a label on a command. */
@@ -112,8 +131,11 @@ export function Empty(props: Omit<Props<"div">, "title"> & { title: ReactNode; d
 
 // ---------- buttons ----------
 
-/** A button, `type="button"` unless you say otherwise. */
-export function Button(props: Props<"button"> & { variant?: "primary" | "ghost" | "danger"; size?: "small" }): ReactElement;
+/**
+ * A button, `type="button"` unless you say otherwise. `busy` shows a spinner and ignores clicks while it keeps the
+ * keyboard focus, unlike `disabled`: it's `aria-busy` and `aria-disabled`.
+ */
+export function Button(props: Props<"button"> & { variant?: "primary" | "ghost" | "danger"; size?: "small"; busy?: boolean }): ReactElement;
 /** A small quiet button. With `pressed` it's a toggle. */
 export function Chip(props: Props<"button"> & { pressed?: boolean }): ReactElement;
 export interface Option<V extends string> {
@@ -122,14 +144,34 @@ export interface Option<V extends string> {
   title?: string;
 }
 /** Chips that pick one of `options`, like a filter, in a group named `label`. `onChange` gets each click, the chip that's on too. */
-export function Chips<V extends string>(props: Omit<Props<"div">, "onChange"> & { label: string; options: Option<V>[]; value: V; onChange: (value: V) => void }): ReactElement;
+export function Chips<V extends string>(
+  props: Omit<Props<"div">, "onChange"> & {
+    label: string;
+    /** Each chip's other props, like `id`, go to its button. */
+    options: (Option<V> & Omit<Props<"button">, "value" | "onClick" | "children">)[];
+    value: V;
+    onChange: (value: V) => void;
+  },
+): ReactElement;
 /** Tabs named `label` over the panel they show, `children`. Arrow keys, Home and End move between tabs. */
 export function Tabs<V extends string>(props: Omit<Props<"div">, "onChange"> & { label: string; items: Option<V>[]; value: V; onChange: (value: V) => void }): ReactElement;
 
 // ---------- fields ----------
 
 /** A labelled field with a `hint` or an `error` under it, for the `TextInput`, `SearchField` or `Select` in `children`. */
-export function Field(props: Props<"div"> & { label: ReactNode; hint?: ReactNode; error?: ReactNode }): ReactElement;
+export function Field(
+  props: Props<"div"> & {
+    label: ReactNode;
+    hint?: ReactNode;
+    error?: ReactNode;
+    /** The input's id, and the label's `htmlFor`, for a page that puts focus back by id. Generated otherwise. */
+    id?: string;
+    /** The label and the input on one line. */
+    inline?: boolean;
+  },
+): ReactElement;
+/** Several controls under one label (a `fieldset` and its `legend`), like checkboxes, with a `hint` or an `error` under them. */
+export function FieldGroup(props: Props<"fieldset"> & { label: ReactNode; hint?: ReactNode; error?: ReactNode }): ReactElement;
 /** A text input. Outside a `Field`, give it a `label`. */
 export function TextInput(props: Props<"input"> & { label?: string; ref?: Ref<HTMLInputElement> }): ReactElement;
 /** A search box. `label` names it for screen readers. */
@@ -140,5 +182,49 @@ export function Select<V extends string>(
 ): ReactElement;
 /** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
 export function Checkbox(props: Omit<Props<"input">, "onChange" | "type"> & { onChange?: (checked: boolean) => void }): ReactElement;
+export interface ComboboxOption {
+  value: string;
+  label: string;
+  /** A second, quieter part, like a project's client. */
+  detail?: string;
+}
+/**
+ * A text field with `options` under it. Arrows move, Enter picks, Escape and Tab close, and pressing outside
+ * closes it. With `freeText` the field keeps what you type (`value`, `onInput`) and starts with nothing
+ * highlighted; otherwise you type to find an option and the field shows `value`, what you picked, once closed.
+ * `filter` decides what matches what's typed: the label or the detail containing it, by default. Without
+ * `freeText` the field's text is selected when it gets focus and after a pick, so typing replaces the label. An
+ * `onKeyDown` you pass runs first; `preventDefault()` in it keeps the Combobox's own keys from running.
+ */
+export function Combobox(
+  props: Omit<Props<"input">, "value" | "onInput" | "type"> & {
+    label?: string;
+    value: string;
+    onInput?: (text: string) => void;
+    options: ComboboxOption[];
+    onPick: (option: ComboboxOption) => void;
+    /** Enter with no option highlighted, with the text typed. The Enter doesn't submit a form around it. */
+    onEnter?: (text: string) => void;
+    freeText?: boolean;
+    /** Open the list when the field gets focus, by default; false opens it on a click, a key or typing only, for a page that puts focus back by id after it renders. */
+    openOnFocus?: boolean;
+    filter?: (option: ComboboxOption, query: string) => boolean;
+    /** What shows when nothing matches. */
+    empty?: ReactNode;
+  },
+): ReactElement;
+export interface MenuItem {
+  id: string;
+  label: ReactNode;
+  onSelect: () => void;
+  tone?: "danger";
+}
+/**
+ * A button, showing `label`, that opens a menu of `items` under it. Arrows, Home and End move, Enter or Space
+ * picks, Escape closes and puts focus back on the button. `align` end lines the menu up with the button's right.
+ */
+export function Menu(
+  props: Omit<Props<"button">, "children"> & { label: ReactNode; items: MenuItem[]; align?: "end"; variant?: "primary" | "ghost" | "danger"; size?: "small" },
+): ReactElement;
 /** More behind a `summary` line that opens it. */
 export function Disclosure(props: Props<"details"> & { summary: ReactNode }): ReactElement;

package/ui.js

@@ -1,7 +1,7 @@
 // wings-plugin-sdk/ui: a page says what to show and where, and Wings decides how it looks. Every component renders
 // plain elements with `w-*` class names and data attributes that Wings' plugin-ui.css styles, never a style of its
 // own, so a Wings update restyles every plugin. Your own components and CSS work alongside them.
-import { createContext, createElement as h, useContext, useEffect, useId, useState } from "react";
+import { createContext, createElement as h, useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 
 import { mountShell } from "./shell.js";
@@ -85,9 +85,14 @@ export function Text({ as = "span", tone, size, weight, mono, numeric, truncate,
   });
 }
 
-/** A section heading, with `actions` like chips or a button on its right. */
-export function Heading({ actions, className, ...rest }) {
-  const heading = h("h2", { ...rest, className: cx("w-heading", className) });
+/** A page's or a card's title: an `h1` unless `as` says otherwise. `size` large for a bigger one. `truncate` for one line. */
+export function Title({ as = "h1", size, truncate, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-title", className), "data-size": size, "data-truncate": flag(truncate) });
+}
+
+/** A small section heading, `h2` unless `level` says 3 or 4, with `actions` like chips or a button on its right. */
+export function Heading({ level = 2, actions, className, ...rest }) {
+  const heading = h(`h${level}`, { ...rest, className: cx("w-heading", className) });
   return actions ? h("div", { className: "w-heading-row" }, heading, actions) : heading;
 }
 
@@ -159,9 +164,20 @@ export function ListButton({ align, type = "button", className, ...rest }) {
 
 // ---------- status ----------
 
-/** A status dot. With a `label` it's announced; otherwise it's decoration next to text that says the same. */
-export function Dot({ tone, label, className, ...rest }) {
-  return h("span", { ...rest, className: cx("w-dot", className), "data-tone": tone, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
+/**
+ * A status dot. With a `label` it's announced; otherwise it's decoration next to text that says the same.
+ * `color` is a colour from your data, like a work item type's; otherwise `tone` colours it.
+ */
+export function Dot({ tone, color, label, className, style, ...rest }) {
+  return h("span", {
+    ...rest,
+    className: cx("w-dot", className),
+    // A colour that comes with the data, not a style: plugin-ui.css paints the dot with it, over any tone.
+    style: color ? { ...style, "--w-color": color } : style,
+    "data-color": color ? "" : undefined,
+    "data-tone": color ? undefined : tone,
+    ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }),
+  });
 }
 
 /** A spinner. With a `label` it's announced. */
@@ -192,8 +208,23 @@ export function Empty({ title, detail, className, ...rest }) {
 // ---------- buttons ----------
 
 /** A button. `variant` is primary, ghost or danger; `size` small. */
-export function Button({ variant, size, type = "button", className, ...rest }) {
-  return h("button", { ...rest, type, className: cx("w-button", className), "data-variant": variant, "data-size": size });
+export function Button({ variant, size, busy, type = "button", onClick, children, className, ...rest }) {
+  return h(
+    "button",
+    {
+      ...rest,
+      type,
+      className: cx("w-button", className),
+      "data-variant": variant,
+      "data-size": size,
+      // Busy, not disabled: a disabled button would drop the keyboard focus on the page.
+      "aria-busy": busy || undefined,
+      "aria-disabled": busy || rest["aria-disabled"],
+      onClick: busy ? (e) => e.preventDefault() : onClick,
+    },
+    busy ? h(Spinner) : null,
+    children,
+  );
 }
 
 /** A small quiet button. With `pressed` it's a toggle. */
@@ -206,7 +237,7 @@ export function Chips({ label, options, value, onChange, className, ...rest }) {
   return h(
     "div",
     { ...rest, className: cx("w-chips", className), role: "group", "aria-label": label },
-    options.map((o) => h(Chip, { key: o.value, pressed: o.value === value, title: o.title, onClick: () => onChange(o.value) }, o.label)),
+    options.map(({ value: v, label: text, ...chip }) => h(Chip, { ...chip, key: v, pressed: v === value, onClick: () => onChange(v) }, text)),
   );
 }
 
@@ -247,16 +278,40 @@ function useFieldProps(rest) {
   return field ? { id: field.id, "aria-describedby": field.hint, "aria-invalid": field.invalid || undefined, ...rest } : rest;
 }
 
-/** A labelled field with a `hint` or an `error` under it, for the input in `children`. */
-export function Field({ label, hint, error, children, className, ...rest }) {
-  const id = useId();
-  const note = error ?? hint;
+/** A hint or an error under a field or a group. */
+const fieldNote = (id, hint, error) => (error ?? hint ? h("p", { id, className: "w-field-hint", "data-tone": error ? "danger" : undefined }, error ?? hint) : null);
+
+/**
+ * A labelled field with a `hint` or an `error` under it, for the input in `children`. `id` is the input's id, for
+ * a page that puts focus back by id; `inline` puts the label and the input on one line.
+ */
+export function Field({ id: given, label, hint, error, inline, children, className, ...rest }) {
+  const generated = useId();
+  const id = given ?? generated;
+  const hintId = error ?? hint ? `${id}-hint` : undefined;
+  const labelled = h("label", { className: "w-field-label", htmlFor: id }, label);
+  const control = h(FieldContext.Provider, { value: { id, hint: hintId, invalid: Boolean(error) } }, children);
   return h(
     "div",
-    { ...rest, className: cx("w-field", className) },
-    h("label", { className: "w-field-label", htmlFor: id }, label),
-    h(FieldContext.Provider, { value: { id, hint: note ? `${id}-hint` : undefined, invalid: Boolean(error) } }, children),
-    note ? h("p", { id: `${id}-hint`, className: "w-field-hint", "data-tone": error ? "danger" : undefined }, note) : null,
+    { ...rest, className: cx("w-field", className), "data-layout": inline ? "inline" : undefined },
+    inline ? h("div", { className: "w-field-row" }, labelled, control) : labelled,
+    inline ? null : control,
+    fieldNote(hintId, hint, error),
+  );
+}
+
+const GroupContext = createContext(null);
+
+/** Several controls under one label, like a list of checkboxes, with a `hint` or an `error` under them. */
+export function FieldGroup({ label, hint, error, children, className, ...rest }) {
+  const id = useId();
+  const hintId = error ?? hint ? `${id}-hint` : undefined;
+  return h(
+    "fieldset",
+    { ...rest, className: cx("w-field-group", className), "aria-describedby": hintId },
+    h("legend", { className: "w-field-label" }, label),
+    h(GroupContext.Provider, { value: { invalid: Boolean(error) } }, children),
+    fieldNote(hintId, hint, error),
   );
 }
 
@@ -281,7 +336,255 @@ export function Select({ label, options, onChange, className, ...rest }) {
 
 /** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
 export function Checkbox({ onChange, children, className, ...rest }) {
-  return h("label", { className: cx("w-check", className) }, h("input", { ...rest, type: "checkbox", onChange: (e) => onChange?.(e.currentTarget.checked) }), children);
+  // In a FieldGroup with an error, each box says so: a group can't be marked invalid itself.
+  const group = useContext(GroupContext);
+  return h("label", { className: cx("w-check", className) }, h("input", { "aria-invalid": group?.invalid || undefined, ...rest, type: "checkbox", onChange: (e) => onChange?.(e.currentTarget.checked) }), children);
+}
+
+const contains = (option, query) => {
+  const q = query.trim().toLowerCase();
+  return !q || option.label.toLowerCase().includes(q) || Boolean(option.detail?.toLowerCase().includes(q));
+};
+
+/** Closes a raised list when you press the mouse outside `root`, while it's open. */
+function useCloseOutside(open, root, close) {
+  const latest = useRef(close);
+  latest.current = close;
+  useEffect(() => {
+    if (!open) return;
+    const away = (e) => {
+      if (!root.current?.contains(e.target)) latest.current();
+    };
+    document.addEventListener("mousedown", away);
+    return () => document.removeEventListener("mousedown", away);
+  }, [open, root]);
+}
+
+/**
+ * A text field with `options` under it. Arrows move, Enter picks, Escape and Tab close. With `freeText` the field
+ * keeps what you type (`value`, `onInput`) and starts with nothing highlighted; otherwise you type to find an
+ * option, the field shows `value` once you've picked, and the list starts on the first option.
+ */
+export function Combobox({ label, value, onInput, options, onPick, onEnter, onKeyDown: onKeyDownProp, freeText = false, openOnFocus = true, filter = contains, empty = "No matches.", className, ...rest }) {
+  const field = useFieldProps(rest);
+  const generated = useId();
+  const id = field.id ?? generated;
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [active, setActive] = useState(-1);
+  const root = useRef(null);
+  const list = useRef(null);
+  const input = useRef(null);
+  const first = freeText ? -1 : 0;
+  const shown = open ? options.filter((o) => filter(o, freeText ? value : query)) : [];
+  const current = Math.min(active, shown.length - 1);
+  const optionId = (i) => `${id}-option-${i}`;
+
+  const close = () => {
+    setOpen(false);
+    setQuery("");
+    setActive(-1);
+  };
+  const openAt = (i) => {
+    setOpen(true);
+    setActive(i);
+  };
+  const pick = (option) => {
+    onPick(option);
+    close();
+  };
+  useCloseOutside(open, root, close);
+  useLayoutEffect(() => {
+    if (current >= 0) list.current?.children[current]?.scrollIntoView({ block: "nearest" });
+  }, [current]);
+  // A picker shows what was picked while it's closed, so select that text: typing replaces it, as it does in a
+  // native select-and-type field, instead of landing after it. MUI's Autocomplete does the same (`selectOnFocus`).
+  useLayoutEffect(() => {
+    if (!freeText && !open && document.activeElement === input.current) input.current.select();
+  }, [freeText, open, value]);
+
+  const onKeyDown = (e) => {
+    onKeyDownProp?.(e);
+    if (e.defaultPrevented) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      // A closed free-text field moves to the first option at once; a closed picker opens on its first.
+      if (!open) openAt(0);
+      else setActive(Math.min(current + 1, shown.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive(Math.max(current - 1, first));
+    } else if (e.key === "Enter" && open && current >= 0) {
+      // Picking from the list doesn't also submit a form around it.
+      e.preventDefault();
+      pick(shown[current]);
+    } else if (e.key === "Enter" && onEnter) {
+      // Nothing highlighted: the text is the answer, and Enter doesn't submit a form around it.
+      e.preventDefault();
+      onEnter(e.currentTarget.value);
+    } else if (e.key === "Escape" || e.key === "Tab") {
+      // An open list takes the Escape, so a form or dialog around it closes on the next one.
+      if (e.key === "Escape" && open) e.preventDefault();
+      close();
+    }
+  };
+
+  return h(
+    "div",
+    { className: cx("w-combobox", className), ref: root },
+    h("input", {
+      "aria-label": label,
+      ...field,
+      id,
+      ref: input,
+      className: "w-input",
+      role: "combobox",
+      "aria-autocomplete": "list",
+      "aria-controls": `${id}-list`,
+      "aria-expanded": open,
+      "aria-activedescendant": current >= 0 ? optionId(current) : undefined,
+      autoComplete: "off",
+      spellCheck: false,
+      value: freeText || !open ? value : query,
+      onFocus: (e) => {
+        if (!freeText) e.currentTarget.select();
+        if (!openOnFocus) return;
+        if (!freeText) setQuery("");
+        openAt(first);
+      },
+      // A field that kept focus after a pick or Escape opens again when you click it.
+      onClick: () => {
+        if (open) return;
+        if (!freeText) setQuery("");
+        openAt(first);
+      },
+      onChange: (e) => {
+        if (freeText) onInput?.(e.currentTarget.value);
+        else setQuery(e.currentTarget.value);
+        openAt(first);
+      },
+      onBlur: (e) => {
+        if (e.relatedTarget && !root.current.contains(e.relatedTarget)) close();
+      },
+      onKeyDown,
+    }),
+    h(
+      "div",
+      { className: "w-listbox", hidden: !open },
+      h(
+        "ul",
+        { id: `${id}-list`, role: "listbox", "aria-label": label, ref: list },
+        shown.map((o, i) =>
+          h(
+            "li",
+            {
+              key: o.value,
+              id: optionId(i),
+              role: "option",
+              className: "w-option",
+              "aria-selected": i === current,
+              // Before the field loses focus, so the pick lands.
+              onMouseDown: (e) => {
+                e.preventDefault();
+                pick(o);
+              },
+              onMouseMove: () => i !== current && setActive(i),
+            },
+            h("span", { className: "w-option-label" }, o.label),
+            o.detail ? h("span", { className: "w-option-detail" }, o.detail) : null,
+          ),
+        ),
+      ),
+      open && !shown.length ? h("p", { className: "w-option-empty", role: "status" }, empty) : null,
+    ),
+  );
+}
+
+/**
+ * A button that opens a menu of `items` under it, each `{ id, label, onSelect, tone? }`. Arrows, Home and End move,
+ * Enter or Space picks, Escape closes and puts focus back on the button. `align` end lines it up on the right.
+ */
+export function Menu({ label, items, align, variant, size, className, ...rest }) {
+  const id = useId();
+  const [open, setOpen] = useState(false);
+  const root = useRef(null);
+  const button = useRef(null);
+  const entries = useRef([]);
+  const close = (refocus) => {
+    setOpen(false);
+    if (refocus) button.current?.focus();
+  };
+  useCloseOutside(open, root, () => close(false));
+  useEffect(() => {
+    if (open) entries.current[0]?.focus();
+  }, [open]);
+  const select = (item) => {
+    close(true);
+    item.onSelect();
+  };
+  const onKeyDown = (e) => {
+    const at = entries.current.indexOf(document.activeElement);
+    const next = { ArrowDown: at + 1, ArrowUp: at - 1, Home: 0, End: items.length - 1 }[e.key];
+    if (next !== undefined) {
+      e.preventDefault();
+      entries.current[(next + items.length) % items.length]?.focus();
+    } else if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      if (at >= 0) select(items[at]);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      close(true);
+    } else if (e.key === "Tab") close(false);
+  };
+  return h(
+    "div",
+    { className: cx("w-menu-root", className), ref: root },
+    h(
+      "button",
+      {
+        ...rest,
+        type: "button",
+        id: `${id}-button`,
+        ref: button,
+        className: "w-button",
+        "data-variant": variant,
+        "data-size": size,
+        "aria-haspopup": "menu",
+        "aria-expanded": open,
+        "aria-controls": open ? `${id}-menu` : undefined,
+        onClick: () => setOpen(!open),
+        onKeyDown: (e) => {
+          if (e.key === "ArrowDown" && !open) {
+            e.preventDefault();
+            setOpen(true);
+          }
+        },
+      },
+      label,
+    ),
+    open
+      ? h(
+          "ul",
+          { id: `${id}-menu`, role: "menu", className: "w-menu", "aria-labelledby": `${id}-button`, "data-align": align, onKeyDown },
+          items.map((item, i) =>
+            h(
+              "li",
+              {
+                key: item.id,
+                role: "menuitem",
+                tabIndex: -1,
+                className: "w-menu-item",
+                "data-tone": item.tone,
+                ref: (el) => (entries.current[i] = el),
+                onClick: () => select(item),
+                onMouseMove: (e) => e.currentTarget.focus(),
+              },
+              item.label,
+            ),
+          ),
+        )
+      : null,
+  );
 }
 
 /** More behind a `summary` line that opens it. */