wings-plugin-sdk 0.5.0 → 0.7.0

package/ui.d.ts

@@ -1,238 +0,0 @@
-/// <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";
-/** The elements `Row` and `Stack` can be. */
-type BoxAs = As | "form" | "ul" | "ol";
-/** The elements `Card` can be. */
-type CardAs = As | "form" | "article" | "ul" | "ol";
-/** The props of element `E`, with `own` on top: where they share a name, `own` wins. */
-type Own<E extends keyof JSX.IntrinsicElements, own> = Omit<Props<E>, keyof own> & own;
-/** 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. `as` picks the element, like a `form` or a `ul`; the props and handlers are the
- * element's, so `<Row as="form" onSubmit={(e) => e.currentTarget.requestSubmit()}>` has a `HTMLFormElement`.
- */
-export function Row<E extends BoxAs = "div">(props: Own<E, { as?: E; gap?: Gap; align?: "start" | "baseline"; justify?: "end" | "between"; wrap?: boolean; grow?: boolean }>): ReactElement;
-/** Children one under the other. As a `ul` or `ol` it's a list with no bullets, of `li` children. `as` types the props like `Row`'s. */
-export function Stack<E extends BoxAs = "div">(props: Own<E, { as?: E; 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"> & { level?: 2 | 3 | 4; actions?: ReactNode }): ReactElement;
-/** A page's or a card's title, like a sprint's name or a setup step's question: an `h1` unless `as` says otherwise. */
-/** `truncate` cuts a title that's too long for its place to one line, with an ellipsis. */
-export function Title(props: Props<"h1"> & { as?: "h1" | "h2" | "h3"; size?: "large"; truncate?: boolean }): ReactElement;
-/** 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;
-
-// ---------- 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">;
-    /** A colour from your data, like a work item type's `#cc293d`, set as `--w-color`. Wins over `tone`. */
-    color?: string;
-    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. `busy` shows a spinner and ignores clicks while it keeps the
- * keyboard focus, unlike `disabled`: it's `aria-busy` and `aria-disabled`.
- */
-export function Button(props: Props<"button"> & { variant?: "primary" | "ghost" | "danger"; size?: "small"; busy?: boolean }): 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;
-    /** Each chip's other props, like `id`, go to its button. */
-    options: (Option<V> & Omit<Props<"button">, "value" | "onClick" | "children">)[];
-    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;
-    /** The input's id, and the label's `htmlFor`, for a page that puts focus back by id. Generated otherwise. */
-    id?: string;
-    /** The label and the input on one line. */
-    inline?: boolean;
-  },
-): ReactElement;
-/** Several controls under one label (a `fieldset` and its `legend`), like checkboxes, with a `hint` or an `error` under them. */
-export function FieldGroup(props: Props<"fieldset"> & { 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;
-export interface ComboboxOption {
-  value: string;
-  label: string;
-  /** A second, quieter part, like a project's client. */
-  detail?: string;
-}
-/**
- * A text field with `options` under it. Arrows move, Enter picks, Escape and Tab close, and pressing outside
- * closes it. With `freeText` the field keeps what you type (`value`, `onInput`) and starts with nothing
- * highlighted; otherwise you type to find an option and the field shows `value`, what you picked, once closed.
- * `filter` decides what matches what's typed: the label or the detail containing it, by default. Without
- * `freeText` the field's text is selected when it gets focus and after a pick, so typing replaces the label. An
- * `onKeyDown` you pass runs first; `preventDefault()` in it keeps the Combobox's own keys from running.
- */
-export function Combobox(
-  props: Omit<Props<"input">, "value" | "onInput" | "type"> & {
-    label?: string;
-    value: string;
-    onInput?: (text: string) => void;
-    options: ComboboxOption[];
-    onPick: (option: ComboboxOption) => void;
-    /** Enter with no option highlighted, with the text typed. The Enter doesn't submit a form around it. */
-    onEnter?: (text: string) => void;
-    freeText?: boolean;
-    /** Open the list when the field gets focus, by default; false opens it on a click, a key or typing only, for a page that puts focus back by id after it renders. */
-    openOnFocus?: boolean;
-    /**
-     * When the list is shown. `"auto"` (default): on focus, a click, a key or typing, and Escape, Tab, blur to another
-     * element or a press outside close it. `"whileText"`: the list is shown exactly while the field has text and an
-     * option matches it, whether or not the field has focus. Escape, Tab and a press outside only clear the highlighted
-     * option (`aria-activedescendant`); emptying the text or picking closes it, and there's no `empty` message. A
-     * list left open after the field loses focus is a screen reader caveat, see the README.
-     */
-    open?: "auto" | "whileText";
-    filter?: (option: ComboboxOption, query: string) => boolean;
-    /** What shows when nothing matches. */
-    empty?: ReactNode;
-  },
-): ReactElement;
-export interface MenuItem {
-  id: string;
-  label: ReactNode;
-  onSelect: () => void;
-  tone?: "danger";
-}
-/**
- * A button, showing `label`, that opens a menu of `items` under it. Arrows, Home and End move, Enter or Space
- * picks, Escape closes and puts focus back on the button. `align` end lines the menu up with the button's right.
- */
-export function Menu(
-  props: Omit<Props<"button">, "children"> & { label: ReactNode; items: MenuItem[]; align?: "end"; variant?: "primary" | "ghost" | "danger"; size?: "small" },
-): ReactElement;
-/** More behind a `summary` line that opens it. */
-export function Disclosure(props: Props<"details"> & { summary: ReactNode }): ReactElement;