wings-plugin-sdk 0.1.0 → 0.2.0

package/ui.js

@@ -0,0 +1,290 @@
+// wings-plugin-sdk/ui: a page says what to show and where, and Wings decides how it looks. Every component renders
+// plain elements with `w-*` class names and data attributes that Wings' plugin-ui.css styles, never a style of its
+// own, so a Wings update restyles every plugin. Your own components and CSS work alongside them.
+import { createContext, createElement as h, useContext, useEffect, useId, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+import { mountShell } from "./shell.js";
+
+export { mountShell } from "./shell.js";
+export { useBroadcast } from "./react.js";
+
+// ---------- places ----------
+
+let root = null;
+
+function show(place, element, options) {
+  const shell = mountShell(place, options);
+  root ??= createRoot(shell);
+  root.render(element);
+}
+
+/** Shows `element` as the page of a sidebar. One call per page; calling again renders the new element. */
+export const showSidebar = (element, options) => show("sidebar", element, options);
+/** Shows `element` as a view's page, in a modal or a window of its own. */
+export const showView = (element, options) => show("view", element, options);
+/** Shows `element` as a view's page in a tab next to the terminals. */
+export const showTab = (element, options) => show("tab", element, options);
+/** Shows `element` as a sidebar's popover. */
+export const showPopover = (element, options) => show("popover", element, options);
+/** Shows `element` as the plugin's page in Wings Settings. */
+export const showSettings = (element, options) => show("settings", element, options);
+
+// ---------- talking to main ----------
+
+const HELLO = { type: "hello" };
+
+/**
+ * The newest message of `type` the plugin's other pages broadcast, or null until one comes. Sends `hello` once
+ * when the component mounts, so main answers with its state; pass null to send nothing.
+ */
+export function useMainState(type, hello = HELLO) {
+  const [state, setState] = useState(null);
+  useEffect(() => {
+    const off = wings.onBroadcast((message) => {
+      if (message?.type === type) setState(message);
+    });
+    if (hello != null) void wings.broadcast(hello);
+    return off;
+    // `hello` is only sent when the component mounts.
+  }, [type]);
+  return state;
+}
+
+// ---------- helpers ----------
+
+const cx = (base, extra) => (extra ? `${base} ${extra}` : base);
+/** A data attribute that's there or not. */
+const flag = (on) => (on ? "" : undefined);
+
+// ---------- layout and text ----------
+
+/** Children side by side, centred. `gap` is none, xs, s, m (default) or l. */
+export function Row({ as = "div", gap, align, justify, wrap, grow, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-row", className), "data-gap": gap, "data-align": align, "data-justify": justify, "data-wrap": flag(wrap), "data-grow": flag(grow) });
+}
+
+/** Children one under the other. */
+export function Stack({ as = "div", gap, grow, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-stack", className), "data-gap": gap, "data-grow": flag(grow) });
+}
+
+/** Text with a tone and size, that can grow to fill a row or truncate with an ellipsis. */
+export function Text({ as = "span", tone, size, weight, mono, numeric, truncate, clamp, grow, className, ...rest }) {
+  return h(as, {
+    ...rest,
+    className: cx("w-text", className),
+    "data-tone": tone,
+    "data-size": size,
+    "data-weight": weight,
+    "data-mono": flag(mono),
+    "data-numeric": flag(numeric),
+    "data-truncate": flag(truncate),
+    "data-clamp": flag(clamp),
+    "data-grow": flag(grow),
+  });
+}
+
+/** A section heading, with `actions` like chips or a button on its right. */
+export function Heading({ actions, className, ...rest }) {
+  const heading = h("h2", { ...rest, className: cx("w-heading", className) });
+  return actions ? h("div", { className: "w-heading-row" }, heading, actions) : heading;
+}
+
+/** A card. `compact` for a summary line. */
+export function Card({ as = "div", compact, className, ...rest }) {
+  return h(as, { ...rest, className: cx("w-card", className), "data-size": compact ? "compact" : undefined });
+}
+
+// ---------- figures ----------
+
+const levelTone = (percent, levels) => (!levels ? undefined : percent >= levels[1] ? "danger" : percent >= levels[0] ? "warn" : undefined);
+
+/** A bar from 0 to 100. `tone` is warn or danger. */
+export function Meter({ percent, label, tone, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-meter", className), role: "meter", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, "data-tone": tone },
+    // How full it is is data, not a style: plugin-ui.css sizes the bar from it.
+    h("span", { className: "w-meter-fill", style: { "--w-value": `${Math.max(0, Math.min(100, percent))}%` } }),
+  );
+}
+
+/** A labelled bar with its percentage and a note under it. `levels` are where it turns warn and danger. */
+export function Gauge({ label, percent, note, tone, levels, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-gauge", className) },
+    h("span", { className: "w-gauge-label" }, label),
+    h("span", { className: "w-gauge-value" }, `${percent}%`),
+    h(Meter, { percent, label, tone: tone ?? levelTone(percent, levels) }),
+    note ? h("span", { className: "w-gauge-note" }, note) : null,
+  );
+}
+
+/** Small figures side by side, label over value. */
+export function Stats({ items, className, ...rest }) {
+  return h(
+    "dl",
+    { ...rest, className: cx("w-stats", className) },
+    items.map((item) => h("div", { key: item.label }, h("dt", { className: "w-stat-label" }, item.label), h("dd", { className: "w-stat-value", "data-tone": item.tone, title: item.title }, item.value))),
+  );
+}
+
+/** Label and value pairs, one per line. */
+export function Properties({ items, className, ...rest }) {
+  return h(
+    "dl",
+    { ...rest, className: cx("w-props", className) },
+    items.map((item) => h("div", { key: item.label, className: "w-prop" }, h("dt", { className: "w-prop-label" }, item.label), h("dd", { className: "w-prop-value" }, item.value))),
+  );
+}
+
+// ---------- lists ----------
+
+/** A list of rows. `ordered` for an `ol`, `compact` for rows with no space between them. */
+export function List({ ordered, compact, className, ...rest }) {
+  return h(ordered ? "ol" : "ul", { ...rest, className: cx("w-list", className), "data-density": compact ? "compact" : undefined });
+}
+
+/** A row in a `List`. Holding a `ListButton`, the button is the row. */
+export function ListItem({ align, className, ...rest }) {
+  return h("li", { ...rest, className: cx("w-list-item", className), "data-align": align });
+}
+
+/** A row that's a button, inside a `ListItem`. */
+export function ListButton({ align, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-list-button", className), "data-align": align });
+}
+
+// ---------- status ----------
+
+/** A status dot. With a `label` it's announced; otherwise it's decoration next to text that says the same. */
+export function Dot({ tone, label, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-dot", className), "data-tone": tone, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
+}
+
+/** A spinner. With a `label` it's announced. */
+export function Spinner({ size, label, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-spinner", className), "data-size": size, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }) });
+}
+
+/** A filled pill, like a label on a command. */
+export function Pill({ tone, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-pill", className), "data-tone": tone });
+}
+
+/** An outlined tag, like a branch name. */
+export function Tag({ tone, className, ...rest }) {
+  return h("span", { ...rest, className: cx("w-tag", className), "data-tone": tone });
+}
+
+/** What shows before the first data comes. */
+export function Loading({ children = "Loading…", className, ...rest }) {
+  return h("p", { ...rest, className: cx("w-loading", className) }, children);
+}
+
+/** Nothing to show: what's missing, and a `detail` line on what to do about it. */
+export function Empty({ title, detail, className, ...rest }) {
+  return h("div", { ...rest, className: cx("w-empty", className) }, h("p", null, title), detail === undefined ? null : h("p", { className: "w-empty-detail" }, detail));
+}
+
+// ---------- buttons ----------
+
+/** A button. `variant` is primary, ghost or danger; `size` small. */
+export function Button({ variant, size, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-button", className), "data-variant": variant, "data-size": size });
+}
+
+/** A small quiet button. With `pressed` it's a toggle. */
+export function Chip({ pressed, type = "button", className, ...rest }) {
+  return h("button", { ...rest, type, className: cx("w-chip", className), "aria-pressed": pressed });
+}
+
+/** Chips that pick one of `options`, like a filter. `onChange` gets each click, the chip that's on too. */
+export function Chips({ label, options, value, onChange, className, ...rest }) {
+  return h(
+    "div",
+    { ...rest, className: cx("w-chips", className), role: "group", "aria-label": label },
+    options.map((o) => h(Chip, { key: o.value, pressed: o.value === value, title: o.title, onClick: () => onChange(o.value) }, o.label)),
+  );
+}
+
+/** Tabs over the panel they show, `children`. Arrow keys, Home and End move between tabs. */
+export function Tabs({ label, items, value, onChange, children, className, ...rest }) {
+  const id = useId();
+  const tabId = (v) => `${id}-tab-${v}`;
+  const onKeyDown = (e) => {
+    const at = items.findIndex((t) => t.value === value);
+    const next = { ArrowRight: at + 1, ArrowLeft: at - 1, Home: 0, End: items.length - 1 }[e.key];
+    if (next === undefined) return;
+    e.preventDefault();
+    const tab = items[(next + items.length) % items.length];
+    onChange(tab.value);
+    document.getElementById(tabId(tab.value))?.focus();
+  };
+  return h(
+    "div",
+    { ...rest, className },
+    h(
+      "div",
+      { className: "w-tabs", role: "tablist", "aria-label": label, onKeyDown },
+      items.map((t) =>
+        h("button", { key: t.value, type: "button", id: tabId(t.value), className: "w-tab", role: "tab", "aria-selected": t.value === value, "aria-controls": `${id}-panel`, tabIndex: t.value === value ? 0 : -1, onClick: () => onChange(t.value) }, t.label),
+      ),
+    ),
+    h("div", { id: `${id}-panel`, role: "tabpanel", "aria-labelledby": tabId(value) }, children),
+  );
+}
+
+// ---------- fields ----------
+
+const FieldContext = createContext(null);
+
+/** Gives an input in a `Field` its label and hint. */
+function useFieldProps(rest) {
+  const field = useContext(FieldContext);
+  return field ? { id: field.id, "aria-describedby": field.hint, "aria-invalid": field.invalid || undefined, ...rest } : rest;
+}
+
+/** A labelled field with a `hint` or an `error` under it, for the input in `children`. */
+export function Field({ label, hint, error, children, className, ...rest }) {
+  const id = useId();
+  const note = error ?? hint;
+  return h(
+    "div",
+    { ...rest, className: cx("w-field", className) },
+    h("label", { className: "w-field-label", htmlFor: id }, label),
+    h(FieldContext.Provider, { value: { id, hint: note ? `${id}-hint` : undefined, invalid: Boolean(error) } }, children),
+    note ? h("p", { id: `${id}-hint`, className: "w-field-hint", "data-tone": error ? "danger" : undefined }, note) : null,
+  );
+}
+
+/** A text input. Outside a `Field`, give it a `label`. */
+export function TextInput({ label, type = "text", className, ...rest }) {
+  return h("input", { "aria-label": label, ...useFieldProps(rest), type, className: cx("w-input", className) });
+}
+
+/** A search box. `label` names it for screen readers. */
+export function SearchField({ label, className, ...rest }) {
+  return h("input", { "aria-label": label, ...useFieldProps(rest), type: "search", className: cx("w-search", className) });
+}
+
+/** A select of `options`. `onChange` gets the value picked. */
+export function Select({ label, options, onChange, className, ...rest }) {
+  return h(
+    "select",
+    { "aria-label": label, ...useFieldProps(rest), className: cx("w-select", className), onChange: (e) => onChange?.(e.currentTarget.value) },
+    options.map((o) => h("option", { key: o.value, value: o.value, disabled: o.disabled }, o.label)),
+  );
+}
+
+/** A checkbox with its label, `children`. `onChange` gets whether it's checked. */
+export function Checkbox({ onChange, children, className, ...rest }) {
+  return h("label", { className: cx("w-check", className) }, h("input", { ...rest, type: "checkbox", onChange: (e) => onChange?.(e.currentTarget.checked) }), children);
+}
+
+/** More behind a `summary` line that opens it. */
+export function Disclosure({ summary, children, className, ...rest }) {
+  return h("details", { ...rest, className: cx("w-disclosure", className) }, h("summary", null, summary), children);
+}

package/wings.d.ts

@@ -204,12 +204,15 @@ interface Wings {
   setSidebarLabel(sidebarId: string, label: string | null, options?: { rows?: { label: string; value: string }[]; tone?: "warning" | "danger" }): Promise<void>;
   /**
    * Opens one of `contributes.sidebars` or `contributes.views` by id: in the right sidebar, in a modal over Wings,
-   * or in a window of its own. `as` must be in the view's `opens`, and defaults to the first. A window that's
-   * already open comes to the front. The page gets the same `wings` object wherever it opens.
+   * in a window of its own or as a tab in the project on screen (`tab` needs Wings 0.1.15). `as` must be in the
+   * view's `opens`, and defaults to the first. A window or tab that's already open comes to the front. The page
+   * gets the same `wings` object wherever it opens.
    */
-  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" }): Promise<void>;
+  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" | "tab" }): Promise<void>;
   /** Closes a sidebar or view wherever it's open. */
   closeView(id: string): Promise<void>;
+  /** Opens Wings Settings at the plugin's settings page, `contributes.settings`. Wings 0.1.15 and newer. */
+  openSettings(): Promise<void>;
   /** Sends a JSON value, up to 64 KB, to the plugin's other pages: its main script and open sidebars, modals and windows. */
   broadcast(message: unknown): Promise<void>;
   /** Gets what the plugin's other pages send with `broadcast`. */
@@ -217,3 +220,6 @@ interface Wings {
 }
 
 declare const wings: Wings;
+
+/** A page's own CSS, `import "./sidebar.css"`: wings-plugin build bundles it into the page's `<name>.css`. */
+declare module "*.css";