wings-plugin-ui 0.1.1 → 0.2.0

package/README.md

@@ -68,6 +68,10 @@ message.
 | `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 |
+| `Page`, `Toolbar` | `Page`: `toolbar`, `flush`; `Toolbar`: `title`, `actions`, `children` | A page that fills a tab: a toolbar row (title, then filters in `children`, `actions` on the right) over a body that scrolls. `flush` drops the body's padding and scrolling for a body that lays itself out. Show it with `showTab(<Page />, { fill: true })` |
+| `ListDetail` | `list`, `detail`, `empty`, `listWidth` (px, 280), `listLabel`, `detailLabel`, `onBack`, `backLabel` | A list pane and a detail pane side by side; `empty` shows until there is a `detail`. Under 560px wide it shows one pane, the list or the detail, with a back button when `onBack` is given |
+| `Board`, `BoardColumn` | `Board`: `label`; `BoardColumn`: `title`, `count`, `actions` | Columns that scroll sideways, each with a header, a count and a scrolling stack of cards (use `Card`). The board is a focusable region, so the arrow keys scroll it |
+| `Split` | `start`, `end`, `direction` (`horizontal`, `vertical`), `defaultSize` (px, 280), `min` (120), `max`, `onResize`, `label` | Two panes with a draggable handle, a `separator` with `aria-valuenow` in px. Arrow keys (Shift for bigger steps), Home and End resize it. A drag only changes a CSS variable and `onResize(size)` runs once when it ends, so save it with `wings.setTabState()` and pass it back as `defaultSize` |
 | `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`, `description` | Before the first data, and nothing to show |
@@ -147,6 +151,7 @@ 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-page`, `w-page-body` with `data-flush`; `w-toolbar`, `w-toolbar-title`, `w-toolbar-main`, `w-toolbar-actions`; `w-list-detail` with `data-has-detail` and `--w-list-width`, `w-list-detail-list`, `w-list-detail-detail`, `w-list-detail-body`, `w-list-detail-back`; `w-board`, `w-board-column`, `w-board-column-header`, `w-board-column-title`, `w-board-column-count`, `w-board-column-actions`, `w-board-column-body`; `w-split` with `data-direction`, `data-dragging` and `--w-split-size`, `w-split-pane`, `w-split-handle`;
 `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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-ui",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "React components and the stylesheet for Wings plugin pages, on Base UI like the Wings app's shadcn/ui components.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19",
-    "wings-plugin-sdk": "^0.6.0"
+    "wings-plugin-sdk": "^0.6.0 || ^0.7.0 || ^0.8.0"
   },
   "devDependencies": {
     "@types/react": "^19.1.8",

package/plugin-ui.css

@@ -357,6 +357,243 @@ textarea::placeholder {
   font-size: 12px;
 }
 
+/* Pages that fill a tab: a toolbar over a body, list and detail, a board, a split. */
+.w-page {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+.w-page-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  min-height: 0;
+  padding: 14px;
+  overflow: auto;
+}
+.w-page-body[data-flush] {
+  gap: 0;
+  padding: 0;
+  overflow: hidden;
+}
+.w-page-body[data-flush] > :is(.w-list-detail, .w-split, .w-board) {
+  flex: 1;
+}
+.w-toolbar {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  padding: 8px 14px;
+  border-bottom: 1px solid var(--wings-hairline);
+}
+.w-toolbar-title {
+  flex: none;
+  max-width: 40%;
+}
+.w-toolbar-main {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.w-toolbar-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 6px;
+}
+
+/* List and detail side by side; one pane when the page is narrower than 560px. */
+.w-list-detail {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  container-type: inline-size;
+}
+.w-list-detail-list {
+  flex: none;
+  width: var(--w-list-width, 280px);
+  min-width: 0;
+  padding: 8px;
+  overflow-y: auto;
+  border-right: 1px solid var(--wings-hairline);
+}
+.w-list-detail-detail {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+  overflow: hidden;
+}
+.w-list-detail-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+  padding: 14px;
+  overflow-y: auto;
+}
+.w-list-detail-body > .w-empty {
+  flex: 1;
+}
+.w-list-detail-back {
+  display: none;
+  align-self: flex-start;
+  margin: 8px 8px 0;
+}
+@container (max-width: 560px) {
+  .w-list-detail-list {
+    flex: 1;
+    width: auto;
+    border-right: 0;
+  }
+  .w-list-detail[data-has-detail] > .w-list-detail-list,
+  .w-list-detail:not([data-has-detail]) > .w-list-detail-detail {
+    display: none;
+  }
+  .w-list-detail-back {
+    display: inline-flex;
+  }
+}
+
+/* A board: columns that scroll sideways, each with a header and its cards. */
+.w-board {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  min-width: 0;
+  min-height: 0;
+  padding: 14px;
+  overflow-x: auto;
+}
+.w-board-column {
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  align-self: stretch;
+  width: 272px;
+  min-height: 0;
+  padding: 8px;
+  border: 1px solid var(--wings-hairline);
+  border-radius: var(--wings-radius);
+  background: var(--wings-surface);
+}
+.w-board-column-header {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  padding: 2px 4px 8px;
+}
+.w-board-column-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  font-size: 12px;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.w-board-column-count {
+  font-variant-numeric: tabular-nums;
+}
+.w-board-column-actions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+.w-board-column-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* A split: --w-split-size is the start pane's size, changed while you drag the handle. */
+.w-split {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+}
+.w-split[data-direction="vertical"] {
+  flex-direction: column;
+}
+.w-split[data-dragging] {
+  user-select: none;
+}
+.w-split-pane {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+}
+.w-split-pane:first-child {
+  flex: none;
+}
+.w-split[data-direction="horizontal"] > .w-split-pane:first-child {
+  width: var(--w-split-size);
+}
+.w-split[data-direction="vertical"] > .w-split-pane:first-child {
+  height: var(--w-split-size);
+}
+.w-split-pane:last-child {
+  flex: 1;
+}
+.w-split-handle {
+  position: relative;
+  flex: none;
+  touch-action: none;
+  outline: none;
+}
+.w-split[data-direction="horizontal"] > .w-split-handle {
+  width: 9px;
+  margin: 0 -4px;
+  cursor: col-resize;
+  z-index: 1;
+}
+.w-split[data-direction="vertical"] > .w-split-handle {
+  height: 9px;
+  margin: -4px 0;
+  cursor: row-resize;
+  z-index: 1;
+}
+.w-split-handle::before {
+  content: "";
+  position: absolute;
+  background: var(--wings-hairline);
+  transition: background-color 150ms;
+}
+.w-split[data-direction="horizontal"] > .w-split-handle::before {
+  inset: 0 4px;
+}
+.w-split[data-direction="vertical"] > .w-split-handle::before {
+  inset: 4px 0;
+}
+.w-split-handle:hover::before,
+.w-split-handle[data-dragging]::before {
+  background: var(--wings-hairline-strong);
+}
+.w-split-handle:focus-visible::before {
+  background: var(--wings-ring);
+}
+.w-split[data-direction="horizontal"] > .w-split-handle:focus-visible::before {
+  inset: 0 3px;
+}
+.w-split[data-direction="vertical"] > .w-split-handle:focus-visible::before {
+  inset: 3px 0;
+}
+
 /* A labelled bar, and the bar on its own. --w-value is how full it is. */
 .w-gauge {
   display: grid;

package/ui.d.ts

@@ -78,6 +78,65 @@ export function Title(props: Props<"h1"> & { as?: "h1" | "h2" | "h3"; size?: "la
 /** 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;
 
+// ---------- pages ----------
+
+/**
+ * A page that fills a tab: a `toolbar`, usually a `Toolbar`, over a body that scrolls. `flush` takes the body's padding
+ * and scrolling away, for a body that lays itself out, like a `ListDetail`, a `Split` or a `Board`. Show it with
+ * `showTab(<Page />, { fill: true })`.
+ */
+export function Page(props: Props<"div"> & { toolbar?: ReactNode; flush?: boolean }): ReactElement;
+/** A page's top row: a `title` (cut to one line) on the left, `children` like filters or a search box after it, and `actions` on the right. */
+export function Toolbar(props: Omit<Props<"header">, "title"> & { title?: ReactNode; actions?: ReactNode }): ReactElement;
+/**
+ * A `list` pane and a `detail` pane side by side. Without a `detail` the detail pane shows `empty`. When the page is
+ * narrower than 560px it shows one pane: the list, or the detail once there is one, with a back button if `onBack`
+ * is given. Each pane is a `section`; name them with `listLabel` and `detailLabel`.
+ */
+export function ListDetail(
+  props: Omit<Props<"div">, "children"> & {
+    list: ReactNode;
+    detail?: ReactNode;
+    /** What the detail pane shows without a `detail`: an `Empty` saying "Nothing selected" by default. */
+    empty?: ReactNode;
+    /** The list's width in px, 280 by default. */
+    listWidth?: number;
+    listLabel?: string;
+    detailLabel?: string;
+    /** Shows a back button above the detail when the page is too narrow for both panes. */
+    onBack?: () => void;
+    /** The back button's text, "Back" by default. */
+    backLabel?: string;
+  },
+): ReactElement;
+/** Columns side by side that scroll sideways, each a `BoardColumn`. A region named `label`, that takes keyboard focus so the arrow keys scroll it. */
+export function Board(props: Omit<Props<"div">, "role"> & { label: string }): ReactElement;
+/** A column of a `Board`: a `title` with the `count` of its cards and `actions`, over `children`, usually `Card`s, that scroll. */
+export function BoardColumn(props: Omit<Props<"section">, "title"> & { title: ReactNode; count?: number; actions?: ReactNode }): ReactElement;
+/**
+ * Two panes, `start` and `end`, with a handle between them. Drag the handle, or focus it and press the arrow keys
+ * (Shift for bigger steps), Home or End. A drag changes a CSS variable only and commits on release, so nothing renders
+ * per frame. The handle is a `separator` with `aria-valuenow` in px.
+ */
+export function Split(
+  props: Omit<Props<"div">, "children"> & {
+    start: ReactNode;
+    end: ReactNode;
+    /** "horizontal" (default) puts the panes side by side, "vertical" one over the other. */
+    direction?: "horizontal" | "vertical";
+    /** The start pane's size in px at first, 280 by default. Read from `wings.tabState()` to restore a saved one. */
+    defaultSize?: number;
+    /** The smallest either pane gets, in px, 120 by default. */
+    min?: number;
+    /** The biggest the start pane gets, in px. */
+    max?: number;
+    /** Gets the start pane's size in px when a drag or a key press ends, to save it with `wings.setTabState()`. */
+    onResize?: (size: number) => void;
+    /** Names the handle: "Resize panes" by default. */
+    label?: string;
+  },
+): ReactElement;
+
 // ---------- figures ----------
 
 /** A bar from 0 to 100, with the meter role. */

package/ui.js

@@ -111,6 +111,176 @@ export function Card({ as = "div", compact, className, ...rest }) {
   return h(as, { ...rest, className: cx("w-card", className), "data-size": compact ? "compact" : undefined });
 }
 
+// ---------- pages ----------
+
+/**
+ * A page that fills a tab: a `toolbar` (usually a `Toolbar`) over a body that scrolls. `flush` takes the body's padding
+ * and scrolling away, for a body that lays itself out, like a `ListDetail`, a `Split` or a `Board`. Show it with
+ * `showTab(<Page />, { fill: true })`.
+ */
+export function Page({ toolbar, flush, children, className, ...rest }) {
+  return h("div", { ...rest, className: cx("w-page", className) }, toolbar, h("div", { className: "w-page-body", "data-flush": flag(flush) }, children));
+}
+
+/** A page's top row: a `title` on the left, `children` like filters or a search box after it, and `actions` on the right. */
+export function Toolbar({ title, actions, children, className, ...rest }) {
+  return h(
+    "header",
+    { ...rest, className: cx("w-toolbar", className) },
+    title === undefined ? null : h(Title, { truncate: true, className: "w-toolbar-title" }, title),
+    h("div", { className: "w-toolbar-main" }, children),
+    actions ? h("div", { className: "w-toolbar-actions" }, actions) : null,
+  );
+}
+
+/**
+ * A `list` pane and a `detail` pane side by side. Without a `detail` the detail pane shows `empty`. Narrower than the
+ * page can fit both, it shows one: the list, or the detail once there is one, with a back button if `onBack` is given.
+ * `listWidth` is the list's width in px.
+ */
+export function ListDetail({ list, detail, empty = h(Empty, { title: "Nothing selected" }), listWidth = 280, listLabel, detailLabel, onBack, backLabel = "Back", className, style, ...rest }) {
+  const has = detail !== undefined && detail !== null && detail !== false;
+  return h(
+    "div",
+    // The width is data, not a style: plugin-ui.css sizes the list from it.
+    { ...rest, className: cx("w-list-detail", className), style: { ...style, "--w-list-width": `${listWidth}px` }, "data-has-detail": flag(has) },
+    h("section", { className: "w-list-detail-list", "aria-label": listLabel }, list),
+    h(
+      "section",
+      { className: "w-list-detail-detail", "aria-label": detailLabel },
+      has && onBack ? h(Button, { variant: "ghost", size: "sm", className: "w-list-detail-back", onClick: onBack }, backLabel) : null,
+      h("div", { className: "w-list-detail-body" }, has ? detail : empty),
+    ),
+  );
+}
+
+/** Columns side by side that scroll sideways, each a `BoardColumn`. `label` names the scrolling region. */
+export function Board({ label, className, ...rest }) {
+  // A scrolling region has to take focus, or a keyboard can't scroll it.
+  return h("div", { tabIndex: 0, ...rest, role: "region", "aria-label": label, className: cx("w-board", className) });
+}
+
+/** A column of a `Board`: a `title` with the `count` of cards and `actions`, over `children`, usually `Card`s, that scroll. */
+export function BoardColumn({ title, count, actions, children, className, ...rest }) {
+  const id = useId();
+  return h(
+    "section",
+    { ...rest, className: cx("w-board-column", className), "aria-labelledby": id },
+    h(
+      "header",
+      { className: "w-board-column-header" },
+      h("h2", { id, className: "w-board-column-title" }, title),
+      count === undefined ? null : h(Badge, { variant: "secondary", className: "w-board-column-count" }, count),
+      actions ? h("div", { className: "w-board-column-actions" }, actions) : null,
+    ),
+    h("div", { className: "w-board-column-body" }, children),
+  );
+}
+
+const SPLIT_STEP = 16;
+const SPLIT_STEP_LARGE = 64;
+const SPLIT_HANDLE = 9;
+
+/**
+ * Two panes, `start` and `end`, with a handle between them. Drag it or use the arrow keys, Home and End. While you drag
+ * only a CSS variable changes, so nothing renders per frame; `onResize` gets the start pane's size in px once, when
+ * the drag or the key press ends. `direction` horizontal puts the panes side by side, vertical one over the other.
+ */
+export function Split({ start, end, direction = "horizontal", defaultSize = 280, min = 120, max, onResize, label = "Resize panes", className, style, ...rest }) {
+  const id = useId();
+  const box = useRef(null);
+  const handle = useRef(null);
+  const drag = useRef(null);
+  const [size, setSize] = useState(defaultSize);
+  const vertical = direction === "vertical";
+
+  // The start pane can't be smaller than `min`, bigger than `max`, or leave the end pane less than `min`.
+  const limits = () => {
+    const rect = box.current?.getBoundingClientRect();
+    const total = rect ? (vertical ? rect.height : rect.width) : 0;
+    const room = total > 0 ? total - SPLIT_HANDLE - min : Infinity;
+    return [min, Math.max(min, Math.min(max ?? Infinity, room))];
+  };
+  const clamp = (value) => {
+    const [low, high] = limits();
+    return Math.round(Math.min(high, Math.max(low, value)));
+  };
+  const syncMax = () => {
+    const [, high] = limits();
+    if (Number.isFinite(high)) handle.current?.setAttribute("aria-valuemax", String(Math.round(high)));
+  };
+  // Dragging writes the DOM, not state: a render per pointer move would re-render the whole page.
+  const preview = (next) => {
+    box.current.style.setProperty("--w-split-size", `${next}px`);
+    handle.current.setAttribute("aria-valuenow", String(next));
+  };
+  const commit = (next) => {
+    setSize(next);
+    if (next !== size) onResize?.(next);
+  };
+  const endDrag = (e, keep) => {
+    if (!drag.current) return;
+    const { value } = drag.current;
+    drag.current = null;
+    handle.current.removeAttribute("data-dragging");
+    box.current.removeAttribute("data-dragging");
+    if (e.currentTarget.hasPointerCapture?.(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
+    if (keep) commit(value);
+    else preview(size);
+  };
+  useLayoutEffect(syncMax);
+
+  const onPointerDown = (e) => {
+    if (e.button !== 0) return;
+    e.preventDefault();
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+    syncMax();
+    drag.current = { from: vertical ? e.clientY : e.clientX, size, value: size };
+    handle.current.setAttribute("data-dragging", "");
+    box.current.setAttribute("data-dragging", "");
+  };
+  const onPointerMove = (e) => {
+    const d = drag.current;
+    if (!d) return;
+    d.value = clamp(d.size + (vertical ? e.clientY : e.clientX) - d.from);
+    preview(d.value);
+  };
+  const onKeyDown = (e) => {
+    const step = e.shiftKey ? SPLIT_STEP_LARGE : SPLIT_STEP;
+    const [low, high] = limits();
+    const [less, more] = vertical ? ["ArrowUp", "ArrowDown"] : ["ArrowLeft", "ArrowRight"];
+    const next = e.key === less ? size - step : e.key === more ? size + step : e.key === "Home" ? low : e.key === "End" ? high : null;
+    if (next === null || !Number.isFinite(next)) return;
+    e.preventDefault();
+    commit(clamp(next));
+  };
+
+  return h(
+    "div",
+    // The size is data, not a style: plugin-ui.css sizes the start pane from it.
+    { ...rest, ref: box, className: cx("w-split", className), style: { ...style, "--w-split-size": `${size}px` }, "data-direction": direction },
+    h("div", { id, className: "w-split-pane" }, start),
+    h("div", {
+      ref: handle,
+      className: "w-split-handle",
+      role: "separator",
+      tabIndex: 0,
+      "aria-label": label,
+      "aria-orientation": vertical ? "horizontal" : "vertical",
+      "aria-controls": id,
+      "aria-valuemin": min,
+      "aria-valuemax": max,
+      "aria-valuenow": size,
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: (e) => endDrag(e, true),
+      onPointerCancel: (e) => endDrag(e, false),
+      onKeyDown,
+    }),
+    h("div", { className: "w-split-pane" }, end),
+  );
+}
+
 // ---------- figures ----------
 
 const levelTone = (percent, levels) => (!levels ? undefined : percent >= levels[1] ? "danger" : percent >= levels[0] ? "warn" : undefined);