deck-plugin-sdk 1.4.0 → 1.6.0

package/template/src/plugin.tsx

@@ -1,65 +1,65 @@
-// __NAME__ — a Deck plugin.
-//
-// The default export is the tab. A plugin can export more than that — a footer readout, a
-// settings panel, palette commands, a pane view — and `plugins/API.md` in the Deck repository
-// lists every slot. One export is enough to start.
-import { useState } from "react";
-import { Sparkles } from "lucide-react";
-import { configRead, configWrite } from "../shim/bridge.js";
-
-/** Where this plugin's own settings live. The `plugin-` prefix keeps them on this machine. */
-const CONFIG = "plugin-__ID__";
-
-export default function __COMPONENT__() {
-  const [note, setNote] = useState("");
-  const [saved, setSaved] = useState(false);
-
-  // Deck's config store, the same one its own modules use. Reading a key that has never been
-  // written resolves to an empty string rather than throwing.
-  const load = async () => {
-    const raw = await configRead(CONFIG).catch(() => "");
-    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
-  };
-
-  const save = async () => {
-    await configWrite(CONFIG, JSON.stringify({ note }));
-    setSaved(true);
-    setTimeout(() => setSaved(false), 1500);
-  };
-
-  return (
-    <div className="flex h-full flex-col gap-4 p-6">
-      <header className="flex items-center gap-3">
-        <Sparkles size={18} style={{ color: "var(--accent)" }} />
-        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
-      </header>
-
-      <p className="max-w-[60ch] text-sm text-text-secondary">
-        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
-        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
-        and Deck reloads the plugin as you save.
-      </p>
-
-      <div className="flex max-w-md items-center gap-2">
-        <input
-          value={note}
-          onChange={(e) => setNote(e.target.value)}
-          onFocus={() => void load()}
-          placeholder="Type something, then save it"
-          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
-        />
-        <button
-          onClick={() => void save()}
-          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
-        >
-          {saved ? "Saved" : "Save"}
-        </button>
-      </div>
-
-      <p className="text-xs text-text-muted">
-        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
-        machine.
-      </p>
-    </div>
-  );
-}
+// __NAME__ — a Deck plugin.
+//
+// The default export is the tab. A plugin can export more than that — a footer readout, a
+// settings panel, palette commands, a pane view — and `docs/guide/api.md` in the Deck repository
+// lists every slot. One export is enough to start.
+import { useState } from "react";
+import { Sparkles } from "lucide-react";
+import { configRead, configWrite } from "deck-plugin-sdk/bridge";
+
+/** This plugin's own settings. Deck keeps a plugin's configs in its own folder, so a plain name. */
+const CONFIG = "settings";
+
+export default function __COMPONENT__() {
+  const [note, setNote] = useState("");
+  const [saved, setSaved] = useState(false);
+
+  // Deck's config store, the same one its own modules use. Reading a key that has never been
+  // written resolves to an empty string rather than throwing.
+  const load = async () => {
+    const raw = await configRead(CONFIG).catch(() => "");
+    setNote(raw.trim() ? (JSON.parse(raw) as { note?: string }).note ?? "" : "");
+  };
+
+  const save = async () => {
+    await configWrite(CONFIG, JSON.stringify({ note }));
+    setSaved(true);
+    setTimeout(() => setSaved(false), 1500);
+  };
+
+  return (
+    <div className="flex h-full flex-col gap-4 p-6">
+      <header className="flex items-center gap-3">
+        <Sparkles size={18} style={{ color: "var(--accent)" }} />
+        <h1 className="text-base font-semibold text-text-primary">__NAME__</h1>
+      </header>
+
+      <p className="max-w-[60ch] text-sm text-text-secondary">
+        Edit <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">src/plugin.tsx</code>,
+        run <code className="rounded bg-elev px-1.5 py-0.5 text-text-primary">npm run dev</code>,
+        and Deck reloads the plugin as you save.
+      </p>
+
+      <div className="flex max-w-md items-center gap-2">
+        <input
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+          onFocus={() => void load()}
+          placeholder="Type something, then save it"
+          className="min-w-0 flex-1 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-primary outline-none focus:border-accent"
+        />
+        <button
+          onClick={() => void save()}
+          className="shrink-0 rounded-lg border border-subtle bg-elev px-3 py-2 text-sm text-text-secondary hover:border-accent hover:text-text-primary"
+        >
+          {saved ? "Saved" : "Save"}
+        </button>
+      </div>
+
+      <p className="text-xs text-text-muted">
+        That writes to Deck's config store under <code>{CONFIG}</code>, which stays on this
+        machine.
+      </p>
+    </div>
+  );
+}

package/types/components/ActivityBar.d.ts

@@ -11,10 +11,12 @@ export interface ActivityView<Id extends string> {
     onClick?: (el: HTMLElement) => void;
 }
 export default ActivityBar;
-export declare function ActivityBar<Id extends string>({ views, active, onSelect, trailing, }: {
+export declare function ActivityBar<Id extends string>({ views, active, onSelect, trailing, grouped, }: {
     views: readonly ActivityView<Id>[];
     active: Id;
     onSelect: (id: Id) => void;
     /** Fixed controls pinned to the right — present for every view, or the icons shift. */
     trailing?: React.ReactNode;
+    /** The icons together in one rounded group, smaller, rather than loose pills. */
+    grouped?: boolean;
 }): import("react").JSX.Element;

package/types/components/ContextMenu.d.ts

@@ -26,6 +26,9 @@ export interface MenuItem {
     /** A setting rather than an action: renders a checkbox and does NOT close the menu, so several
      *  can be flipped in one visit. The caller re-renders with the new value. */
     checked?: boolean;
+    /** Controls of its own at the row's right (a zoom's − and +, a slider): the row is not
+     *  clicked itself, and using them leaves the menu open. */
+    controls?: React.ReactNode;
 }
 export type MenuEntry = MenuItem | "sep";
 export declare function ContextMenu({ x, y, items, alignRight, onClose, onReorder, flipAt, up }: {

package/types/components/TabStrip.d.ts

@@ -12,7 +12,7 @@ export interface TabItem {
     /** Tooltip for the close button; defaults to "Close". */
     closeTitle?: string;
 }
-export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder, onDoubleClick, trailing, pill, onAdd, addTitle, }: {
+export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder, onDoubleClick, leading, trailing, pill: pillProp, chip, onAdd, addTitle, }: {
     tabs: readonly TabItem[];
     activeId: string | null;
     onSelect: (id: string) => void;
@@ -20,11 +20,16 @@ export declare function TabStrip({ tabs, activeId, onSelect, onClose, onReorder,
     /** Moves `from` to `to`'s position. Omit to make the strip non-reorderable. */
     onReorder?: (from: string, to: string) => void;
     onDoubleClick?: (id: string) => void;
+    /** Controls before the first tab. */
+    leading?: ReactNode;
     /** Right-aligned controls after the tabs — view toggles, save state. */
     trailing?: ReactNode;
     /** Rounded tabs with the active one lit in the accent, the look of the workspace tabs in the
      *  title bar, instead of the editor-style boxed row. */
     pill?: boolean;
+    /** Rounded like `pill`, with the open tab raised on the card colour rather than lit in the
+     *  accent: the editor's tabs, where the accent already marks the open file in the tree. */
+    chip?: boolean;
     /** A + right after the last tab, as the workspace tabs have. */
     onAdd?: () => void;
     addTitle?: string;

package/types/components/ui.d.ts

@@ -58,10 +58,14 @@ export declare function DayPicker({ value, onChange, }: {
     onChange: (days: string[]) => void;
 }): import("react").JSX.Element;
 /** One readout in the footer strip: an icon, a short label, and an optional click. */
-export declare function StatusItem({ icon, color, label, title, onClick, }: {
+export declare function StatusItem({ icon, color, label, detail, meter, title, onClick, }: {
     icon: React.ReactNode;
     color: string;
     label: string;
+    /** A second, quieter part after the label: a branch, a commit. */
+    detail?: string;
+    /** 0 to 100: a small bar before the label, in the item's colour (a limit's use). */
+    meter?: number;
     title?: string;
     onClick?: () => void;
 }): import("react").JSX.Element;
@@ -100,3 +104,46 @@ export declare function Toggle({ on, onChange }: {
     on: boolean;
     onChange: (v: boolean) => void;
 }): import("react").JSX.Element;
+/** A state in its colour: Ready, Running, Paused, Failed. `color` is any CSS colour; a `--tone-*`
+ *  one (`tone("green")`) follows a light theme. */
+export declare function Chip({ color, title, children }: {
+    color: string;
+    title?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A `--tone-*` colour as CSS, for a Chip, a dot or text: `tone("amber")`. */
+export declare function tone(name: "red" | "emerald" | "amber" | "blue" | "green" | "cyan" | "sky" | "violet" | "pink" | "orange", shade?: 300 | 400): string;
+/** How many, after a heading or a row. */
+export declare function CountChip({ n, title }: {
+    n: number;
+    title?: string;
+}): import("react").JSX.Element;
+/**
+ * What a space is for and the way in, when it has nothing to show: a sentence and, usually, a
+ * button. `card` puts it in a quiet card, for when it is the only thing on screen.
+ */
+export declare function EmptyState({ icon, title, children, action, card }: {
+    icon?: ReactNode;
+    /** A short line above the sentence, when the space needs naming. */
+    title?: string;
+    children: ReactNode;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    card?: boolean;
+}): import("react").JSX.Element;
+/**
+ * An icon-only button. `toolbar` (size-7) for a panel's own actions, `row` (size-5) for one inside
+ * a list row, shown on the row's hover by the caller. `danger` turns it red on hover only; `active`
+ * marks a toggle that is on. `title` is required: it is the only label the button has.
+ */
+export declare function IconButton({ title, onClick, children, size, danger, active, disabled }: {
+    title: string;
+    onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    children: ReactNode;
+    size?: "toolbar" | "row";
+    danger?: boolean;
+    active?: boolean;
+    disabled?: boolean;
+}): import("react").JSX.Element;

package/types/components/useResize.d.ts

@@ -19,7 +19,7 @@ export declare function useNarrow(px: number): [boolean, (el: HTMLElement | null
  * Listeners go on `window`, not the divider, so a fast drag that outruns the pointer keeps
  * resizing instead of stopping the moment the cursor leaves the 4px handle.
  */
-export declare function useResize({ initial, min, max, direction, invert, }: {
+export declare function useResize({ initial, min, max, direction, invert, collapseBelow, onCollapse, }: {
     initial: number;
     min: number;
     max: number;
@@ -31,6 +31,13 @@ export declare function useResize({ initial, min, max, direction, invert, }: {
      * would grow a pane that is actually being squeezed from above.
      */
     invert?: boolean;
+    /**
+     * Dragged this far down (below `min`), the drag ends and `onCollapse` runs: the pane snaps shut
+     * rather than stopping at its minimum. Its size goes back to what it was when the drag began, so
+     * opening it again gives the width it had.
+     */
+    collapseBelow?: number;
+    onCollapse?: () => void;
 }): readonly [number, {
     readonly onMouseDown: (e: React.MouseEvent) => void;
 }, boolean];

package/types/core/bookmarks.d.ts

@@ -0,0 +1,79 @@
+// GENERATED by sdk/gen-types.mjs from Deck's source — do not edit.
+export interface BookmarkNode {
+    id: string;
+    title: string;
+    /** A page has a URL; a folder has children instead. */
+    url?: string;
+    children?: BookmarkNode[];
+}
+export interface Bookmarks {
+    bar: BookmarkNode[];
+    other: BookmarkNode[];
+}
+export declare const EMPTY: Bookmarks;
+export declare const isFolder: (n: BookmarkNode) => boolean;
+/** An id unique within this run and across runs: time, then a counter. */
+export declare const newId: () => string;
+/** Every page in the tree, depth first, with the folder titles above it. */
+export declare function pages(b: Bookmarks): {
+    node: BookmarkNode;
+    path: string[];
+}[];
+/** The bookmark for `url`, if there is one (the first, when it was saved twice). */
+export declare const findByUrl: (b: Bookmarks, url: string) => BookmarkNode | undefined;
+/** Every folder, for a "save in" list: the two roots first, then each folder by its path. */
+export declare function folders(b: Bookmarks): {
+    id: string;
+    path: string;
+}[];
+/** Add `node` at the end of `folder`. */
+export declare const add: (b: Bookmarks, folder: string, node: BookmarkNode) => Bookmarks;
+/** Remove the node with `id`, wherever it is (a folder goes with what is in it). */
+export declare function remove(b: Bookmarks, id: string): Bookmarks;
+/** Change a node's title or URL. */
+export declare function update(b: Bookmarks, id: string, patch: Partial<Pick<BookmarkNode, "title" | "url">>): Bookmarks;
+/** The node with `id`, and the id of the folder it is in. */
+export declare function locate(b: Bookmarks, id: string): {
+    node: BookmarkNode;
+    folder: string;
+} | null;
+/** Move a node to the end of another folder. A folder cannot go inside itself. */
+export declare function move(b: Bookmarks, id: string, folder: string): Bookmarks;
+/**
+ * A Chromium browser's Bookmarks file (Chrome, Edge, Brave all keep the same JSON) as Deck's
+ * nodes: its bar, its other bookmarks, and on Chrome its mobile ones, each as given. Anything that
+ * is not a page or a folder (a separator, an app link) is left out.
+ */
+export declare function fromChrome(json: string): {
+    bar: BookmarkNode[];
+    other: BookmarkNode[];
+};
+/** An import, as one folder in each root named after where it came from ("From Chrome"), left out
+ *  of a root it has nothing for. */
+export declare function addImport(b: Bookmarks, from: string, got: {
+    bar: BookmarkNode[];
+    other: BookmarkNode[];
+}): Bookmarks;
+/** How many pages a set of nodes holds. */
+export declare const countPages: (ns: readonly BookmarkNode[]) => number;
+/** Deck's bookmarks as a bookmarks HTML file. */
+export declare function toHtml(b: Bookmarks): string;
+/** A bookmarks HTML file as Deck's two roots. Read by its tags, not as a page: folders (H3) open
+ *  the list (DL) that follows them, pages are links (A HREF). */
+export declare function fromHtml(html: string): {
+    bar: BookmarkNode[];
+    other: BookmarkNode[];
+};
+/**
+ * An import merged in: a folder joins the folder of the same name where it lands (made if there
+ * is none), and a page already bookmarked anywhere is left out. So a file exported from Deck
+ * restores into the same places, and importing one twice adds nothing the second time.
+ * Returns the bookmarks and how many pages were added.
+ */
+export declare function mergeImport(b: Bookmarks, got: {
+    bar: BookmarkNode[];
+    other: BookmarkNode[];
+}): {
+    bookmarks: Bookmarks;
+    added: number;
+};