@nativedesktop/ui 0.3.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nativedesktop/ui",
+  "version": "0.3.1",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
+  "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FormalSnake/NativeDesktop.git",
+    "directory": "packages/ui"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@nativedesktop/react": "^0.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "react": "19.2.7"
+  }
+}

package/src/Accordion.tsx

@@ -0,0 +1,68 @@
+/** @jsxImportSource @nativedesktop/react */
+// The pragma is load-bearing: see packages/panes/src/PaneTree.tsx for why.
+
+import type { ReactNode } from "react";
+import { accordionDragPayload, nextExpandedIds, parseAccordionDrag, reorderedIds } from "./accordion.ts";
+
+export interface AccordionItem {
+  id: string;
+  label: string;
+  content: ReactNode;
+}
+
+export interface AccordionProps {
+  items: AccordionItem[];
+  expandedIds: string[];
+  onExpandedChange: (ids: string[]) => void;
+  /** Default false: opening one section closes the others. */
+  allowMultiple?: boolean;
+  /** Supply it and the sections become reorderable by dragging one header
+   * onto another: the dragged section takes the target's place. It is handed
+   * the full id order, in the same shape `expandedIds` uses, so the app keeps
+   * owning `items`. Omit it and no header is a drag source. */
+  onReorder?: (ids: string[]) => void;
+  testID?: string;
+}
+
+export function Accordion(props: AccordionProps): ReactNode {
+  const { items, expandedIds, onExpandedChange, allowMultiple = false, onReorder, testID } = props;
+
+  // The <expander> IS the section header, so it is both the drag source and
+  // the drop target: there is no separate handle widget to attach either to.
+  function reorderProps(id: string): {
+    draggable: true;
+    dragPayload: string;
+    dropTarget: true;
+    onDropped: (e: { text: string }) => void;
+  } {
+    return {
+      draggable: true,
+      dragPayload: accordionDragPayload(id),
+      dropTarget: true,
+      onDropped: (e) => {
+        const moved = parseAccordionDrag(e.text);
+        if (moved === undefined) return;
+        const order = items.map((item) => item.id);
+        const next = reorderedIds(order, moved, id);
+        if (next !== order) onReorder?.(next);
+      },
+    };
+  }
+
+  return (
+    <box orientation="vertical" testID={testID}>
+      {items.map((item) => (
+        <expander
+          key={item.id}
+          label={item.label}
+          expanded={expandedIds.includes(item.id)}
+          testID={testID ? `${testID}-item-${item.id}` : undefined}
+          onToggled={(e) => onExpandedChange(nextExpandedIds(expandedIds, item.id, e.checked, allowMultiple))}
+          {...(onReorder ? reorderProps(item.id) : {})}
+        >
+          {item.content}
+        </expander>
+      ))}
+    </box>
+  );
+}

package/src/ButtonGroup.tsx

@@ -0,0 +1,36 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+
+export interface ButtonGroupItem {
+  id: string;
+  label: string;
+  iconName?: string;
+}
+
+export interface ButtonGroupProps {
+  items: ButtonGroupItem[];
+  onPress: (id: string) => void;
+  /** Toggle mode: the matching button renders prominent. Omit for a plain
+   * action group with no selection state. */
+  selectedId?: string;
+  testID?: string;
+}
+
+export function ButtonGroup(props: ButtonGroupProps): ReactNode {
+  const { items, onPress, selectedId, testID } = props;
+  return (
+    <box orientation="horizontal" cssClasses={["linked"]} testID={testID}>
+      {items.map((item) => (
+        <button
+          key={item.id}
+          label={item.label}
+          iconName={item.iconName}
+          prominent={item.id === selectedId}
+          onClick={() => onPress(item.id)}
+          testID={testID ? `${testID}-${item.id}` : undefined}
+        />
+      ))}
+    </box>
+  );
+}

package/src/DescriptionList.tsx

@@ -0,0 +1,31 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+
+export interface DescriptionListItem {
+  label: string;
+  value: string;
+}
+
+export interface DescriptionListProps {
+  items: DescriptionListItem[];
+  title?: string;
+  testID?: string;
+}
+
+export function DescriptionList(props: DescriptionListProps): ReactNode {
+  const { items, title, testID } = props;
+  return (
+    <settingsgroup title={title} testID={testID}>
+      {items.map((item, i) => (
+        <row
+          key={`${item.label}-${i}`}
+          title={item.label}
+          subtitle={item.value}
+          cssClasses={["property"]}
+          testID={testID ? `${testID}-row-${i}` : undefined}
+        />
+      ))}
+    </settingsgroup>
+  );
+}

package/src/Form.tsx

@@ -0,0 +1,38 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+
+export interface FormProps {
+  title?: string;
+  description?: string;
+  children: ReactNode;
+  testID?: string;
+}
+
+export function Form(props: FormProps): ReactNode {
+  const { title, description, children, testID } = props;
+  return (
+    <settingsgroup title={title} description={description} testID={testID}>
+      {children}
+    </settingsgroup>
+  );
+}
+
+export interface FormFieldProps {
+  label: string;
+  error?: string;
+  hint?: string;
+  children: ReactNode;
+  testID?: string;
+}
+
+/** The control renders into the row's default (suffix) slot, matching the
+ * label-left/control-right shape every other settings row already uses. */
+export function FormField(props: FormFieldProps): ReactNode {
+  const { label, error, hint, children, testID } = props;
+  return (
+    <row title={label} subtitle={error ?? hint} cssClasses={error ? ["error"] : undefined} testID={testID}>
+      {children}
+    </row>
+  );
+}

package/src/HoverCard.tsx

@@ -0,0 +1,46 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import { useMountEffect, useRef, useState } from "@nativedesktop/react";
+
+export interface HoverCardProps {
+  content: ReactNode;
+  children: ReactNode;
+  /** Ms of continuous hover before the card opens. */
+  openDelay?: number;
+  /** Ms after the pointer leaves before the card closes. */
+  closeDelay?: number;
+  testID?: string;
+}
+
+/** The anchor's `hoverChanged` is the only signal available (no separate
+ * enter/leave events), so open/close both key off that one boolean, each on
+ * its own timer so a quick pass-through never flashes the card open. */
+export function HoverCard(props: HoverCardProps): ReactNode {
+  const { content, children, openDelay = 400, closeDelay = 200, testID } = props;
+  const [open, setOpen] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  function clearPending(): void {
+    if (timerRef.current !== undefined) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+    }
+  }
+
+  useMountEffect(() => clearPending);
+
+  function handleHoverChanged(hovering: boolean): void {
+    clearPending();
+    timerRef.current = setTimeout(() => setOpen(hovering), hovering ? openDelay : closeDelay);
+  }
+
+  return (
+    <box orientation="vertical" onHoverChanged={(e) => handleHoverChanged(e.checked)} testID={testID}>
+      {children}
+      <popover open={open} onClosed={() => setOpen(false)} testID={testID ? `${testID}-popover` : undefined}>
+        {content}
+      </popover>
+    </box>
+  );
+}

package/src/OtpInput.tsx

@@ -0,0 +1,46 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import type { NdNodeRef } from "@nativedesktop/react";
+import { Spacing, sendCommand, useRef } from "@nativedesktop/react";
+import { otpCellChanged, otpChars } from "./otp.ts";
+
+export interface OtpInputProps {
+  length?: number;
+  value: string;
+  onChange: (value: string) => void;
+  onComplete?: (value: string) => void;
+  testID?: string;
+}
+
+/** N single-character <textinput>s. otp.ts computes the cell focus should move
+ * to, and the `focus` command moves the caret there, so typing, backspace and
+ * paste all advance without the user clicking between boxes. */
+export function OtpInput(props: OtpInputProps): ReactNode {
+  const { length = 6, value, onChange, onComplete, testID } = props;
+  const chars = otpChars(value, length);
+  const cells = useRef<(NdNodeRef<"textinput"> | null)[]>([]);
+
+  return (
+    <box orientation="horizontal" spacing={Spacing.xs} testID={testID}>
+      {chars.map((ch, i) => (
+        <textinput
+          key={i}
+          ref={(node) => { cells.current[i] = node; }}
+          text={ch}
+          cssClasses={["numeric"]}
+          testID={testID ? `${testID}-cell-${i}` : undefined}
+          onChanged={(e) => {
+            const result = otpCellChanged(value, length, i, e.text);
+            onChange(result.value);
+            if (result.activeIndex !== i) {
+              const next = cells.current[result.activeIndex];
+              if (next) sendCommand(next, "focus");
+            }
+            if (onComplete && result.value.length === length) onComplete(result.value);
+          }}
+        />
+      ))}
+    </box>
+  );
+}

package/src/Pagination.tsx

@@ -0,0 +1,61 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import { Spacing } from "@nativedesktop/react";
+import { computePaginationRange } from "./pagination.ts";
+
+export interface PaginationProps {
+  page: number;
+  pageCount: number;
+  onPageChange: (page: number) => void;
+  siblingCount?: number;
+  testID?: string;
+}
+
+export function Pagination(props: PaginationProps): ReactNode {
+  const { page, pageCount, onPageChange, siblingCount = 1, testID } = props;
+  if (pageCount <= 0) return null;
+  const items = computePaginationRange(page, pageCount, siblingCount);
+
+  return (
+    <box orientation="horizontal" spacing={Spacing.xs} cssClasses={["linked"]} testID={testID}>
+      <button
+        label="First"
+        onClick={() => onPageChange(1)}
+        testID={testID ? `${testID}-first` : undefined}
+        cssClasses={page === 1 ? ["flat"] : undefined}
+      />
+      <button
+        label="Prev"
+        onClick={() => onPageChange(Math.max(page - 1, 1))}
+        testID={testID ? `${testID}-prev` : undefined}
+        cssClasses={page === 1 ? ["flat"] : undefined}
+      />
+      {items.map((item, i) =>
+        item === "dots-start" || item === "dots-end" ? (
+          <label key={item} text="…" style={{ valign: "center" }} />
+        ) : (
+          <button
+            key={item}
+            label={String(item)}
+            prominent={item === page}
+            onClick={() => onPageChange(item)}
+            testID={testID ? `${testID}-page-${item}` : undefined}
+          />
+        ),
+      )}
+      <button
+        label="Next"
+        onClick={() => onPageChange(Math.min(page + 1, pageCount))}
+        testID={testID ? `${testID}-next` : undefined}
+        cssClasses={page === pageCount ? ["flat"] : undefined}
+      />
+      <button
+        label="Last"
+        onClick={() => onPageChange(pageCount)}
+        testID={testID ? `${testID}-last` : undefined}
+        cssClasses={page === pageCount ? ["flat"] : undefined}
+      />
+    </box>
+  );
+}

package/src/SearchableList.tsx

@@ -0,0 +1,46 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import { Spacing, useMemo, useState } from "@nativedesktop/react";
+import { filterItems } from "./searchable-list.ts";
+import type { SearchableListFilter, SearchableListItem } from "./searchable-list.ts";
+
+export interface SearchableListProps {
+  items: SearchableListItem[];
+  onActivate: (item: SearchableListItem) => void;
+  filter?: SearchableListFilter;
+  placeholder?: string;
+  emptyIconName?: string;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  testID?: string;
+}
+
+export function SearchableList(props: SearchableListProps): ReactNode {
+  const { items, onActivate, filter, placeholder, emptyIconName, emptyTitle, emptyDescription, testID } = props;
+  const [query, setQuery] = useState("");
+  const filtered = useMemo(() => filterItems(items, query, filter), [items, query, filter]);
+
+  return (
+    <box orientation="vertical" spacing={Spacing.sm} testID={testID}>
+      <searchinput
+        text={query}
+        placeholder={placeholder}
+        onChanged={(e) => setQuery(e.text)}
+        testID={testID ? `${testID}-search` : undefined}
+      />
+      <listview
+        items={filtered.map((item) => item.label)}
+        emptyIconName={emptyIconName}
+        emptyTitle={emptyTitle}
+        emptyDescription={emptyDescription}
+        style={{ vexpand: true }}
+        onRowActivated={(e) => {
+          const item = filtered[e.index];
+          if (item) onActivate(item);
+        }}
+        testID={testID ? `${testID}-list` : undefined}
+      />
+    </box>
+  );
+}

package/src/StatusBar.tsx

@@ -0,0 +1,28 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import { Spacing } from "@nativedesktop/react";
+
+export interface StatusBarProps {
+  left?: ReactNode;
+  center?: ReactNode;
+  right?: ReactNode;
+  testID?: string;
+}
+
+export function StatusBar(props: StatusBarProps): ReactNode {
+  const { left, center, right, testID } = props;
+  return (
+    <box orientation="horizontal" spacing={Spacing.sm} cssClasses={["toolbar"]} testID={testID}>
+      <box orientation="horizontal" spacing={Spacing.xs} style={{ halign: "start" }}>
+        {left}
+      </box>
+      <box orientation="horizontal" spacing={Spacing.xs} style={{ hexpand: true, halign: "center" }}>
+        {center}
+      </box>
+      <box orientation="horizontal" spacing={Spacing.xs} style={{ halign: "end" }}>
+        {right}
+      </box>
+    </box>
+  );
+}

package/src/Stepper.tsx

@@ -0,0 +1,60 @@
+/** @jsxImportSource @nativedesktop/react */
+
+import type { ReactNode } from "react";
+import { Spacing } from "@nativedesktop/react";
+import { stepState } from "./stepper.ts";
+
+export interface StepperStep {
+  id: string;
+  title: string;
+  description?: string;
+}
+
+export interface StepperProps {
+  steps: StepperStep[];
+  activeIndex: number;
+  onStepClick?: (index: number) => void;
+  testID?: string;
+}
+
+export function Stepper(props: StepperProps): ReactNode {
+  const { steps, activeIndex, onStepClick, testID } = props;
+  const nodes: ReactNode[] = [];
+
+  steps.forEach((step, i) => {
+    const state = stepState(i, activeIndex);
+    if (i > 0) {
+      nodes.push(
+        <separator
+          key={`sep-${step.id}`}
+          orientation="horizontal"
+          style={{ hexpand: true, valign: "center" }}
+          cssClasses={state === "pending" ? ["dimmed"] : ["accent"]}
+        />,
+      );
+    }
+    nodes.push(
+      <box
+        key={step.id}
+        orientation="vertical"
+        spacing={Spacing.xs}
+        testID={testID ? `${testID}-step-${step.id}` : undefined}
+      >
+        <button
+          label={state === "completed" ? undefined : String(i + 1)}
+          iconName={state === "completed" ? "emblem-ok" : undefined}
+          cssClasses={["circular", state === "active" ? "suggested-action" : state === "completed" ? "success" : "flat"]}
+          onClick={onStepClick ? () => onStepClick(i) : undefined}
+        />
+        <label text={step.title} cssClasses={state === "pending" ? ["dimmed", "caption"] : ["caption-heading"]} />
+        {step.description && <label text={step.description} cssClasses={["dimmed", "caption"]} />}
+      </box>,
+    );
+  });
+
+  return (
+    <box orientation="horizontal" spacing={Spacing.sm} testID={testID}>
+      {nodes}
+    </box>
+  );
+}

package/src/accordion.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { accordionDragPayload, nextExpandedIds, parseAccordionDrag, reorderedIds } from "./accordion.ts";
+
+describe("nextExpandedIds", () => {
+  test("single mode: opening one closes the others", () => {
+    expect(nextExpandedIds(["a"], "b", true, false)).toEqual(["b"]);
+    expect(nextExpandedIds([], "a", true, false)).toEqual(["a"]);
+  });
+
+  test("single mode: closing the open item empties the list", () => {
+    expect(nextExpandedIds(["a"], "a", false, false)).toEqual([]);
+  });
+
+  test("single mode: redundant toggles are a same-reference no-op", () => {
+    const open = ["a"];
+    expect(nextExpandedIds(open, "a", true, false)).toBe(open);
+    const closed: string[] = [];
+    expect(nextExpandedIds(closed, "a", false, false)).toBe(closed);
+  });
+
+  test("multiple mode: several items can stay open at once", () => {
+    expect(nextExpandedIds(["a"], "b", true, true)).toEqual(["a", "b"]);
+    expect(nextExpandedIds(["a", "b"], "a", false, true)).toEqual(["b"]);
+  });
+
+  test("multiple mode: redundant toggles are a same-reference no-op", () => {
+    const ids = ["a", "b"];
+    expect(nextExpandedIds(ids, "a", true, true)).toBe(ids);
+    expect(nextExpandedIds(ids, "z", false, true)).toBe(ids);
+  });
+});
+
+describe("accordion reordering", () => {
+  const ids = ["a", "b", "c"];
+
+  test("round-trip payloads, and anything foreign is not a section drag", () => {
+    expect(parseAccordionDrag(accordionDragPayload("a"))).toBe("a");
+    for (const foreign of ["", "a", "nd-accordion:item:", "nd-dock:tab:a"]) {
+      expect(parseAccordionDrag(foreign)).toBeUndefined();
+    }
+  });
+
+  test("the dragged section takes the target's place", () => {
+    expect(reorderedIds(ids, "c", "a")).toEqual(["c", "a", "b"]);
+    expect(reorderedIds(ids, "a", "c")).toEqual(["b", "c", "a"]);
+    expect(reorderedIds(ids, "b", "c")).toEqual(["a", "c", "b"]);
+  });
+
+  test("a drop that changes nothing is the same reference", () => {
+    expect(reorderedIds(ids, "b", "b")).toBe(ids);
+    expect(reorderedIds(ids, "gone", "a")).toBe(ids);
+    expect(reorderedIds(ids, "a", "gone")).toBe(ids);
+  });
+});

package/src/accordion.ts

@@ -0,0 +1,51 @@
+// Pure expansion-state transition for Accordion. Each <expander> reports its
+// own `checked` on toggle; this decides what the FULL expandedIds list
+// becomes, including closing siblings in single mode. Returns the same
+// reference when the toggle is a no-op (e.g. an echo of the already-applied
+// state), matching the panes model's echo-guard convention.
+
+export function nextExpandedIds(
+  expandedIds: readonly string[],
+  id: string,
+  checked: boolean,
+  allowMultiple: boolean,
+): string[] {
+  if (allowMultiple) {
+    const has = expandedIds.includes(id);
+    if (checked === has) return expandedIds as string[];
+    return checked ? [...expandedIds, id] : expandedIds.filter((x) => x !== id);
+  }
+  const isOnlyOpen = expandedIds.length === 1 && expandedIds[0] === id;
+  if (checked) return isOnlyOpen ? (expandedIds as string[]) : [id];
+  return isOnlyOpen ? [] : (expandedIds as string[]);
+}
+
+const DRAG_PREFIX = "nd-accordion:item:";
+
+/** The `dragPayload` a reorderable section header carries. Namespaced because
+ * the drop side also receives plain text dragged in from other applications,
+ * and that must not be read as a section id. */
+export function accordionDragPayload(id: string): string {
+  return `${DRAG_PREFIX}${id}`;
+}
+
+export function parseAccordionDrag(payload: string): string | undefined {
+  if (!payload.startsWith(DRAG_PREFIX)) return undefined;
+  const id = payload.slice(DRAG_PREFIX.length);
+  return id.length > 0 ? id : undefined;
+}
+
+/** Order after dropping section `movedId` on section `targetId`: the dragged
+ * section takes the target's place and the ones between it shift up. Returns
+ * the same reference when the drop changes nothing (a section dropped on
+ * itself, or an id from another accordion), so a drag that ends where it
+ * started cannot loop a render+persist cycle. */
+export function reorderedIds(ids: readonly string[], movedId: string, targetId: string): string[] {
+  const from = ids.indexOf(movedId);
+  const to = ids.indexOf(targetId);
+  if (from < 0 || to < 0 || from === to) return ids as string[];
+  const next = ids.slice();
+  next.splice(from, 1);
+  next.splice(to, 0, movedId);
+  return next;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export { accordionDragPayload, nextExpandedIds, parseAccordionDrag, reorderedIds } from "./accordion.ts";
+export { Accordion } from "./Accordion.tsx";
+export type { AccordionItem, AccordionProps } from "./Accordion.tsx";
+
+export { DescriptionList } from "./DescriptionList.tsx";
+export type { DescriptionListItem, DescriptionListProps } from "./DescriptionList.tsx";
+
+export { computePaginationRange } from "./pagination.ts";
+export type { PaginationItem } from "./pagination.ts";
+export { Pagination } from "./Pagination.tsx";
+export type { PaginationProps } from "./Pagination.tsx";
+
+export { stepState } from "./stepper.ts";
+export type { StepState } from "./stepper.ts";
+export { Stepper } from "./Stepper.tsx";
+export type { StepperProps, StepperStep } from "./Stepper.tsx";
+
+export { HoverCard } from "./HoverCard.tsx";
+export type { HoverCardProps } from "./HoverCard.tsx";
+
+export { defaultFilter, filterItems } from "./searchable-list.ts";
+export type { SearchableListFilter, SearchableListItem } from "./searchable-list.ts";
+export { SearchableList } from "./SearchableList.tsx";
+export type { SearchableListProps } from "./SearchableList.tsx";
+
+export { Form, FormField } from "./Form.tsx";
+export type { FormFieldProps, FormProps } from "./Form.tsx";
+
+export { otpCellChanged, otpChars } from "./otp.ts";
+export type { OtpEdit } from "./otp.ts";
+export { OtpInput } from "./OtpInput.tsx";
+export type { OtpInputProps } from "./OtpInput.tsx";
+
+export { ButtonGroup } from "./ButtonGroup.tsx";
+export type { ButtonGroupItem, ButtonGroupProps } from "./ButtonGroup.tsx";
+
+export { StatusBar } from "./StatusBar.tsx";
+export type { StatusBarProps } from "./StatusBar.tsx";

package/src/otp.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { otpCellChanged, otpChars } from "./otp.ts";
+
+describe("otpChars", () => {
+  test("pads and truncates to length", () => {
+    expect(otpChars("12", 6)).toEqual(["1", "2", "", "", "", ""]);
+    expect(otpChars("1234567", 6)).toEqual(["1", "2", "3", "4", "5", "6"]);
+    expect(otpChars("", 4)).toEqual(["", "", "", ""]);
+  });
+});
+
+describe("otpCellChanged", () => {
+  test("typing a digit fills the cell and advances", () => {
+    expect(otpCellChanged("", 6, 0, "1")).toEqual({ value: "1", activeIndex: 1 });
+    expect(otpCellChanged("1", 6, 1, "2")).toEqual({ value: "12", activeIndex: 2 });
+  });
+
+  test("advancing stops at the last cell", () => {
+    expect(otpCellChanged("12345", 6, 5, "6")).toEqual({ value: "123456", activeIndex: 5 });
+  });
+
+  test("a multi-character box (paste) distributes across the following cells", () => {
+    expect(otpCellChanged("", 6, 0, "123456")).toEqual({ value: "123456", activeIndex: 5 });
+    expect(otpCellChanged("ab", 6, 2, "cdef")).toEqual({ value: "abcdef", activeIndex: 5 });
+  });
+
+  test("a paste longer than the remaining cells is truncated", () => {
+    expect(otpCellChanged("", 4, 2, "999999")).toEqual({ value: "99", activeIndex: 3 });
+  });
+
+  test("clearing a filled cell (backspace) stays on that cell", () => {
+    expect(otpCellChanged("123456", 6, 5, "")).toEqual({ value: "12345", activeIndex: 5 });
+  });
+
+  test("clearing an already-empty cell steps back one", () => {
+    expect(otpCellChanged("12", 6, 2, "")).toEqual({ value: "12", activeIndex: 1 });
+    expect(otpCellChanged("", 6, 0, "")).toEqual({ value: "", activeIndex: 0 });
+  });
+
+  test("typing into a mid box that already had a character overwrites it", () => {
+    expect(otpCellChanged("123456", 6, 2, "9")).toEqual({ value: "129456", activeIndex: 3 });
+  });
+});

package/src/otp.ts

@@ -0,0 +1,49 @@
+// Pure per-cell edit resolution for OtpInput. `<textinput>` only reports
+// `onChanged`/`text` (no per-key event on the widget yet), so a paste into
+// one box arrives as that box's `text` suddenly holding every pasted
+// character, which is what tells a paste apart from a normal keystroke.
+//
+// `activeIndex` is the cell focus moves to next. OtpInput sends the `focus`
+// command to that cell, which is what makes typing, backspace and paste
+// advance the caret without the user clicking between boxes.
+
+export interface OtpEdit {
+  value: string;
+  activeIndex: number;
+}
+
+export function otpChars(value: string, length: number): string[] {
+  const chars = new Array<string>(length).fill("");
+  for (let i = 0; i < Math.min(value.length, length); i++) chars[i] = value[i]!;
+  return chars;
+}
+
+/** One cell's onChanged fired with `text`. */
+export function otpCellChanged(value: string, length: number, index: number, text: string): OtpEdit {
+  const chars = otpChars(value, length);
+
+  if (text.length > 1) {
+    // A paste landed in this box: distribute it across this cell and the
+    // ones that follow.
+    let i = index;
+    for (const ch of text) {
+      if (i >= length) break;
+      chars[i] = ch;
+      i++;
+    }
+    return { value: chars.join(""), activeIndex: Math.min(i, length - 1) };
+  }
+
+  if (text.length === 0) {
+    // Backspace on a filled cell just clears it, staying put. Backspace on
+    // an already-empty cell would step back one, but that keystroke never
+    // changes this cell's text, so it never reaches onChanged; only a real
+    // key event could report it.
+    const wasFilled = chars[index] !== "";
+    chars[index] = "";
+    return { value: chars.join(""), activeIndex: wasFilled ? index : Math.max(index - 1, 0) };
+  }
+
+  chars[index] = text[text.length - 1]!;
+  return { value: chars.join(""), activeIndex: Math.min(index + 1, length - 1) };
+}

package/src/pagination.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { computePaginationRange } from "./pagination.ts";
+
+describe("computePaginationRange", () => {
+  test("everything fits: no dots", () => {
+    expect(computePaginationRange(1, 5)).toEqual([1, 2, 3, 4, 5]);
+    expect(computePaginationRange(3, 7)).toEqual([1, 2, 3, 4, 5, 6, 7]);
+  });
+
+  test("near the start: dots only on the right", () => {
+    expect(computePaginationRange(1, 10)).toEqual([1, 2, 3, 4, 5, "dots-end", 10]);
+    expect(computePaginationRange(3, 10)).toEqual([1, 2, 3, 4, 5, "dots-end", 10]);
+  });
+
+  test("near the end: dots only on the left", () => {
+    expect(computePaginationRange(10, 10)).toEqual([1, "dots-start", 6, 7, 8, 9, 10]);
+    expect(computePaginationRange(8, 10)).toEqual([1, "dots-start", 6, 7, 8, 9, 10]);
+  });
+
+  test("in the middle: dots on both sides", () => {
+    expect(computePaginationRange(5, 10)).toEqual([1, "dots-start", 4, 5, 6, "dots-end", 10]);
+  });
+
+  test("siblingCount widens the visible window", () => {
+    expect(computePaginationRange(5, 10, 2)).toEqual([1, "dots-start", 3, 4, 5, 6, 7, "dots-end", 10]);
+  });
+
+  test("edges: pageCount 0, out-of-range page clamps into range", () => {
+    expect(computePaginationRange(1, 0)).toEqual([]);
+    expect(computePaginationRange(99, 10)).toEqual([1, "dots-start", 6, 7, 8, 9, 10]);
+    expect(computePaginationRange(-5, 10)).toEqual([1, 2, 3, 4, 5, "dots-end", 10]);
+  });
+});

package/src/pagination.ts

@@ -0,0 +1,35 @@
+// Pure page-range computation for Pagination: which numbered buttons show,
+// and where the ellipsis gaps sit. Mirrors the standard sibling-count
+// windowing (first, last, current +/- siblings, collapse the rest to dots).
+
+export type PaginationItem = number | "dots-start" | "dots-end";
+
+function range(start: number, end: number): number[] {
+  if (end < start) return [];
+  return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+}
+
+export function computePaginationRange(page: number, pageCount: number, siblingCount = 1): PaginationItem[] {
+  if (pageCount <= 0) return [];
+  const clampedPage = Math.min(Math.max(page, 1), pageCount);
+  const clampedSiblings = Math.max(siblingCount, 0);
+
+  // first + last + current + two sibling runs + slack for the two dots.
+  const totalVisible = clampedSiblings * 2 + 5;
+  if (pageCount <= totalVisible) return range(1, pageCount);
+
+  const leftSibling = Math.max(clampedPage - clampedSiblings, 1);
+  const rightSibling = Math.min(clampedPage + clampedSiblings, pageCount);
+  const showLeftDots = leftSibling > 2;
+  const showRightDots = rightSibling < pageCount - 1;
+
+  if (!showLeftDots && showRightDots) {
+    const leftCount = 3 + clampedSiblings * 2;
+    return [...range(1, leftCount), "dots-end", pageCount];
+  }
+  if (showLeftDots && !showRightDots) {
+    const rightCount = 3 + clampedSiblings * 2;
+    return [1, "dots-start", ...range(pageCount - rightCount + 1, pageCount)];
+  }
+  return [1, "dots-start", ...range(leftSibling, rightSibling), "dots-end", pageCount];
+}

package/src/searchable-list.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { defaultFilter, filterItems } from "./searchable-list.ts";
+import type { SearchableListItem } from "./searchable-list.ts";
+
+const items: SearchableListItem[] = [
+  { id: "1", label: "Apple" },
+  { id: "2", label: "Banana" },
+  { id: "3", label: "Blueberry" },
+  { id: "4", label: "Cherry" },
+];
+
+describe("filterItems", () => {
+  test("empty query returns every item, same reference", () => {
+    expect(filterItems(items, "")).toBe(items as SearchableListItem[]);
+  });
+
+  test("matches case-insensitively against the label", () => {
+    expect(filterItems(items, "b").map((i) => i.id)).toEqual(["2", "3"]);
+    expect(filterItems(items, "BLUE").map((i) => i.id)).toEqual(["3"]);
+  });
+
+  test("no matches returns an empty list", () => {
+    expect(filterItems(items, "zzz")).toEqual([]);
+  });
+
+  test("a custom predicate overrides the default label match", () => {
+    const byId: typeof defaultFilter = (item, query) => item.id === query;
+    expect(filterItems(items, "3", byId).map((i) => i.label)).toEqual(["Blueberry"]);
+  });
+});

package/src/searchable-list.ts

@@ -0,0 +1,23 @@
+// Pure client-side filtering for SearchableList.
+
+export interface SearchableListItem {
+  id: string;
+  label: string;
+}
+
+export type SearchableListFilter = (item: SearchableListItem, query: string) => boolean;
+
+export function defaultFilter(item: SearchableListItem, query: string): boolean {
+  return item.label.toLowerCase().includes(query.toLowerCase());
+}
+
+/** Empty query is a same-reference no-op: every item passes, and skipping
+ * the filter call keeps an unrelated re-render from allocating a new array. */
+export function filterItems(
+  items: readonly SearchableListItem[],
+  query: string,
+  filter: SearchableListFilter = defaultFilter,
+): SearchableListItem[] {
+  if (query.length === 0) return items as SearchableListItem[];
+  return items.filter((item) => filter(item, query));
+}

package/src/stepper.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { stepState } from "./stepper.ts";
+
+describe("stepState", () => {
+  test("classifies steps relative to the active index", () => {
+    expect(stepState(0, 2)).toBe("completed");
+    expect(stepState(1, 2)).toBe("completed");
+    expect(stepState(2, 2)).toBe("active");
+    expect(stepState(3, 2)).toBe("pending");
+  });
+
+  test("activeIndex 0: only the first step is active, nothing completed", () => {
+    expect(stepState(0, 0)).toBe("active");
+    expect(stepState(1, 0)).toBe("pending");
+  });
+});

package/src/stepper.ts

@@ -0,0 +1,7 @@
+export type StepState = "completed" | "active" | "pending";
+
+export function stepState(index: number, activeIndex: number): StepState {
+  if (index < activeIndex) return "completed";
+  if (index === activeIndex) return "active";
+  return "pending";
+}