wings-plugin-sdk 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # wings-plugin-sdk
 
-Types, a React hook and a build command for [Wings](https://github.com/josippapez/Wings) plugins.
+The `wings` API types, the page frame, React hooks and the build command for [Wings](https://github.com/josippapez/Wings)
+plugins. The components for plugin pages are in [wings-plugin-ui](../plugin-ui/README.md).
 
 Wings itself gives each plugin the `wings` object at runtime. This package doesn't contain it: it types it, and
 bundles your TypeScript and React into the plain scripts Wings loads.
@@ -9,7 +10,7 @@ bundles your TypeScript and React into the plain scripts Wings loads.
 
 ```sh
 npm install --save-dev wings-plugin-sdk typescript
-npm install --save-dev react react-dom @types/react @types/react-dom   # only for React pages
+npm install --save-dev wings-plugin-ui react react-dom @types/react @types/react-dom   # only for React pages
 ```
 
 `tsconfig.json`:
@@ -33,7 +34,7 @@ npm install --save-dev react react-dom @types/react @types/react-dom   # only fo
 
 Put the code in `src/`, next to `wings-plugin.json`. Every file at the top of `src/` builds to the file of the
 same name, so `src/main.ts` becomes `main.js` and `src/sidebar.tsx` becomes `sidebar.js`. A page that uses
-`wings-plugin-sdk/ui` also gets its `.html` written for it, unless you wrote your own. Folders inside `src/` hold
+`wings-plugin-ui` also gets its `.html` written for it, unless you wrote your own. Folders inside `src/` hold
 the modules they import.
 
 ```sh
@@ -47,9 +48,11 @@ as it is, like the plugins in the Wings repo.
 
 ## Pages
 
-A sidebar, popover, view, tab or settings page is a file in `src/` that calls one of the `show*` functions in
-[UI](#ui). The build writes its HTML. Every `wings.on*` call returns a function that removes the listener, so
-`useBroadcast` and `useMainState`, or your own `useEffect`, clean up when a component goes. The API reference is
+A sidebar, popover, view, tab or settings page is a file in `src/` that calls one of the `show*` functions of
+[wings-plugin-ui](../plugin-ui/README.md). The build writes its HTML. A page that builds its DOM itself, without
+React, gets the same frame from `mountShell(place, options)` in `wings-plugin-sdk/shell`, which returns the element
+to fill. Every `wings.on*` call returns a function that removes the listener, so `useBroadcast` from
+`wings-plugin-sdk/react`, or your own `useEffect`, cleans up when a component goes. The API reference is
 [plugins/README.md](https://github.com/josippapez/Wings/blob/main/plugins/README.md) in the Wings repo.
 
 ## Pack
@@ -67,178 +70,3 @@ files your plugin ships, like its own `.html`, `.css` and images. It leaves out
 `package.json` and lock files, `tsconfig*.json`, `README*`, `HANDOVER*`, dotfiles and other `.wings-plugin` files.
 Your folder gets no built files. From a script, `pack(dir, { out })` in `wings-plugin-sdk/build` does the same and
 resolves the package's path.
-
-## UI
-
-`wings-plugin-sdk/ui` lets a page say what it shows and where, and Wings decides how it looks. A page built from
-it never touches the DOM, writes HTML or lays itself out with CSS, so when Wings moves or redesigns a place,
-your page follows without a release.
-
-```tsx
-import { Card, Gauge, Heading, showSidebar, useMainState } from "wings-plugin-sdk/ui";
-
-type Usage = { type: "usage"; percent: number };
-
-function Usage() {
-  // Says hello to your main script once, then shows the newest `usage` message it broadcasts.
-  const usage = useMainState<Usage>("usage");
-  if (!usage) return null;
-  return (
-    <>
-      <Heading>Usage</Heading>
-      <Card>
-        <Gauge label="Today" percent={usage.percent} levels={[75, 90]} />
-      </Card>
-    </>
-  );
-}
-
-showSidebar(<Usage />);
-```
-
-### Places
-
-`showSidebar`, `showPopover`, `showView`, `showTab` and `showSettings` take any React element, your own
-components too, and mount it in that place's shell: Wings' padding, spacing and scrolling for a sidebar, a
-popover, a view (in a modal or a window), a tab or the settings page. Call one per page. `{ fill: true }` lays
-the page out edge to edge with no padding, for a page that scrolls on its own, like a canvas.
-
-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 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
-
-`useMainState<T>(type, hello?)` returns the newest message of `type` your plugin's other pages broadcast, or
-`null` until one comes. It sends `hello` (`{ type: "hello" }` by default, `null` for none) once when the
-component mounts, so main answers with what it has. `useBroadcast(listener)` gets every message.
-
-### Components
-
-| Component | Props | Renders |
-|---|---|---|
-| `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`), `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`; `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`), `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`, `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
-own components next to them, and your own CSS: import it from the page, `import "./sidebar.css"`, and the build
-bundles it into `sidebar.css` and links it from the generated page. Match Wings with its variables, which every
-page has:
-
-| Variable | What |
-|---|---|
-| `--wings-fg`, `--wings-muted` | Text, and quieter text |
-| `--wings-surface`, `--wings-hover`, `--wings-pressed`, `--wings-input` | Card, hovered, pressed and input backgrounds |
-| `--wings-hairline`, `--wings-hairline-strong` | Borders |
-| `--wings-ring` | The focus ring |
-| `--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
-// src/sidebar.tsx
-import "./sidebar.css";
-
-function Banner({ children }: { children: string }) {
-  return <div className="banner">{children}</div>;
-}
-```
-
-```css
-/* src/sidebar.css */
-.banner {
-  padding: 8px 10px;
-  border-radius: var(--wings-radius);
-  background: color-mix(in srgb, var(--wings-info) 14%, transparent);
-  color: var(--wings-info);
-}
-```
-
-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; }`.
-
-### 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, `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-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` 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, 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
-
-With the SDK linked from a local folder (`npm link`, or `link:` in `package.json`) rather than installed,
-TypeScript looks for React next to the SDK's folder. Point it at yours in `tsconfig.json`; the build already
-does:
-
-```json
-"paths": {
-  "react": ["./node_modules/@types/react"],
-  "react/*": ["./node_modules/@types/react/*"]
-}
-```

package/build.d.ts

@@ -3,7 +3,7 @@ export function entries(dir: string): { src: string; out: string }[];
 
 /**
  * Builds the plugin in `dir`: `src/main.ts` to `main.js`, `src/sidebar.tsx` to `sidebar.js`, and so on. CSS a page
- * imports becomes `<name>.css`, and a page that mounts with `wings-plugin-sdk/ui` or `/shell` gets a generated
+ * imports becomes `<name>.css`, and a page that mounts with `wings-plugin-ui` or `wings-plugin-sdk/shell` gets a generated
  * `<name>.html` unless the plugin has its own. With `check`, writes nothing and lists in `stale` the outputs that
  * differ from what's on disk. With `outDir`, writes there instead of `dir`.
  */

package/build.mjs

@@ -2,7 +2,7 @@
 // becomes main.js and src/sidebar.tsx becomes sidebar.js, next to wings-plugin.json. Folders inside src/ hold
 // the modules they import. Wings runs plain scripts, so each file is one bundle with its imports, React too.
 // The CSS a page imports, like `import "./sidebar.css"`, becomes <name>.css, and a page that mounts with
-// wings-plugin-sdk/ui or /shell gets a <name>.html written for it unless the plugin has its own.
+// wings-plugin-ui or wings-plugin-sdk/shell gets a <name>.html written for it unless the plugin has its own.
 import * as esbuild from "esbuild";
 import { zipSync } from "fflate";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -54,12 +54,12 @@ ${hasCss ? `    <link rel="stylesheet" href="${name}.css" />\n` : ""}  </head>
 /** Whether `file` is missing or was written by this build, so the build may write it. */
 const ours = (file) => !existsSync(file) || readFileSync(file, "utf8").includes(GENERATED);
 
-/** Notes whether the bundle imports wings-plugin-sdk's ui or shell, which mount the page themselves. */
+/** Notes whether the bundle imports wings-plugin-ui or wings-plugin-sdk/shell, which mount the page themselves. */
 function shellPlugin(seen) {
   return {
     name: "wings-shell",
     setup(build) {
-      build.onResolve({ filter: /^wings-plugin-sdk\/(ui|shell)$/ }, () => {
+      build.onResolve({ filter: /^(wings-plugin-ui|wings-plugin-sdk\/shell)$/ }, () => {
         seen.shell = true;
         // Resolve as usual.
         return undefined;
@@ -69,8 +69,8 @@ function shellPlugin(seen) {
 }
 
 /**
- * Resolves React from the plugin's folder wherever it's imported, so a page and a linked wings-plugin-sdk (npm
- * link, or link: in package.json) share one React instead of the SDK finding its own, or none.
+ * Resolves React from the plugin's folder wherever it's imported, so a page and a linked wings-plugin-ui (npm
+ * link, or link: in package.json) share one React instead of the package finding its own, or none.
  */
 function oneReact(dir) {
   return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.4.0",
-  "description": "Types, React hooks, UI components and a build command for Wings plugins.",
+  "version": "0.6.0",
+  "description": "The wings API types, the page frame, React hooks and the build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
   "types": "./wings.d.ts",
@@ -13,10 +13,6 @@
       "types": "./react.d.ts",
       "default": "./react.js"
     },
-    "./ui": {
-      "types": "./ui.d.ts",
-      "default": "./ui.js"
-    },
     "./shell": {
       "types": "./shell.d.ts",
       "default": "./shell.js"
@@ -27,7 +23,7 @@
     }
   },
   "scripts": {
-    "test": "tsc -p tsconfig.json && node --test"
+    "test": "node --test"
   },
   "bin": {
     "wings-plugin": "bin.mjs"
@@ -36,10 +32,6 @@
     "wings.d.ts",
     "react.js",
     "react.d.ts",
-    "ui.js",
-    "ui.d.ts",
-    "ui-css.js",
-    "ui-css.d.ts",
     "shell.js",
     "shell.d.ts",
     "build.mjs",
@@ -71,7 +63,6 @@
   },
   "devDependencies": {
     "@types/react": "^19.1.8",
-    "jsdom": "^30.1.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "~6.0.3"

package/shell.d.ts

@@ -9,6 +9,6 @@ export interface ShellOptions {
 
 /**
  * Makes the page's `#app` element (or a new `<main>`) the shell for `place`, and returns it, for a page that
- * builds its DOM itself. React pages use `showSidebar` and the others from `wings-plugin-sdk/ui` instead.
+ * builds its DOM itself. React pages use `showSidebar` and the others from `wings-plugin-ui` instead.
  */
 export function mountShell(place: Place, options?: ShellOptions): HTMLElement;

package/shell.js

@@ -1,28 +1,15 @@
 // The frame a plugin page lives in, without React: where it is, its padding and how it scrolls come from Wings'
-// plugin-ui.css, so a page only says which place it is. wings-plugin-sdk/ui mounts React into it.
-import { fallbackCss, UI_VERSION } from "./ui-css.js";
-
+// plugin-ui.css, so a page only says which place it is. wings-plugin-ui mounts React into it.
 const PLACES = ["sidebar", "popover", "view", "tab", "settings"];
 // Sidebars and popovers change while you look at them, so a screen reader hears what changed.
 const LIVE = new Set(["sidebar", "popover"]);
 
-/** Wings older than the classes this package renders have none, or older ones: bring them, before the page's own CSS. */
-function ensureStyles() {
-  const host = Number(getComputedStyle(document.documentElement).getPropertyValue("--wings-ui")) || 0;
-  if (host >= UI_VERSION || document.querySelector("style[data-wings-ui]")) return;
-  const style = document.createElement("style");
-  style.dataset.wingsUi = String(UI_VERSION);
-  style.textContent = fallbackCss;
-  document.head.prepend(style);
-}
-
 /**
  * Makes the page's `#app` element (or a new `<main>`) the shell for `place`, and returns it. Calling it again
  * returns the same element. `fill` lays the page out edge to edge, for a page that scrolls on its own.
  */
 export function mountShell(place, { fill = false } = {}) {
   if (!PLACES.includes(place)) throw new Error(`Unknown place ${place}: use one of ${PLACES.join(", ")}`);
-  ensureStyles();
   let shell = document.getElementById("app");
   if (!shell) {
     shell = document.createElement("main");

package/ui-css.d.ts

@@ -1,4 +0,0 @@
-/** The version of the classes wings-plugin-sdk/ui renders. Wings' plugin-ui.css sets it as `--wings-ui`. */
-export const UI_VERSION: number;
-/** The wings-plugin-sdk/ui styles, for Wings versions whose plugin-ui.css doesn't have them yet. */
-export const fallbackCss: string;