wings-plugin-sdk 0.5.0 → 0.7.0

package/ui.js

@@ -1,601 +0,0 @@
-// 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, useLayoutEffect, useRef, useState } from "react";
-import { createRoot } from "react-dom/client";
-
-import { mountShell } from "./shell.js";
-
-export { mountShell } from "./shell.js";
-export { useBroadcast } from "./react.js";
-
-// ---------- places ----------
-
-let root = null;
-
-function show(place, element, options) {
-  const shell = mountShell(place, options);
-  root ??= createRoot(shell);
-  root.render(element);
-}
-
-/** Shows `element` as the page of a sidebar. One call per page; calling again renders the new element. */
-export const showSidebar = (element, options) => show("sidebar", element, options);
-/** Shows `element` as a view's page, in a modal or a window of its own. */
-export const showView = (element, options) => show("view", element, options);
-/** Shows `element` as a view's page in a tab next to the terminals. */
-export const showTab = (element, options) => show("tab", element, options);
-/** Shows `element` as a sidebar's popover. */
-export const showPopover = (element, options) => show("popover", element, options);
-/** Shows `element` as the plugin's page in Wings Settings. */
-export const showSettings = (element, options) => show("settings", element, options);
-
-// ---------- talking to main ----------
-
-const HELLO = { type: "hello" };
-
-/**
- * The newest message of `type` the plugin's other pages broadcast, or null until one comes. Sends `hello` once
- * when the component mounts, so main answers with its state; pass null to send nothing.
- */
-export function useMainState(type, hello = HELLO) {
-  const [state, setState] = useState(null);
-  useEffect(() => {
-    const off = wings.onBroadcast((message) => {
-      if (message?.type === type) setState(message);
-    });
-    if (hello != null) void wings.broadcast(hello);
-    return off;
-    // `hello` is only sent when the component mounts.
-  }, [type]);
-  return state;
-}
-
-// ---------- helpers ----------
-
-const cx = (base, extra) => (extra ? `${base} ${extra}` : base);
-/** A data attribute that's there or not. */
-const flag = (on) => (on ? "" : undefined);
-
-// ---------- layout and text ----------
-
-/** Children side by side, centred. `gap` is none, xs, s, m (default) or l. */
-export function Row({ as = "div", gap, align, justify, wrap, grow, className, ...rest }) {
-  return h(as, { ...rest, className: cx("w-row", className), "data-gap": gap, "data-align": align, "data-justify": justify, "data-wrap": flag(wrap), "data-grow": flag(grow) });
-}
-
-/** Children one under the other. */
-export function Stack({ as = "div", gap, grow, className, ...rest }) {
-  return h(as, { ...rest, className: cx("w-stack", className), "data-gap": gap, "data-grow": flag(grow) });
-}
-
-/** Text with a tone and size, that can grow to fill a row or truncate with an ellipsis. */
-export function Text({ as = "span", tone, size, weight, mono, numeric, truncate, clamp, grow, className, ...rest }) {
-  return h(as, {
-    ...rest,
-    className: cx("w-text", className),
-    "data-tone": tone,
-    "data-size": size,
-    "data-weight": weight,
-    "data-mono": flag(mono),
-    "data-numeric": flag(numeric),
-    "data-truncate": flag(truncate),
-    "data-clamp": flag(clamp),
-    "data-grow": flag(grow),
-  });
-}
-
-/** 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;
-}
-
-/** A card. `compact` for a summary line. */
-export function Card({ as = "div", compact, className, ...rest }) {
-  return h(as, { ...rest, className: cx("w-card", className), "data-size": compact ? "compact" : undefined });
-}
-
-// ---------- figures ----------
-
-const levelTone = (percent, levels) => (!levels ? undefined : percent >= levels[1] ? "danger" : percent >= levels[0] ? "warn" : undefined);
-
-/** A bar from 0 to 100. `tone` is warn or danger. */
-export function Meter({ percent, label, tone, className, ...rest }) {
-  return h(
-    "div",
-    { ...rest, className: cx("w-meter", className), role: "meter", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, "data-tone": tone },
-    // How full it is is data, not a style: plugin-ui.css sizes the bar from it.
-    h("span", { className: "w-meter-fill", style: { "--w-value": `${Math.max(0, Math.min(100, percent))}%` } }),
-  );
-}
-
-/** A labelled bar with its percentage and a note under it. `levels` are where it turns warn and danger. */
-export function Gauge({ label, percent, note, tone, levels, className, ...rest }) {
-  return h(
-    "div",
-    { ...rest, className: cx("w-gauge", className) },
-    h("span", { className: "w-gauge-label" }, label),
-    h("span", { className: "w-gauge-value" }, `${percent}%`),
-    h(Meter, { percent, label, tone: tone ?? levelTone(percent, levels) }),
-    note ? h("span", { className: "w-gauge-note" }, note) : null,
-  );
-}
-
-/** Small figures side by side, label over value. */
-export function Stats({ items, className, ...rest }) {
-  return h(
-    "dl",
-    { ...rest, className: cx("w-stats", className) },
-    items.map((item) => h("div", { key: item.label }, h("dt", { className: "w-stat-label" }, item.label), h("dd", { className: "w-stat-value", "data-tone": item.tone, title: item.title }, item.value))),
-  );
-}
-
-/** Label and value pairs, one per line. */
-export function Properties({ items, className, ...rest }) {
-  return h(
-    "dl",
-    { ...rest, className: cx("w-props", className) },
-    items.map((item) => h("div", { key: item.label, className: "w-prop" }, h("dt", { className: "w-prop-label" }, item.label), h("dd", { className: "w-prop-value" }, item.value))),
-  );
-}
-
-// ---------- lists ----------
-
-/** A list of rows. `ordered` for an `ol`, `compact` for rows with no space between them. */
-export function List({ ordered, compact, className, ...rest }) {
-  return h(ordered ? "ol" : "ul", { ...rest, className: cx("w-list", className), "data-density": compact ? "compact" : undefined });
-}
-
-/** A row in a `List`. Holding a `ListButton`, the button is the row. */
-export function ListItem({ align, className, ...rest }) {
-  return h("li", { ...rest, className: cx("w-list-item", className), "data-align": align });
-}
-
-/** A row that's a button, inside a `ListItem`. */
-export function ListButton({ align, type = "button", className, ...rest }) {
-  return h("button", { ...rest, type, className: cx("w-list-button", className), "data-align": align });
-}
-
-// ---------- status ----------
-
-/**
- * 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. */
-export function Spinner({ size, label, className, ...rest }) {
-  return h("span", { ...rest, className: cx("w-spinner", className), "data-size": size, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
-}
-
-/** A filled pill, like a label on a command. */
-export function Pill({ tone, className, ...rest }) {
-  return h("span", { ...rest, className: cx("w-pill", className), "data-tone": tone });
-}
-
-/** An outlined tag, like a branch name. */
-export function Tag({ tone, className, ...rest }) {
-  return h("span", { ...rest, className: cx("w-tag", className), "data-tone": tone });
-}
-
-/** What shows before the first data comes. */
-export function Loading({ children = "Loading…", className, ...rest }) {
-  return h("p", { ...rest, className: cx("w-loading", className) }, children);
-}
-
-/** Nothing to show: what's missing, and a `detail` line on what to do about it. */
-export function Empty({ title, detail, className, ...rest }) {
-  return h("div", { ...rest, className: cx("w-empty", className) }, h("p", null, title), detail === undefined ? null : h("p", { className: "w-empty-detail" }, detail));
-}
-
-// ---------- buttons ----------
-
-/** A button. `variant` is primary, ghost or danger; `size` small. */
-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. */
-export function Chip({ pressed, type = "button", className, ...rest }) {
-  return h("button", { ...rest, type, className: cx("w-chip", className), "aria-pressed": pressed });
-}
-
-/** Chips that pick one of `options`, like a filter. `onChange` gets each click, the chip that's on too. */
-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(({ value: v, label: text, ...chip }) => h(Chip, { ...chip, key: v, pressed: v === value, onClick: () => onChange(v) }, text)),
-  );
-}
-
-/** Tabs over the panel they show, `children`. Arrow keys, Home and End move between tabs. */
-export function Tabs({ label, items, value, onChange, children, className, ...rest }) {
-  const id = useId();
-  const tabId = (v) => `${id}-tab-${v}`;
-  const onKeyDown = (e) => {
-    const at = items.findIndex((t) => t.value === value);
-    const next = { ArrowRight: at + 1, ArrowLeft: at - 1, Home: 0, End: items.length - 1 }[e.key];
-    if (next === undefined) return;
-    e.preventDefault();
-    const tab = items[(next + items.length) % items.length];
-    onChange(tab.value);
-    document.getElementById(tabId(tab.value))?.focus();
-  };
-  return h(
-    "div",
-    { ...rest, className },
-    h(
-      "div",
-      { className: "w-tabs", role: "tablist", "aria-label": label, onKeyDown },
-      items.map((t) =>
-        h("button", { key: t.value, type: "button", id: tabId(t.value), className: "w-tab", role: "tab", "aria-selected": t.value === value, "aria-controls": `${id}-panel`, tabIndex: t.value === value ? 0 : -1, onClick: () => onChange(t.value) }, t.label),
-      ),
-    ),
-    h("div", { id: `${id}-panel`, role: "tabpanel", "aria-labelledby": tabId(value) }, children),
-  );
-}
-
-// ---------- fields ----------
-
-const FieldContext = createContext(null);
-
-/** Gives an input in a `Field` its label and hint. */
-function useFieldProps(rest) {
-  const field = useContext(FieldContext);
-  return field ? { id: field.id, "aria-describedby": field.hint, "aria-invalid": field.invalid || undefined, ...rest } : rest;
-}
-
-/** 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), "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),
-  );
-}
-
-/** A text input. Outside a `Field`, give it a `label`. */
-export function TextInput({ label, type = "text", className, ...rest }) {
-  return h("input", { "aria-label": label, ...useFieldProps(rest), type, className: cx("w-input", className) });
-}
-
-/** A search box. `label` names it for screen readers. */
-export function SearchField({ label, className, ...rest }) {
-  return h("input", { "aria-label": label, ...useFieldProps(rest), type: "search", className: cx("w-search", className) });
-}
-
-/** A select of `options`. `onChange` gets the value picked. */
-export function Select({ label, options, onChange, className, ...rest }) {
-  return h(
-    "select",
-    { "aria-label": label, ...useFieldProps(rest), className: cx("w-select", className), onChange: (e) => onChange?.(e.currentTarget.value) },
-    options.map((o) => h("option", { key: o.value, value: o.value, disabled: o.disabled }, o.label)),
-  );
-}
-
-/** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
-export function Checkbox({ onChange, children, className, ...rest }) {
-  // 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. `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, 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 [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 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 = () => {
-    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) => {
-    setOpened(true);
-    setActive(i);
-  };
-  const pick = (option) => {
-    onPick(option);
-    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.
-      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" && (whileText ? current >= 0 : open)) e.preventDefault();
-      dismiss();
-    }
-  };
-
-  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": visible,
-      "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)) dismiss();
-      },
-      onKeyDown,
-    }),
-    h(
-      "div",
-      { className: "w-listbox", hidden: !visible },
-      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 && !whileText && !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. */
-export function Disclosure({ summary, children, className, ...rest }) {
-  return h("details", { ...rest, className: cx("w-disclosure", className) }, h("summary", null, summary), children);
-}