@silo-code/sdk 0.28.1 → 0.29.0

package/src/List.tsx

@@ -0,0 +1,240 @@
+import {
+  Children,
+  cloneElement,
+  createContext,
+  isValidElement,
+  useContext,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useFocusGroup, type FocusGroupItemProps } from "./use-focus-group";
+import {
+  listRowDataSelected,
+  listRowNameTruncate,
+  type ListRowTruncate,
+} from "./list-classes";
+
+export type { ListRowTruncate };
+
+interface ListRowInternalProps {
+  /** Injected by {@link List} — index in the focus group. */
+  __listIndex?: number;
+  /** Injected by {@link List} — focus-group item props to spread. */
+  __focusProps?: FocusGroupItemProps;
+}
+
+interface ListContextValue {
+  onActivate?: (index: number) => void;
+}
+
+const ListContext = createContext<ListContextValue | null>(null);
+
+/**
+ * A full-width listbox of selectable rows. One tab stop; ↑/↓ move the focus
+ * ring, Space/Enter select. Pair with {@link ListRow} children.
+ *
+ * Styled purely via the host-provided `.silo-list` class — no stylesheet
+ * import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <List aria-label="Workspace folders">
+ *   <ListRow
+ *     selected={folder.primary}
+ *     leading={<FolderIcon />}
+ *     trailing={<Badge tone="accent">primary</Badge>}
+ *     onSelect={() => choose(folder)}
+ *   >
+ *     {folder.path}
+ *   </ListRow>
+ * </List>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function List({
+  "aria-label": ariaLabel,
+  onActivate,
+  children,
+}: {
+  /** Required — it's a listbox. */
+  "aria-label": string;
+  /** Enter / double-click on a row. */
+  onActivate?: (index: number) => void;
+  children?: ReactNode;
+}) {
+  const rows = Children.toArray(children).filter(
+    isValidElement,
+  ) as ReactElement<ListRowProps & ListRowInternalProps>[];
+  const selectedIndex = rows.findIndex((row) => row.props.selected);
+  const group = useFocusGroup({
+    count: rows.length,
+    start: selectedIndex >= 0 ? selectedIndex : 0,
+    // Space/Enter both select (RFC 0016). Enter-only activation is layered
+    // on in ListRow's own keydown after the focus-group handler runs.
+    onActivate: (index) => {
+      rows[index]?.props.onSelect?.();
+    },
+  });
+
+  return (
+    <ListContext.Provider value={{ onActivate }}>
+      <div
+        role="listbox"
+        aria-label={ariaLabel}
+        className="silo-list"
+        {...group.containerProps}
+      >
+        {rows.map((row, index) =>
+          cloneElement(row, {
+            key: row.key ?? index,
+            __listIndex: index,
+            __focusProps: group.getItemProps(index),
+          }),
+        )}
+      </div>
+    </ListContext.Provider>
+  );
+}
+
+/**
+ * One row inside a {@link List}. Stretches full-width; long text truncates
+ * (use `truncate="start"` for paths). `trailing` content never shrinks.
+ *
+ * @example
+ * ```tsx
+ * <ListRow
+ *   selected={folder.primary}
+ *   leading={<FolderIcon />}
+ *   trailing={<Badge tone="accent">primary</Badge>}
+ *   truncate="start"
+ *   onSelect={() => choose(folder)}
+ * >
+ *   {folder.path}
+ * </ListRow>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ListRowProps {
+  selected?: boolean;
+  /** Icon slot (dimmed, fixed). */
+  leading?: ReactNode;
+  /** Badge(s) and/or `IconButton size="sm"`(s). */
+  trailing?: ReactNode;
+  /** Default `"end"`. Use `"start"` for paths. */
+  truncate?: ListRowTruncate;
+  /** Click / Space select. */
+  onSelect?: () => void;
+  /** Enter / double-click. */
+  onActivate?: () => void;
+  children?: ReactNode;
+}
+
+/**
+ * @category Consumer Services
+ * @public
+ */
+export function ListRow(props: ListRowProps) {
+  // List injects focus-group props via cloneElement; keep them off the public
+  // signature so they stay out of the generated API reference.
+  const {
+    selected = false,
+    leading,
+    trailing,
+    truncate = "end",
+    onSelect,
+    onActivate,
+    children,
+    __listIndex,
+    __focusProps,
+  } = props as ListRowProps & ListRowInternalProps;
+  const list = useContext(ListContext);
+  const dataSelected = listRowDataSelected(selected);
+  const truncateAttr = listRowNameTruncate(truncate);
+
+  const focusProps = __focusProps;
+  const {
+    ref,
+    onKeyDown: focusKeyDown,
+    onFocus,
+    onPointerDown,
+    tabIndex,
+    "data-focus-item": dataFocusItem,
+    "data-focus-visible": dataFocusVisible,
+  } = focusProps ?? {
+    ref: undefined as Ref<HTMLElement> | undefined,
+    onKeyDown: undefined,
+    onFocus: undefined,
+    onPointerDown: undefined,
+    tabIndex: -1 as number,
+    "data-focus-item": "" as const,
+    "data-focus-visible": undefined as "" | undefined,
+  };
+
+  function fireActivate() {
+    onActivate?.();
+    if (__listIndex != null) list?.onActivate?.(__listIndex);
+  }
+
+  const rowProps: HTMLAttributes<HTMLDivElement> & {
+    ref?: Ref<HTMLDivElement>;
+    "data-focus-item"?: "";
+    "data-focus-visible"?: "";
+    "data-selected"?: "true";
+  } = {
+    role: "option",
+    "aria-selected": selected,
+    className: "silo-list-row",
+    tabIndex,
+    ref: ref as Ref<HTMLDivElement> | undefined,
+    onFocus,
+    onPointerDown,
+    "data-focus-item": dataFocusItem,
+    ...(dataFocusVisible != null
+      ? { "data-focus-visible": dataFocusVisible }
+      : {}),
+    ...(dataSelected != null ? { "data-selected": dataSelected } : {}),
+    onClick: () => {
+      onSelect?.();
+    },
+    onDoubleClick: () => {
+      fireActivate();
+    },
+    onKeyDown: (e: KeyboardEvent<HTMLDivElement>) => {
+      focusKeyDown?.(e);
+      if (e.key === "Enter") fireActivate();
+    },
+  };
+
+  return (
+    <div {...rowProps}>
+      {leading != null && (
+        <span className="silo-list-row-leading">{leading}</span>
+      )}
+      <span
+        className="silo-list-row-name"
+        {...(truncateAttr != null ? { "data-truncate": truncateAttr } : {})}
+      >
+        {children}
+      </span>
+      {trailing != null && (
+        <span
+          className="silo-list-row-trailing"
+          onClick={(e: MouseEvent) => {
+            // Trailing IconButtons own their clicks — don't select the row.
+            e.stopPropagation();
+          }}
+        >
+          {trailing}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/ModalActions.tsx

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+
+/**
+ * The right-aligned footer row for a modal's action buttons — a thin
+ * `.silo-modal-actions` wrapper so every modal's footer lines up without each
+ * caller re-specifying the flex row. Optional `start` slot pins meta text or
+ * a secondary action on the left.
+ *
+ * Styled purely via host-provided `.silo-modal-actions*` classes — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <ModalActions>
+ *   <Button onClick={close}>Cancel</Button>
+ *   <Button variant="primary" onClick={save}>Create</Button>
+ * </ModalActions>
+ *
+ * <ModalActions start="6 sessions · 6 procs">
+ *   <Button>Go to Terminal</Button>
+ *   <Button variant="danger">End Task</Button>
+ * </ModalActions>
+ *
+ * <ModalActions
+ *   start={<Button size="sm" onClick={create}>+ Create branch</Button>}
+ * >
+ *   <Button onClick={fetch}>Fetch</Button>
+ * </ModalActions>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function ModalActions({
+  start,
+  children,
+}: {
+  /**
+   * Optional left-pinned slot for meta text or a secondary action.
+   */
+  start?: ReactNode;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="silo-modal-actions">
+      {start != null && start !== false && (
+        <div className="silo-modal-actions-start">{start}</div>
+      )}
+      {children}
+    </div>
+  );
+}

package/src/RadioGroup.tsx

@@ -0,0 +1,101 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { radioCardDataSelected } from "./radio-card-classes";
+
+const RadioGroupContext = createContext<{
+  value: string;
+  onChange: (value: string) => void;
+} | null>(null);
+
+/**
+ * Stacked option cards — each a full-width click target with a radio dot, a
+ * bold title, and a dim description. Wrap {@link RadioCard} children; the
+ * selected card gets an accent border and a faint accent tint. Native tab
+ * stops per card — no arrow-key roving.
+ *
+ * Styled purely via host-provided `.silo-radio-card*` classes — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup value={mode} onChange={setMode}>
+ *   <RadioCard
+ *     value="clear"
+ *     title="Clear the finished indicator"
+ *     description="Viewing the terminal acknowledges the run — the green check disappears."
+ *   />
+ *   <RadioCard
+ *     value="keep"
+ *     title="Keep it until the next run"
+ *     description="Viewing changes nothing."
+ *   />
+ * </RadioGroup>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function RadioGroup({
+  value,
+  onChange,
+  children,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  children?: ReactNode;
+}) {
+  return (
+    <RadioGroupContext.Provider value={{ value, onChange }}>
+      {children}
+    </RadioGroupContext.Provider>
+  );
+}
+
+/**
+ * One option inside a {@link RadioGroup}. The whole card is the click target.
+ *
+ * @example
+ * ```tsx
+ * <RadioCard
+ *   value="clear"
+ *   title="Clear the finished indicator"
+ *   description="Viewing the terminal acknowledges the run."
+ * />
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function RadioCard({
+  value,
+  title,
+  description,
+}: {
+  value: string;
+  title: string;
+  description?: string;
+}) {
+  const group = useContext(RadioGroupContext);
+  if (!group) {
+    throw new Error("RadioCard must be used inside a RadioGroup");
+  }
+  const selected = group.value === value;
+  const dataSelected = radioCardDataSelected(selected);
+  return (
+    <button
+      type="button"
+      role="radio"
+      aria-checked={selected}
+      className="silo-radio-card"
+      {...(dataSelected != null ? { "data-selected": dataSelected } : {})}
+      onClick={() => group.onChange(value)}
+    >
+      <span className="silo-radio-card-dot" aria-hidden="true" />
+      <span>
+        <span className="silo-radio-card-title">{title}</span>
+        {description != null && (
+          <span className="silo-radio-card-desc">{description}</span>
+        )}
+      </span>
+    </button>
+  );
+}

package/src/SearchInput.tsx

@@ -0,0 +1,98 @@
+import type { ReactNode } from "react";
+import { searchInputClass } from "./search-input-classes";
+
+function SearchIcon() {
+  return (
+    <svg
+      className="silo-search-input-icon"
+      width="13"
+      height="13"
+      viewBox="0 0 16 16"
+      fill="none"
+      aria-hidden="true"
+    >
+      <circle cx="7" cy="7" r="5.2" stroke="currentColor" strokeWidth="1.4" />
+      <path
+        d="M11 11l3.5 3.5"
+        stroke="currentColor"
+        strokeWidth="1.4"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+function ClearIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" aria-hidden="true">
+      <path
+        d="M4 4l8 8M12 4l-8 8"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+/**
+ * The filter-as-you-type field: leading search icon, and a clear ✕ that
+ * appears once there's a value (and stays a real tab stop). Pair with
+ * {@link List} for the standard picker pattern.
+ *
+ * Styled purely via host-provided `.silo-search-input*` classes — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <SearchInput
+ *   value={query}
+ *   onValueChange={setQuery}
+ *   placeholder="Filter branches…"
+ * />
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function SearchInput({
+  value,
+  onValueChange,
+  placeholder,
+  autoFocus,
+  onClear,
+}: {
+  value: string;
+  onValueChange: (value: string) => void;
+  placeholder?: string;
+  autoFocus?: boolean;
+  /** Extra hook when ✕ clears the field. */
+  onClear?: () => void;
+}): ReactNode {
+  const hasValue = value.length > 0;
+  return (
+    <div className={searchInputClass(hasValue)}>
+      <SearchIcon />
+      <input
+        type="text"
+        value={value}
+        placeholder={placeholder}
+        autoFocus={autoFocus}
+        onChange={(e) => onValueChange(e.target.value)}
+        autoComplete="off"
+      />
+      <button
+        type="button"
+        className="silo-search-input-clear"
+        aria-label="Clear"
+        tabIndex={hasValue ? 0 : -1}
+        onClick={() => {
+          onValueChange("");
+          onClear?.();
+        }}
+      >
+        <ClearIcon />
+      </button>
+    </div>
+  );
+}

package/src/Section.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+
+/**
+ * A labeled group — the uppercase `NAME` / `FOLDERS` / `FORMATTING` headers
+ * seen throughout Silo's modals and settings pages.
+ *
+ * Styled purely via host-provided `.silo-section*` classes — no stylesheet
+ * import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <Section label="Formatting">
+ *   <SettingRow
+ *     label="Format on save"
+ *     hint="Run Format Document before writing to disk."
+ *   >
+ *     <Switch
+ *       checked={formatOnSave}
+ *       onChange={setFormatOnSave}
+ *       aria-label="Format on save"
+ *     />
+ *   </SettingRow>
+ * </Section>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function Section({
+  label,
+  accessory,
+  children,
+}: {
+  /** Rendered uppercase, letter-spaced, chrome−1, `text-lo`. */
+  label: string;
+  /** Right-aligned — a count badge, an add affordance. */
+  accessory?: ReactNode;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="silo-section">
+      <div className="silo-section-header">
+        <span className="silo-section-label">{label}</span>
+        {accessory}
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/SegmentedTabs.tsx

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import { segmentedTabDataActive } from "./segmented-tabs-classes";
+
+/**
+ * One segment in a {@link SegmentedTabs} strip.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface SegmentedTabItem<T extends string = string> {
+  id: T;
+  label: string;
+  icon?: ReactNode;
+}
+
+/**
+ * A pill riding in a recessed well — self-contained, no relationship to
+ * content below it, so it can sit in a header row next to other controls.
+ * Native tab stops per segment; no arrow-key roving.
+ *
+ * Styled purely via host-provided `.silo-segmented*` classes — no stylesheet
+ * import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedTabs
+ *   tabs={[
+ *     { id: "browse", label: "Browse" },
+ *     { id: "installed", label: "Installed" },
+ *   ]}
+ *   active={tab}
+ *   onSelect={setTab}
+ * />
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function SegmentedTabs<T extends string>({
+  tabs,
+  active,
+  onSelect,
+}: {
+  tabs: SegmentedTabItem<T>[];
+  active: T;
+  onSelect: (id: T) => void;
+}) {
+  return (
+    <div className="silo-segmented" role="tablist">
+      {tabs.map((tab) => {
+        const isActive = tab.id === active;
+        const dataActive = segmentedTabDataActive(isActive);
+        return (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={isActive}
+            className="silo-segmented-tab"
+            {...(dataActive != null ? { "data-active": dataActive } : {})}
+            onClick={() => onSelect(tab.id)}
+          >
+            {tab.icon}
+            {tab.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/Select.tsx

@@ -0,0 +1,36 @@
+import type { SelectHTMLAttributes, ReactNode } from "react";
+
+/**
+ * A native `<select>` wearing the {@link Input} treatment — keep it for short
+ * enumerable values ("Block / Bar / Underline").
+ *
+ * Styled purely via the host-provided `.silo-select` class — no stylesheet
+ * import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <Select value={cursorStyle} onChange={(e) => setCursorStyle(e.target.value)}>
+ *   <option value="block">Block</option>
+ *   <option value="bar">Bar</option>
+ * </Select>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function Select({
+  className,
+  children,
+  ...rest
+}: {
+  children?: ReactNode;
+} & Omit<SelectHTMLAttributes<HTMLSelectElement>, "children">) {
+  return (
+    <select
+      className={className ? `silo-select ${className}` : "silo-select"}
+      {...rest}
+    >
+      {children}
+    </select>
+  );
+}

package/src/SettingRow.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from "react";
+
+/**
+ * The label + hint + control row every settings surface uses: title and dim
+ * description on the left, the control pinned right. Rows in a group are
+ * separated by hairline dividers.
+ *
+ * Styled purely via host-provided `.silo-setting-row*` classes — no
+ * stylesheet import is needed in the extension.
+ *
+ * @example
+ * ```tsx
+ * <SettingRow
+ *   label="Format on save"
+ *   hint="Run Format Document before writing to disk."
+ * >
+ *   <Switch
+ *     checked={formatOnSave}
+ *     onChange={setFormatOnSave}
+ *     aria-label="Format on save"
+ *   />
+ * </SettingRow>
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ */
+export function SettingRow({
+  label,
+  hint,
+  children,
+}: {
+  label: string;
+  hint?: string;
+  /** The control — `Switch`, `Select`, `Input`, etc. */
+  children?: ReactNode;
+}) {
+  return (
+    <div className="silo-setting-row">
+      <div className="silo-setting-row-text">
+        <div className="silo-setting-row-label">{label}</div>
+        {hint != null && <div className="silo-setting-row-hint">{hint}</div>}
+      </div>
+      <div className="silo-setting-row-control">{children}</div>
+    </div>
+  );
+}