@silo-code/sdk 0.28.1 → 0.29.1

package/src/Switch.tsx

@@ -0,0 +1,63 @@
+import type { ButtonHTMLAttributes } from "react";
+import { switchDataChecked } from "./switch-classes";
+
+/**
+ * The iOS-style on/off toggle used throughout settings. Off = recessed
+ * `bg-active` track with a hairline border; on = accent fill. Focus uses a
+ * positive-offset ring (the one deliberate exception to the shared inset
+ * ring — an 18px pill can't take an inset outline).
+ *
+ * Styled purely via the host-provided `.silo-switch-track` class — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={formatOnSave}
+ *   onChange={setFormatOnSave}
+ *   aria-label="Format on save"
+ * />
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function Switch({
+  checked,
+  onChange,
+  disabled,
+  "aria-label": ariaLabel,
+  className,
+  type = "button",
+  ...rest
+}: {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  disabled?: boolean;
+  /**
+   * Required unless wrapped by a labeled {@link SettingRow}.
+   */
+  "aria-label"?: string;
+} & Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "onChange" | "aria-label" | "children" | "role" | "aria-checked"
+>) {
+  return (
+    <button
+      type={type}
+      role="switch"
+      aria-checked={checked}
+      aria-label={ariaLabel}
+      disabled={disabled}
+      data-checked={switchDataChecked(checked)}
+      className={
+        className ? `silo-switch-track ${className}` : "silo-switch-track"
+      }
+      onClick={() => {
+        if (disabled) return;
+        onChange(!checked);
+      }}
+      {...rest}
+    />
+  );
+}

package/src/Tabs.tsx

@@ -0,0 +1,89 @@
+import type { ReactNode } from "react";
+import { tabDataActive } from "./tabs-classes";
+
+/**
+ * One tab in a {@link Tabs} strip.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface TabItem<T extends string = string> {
+  id: T;
+  label: string;
+  icon?: ReactNode;
+}
+
+/**
+ * A borderless strip attached to the content panel it switches. The active
+ * tab's background **is** the panel's background — that shared fill is what
+ * makes the tab read as part of the panel. Pair with {@link TabPanel}.
+ * Native tab stops per tab; no arrow-key roving.
+ *
+ * Styled purely via host-provided `.silo-tabs` / `.silo-tab` classes — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <Tabs
+ *   tabs={[
+ *     { id: "panels", label: "Side Panels" },
+ *     { id: "statusBar", label: "Status Bar" },
+ *     { id: "options", label: "Options" },
+ *   ]}
+ *   active={tab}
+ *   onSelect={setTab}
+ * />
+ * <TabPanel>{tab === "panels" && <PanelsSettings />}</TabPanel>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function Tabs<T extends string>({
+  tabs,
+  active,
+  onSelect,
+}: {
+  tabs: TabItem<T>[];
+  active: T;
+  onSelect: (id: T) => void;
+}) {
+  return (
+    <div className="silo-tabs" role="tablist">
+      {tabs.map((tab) => {
+        const isActive = tab.id === active;
+        const dataActive = tabDataActive(isActive);
+        return (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={isActive}
+            className="silo-tab"
+            {...(dataActive != null ? { "data-active": dataActive } : {})}
+            onClick={() => onSelect(tab.id)}
+          >
+            {tab.icon}
+            {tab.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * The content panel a {@link Tabs} strip attaches to. Active-tab and panel
+ * share the same background token — that's the "attached" illusion.
+ *
+ * @example
+ * ```tsx
+ * <TabPanel>{tab === "panels" && <PanelsSettings />}</TabPanel>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function TabPanel({ children }: { children?: ReactNode }) {
+  return <div className="silo-tab-panel">{children}</div>;
+}

package/src/Textarea.tsx

@@ -0,0 +1,33 @@
+import { forwardRef, type TextareaHTMLAttributes } from "react";
+
+/**
+ * Multi-line text entry wearing the same tokens as {@link Input}, plus
+ * comfortable line-height, vertical resize, and a 64px minimum height.
+ *
+ * Styled purely via the host-provided `.silo-textarea` class — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <Textarea
+ *   value={notes}
+ *   onChange={(e) => setNotes(e.target.value)}
+ *   placeholder="Notes…"
+ * />
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export const Textarea = forwardRef<
+  HTMLTextAreaElement,
+  TextareaHTMLAttributes<HTMLTextAreaElement>
+>(function Textarea({ className, ...rest }, ref) {
+  return (
+    <textarea
+      ref={ref}
+      className={className ? `silo-textarea ${className}` : "silo-textarea"}
+      {...rest}
+    />
+  );
+});

package/src/badge-classes.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { badgeClass } from "./badge-classes";
+
+describe("badgeClass", () => {
+  it("defaults to neutral", () => {
+    expect(badgeClass()).toBe("silo-badge silo-badge-neutral");
+  });
+
+  it("maps every tone to silo-badge-{tone}", () => {
+    expect(badgeClass("accent")).toBe("silo-badge silo-badge-accent");
+    expect(badgeClass("ok")).toBe("silo-badge silo-badge-ok");
+    expect(badgeClass("warn")).toBe("silo-badge silo-badge-warn");
+    expect(badgeClass("err")).toBe("silo-badge silo-badge-err");
+    expect(badgeClass("outline")).toBe("silo-badge silo-badge-outline");
+  });
+
+  it("uses silo-badge-custom when color is set (overrides tone)", () => {
+    expect(badgeClass("ok", "#e06c75")).toBe("silo-badge silo-badge-custom");
+  });
+});

package/src/badge-classes.ts

@@ -0,0 +1,27 @@
+/**
+ * Class-string mapping for {@link Badge} — pinned by unit tests so a rename
+ * of the host contract classes fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export type BadgeTone =
+  | "neutral"
+  | "accent"
+  | "ok"
+  | "warn"
+  | "err"
+  | "outline";
+
+/**
+ * Resolve the host `.silo-badge*` class string. An arbitrary `color` wins over
+ * `tone` and selects `.silo-badge-custom` (fed via `--badge-color`).
+ *
+ * @internal
+ */
+export function badgeClass(
+  tone: BadgeTone = "neutral",
+  color?: string,
+): string {
+  if (color != null) return "silo-badge silo-badge-custom";
+  return `silo-badge silo-badge-${tone}`;
+}

package/src/button-classes.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { buttonClass } from "./button-classes";
+
+describe("buttonClass", () => {
+  it("maps normal variant to silo-button", () => {
+    expect(buttonClass("normal")).toBe("silo-button");
+    expect(buttonClass()).toBe("silo-button");
+  });
+
+  it("maps primary and danger to their standalone classes", () => {
+    expect(buttonClass("primary")).toBe("silo-button-primary");
+    expect(buttonClass("danger")).toBe("silo-button-danger");
+  });
+
+  it("composes silo-button-sm onto any variant", () => {
+    expect(buttonClass("normal", "sm")).toBe("silo-button silo-button-sm");
+    expect(buttonClass("primary", "sm")).toBe(
+      "silo-button-primary silo-button-sm",
+    );
+    expect(buttonClass("danger", "sm")).toBe(
+      "silo-button-danger silo-button-sm",
+    );
+  });
+});

package/src/button-classes.ts

@@ -0,0 +1,32 @@
+/**
+ * Class-string mapping for {@link Button} — pinned by unit tests so a rename
+ * of the host contract classes fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export type ButtonVariant = "normal" | "primary" | "danger";
+
+/**
+ * @internal
+ */
+export type ButtonSize = "normal" | "sm";
+
+/**
+ * Resolve the host `.silo-button*` class string for a Button's `variant` +
+ * `size`. Primary/danger are standalone class names (not modifiers on
+ * `.silo-button`); `sm` composes with any variant.
+ *
+ * @internal
+ */
+export function buttonClass(
+  variant: ButtonVariant = "normal",
+  size: ButtonSize = "normal",
+): string {
+  const base =
+    variant === "primary"
+      ? "silo-button-primary"
+      : variant === "danger"
+        ? "silo-button-danger"
+        : "silo-button";
+  return size === "sm" ? `${base} silo-button-sm` : base;
+}

package/src/editor-service.ts

@@ -291,9 +291,12 @@ export interface EditorService {
    * The current buffer text of an open editor tab, including unsaved edits.
    *
    * Resolves `undefined` when the tab isn't text-backed (e.g. the image
-   * viewer) or hasn't mounted yet — a lazy-mounted dock panel is **not**
-   * force-mounted to read its text. It is async precisely because the text
-   * lives in the mounted editor component, not in host state.
+   * viewer), has never mounted a text document, and has no retained unsaved
+   * buffer. A dirty text editor that unmounts on a view switch (e.g. Text →
+   * Markdown Preview) retains its buffer so presenters can still read it. A
+   * lazy-mounted dock panel is **not** force-mounted to read its text. It is
+   * async precisely because the live text lives in the mounted editor
+   * component, not in host state.
    *
    * @example
    * ```ts
@@ -304,7 +307,8 @@ export interface EditorService {
   getText(editorId: string): Promise<string | undefined>;
   /**
    * Whether an open editor tab has unsaved changes. Returns `false` for an
-   * unknown id or a tab that isn't mounted / text-backed.
+   * unknown id or a tab that isn't text-backed and has no retained dirty
+   * buffer. Stays `true` across a dirty Text → Preview view switch.
    */
   isDirty(editorId: string): boolean;
   /**

package/src/empty-state-classes.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from "vitest";
+import { emptyStateIconDataTone } from "./empty-state-classes";
+
+describe("emptyStateIconDataTone", () => {
+  it("omits data-tone for the neutral default", () => {
+    expect(emptyStateIconDataTone()).toBeUndefined();
+    expect(emptyStateIconDataTone("neutral")).toBeUndefined();
+  });
+
+  it("sets data-tone=ok for the positive-empty tone", () => {
+    expect(emptyStateIconDataTone("ok")).toBe("ok");
+  });
+});

package/src/empty-state-classes.ts

@@ -0,0 +1,17 @@
+/**
+ * Class-string / data-attribute mapping for {@link EmptyState} — pinned by
+ * unit tests so a rename of the host contract fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export type EmptyStateTone = "ok" | "neutral";
+
+/**
+ * @internal
+ */
+export function emptyStateIconDataTone(
+  tone: EmptyStateTone = "neutral",
+): "ok" | undefined {
+  // CSS keys the ok tone on data-tone="ok"; neutral is the default (no attr).
+  return tone === "ok" ? "ok" : undefined;
+}

package/src/icon-button-classes.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from "vitest";
+import { iconButtonClass } from "./icon-button-classes";
+
+describe("iconButtonClass", () => {
+  it("defaults to silo-icon-button", () => {
+    expect(iconButtonClass()).toBe("silo-icon-button");
+    expect(iconButtonClass("normal")).toBe("silo-icon-button");
+  });
+
+  it("adds the sm modifier", () => {
+    expect(iconButtonClass("sm")).toBe("silo-icon-button silo-icon-button-sm");
+  });
+});

package/src/icon-button-classes.ts

@@ -0,0 +1,19 @@
+/**
+ * Class-string mapping for {@link IconButton} — pinned by unit tests so a
+ * rename of the host contract classes fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export type IconButtonSize = "normal" | "sm";
+
+/**
+ * Resolve the host `.silo-icon-button*` class string for an IconButton's
+ * `size`. Default is the 32px standalone size; `sm` adds the 26px modifier.
+ *
+ * @internal
+ */
+export function iconButtonClass(size: IconButtonSize = "normal"): string {
+  return size === "sm"
+    ? "silo-icon-button silo-icon-button-sm"
+    : "silo-icon-button";
+}

package/src/index.ts

@@ -5,10 +5,10 @@
  * host-internal and may change without notice.
  *
  * **What's here:** the types-first extension contract (see `types.ts`) plus a
- * small set of blessed runtime helpers (`Tooltip`, `useFocusGroup`,
- * `useServiceState`, `DND_MIME`, `PathDeniedError`, `NetworkError`). The SDK
- * peer-depends on React 19; changes to the runtime helpers can be breaking
- * even when the types are unchanged.
+ * small set of blessed runtime helpers (`Tooltip`, the modal design-system
+ * kit, `useFocusGroup`, `useServiceState`, `DND_MIME`, `PathDeniedError`,
+ * `NetworkError`). The SDK peer-depends on React 19; changes to the runtime
+ * helpers can be breaking even when the types are unchanged.
  *
  * This is also the entry point the API-reference generator (TypeDoc) reads, so
  * the published reference is exactly this surface — no more, no less.
@@ -220,6 +220,39 @@ export { path } from "./path";
 // Extensions use this instead of native `title` attributes to match host chrome.
 export { Tooltip } from "./Tooltip";
 
+// Modal design-system kit (RFC 0016 / ADR 0026) — presentational components
+// styled purely via host-provided `.silo-*` classes.
+export { Button } from "./Button";
+export type { ButtonVariant, ButtonSize } from "./Button";
+export { IconButton } from "./IconButton";
+export type { IconButtonSize } from "./IconButton";
+export { Input } from "./Input";
+export { Textarea } from "./Textarea";
+export { SearchInput } from "./SearchInput";
+export { InlineEdit } from "./InlineEdit";
+export type { InlineEditValidation } from "./InlineEdit";
+export { Select } from "./Select";
+export { Switch } from "./Switch";
+export { CheckboxRow } from "./CheckboxRow";
+export { RadioGroup, RadioCard } from "./RadioGroup";
+export { ModalActions } from "./ModalActions";
+
+// Structure half of the modal design-system kit (RFC 0016).
+export { SegmentedTabs } from "./SegmentedTabs";
+export type { SegmentedTabItem } from "./SegmentedTabs";
+export { Tabs, TabPanel } from "./Tabs";
+export type { TabItem } from "./Tabs";
+export { List, ListRow } from "./List";
+export type { ListRowProps, ListRowTruncate } from "./List";
+export { AddRow } from "./AddRow";
+export { Badge } from "./Badge";
+export type { BadgeTone } from "./Badge";
+export { EmptyState } from "./EmptyState";
+export type { EmptyStateTone } from "./EmptyState";
+export { Callout } from "./Callout";
+export { Section } from "./Section";
+export { SettingRow } from "./SettingRow";
+
 // Runtime helpers. The one blessed way for an extension to read a `ctx`
 // service's reactive state in React — replaces hand-rolled useSyncExternalStore.
 export { useServiceState } from "./use-service-state";
@@ -237,3 +270,11 @@ export type {
   FocusGroupOrientation,
   FocusGroupNavQuery,
 } from "./use-focus-group";
+
+// Host/InlineEdit coordination for InlineEdit's two-stage Escape (RFC 0016).
+// @internal — host-only plumbing, not part of the documented reference;
+// extension authors never call these directly.
+export {
+  setActiveInlineEditCancel,
+  yieldEscapeToInlineEdit,
+} from "./inline-edit-controller";

package/src/inline-edit-classes.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import {
+  inlineEditDisplayClass,
+  inlineEditRowClass,
+} from "./inline-edit-classes";
+
+describe("inlineEditDisplayClass", () => {
+  it("is silo-inline-edit-display by default", () => {
+    expect(inlineEditDisplayClass(false)).toBe("silo-inline-edit-display");
+  });
+
+  it("adds multiline", () => {
+    expect(inlineEditDisplayClass(true)).toBe(
+      "silo-inline-edit-display multiline",
+    );
+  });
+});
+
+describe("inlineEditRowClass", () => {
+  it("is silo-inline-edit-row by default", () => {
+    expect(inlineEditRowClass(false)).toBe("silo-inline-edit-row");
+  });
+
+  it("adds multiline", () => {
+    expect(inlineEditRowClass(true)).toBe("silo-inline-edit-row multiline");
+  });
+});

package/src/inline-edit-classes.ts

@@ -0,0 +1,18 @@
+/**
+ * Class-string mapping for {@link InlineEdit} — pinned by unit tests so a
+ * rename of the host contract classes fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export function inlineEditDisplayClass(multiline: boolean): string {
+  return multiline
+    ? "silo-inline-edit-display multiline"
+    : "silo-inline-edit-display";
+}
+
+/**
+ * @internal
+ */
+export function inlineEditRowClass(multiline: boolean): string {
+  return multiline ? "silo-inline-edit-row multiline" : "silo-inline-edit-row";
+}

package/src/inline-edit-controller.ts

@@ -0,0 +1,53 @@
+// Coordination for `InlineEdit`'s two-stage Escape (RFC 0016): the first
+// Escape cancels an in-progress edit, the next Escape closes the enclosing
+// modal. Mirrors the host's `menu-controller.ts` `getMenu()` pattern — a
+// single piece of module state the modal's own Escape handler checks before
+// acting on the key itself — because `InlineEdit` doesn't have (and doesn't
+// need) a document-level keydown listener of its own; the host's `Modal.tsx`
+// already owns one.
+//
+// Lives in the SDK, not the host, even though only host code (`Modal.tsx`)
+// calls `yieldEscapeToInlineEdit`: the dependency only runs one direction
+// (extension-host depends on @silo-code/sdk, never the reverse), and
+// `InlineEdit` — a public SDK component — is the thing calling
+// `setActiveInlineEditCancel`. Exported from the barrel so the host can
+// import it like anything else in `@silo-code/sdk`, tagged `@internal` to
+// keep it out of the public docs reference — extension authors never call
+// these directly.
+//
+// This intentionally works regardless of the modal's `dismissible` option:
+// InlineEdit ships on `Workspace Properties`-style non-dismissible modals
+// (protecting other staged input) as often as dismissible ones, and
+// cancelling an edit-in-place is a narrower, always-safe action than closing
+// the whole modal.
+
+let activeCancel: (() => void) | null = null;
+
+/**
+ * Registers the currently-editing `InlineEdit`'s cancel callback so the
+ * enclosing modal's Escape handler can yield to it. Call with `null` when
+ * editing stops for any reason (save, the ✗ button, unmount) so a stale
+ * callback never lingers.
+ *
+ * @category Consumer Services
+ * @internal
+ */
+export function setActiveInlineEditCancel(cancel: (() => void) | null): void {
+  activeCancel = cancel;
+}
+
+/**
+ * If an `InlineEdit` is mid-edit, cancels it and returns `true` (the
+ * caller's Escape handler should stop there, not close the modal). Returns
+ * `false` when nothing is being edited.
+ *
+ * @category Consumer Services
+ * @internal
+ */
+export function yieldEscapeToInlineEdit(): boolean {
+  if (!activeCancel) return false;
+  const cancel = activeCancel;
+  activeCancel = null;
+  cancel();
+  return true;
+}

package/src/input-classes.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from "vitest";
+import { inputClass } from "./input-classes";
+
+describe("inputClass", () => {
+  it("defaults to silo-input", () => {
+    expect(inputClass()).toBe("silo-input");
+    expect(inputClass(false)).toBe("silo-input");
+  });
+
+  it("adds silo-input-block when block is true", () => {
+    expect(inputClass(true)).toBe("silo-input silo-input-block");
+  });
+});

package/src/input-classes.ts

@@ -0,0 +1,9 @@
+/**
+ * Class-string mapping for {@link Input} — pinned by unit tests so a rename
+ * of the host contract classes fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export function inputClass(block = false): string {
+  return block ? "silo-input silo-input-block" : "silo-input";
+}

package/src/list-classes.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { listRowDataSelected, listRowNameTruncate } from "./list-classes";
+
+describe("listRowDataSelected", () => {
+  it("sets data-selected=true when selected", () => {
+    expect(listRowDataSelected(true)).toBe("true");
+  });
+
+  it("omits the attribute when not selected", () => {
+    expect(listRowDataSelected(false)).toBeUndefined();
+  });
+});
+
+describe("listRowNameTruncate", () => {
+  it("defaults to end truncation (no data attribute)", () => {
+    expect(listRowNameTruncate()).toBeUndefined();
+    expect(listRowNameTruncate("end")).toBeUndefined();
+  });
+
+  it("sets data-truncate=start for front truncation", () => {
+    expect(listRowNameTruncate("start")).toBe("start");
+  });
+});

package/src/list-classes.ts

@@ -0,0 +1,26 @@
+/**
+ * Class-string / data-attribute mapping for {@link ListRow} — pinned by unit
+ * tests so a rename of the host contract fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export type ListRowTruncate = "end" | "start";
+
+/**
+ * @internal
+ */
+export function listRowDataSelected(selected: boolean): "true" | undefined {
+  return selected ? "true" : undefined;
+}
+
+/**
+ * Front-truncation is expressed as `data-truncate="start"` on
+ * `.silo-list-row-name`; end-truncation is the CSS default (no attribute).
+ *
+ * @internal
+ */
+export function listRowNameTruncate(
+  truncate: ListRowTruncate = "end",
+): "start" | undefined {
+  return truncate === "start" ? "start" : undefined;
+}

package/src/radio-card-classes.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from "vitest";
+import { radioCardDataSelected } from "./radio-card-classes";
+
+describe("radioCardDataSelected", () => {
+  it("sets data-selected=true when selected", () => {
+    expect(radioCardDataSelected(true)).toBe("true");
+  });
+
+  it("omits the attribute when not selected", () => {
+    expect(radioCardDataSelected(false)).toBeUndefined();
+  });
+});

package/src/radio-card-classes.ts

@@ -0,0 +1,9 @@
+/**
+ * `data-selected` value for {@link RadioCard} — pinned by unit tests so a
+ * rename of the host contract attribute fails CI (RFC 0016).
+ *
+ * @internal
+ */
+export function radioCardDataSelected(selected: boolean): "true" | undefined {
+  return selected ? "true" : undefined;
+}

package/src/search-input-classes.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from "vitest";
+import { searchInputClass } from "./search-input-classes";
+
+describe("searchInputClass", () => {
+  it("is silo-search-input when empty", () => {
+    expect(searchInputClass(false)).toBe("silo-search-input");
+  });
+
+  it("adds has-value when there is a value", () => {
+    expect(searchInputClass(true)).toBe("silo-search-input has-value");
+  });
+});