wings-plugin-sdk 0.3.0 → 0.5.0

package/README.md

@@ -120,11 +120,11 @@ 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; as a `ul` or `ol`, a list with no bullets |
+| `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` |
-| `Title` | `as` (`h1`, `h2`, `h3`), `size` (`large`) | A page's or a card's title, like a sprint's name or a setup step's question |
+| `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 |
+| `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 |
@@ -139,7 +139,7 @@ component mounts, so main answers with what it has. `useBroadcast(listener)` get
 | `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`, `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 |
+| `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `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/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
 | `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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.3.0",
+  "version": "0.5.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"
@@ -70,8 +70,10 @@
     }
   },
   "devDependencies": {
+    "@types/react": "^19.1.8",
     "jsdom": "^30.1.2",
     "react": "^19.1.0",
-    "react-dom": "^19.1.0"
+    "react-dom": "^19.1.0",
+    "typescript": "~6.0.3"
   }
 }

package/ui-css.js

@@ -152,6 +152,15 @@ export const fallbackCss = `/* wings-ui 2 start
 .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 {
@@ -484,6 +493,11 @@ export const fallbackCss = `/* wings-ui 2 start
   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 {

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 | "ul" | "ol"; 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. */
-export function Stack(props: Props<"div"> & { as?: As | "ul" | "ol"; 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"> & {
@@ -67,9 +76,10 @@ export function Text(
 /** A section heading, an `h2`, with `actions` like chips or a button on its right. */
 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. */
-export function Title(props: Props<"h1"> & { as?: "h1" | "h2" | "h3"; size?: "large" }): ReactElement;
-/** A card. `compact` for a summary line. As a `form` it holds a form; as a `ul` or `ol`, a list of `li`. */
-export function Card(props: Props<"div"> & { as?: As | "form" | "article" | "ul" | "ol"; compact?: boolean }): ReactElement;
+/** `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 ----------
 
@@ -182,7 +192,9 @@ export interface ComboboxOption {
  * 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.
+ * `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"> & {
@@ -191,9 +203,19 @@ export function Combobox(
     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;
+    /**
+     * When the list is shown. `"auto"` (default): on focus, a click, a key or typing, and Escape, Tab, blur to another
+     * element or a press outside close it. `"whileText"`: the list is shown exactly while the field has text and an
+     * option matches it, whether or not the field has focus. Escape, Tab and a press outside only clear the highlighted
+     * option (`aria-activedescendant`); emptying the text or picking closes it, and there's no `empty` message. A
+     * list left open after the field loses focus is a screen reader caveat, see the README.
+     */
+    open?: "auto" | "whileText";
     filter?: (option: ComboboxOption, query: string) => boolean;
     /** What shows when nothing matches. */
     empty?: ReactNode;

package/ui.js

@@ -85,9 +85,9 @@ export function Text({ as = "span", tone, size, weight, mono, numeric, truncate,
   });
 }
 
-/** A page's or a card's title: an `h1` unless `as` says otherwise. `size` large for a bigger one. */
-export function Title({ as = "h1", size, className, ...rest }) {
-  return h(as, { ...rest, className: cx("w-title", className), "data-size": size });
+/** 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. */
@@ -363,41 +363,57 @@ function useCloseOutside(open, root, close) {
 /**
  * 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.
+ * option, the field shows `value` once you've picked, and the list starts on the first option. `open="whileText"`
+ * keeps the list shown while the field has text and something matches, which Escape, Tab and a press outside don't close.
  */
-export function Combobox({ label, value, onInput, options, onPick, freeText = false, openOnFocus = true, filter = contains, empty = "No matches.", className, ...rest }) {
+export function Combobox({ label, value, onInput, options, onPick, onEnter, onKeyDown: onKeyDownProp, freeText = false, openOnFocus = true, open: openMode = "auto", 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 [opened, setOpened] = 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 text = freeText ? value : query;
+  // "whileText": the list is open exactly while there is text and something matches it, whatever has focus.
+  const whileText = openMode === "whileText";
+  const open = whileText ? text !== "" : opened;
+  const shown = open ? options.filter((o) => filter(o, text)) : [];
+  const visible = whileText ? shown.length > 0 : open;
   const current = Math.min(active, shown.length - 1);
   const optionId = (i) => `${id}-option-${i}`;
 
   const close = () => {
-    setOpen(false);
+    setOpened(false);
     setQuery("");
     setActive(-1);
   };
+  // Escape, Tab and a press outside: a "whileText" list stays, so only the highlight goes.
+  const dismiss = whileText ? () => setActive(-1) : close;
   const openAt = (i) => {
-    setOpen(true);
+    setOpened(true);
     setActive(i);
   };
   const pick = (option) => {
     onPick(option);
     close();
   };
-  useCloseOutside(open, root, close);
+  useCloseOutside(open && !whileText, root, dismiss);
   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.
@@ -410,10 +426,14 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
       // 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();
+      if (e.key === "Escape" && (whileText ? current >= 0 : open)) e.preventDefault();
+      dismiss();
     }
   };
 
@@ -424,16 +444,18 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
       "aria-label": label,
       ...field,
       id,
+      ref: input,
       className: "w-input",
       role: "combobox",
       "aria-autocomplete": "list",
       "aria-controls": `${id}-list`,
-      "aria-expanded": open,
+      "aria-expanded": visible,
       "aria-activedescendant": current >= 0 ? optionId(current) : undefined,
       autoComplete: "off",
       spellCheck: false,
       value: freeText || !open ? value : query,
-      onFocus: () => {
+      onFocus: (e) => {
+        if (!freeText) e.currentTarget.select();
         if (!openOnFocus) return;
         if (!freeText) setQuery("");
         openAt(first);
@@ -450,13 +472,13 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
         openAt(first);
       },
       onBlur: (e) => {
-        if (e.relatedTarget && !root.current.contains(e.relatedTarget)) close();
+        if (e.relatedTarget && !root.current.contains(e.relatedTarget)) dismiss();
       },
       onKeyDown,
     }),
     h(
       "div",
-      { className: "w-listbox", hidden: !open },
+      { className: "w-listbox", hidden: !visible },
       h(
         "ul",
         { id: `${id}-list`, role: "listbox", "aria-label": label, ref: list },
@@ -481,7 +503,7 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
           ),
         ),
       ),
-      open && !shown.length ? h("p", { className: "w-option-empty", role: "status" }, empty) : null,
+      open && !whileText && !shown.length ? h("p", { className: "w-option-empty", role: "status" }, empty) : null,
     ),
   );
 }