wings-plugin-sdk 0.1.0 → 0.2.0

package/ui-css.js

@@ -0,0 +1,547 @@
+// The wings-plugin-sdk/ui styles, for Wings versions whose plugin-ui.css doesn't have them yet. Wings' own copy
+// in plugin-ui.css wins whenever it's there, so a Wings update restyles every plugin. Keep both the same.
+
+/** The version of the classes this package renders. Wings' plugin-ui.css sets it as `--wings-ui`. */
+export const UI_VERSION = 1;
+
+export const fallbackCss = `/* wings-ui 1 start
+   The classes wings-plugin-sdk/ui renders, a public contract: the names and data attributes stay, and Wings may
+   restyle them. wings-plugin-sdk carries a copy of this block for older Wings without --wings-ui, so keep the
+   two the same (apps/desktop/src/lib/plugin-ui.test.ts checks). Bump --wings-ui when a class is added. */
+
+/* The page's place: a sidebar, popover, view (modal, window or tab) or settings page. */
+.w-shell {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px;
+}
+.w-shell[data-place="popover"] {
+  gap: 12px;
+  padding: 12px 14px 14px;
+}
+.w-shell[data-place="settings"] {
+  gap: 12px;
+}
+/* A page that lays itself out edge to edge, like a canvas, fills the frame and scrolls on its own. */
+.w-shell[data-fill] {
+  height: 100vh;
+  gap: 0;
+  padding: 0;
+  overflow: hidden;
+}
+
+/* Layout. */
+.w-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.w-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+}
+:is(.w-row, .w-stack)[data-gap="none"] {
+  gap: 0;
+}
+:is(.w-row, .w-stack)[data-gap="xs"] {
+  gap: 2px;
+}
+:is(.w-row, .w-stack)[data-gap="s"] {
+  gap: 4px;
+}
+:is(.w-row, .w-stack)[data-gap="l"] {
+  gap: 12px;
+}
+.w-row[data-align="start"] {
+  align-items: flex-start;
+}
+.w-row[data-align="baseline"] {
+  align-items: baseline;
+}
+.w-row[data-justify="end"] {
+  justify-content: flex-end;
+}
+.w-row[data-justify="between"] {
+  justify-content: space-between;
+}
+.w-row[data-wrap] {
+  flex-wrap: wrap;
+}
+:is(.w-row, .w-stack, .w-text)[data-grow] {
+  flex: 1;
+  min-width: 0;
+}
+
+/* Text. */
+.w-text[data-tone="muted"] {
+  color: var(--wings-muted);
+}
+.w-text[data-tone="info"] {
+  color: var(--wings-info);
+}
+.w-text[data-tone="success"] {
+  color: var(--wings-success);
+}
+.w-text[data-tone="warn"] {
+  color: var(--wings-warning);
+}
+.w-text[data-tone="danger"] {
+  color: var(--wings-danger);
+}
+.w-text[data-size="small"] {
+  font-size: 12px;
+}
+.w-text[data-size="tiny"] {
+  font-size: 11px;
+}
+.w-text[data-weight="medium"] {
+  font-weight: 500;
+}
+.w-text[data-weight="strong"] {
+  font-weight: 600;
+}
+.w-text[data-mono] {
+  font-family: var(--wings-mono);
+}
+.w-text[data-numeric] {
+  font-variant-numeric: tabular-nums;
+}
+.w-text[data-truncate] {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.w-text[data-clamp] {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+:is(.w-row, .w-list-item, .w-list-button) > .w-text[data-truncate] {
+  min-width: 0;
+}
+
+/* A section heading, with its controls on the right. */
+.w-heading {
+  margin-top: 6px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--wings-muted);
+}
+.w-heading-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.w-heading-row > .w-heading {
+  flex: 1;
+  min-width: 0;
+}
+
+/* A card, and the quieter one for a summary line. */
+.w-card {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  padding: 10px 12px;
+  border: 1px solid var(--wings-hairline);
+  border-radius: var(--wings-radius);
+  background: var(--wings-surface);
+}
+.w-card[data-size="compact"] {
+  gap: 6px;
+  padding: 8px 10px;
+  font-size: 12px;
+}
+
+/* A labelled bar, and the bar on its own. --w-value is how full it is. */
+.w-gauge {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 4px 8px;
+  font-size: 12px;
+}
+.w-gauge-value {
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
+}
+.w-gauge-note {
+  grid-column: 1 / -1;
+  color: var(--wings-muted);
+}
+.w-meter {
+  grid-column: 1 / -1;
+  height: 4px;
+  border-radius: 2px;
+  background: var(--wings-hairline-strong);
+  overflow: hidden;
+}
+.w-meter-fill {
+  display: block;
+  width: var(--w-value, 0%);
+  height: 100%;
+  border-radius: 2px;
+  background: var(--wings-info);
+}
+.w-meter[data-tone="warn"] > .w-meter-fill {
+  background: var(--wings-warning);
+}
+.w-meter[data-tone="danger"] > .w-meter-fill {
+  background: var(--wings-danger);
+}
+
+/* A row of small figures, label over value. */
+.w-stats {
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: minmax(0, 1fr);
+  gap: 8px;
+  margin: 0;
+  padding: 10px 12px;
+  border: 1px solid var(--wings-hairline);
+  border-radius: var(--wings-radius);
+  background: var(--wings-surface);
+}
+.w-stat-label {
+  font-size: 11px;
+  color: var(--wings-muted);
+}
+.w-stat-value {
+  margin: 2px 0 0;
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.w-stat-value[data-tone="warn"] {
+  color: var(--wings-warning);
+}
+.w-stat-value[data-tone="danger"] {
+  color: var(--wings-danger);
+}
+
+/* Label and value pairs, like a work item's fields. */
+.w-props {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin: 0;
+}
+.w-prop {
+  display: grid;
+  grid-template-columns: 92px minmax(0, 1fr);
+  gap: 8px;
+  align-items: start;
+  font-size: 12px;
+  line-height: 22px;
+}
+.w-prop-label {
+  color: var(--wings-muted);
+}
+.w-prop-value {
+  min-width: 0;
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+/* Lists: rows that light up under the pointer, or rows that are a button. */
+.w-list {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: 12px;
+}
+.w-list-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  padding: 4px 6px;
+  border-radius: 6px;
+}
+.w-list[data-density="compact"] > .w-list-item {
+  padding: 0 6px;
+}
+.w-list-item[data-align="start"] {
+  align-items: flex-start;
+}
+.w-list-item:hover {
+  background: var(--wings-hover);
+}
+.w-list-item:has(> .w-list-button) {
+  display: block;
+  padding: 0;
+}
+.w-list-item:has(> .w-list-button):hover {
+  background: none;
+}
+.w-list-button {
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 8px;
+  width: 100%;
+  min-width: 0;
+  height: auto;
+  padding: 5px 6px;
+  border: 0;
+  border-radius: 6px;
+  background: none;
+  font-size: inherit;
+  font-weight: inherit;
+  text-align: left;
+}
+.w-list-button[data-align="baseline"] {
+  align-items: baseline;
+}
+.w-list-button:hover {
+  background: var(--wings-hover);
+}
+.w-list-button:active {
+  transform: none;
+}
+
+/* Status: a dot, a spinner, a filled pill and an outlined tag. */
+.w-dot {
+  flex: none;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--wings-success);
+}
+.w-dot[data-tone="muted"] {
+  background: var(--wings-muted);
+}
+.w-dot[data-tone="info"] {
+  background: var(--wings-info);
+}
+.w-dot[data-tone="warn"] {
+  background: var(--wings-warning);
+}
+.w-dot[data-tone="danger"] {
+  background: var(--wings-danger);
+}
+.w-spinner {
+  flex: none;
+  width: 10px;
+  height: 10px;
+  border: 2px solid var(--wings-hairline-strong);
+  border-top-color: var(--wings-fg);
+  border-radius: 50%;
+  animation: w-spin 0.8s linear infinite;
+}
+.w-spinner[data-size="large"] {
+  width: 14px;
+  height: 14px;
+}
+@keyframes w-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+.w-pill {
+  flex: none;
+  padding: 0 6px;
+  border-radius: 999px;
+  background: var(--wings-hover);
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 18px;
+  white-space: nowrap;
+}
+.w-pill[data-tone="info"] {
+  color: var(--wings-info);
+  background: color-mix(in srgb, var(--wings-info) 14%, transparent);
+}
+.w-pill[data-tone="success"] {
+  color: var(--wings-success);
+  background: color-mix(in srgb, var(--wings-success) 14%, transparent);
+}
+.w-pill[data-tone="warn"] {
+  color: var(--wings-warning);
+  background: color-mix(in srgb, var(--wings-warning) 14%, transparent);
+}
+.w-pill[data-tone="danger"] {
+  color: var(--wings-danger);
+  background: color-mix(in srgb, var(--wings-danger) 14%, transparent);
+}
+.w-tag {
+  flex: none;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 0 5px;
+  border: 1px solid var(--wings-hairline-strong);
+  border-radius: 5px;
+  font-size: 10.5px;
+  line-height: 15px;
+  color: var(--wings-muted);
+}
+.w-tag[data-tone="info"] {
+  border-color: color-mix(in srgb, var(--wings-info) 45%, transparent);
+  color: var(--wings-info);
+}
+.w-tag[data-tone="success"] {
+  border-color: color-mix(in srgb, var(--wings-success) 45%, transparent);
+  color: var(--wings-success);
+}
+.w-tag[data-tone="warn"] {
+  border-color: color-mix(in srgb, var(--wings-warning) 45%, transparent);
+  color: var(--wings-warning);
+}
+.w-tag[data-tone="danger"] {
+  border-color: color-mix(in srgb, var(--wings-danger) 45%, transparent);
+  color: var(--wings-danger);
+}
+
+/* Nothing to show yet, or nothing at all. */
+.w-loading {
+  color: var(--wings-muted);
+}
+.w-empty {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 24px 4px;
+  text-align: center;
+}
+.w-empty-detail {
+  color: var(--wings-muted);
+}
+
+/* Buttons. Plain buttons already look like Wings; these add the variants and sizes. */
+.w-button[data-variant="primary"] {
+  border-color: transparent;
+  background: var(--wings-primary);
+  color: var(--wings-primary-fg);
+}
+.w-button[data-variant="primary"]:hover {
+  background: color-mix(in srgb, var(--wings-primary) 85%, transparent);
+}
+.w-button[data-variant="danger"] {
+  border-color: transparent;
+  background: color-mix(in srgb, var(--wings-danger) 85%, transparent);
+  color: #1b0f0d;
+}
+.w-button[data-variant="ghost"] {
+  border-color: transparent;
+  background: transparent;
+}
+.w-button[data-variant="ghost"]:hover {
+  background: var(--wings-hover);
+}
+.w-button[data-size="small"] {
+  height: 24px;
+  padding: 0 8px;
+  font-size: 12px;
+}
+
+/* Chips: small quiet buttons, and a group of them that filters what shows. */
+.w-chips {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+}
+.w-chip {
+  height: 22px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 6px;
+  background: none;
+  font-size: 11px;
+  color: var(--wings-muted);
+}
+.w-chip:hover,
+.w-chip[aria-pressed="true"] {
+  background: var(--wings-pressed);
+}
+.w-chip[aria-pressed="true"] {
+  color: var(--wings-fg);
+}
+
+/* Tabs over a panel. */
+.w-tabs {
+  display: flex;
+  gap: 2px;
+  border-bottom: 1px solid var(--wings-hairline);
+}
+.w-tab {
+  height: 28px;
+  padding: 0 10px;
+  border: 0;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  background: none;
+  font-size: 12px;
+  color: var(--wings-muted);
+}
+.w-tab:hover {
+  background: none;
+  color: var(--wings-fg);
+}
+.w-tab:active {
+  transform: none;
+}
+.w-tab[aria-selected="true"] {
+  border-bottom-color: var(--wings-fg);
+  color: var(--wings-fg);
+}
+
+/* Form fields. Inputs, selects and text areas already look like Wings. */
+.w-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.w-field-label {
+  font-size: 12px;
+  font-weight: 500;
+}
+.w-field-hint {
+  font-size: 12px;
+  color: var(--wings-muted);
+}
+.w-field-hint[data-tone="danger"] {
+  color: var(--wings-danger);
+}
+.w-check {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  font-size: 12px;
+  cursor: pointer;
+}
+.w-check > input {
+  flex: none;
+  width: auto;
+  height: auto;
+  margin: 0;
+}
+
+/* More behind a summary line. */
+.w-disclosure > summary {
+  padding: 4px 6px;
+  font-size: 12px;
+  color: var(--wings-muted);
+  cursor: pointer;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .w-spinner {
+    animation: none;
+  }
+}
+/* wings-ui 1 end */
+`;

package/ui.d.ts

@@ -0,0 +1,144 @@
+/// <reference path="./wings.d.ts" />
+// wings-plugin-sdk/ui: say what a page shows and where, and Wings decides how it looks. Every component renders
+// plain elements with `w-*` class names that Wings' plugin-ui.css styles. Your own components and CSS work too.
+import type { ComponentPropsWithoutRef, JSX, ReactElement, ReactNode, Ref } from "react";
+
+import type { Place, ShellOptions } from "./shell";
+
+export type { Place, ShellOptions } from "./shell";
+export { mountShell } from "./shell";
+export { useBroadcast } from "./react";
+
+// ---------- places ----------
+
+/** Shows `element`, any React element, as the page of a sidebar. One call per page; calling again renders the new element. */
+export function showSidebar(element: ReactElement, options?: ShellOptions): void;
+/** Shows `element` as a view's page, in a modal or a window of its own. */
+export function showView(element: ReactElement, options?: ShellOptions): void;
+/** Shows `element` as a view's page in a tab next to the terminals. */
+export function showTab(element: ReactElement, options?: ShellOptions): void;
+/** Shows `element` as a sidebar's popover. */
+export function showPopover(element: ReactElement, options?: ShellOptions): void;
+/** Shows `element` as the plugin's page in Wings Settings. */
+export function showSettings(element: ReactElement, options?: ShellOptions): void;
+
+// ---------- talking to main ----------
+
+/**
+ * The newest message of `type` the plugin's other pages broadcast, or null until one comes. Sends `hello`
+ * (`{ type: "hello" }` by default) once when the component mounts, so main answers with its state; pass null to
+ * send nothing.
+ */
+export function useMainState<T extends { type: string }>(type: T["type"], hello?: unknown): T | null;
+
+// ---------- shared ----------
+
+/** A colour that says something. */
+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";
+/** 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; gap?: Gap; align?: "start" | "baseline"; justify?: "end" | "between"; wrap?: boolean; grow?: boolean }): ReactElement;
+/** Children one under the other. */
+export function Stack(props: Props<"div"> & { as?: As; 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"> & {
+    as?: As;
+    tone?: Tone;
+    /** small is 12px, tiny 11px. */
+    size?: "small" | "tiny";
+    weight?: "medium" | "strong";
+    mono?: boolean;
+    /** Digits of equal width, for figures that change. */
+    numeric?: boolean;
+    /** One line, cut with an ellipsis. */
+    truncate?: boolean;
+    /** Up to three lines. */
+    clamp?: boolean;
+    grow?: boolean;
+  },
+): ReactElement;
+/** A section heading, an `h2`, with `actions` like chips or a button on its right. */
+export function Heading(props: Props<"h2"> & { actions?: ReactNode }): ReactElement;
+/** A card. `compact` for a summary line. */
+export function Card(props: Props<"div"> & { as?: As; compact?: boolean }): ReactElement;
+
+// ---------- figures ----------
+
+/** A bar from 0 to 100, with the meter role. */
+export function Meter(props: Props<"div"> & { percent: number; label: string; tone?: "warn" | "danger" }): ReactElement;
+/** A labelled bar with its percentage and a `note` under it. `levels` are where it turns warn and danger, like `[75, 90]`. */
+export function Gauge(props: Props<"div"> & { label: string; percent: number; note?: ReactNode; tone?: "warn" | "danger"; levels?: [number, number] }): ReactElement;
+export interface Stat {
+  label: string;
+  value: ReactNode;
+  tone?: "warn" | "danger";
+  title?: string;
+}
+/** Small figures side by side, label over value. */
+export function Stats(props: Props<"dl"> & { items: Stat[] }): ReactElement;
+/** Label and value pairs, one per line. */
+export function Properties(props: Props<"dl"> & { items: { label: string; value: ReactNode }[] }): ReactElement;
+
+// ---------- lists ----------
+
+/** A list of rows: a `ul`, or an `ol` when `ordered`. `compact` rows have no space between them, for long lists. */
+export function List(props: Props<"ul"> & { ordered?: boolean; compact?: boolean }): ReactElement;
+/** A row in a `List`. Holding a `ListButton`, the button is the row. */
+export function ListItem(props: Props<"li"> & { align?: "start" }): ReactElement;
+/** A row that's a button, inside a `ListItem`. */
+export function ListButton(props: Props<"button"> & { align?: "baseline" }): ReactElement;
+
+// ---------- status ----------
+
+/** A status dot, green unless `tone` says otherwise. With a `label` it's announced; otherwise it's decoration. */
+export function Dot(props: Props<"span"> & { tone?: Exclude<Tone, "success">; label?: string }): ReactElement;
+/** A spinner. With a `label` it's announced; otherwise it's decoration. */
+export function Spinner(props: Props<"span"> & { size?: "large"; label?: string }): ReactElement;
+/** A filled pill, like a label on a command. */
+export function Pill(props: Props<"span"> & { tone?: Exclude<Tone, "muted"> }): ReactElement;
+/** An outlined tag, like a branch name. */
+export function Tag(props: Props<"span"> & { tone?: Exclude<Tone, "muted"> }): ReactElement;
+/** What shows before the first data comes: "Loading…" unless `children` say otherwise. */
+export function Loading(props: Props<"p">): ReactElement;
+/** Nothing to show: what's missing, and a `detail` line on what to do about it. */
+export function Empty(props: Omit<Props<"div">, "title"> & { title: ReactNode; detail?: ReactNode }): ReactElement;
+
+// ---------- buttons ----------
+
+/** A button, `type="button"` unless you say otherwise. */
+export function Button(props: Props<"button"> & { variant?: "primary" | "ghost" | "danger"; size?: "small" }): ReactElement;
+/** A small quiet button. With `pressed` it's a toggle. */
+export function Chip(props: Props<"button"> & { pressed?: boolean }): ReactElement;
+export interface Option<V extends string> {
+  value: V;
+  label: ReactNode;
+  title?: string;
+}
+/** Chips that pick one of `options`, like a filter, in a group named `label`. `onChange` gets each click, the chip that's on too. */
+export function Chips<V extends string>(props: Omit<Props<"div">, "onChange"> & { label: string; options: Option<V>[]; value: V; onChange: (value: V) => void }): ReactElement;
+/** Tabs named `label` over the panel they show, `children`. Arrow keys, Home and End move between tabs. */
+export function Tabs<V extends string>(props: Omit<Props<"div">, "onChange"> & { label: string; items: Option<V>[]; value: V; onChange: (value: V) => void }): ReactElement;
+
+// ---------- fields ----------
+
+/** A labelled field with a `hint` or an `error` under it, for the `TextInput`, `SearchField` or `Select` in `children`. */
+export function Field(props: Props<"div"> & { label: ReactNode; hint?: ReactNode; error?: ReactNode }): ReactElement;
+/** A text input. Outside a `Field`, give it a `label`. */
+export function TextInput(props: Props<"input"> & { label?: string; ref?: Ref<HTMLInputElement> }): ReactElement;
+/** A search box. `label` names it for screen readers. */
+export function SearchField(props: Omit<Props<"input">, "type"> & { label?: string; ref?: Ref<HTMLInputElement> }): ReactElement;
+/** A select of `options`. `onChange` gets the value picked. */
+export function Select<V extends string>(
+  props: Omit<Props<"select">, "onChange" | "children"> & { label?: string; options: (Option<V> & { label: string; disabled?: boolean })[]; value?: V; onChange?: (value: V) => void },
+): ReactElement;
+/** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
+export function Checkbox(props: Omit<Props<"input">, "onChange" | "type"> & { onChange?: (checked: boolean) => void }): ReactElement;
+/** More behind a `summary` line that opens it. */
+export function Disclosure(props: Props<"details"> & { summary: ReactNode }): ReactElement;