wings-plugin-sdk 0.3.0 → 0.4.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`, `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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.3.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"
@@ -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,6 +203,8 @@ 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;

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. */
@@ -365,7 +365,7 @@ function useCloseOutside(open, root, close) {
  * 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, 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, filter = contains, empty = "No matches.", className, ...rest }) {
   const field = useFieldProps(rest);
   const generated = useId();
   const id = field.id ?? generated;
@@ -374,6 +374,7 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
   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);
@@ -396,8 +397,15 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
   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,6 +418,10 @@ 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();
@@ -424,6 +436,7 @@ 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",
@@ -433,7 +446,8 @@ export function Combobox({ label, value, onInput, options, onPick, freeText = fa
       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);