wings-plugin-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Josip Papež
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# wings-plugin-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components for [Wings](https://github.com/josippapez/Wings) plugin pages, and the stylesheet Wings draws them
+with. The components are Base UI's, like the Wings app's own shadcn/ui ones, with shadcn's names and variants.
+Build and pack the plugin with [wings-plugin-sdk](../plugin-sdk/README.md).
+
+```sh
+npm install --save-dev wings-plugin-sdk wings-plugin-ui react react-dom @types/react @types/react-dom
+```
+
+`wings-plugin-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-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)` from `wings-plugin-sdk/react` 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`, `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 |
+
+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. `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.
+
+## Tailwind or any CSS
+
+Wings' styles sit in CSS cascade layers, declared before anything else on the page, in this order:
+`wings-base, theme, base, wings-components, components, utilities`. Any CSS a page brings that isn't in a layer
+wins over all of Wings'. Tailwind v4 fits in as it is: `@import "tailwindcss";` puts its reset in `base`, under the
+components here, and its utilities in `utilities`, over them. So a page can use Tailwind for its own parts next to
+these components, and both look right. Build Tailwind's CSS with its CLI before `wings-plugin build` and import
+it from the page. Rem units mean 16px, the browser's root size, while the page's text is 13px.
+
+## Linked packages
+
+With the packages linked from a local folder (`npm link`, or `link:` in `package.json`) rather than installed,
+TypeScript looks for React next to their 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/package.json

@@ -1,6 +1,46 @@
 {
   "name": "wings-plugin-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "types": "./ui.d.ts",
+  "exports": {
+    ".": {
+      "types": "./ui.d.ts",
+      "default": "./ui.js"
+    },
+    "./plugin-ui.css": "./plugin-ui.css"
+  },
+  "files": [
+    "ui.js",
+    "ui.d.ts",
+    "plugin-ui.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josippapez/Wings.git",
+    "directory": "packages/plugin-ui"
+  },
+  "scripts": {
+    "test": "tsc -p tsconfig.json && node --test"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.8.0"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19",
+    "wings-plugin-sdk": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "jsdom": "^30.1.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "~6.0.3",
+    "wings-plugin-sdk": "link:../plugin-sdk"
+  }
+}