@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/chat-history/ChatHistoryRail.spec.tsx

@@ -0,0 +1,312 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ActionButton, IconButton } from "../design-system/components.js";
+import { defineDesignSystem } from "../design-system/definition.js";
+import { ToolkitProvider } from "../provider.js";
+import type { ChatHistoryItem } from "./ChatHistoryList.js";
+import { ChatHistoryRail } from "./ChatHistoryRail.js";
+
+const railLabels = {
+  newChat: "New chat",
+  showMore: "Show more chats",
+  showLess: "Show fewer chats",
+};
+
+function makeItems(count: number): ChatHistoryItem[] {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `thread-${index + 1}`,
+    title: `Chat ${index + 1}`,
+  }));
+}
+
+describe("ChatHistoryRail", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("shows five recent chats before progressively disclosing up to fifteen", () => {
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(20)}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+        />,
+      );
+    });
+
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(5);
+    const disclosure = container.querySelector<HTMLButtonElement>(
+      ".an-chat-history-rail__disclosure",
+    );
+    expect(disclosure?.getAttribute("aria-label")).toBe("Show more chats");
+
+    act(() => disclosure?.click());
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(15);
+    expect(disclosure?.getAttribute("aria-label")).toBe("Show fewer chats");
+
+    act(() => disclosure?.click());
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(5);
+  });
+
+  it("keeps the disclosure to the right of new chat and calls its handler", () => {
+    const onNewChat = vi.fn();
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(6)}
+          onSelect={() => {}}
+          onNewChat={onNewChat}
+          railLabels={railLabels}
+        />,
+      );
+    });
+
+    const disclosure = container.querySelector<HTMLButtonElement>(
+      ".an-chat-history-rail__disclosure",
+    );
+    const newChat = container.querySelector<HTMLButtonElement>(
+      ".an-chat-history-rail__new-chat",
+    );
+    expect(newChat?.textContent).toBe("New chat");
+    expect(newChat?.nextElementSibling).toBe(disclosure);
+    expect(newChat?.parentElement?.lastElementChild).toBe(disclosure);
+
+    act(() => newChat?.click());
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+
+  it("lets new chat fill the footer when there are no more chats", () => {
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(3)}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+        />,
+      );
+    });
+
+    expect(
+      container.querySelector(".an-chat-history-rail__disclosure"),
+    ).toBeNull();
+    expect(
+      container.querySelector(".an-chat-history-rail__new-chat"),
+    ).not.toBeNull();
+  });
+
+  it("preserves list actions for progressively disclosed rows", () => {
+    const onSelect = vi.fn();
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(6)}
+          onSelect={onSelect}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+        />,
+      );
+    });
+
+    act(() => {
+      container
+        .querySelector<HTMLButtonElement>(".an-chat-history-rail__disclosure")
+        ?.click();
+    });
+    const rows = container.querySelectorAll<HTMLButtonElement>(
+      ".an-chat-history-row__button",
+    );
+    act(() => rows[5]?.click());
+    expect(onSelect).toHaveBeenCalledWith("thread-6");
+  });
+
+  it("lets a design system replace the whole view without replacing its controller", () => {
+    const onNewChat = vi.fn();
+    const CustomActionButton = vi.fn(
+      ({ children, onPress }: Parameters<typeof ActionButton>[0]) => (
+        <button
+          data-acme-action
+          type="button"
+          onClick={(event) => onPress?.(event)}
+        >
+          {children}
+        </button>
+      ),
+    );
+    const designSystem = defineDesignSystem({
+      name: "Acme",
+      components: { ActionButton: CustomActionButton },
+    });
+
+    act(() => {
+      root.render(
+        <ToolkitProvider designSystem={designSystem}>
+          <ChatHistoryRail
+            items={makeItems(20)}
+            onSelect={() => {}}
+            onNewChat={onNewChat}
+            railLabels={railLabels}
+            renderRail={({ controller }) => (
+              <section data-acme-rail>
+                <output>{controller.visibleItems.length}</output>
+                <ActionButton onPress={controller.onNewChat}>
+                  {controller.newChatLabel}
+                </ActionButton>
+                <ActionButton onPress={controller.toggleExpanded}>
+                  {controller.disclosureLabel}
+                </ActionButton>
+              </section>
+            )}
+          />
+        </ToolkitProvider>,
+      );
+    });
+
+    const actions =
+      container.querySelectorAll<HTMLButtonElement>("[data-acme-action]");
+    expect(container.querySelector("[data-acme-rail]")).not.toBeNull();
+    expect(container.querySelector("output")?.textContent).toBe("5");
+    expect(actions[1]?.textContent).toBe("Show more chats");
+
+    act(() => actions[1]?.click());
+    expect(container.querySelector("output")?.textContent).toBe("15");
+    expect(actions[1]?.textContent).toBe("Show fewer chats");
+
+    act(() => actions[0]?.click());
+    expect(onNewChat).toHaveBeenCalledOnce();
+    expect(CustomActionButton).toHaveBeenCalled();
+  });
+
+  it("routes the default footer through the semantic action bridge", () => {
+    const onNewChat = vi.fn();
+    const CustomActionButton = vi.fn(
+      ({ children, onPress }: Parameters<typeof ActionButton>[0]) => (
+        <button
+          data-semantic-action
+          type="button"
+          onClick={(event) => onPress?.(event)}
+        >
+          {children}
+        </button>
+      ),
+    );
+    const CustomIconButton = vi.fn(
+      ({ icon, label, onPress }: Parameters<typeof IconButton>[0]) => (
+        <button
+          data-semantic-icon
+          type="button"
+          aria-label={label}
+          onClick={(event) => onPress?.(event)}
+        >
+          {icon}
+        </button>
+      ),
+    );
+    const designSystem = defineDesignSystem({
+      name: "Acme",
+      components: {
+        ActionButton: CustomActionButton,
+        IconButton: CustomIconButton,
+      },
+    });
+
+    act(() => {
+      root.render(
+        <ToolkitProvider designSystem={designSystem}>
+          <ChatHistoryRail
+            items={makeItems(6)}
+            onSelect={() => {}}
+            onNewChat={onNewChat}
+            railLabels={railLabels}
+          />
+        </ToolkitProvider>,
+      );
+    });
+
+    const newChat = container.querySelector<HTMLButtonElement>(
+      "[data-semantic-action]",
+    );
+    const disclosure = container.querySelector<HTMLButtonElement>(
+      "[data-semantic-icon]",
+    );
+    expect(newChat).not.toBeNull();
+    expect(disclosure?.getAttribute("aria-label")).toBe("Show more chats");
+    expect(CustomActionButton.mock.calls[0]?.[0]).toMatchObject({
+      emphasis: "ghost",
+      size: "compact",
+      leadingIcon: expect.anything(),
+    });
+    expect(CustomIconButton.mock.calls[0]?.[0]).toMatchObject({
+      size: "compact",
+      "aria-expanded": false,
+      label: "Show more chats",
+    });
+
+    act(() => newChat?.click());
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+
+  it("keeps native button semantics and focus in the default view", () => {
+    const onNewChat = vi.fn();
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(6)}
+          onSelect={() => {}}
+          onNewChat={onNewChat}
+          railLabels={railLabels}
+        />,
+      );
+    });
+
+    const newChat = container.querySelector<HTMLButtonElement>(
+      ".an-chat-history-rail__new-chat",
+    );
+    newChat?.focus();
+    act(() => newChat?.click());
+
+    expect(newChat?.type).toBe("button");
+    expect(document.activeElement).toBe(newChat);
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to the default rail when a product renderer fails", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(6)}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+          renderRail={() => {
+            throw new Error("broken company rail");
+          }}
+        />,
+      );
+    });
+
+    expect(
+      container.querySelector(".an-chat-history-rail__new-chat"),
+    ).not.toBeNull();
+  });
+});

package/src/chat-history/ChatHistoryRail.tsx

@@ -0,0 +1,150 @@
+import { IconDots, IconPlus } from "@tabler/icons-react";
+import type { ReactNode } from "react";
+
+import { ActionButton, IconButton } from "../design-system/components.js";
+import { DesignSystemErrorBoundary } from "../design-system/error-boundary.js";
+import {
+  ChatHistoryList,
+  type ChatHistoryItem,
+  type ChatHistoryListProps,
+} from "./ChatHistoryList.js";
+import {
+  type ChatHistoryRailController,
+  useChatHistoryRailController,
+} from "./useChatHistoryRailController.js";
+
+export interface ChatHistoryRailLabels {
+  newChat: string;
+  showMore: string;
+  showLess: string;
+}
+
+export interface ChatHistoryRailProps extends Omit<
+  ChatHistoryListProps,
+  "footer" | "items" | "sections" | "variant"
+> {
+  items: ChatHistoryItem[];
+  onNewChat: () => void;
+  railLabels: ChatHistoryRailLabels;
+  previewCount?: number;
+  expandedCount?: number;
+  /**
+   * Product-level presentation slot for design systems that want to replace
+   * the rail wholesale. State and actions still come from the same controller
+   * as the default view.
+   */
+  renderRail?: (context: ChatHistoryRailRenderContext) => ReactNode;
+}
+
+export interface ChatHistoryRailRenderContext {
+  controller: ChatHistoryRailController<ChatHistoryItem>;
+  listProps: Omit<
+    ChatHistoryListProps,
+    "footer" | "items" | "sections" | "variant"
+  >;
+}
+
+export type DefaultChatHistoryRailViewProps = ChatHistoryRailRenderContext;
+
+export function DefaultChatHistoryRailView({
+  controller,
+  listProps,
+}: ChatHistoryRailRenderContext) {
+  const {
+    canExpand,
+    disclosureLabel,
+    expanded,
+    newChatLabel,
+    onNewChat,
+    toggleExpanded,
+    visibleItems,
+  } = controller;
+  const { className, emptyLabel, ...rest } = listProps;
+
+  const footer = (
+    <div className="an-chat-history-rail__footer">
+      <ActionButton
+        type="button"
+        className="an-chat-history-rail__new-chat"
+        emphasis="ghost"
+        size="compact"
+        leadingIcon={
+          <IconPlus size={13} strokeWidth={1.8} aria-hidden="true" />
+        }
+        onPress={onNewChat}
+      >
+        <span>{newChatLabel}</span>
+      </ActionButton>
+      {canExpand && (
+        <IconButton
+          type="button"
+          className="an-chat-history-rail__disclosure"
+          size="compact"
+          icon={<IconDots size={14} strokeWidth={1.8} aria-hidden="true" />}
+          onPress={toggleExpanded}
+          aria-expanded={expanded}
+          label={disclosureLabel}
+          title={disclosureLabel}
+        />
+      )}
+    </div>
+  );
+
+  return (
+    <ChatHistoryList
+      {...rest}
+      items={visibleItems}
+      footer={footer}
+      emptyLabel={emptyLabel ?? null}
+      variant="rail"
+      className={["an-chat-history-rail", className].filter(Boolean).join(" ")}
+    />
+  );
+}
+
+/**
+ * Compact recent-chat rail for app sidebars. Hosts own thread persistence,
+ * sorting, routing, and mutations; the rail only owns progressive disclosure.
+ */
+export function ChatHistoryRail({
+  items,
+  onNewChat,
+  railLabels,
+  previewCount = 5,
+  expandedCount = 15,
+  renderRail,
+  className,
+  emptyLabel,
+  ...listProps
+}: ChatHistoryRailProps) {
+  const controller = useChatHistoryRailController({
+    items,
+    onNewChat,
+    labels: railLabels,
+    previewCount,
+    expandedCount,
+  });
+  const context: ChatHistoryRailRenderContext = {
+    controller,
+    listProps: { ...listProps, className, emptyLabel },
+  };
+  const fallback = <DefaultChatHistoryRailView {...context} />;
+
+  return renderRail ? (
+    <DesignSystemErrorBoundary component="ChatHistoryRail" fallback={fallback}>
+      <ChatHistoryRailCustomView renderRail={renderRail} context={context} />
+    </DesignSystemErrorBoundary>
+  ) : (
+    fallback
+  );
+}
+
+function ChatHistoryRailCustomView({
+  renderRail,
+  context,
+}: {
+  renderRail: NonNullable<ChatHistoryRailProps["renderRail"]>;
+  context: ChatHistoryRailRenderContext;
+}) {
+  return renderRail(context);
+}

package/src/chat-history/index.ts

@@ -0,0 +1,21 @@
+export {
+  ChatHistoryList,
+  type ChatHistoryItem,
+  type ChatHistoryListLabels,
+  type ChatHistoryListProps,
+  type ChatHistorySection,
+} from "./ChatHistoryList.js";
+export {
+  ChatHistoryRail,
+  DefaultChatHistoryRailView,
+  type DefaultChatHistoryRailViewProps,
+  type ChatHistoryRailLabels,
+  type ChatHistoryRailProps,
+  type ChatHistoryRailRenderContext,
+} from "./ChatHistoryRail.js";
+export {
+  type ChatHistoryRailController,
+  type ChatHistoryRailControllerLabels,
+  type UseChatHistoryRailControllerOptions,
+  useChatHistoryRailController,
+} from "./useChatHistoryRailController.js";

package/src/chat-history/useChatHistoryRailController.spec.tsx

@@ -0,0 +1,131 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  type ChatHistoryRailController,
+  type UseChatHistoryRailControllerOptions,
+  useChatHistoryRailController,
+} from "./useChatHistoryRailController.js";
+
+interface Item {
+  id: string;
+}
+
+const labels = {
+  newChat: "New chat",
+  showMore: "Show more chats",
+  showLess: "Show fewer chats",
+};
+
+function makeItems(count: number): Item[] {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `thread-${index + 1}`,
+  }));
+}
+
+describe("useChatHistoryRailController", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let controller: ChatHistoryRailController<Item>;
+
+  function Harness(props: UseChatHistoryRailControllerOptions<Item>) {
+    controller = useChatHistoryRailController(props);
+    return null;
+  }
+
+  function render(options: Partial<UseChatHistoryRailControllerOptions<Item>>) {
+    const props: UseChatHistoryRailControllerOptions<Item> = {
+      items: makeItems(20),
+      labels,
+      onNewChat: () => {},
+      ...options,
+    };
+    act(() => root.render(<Harness {...props} />));
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("progressively discloses the default five and fifteen item limits", () => {
+    const items = makeItems(20);
+    render({ items });
+
+    expect(controller.expanded).toBe(false);
+    expect(controller.collapsedLimit).toBe(5);
+    expect(controller.expandedLimit).toBe(15);
+    expect(controller.visibleItems).toEqual(items.slice(0, 5));
+    expect(controller.canExpand).toBe(true);
+    expect(controller.disclosureLabel).toBe("Show more chats");
+
+    act(() => controller.toggleExpanded());
+
+    expect(controller.expanded).toBe(true);
+    expect(controller.visibleItems).toEqual(items.slice(0, 15));
+    expect(controller.disclosureLabel).toBe("Show fewer chats");
+  });
+
+  it("clamps finite limits while preserving legacy disclosure behavior", () => {
+    render({ previewCount: -2.5, expandedCount: 1.9 });
+
+    expect(controller.collapsedLimit).toBe(1);
+    expect(controller.expandedLimit).toBe(1);
+    expect(controller.visibleItems).toHaveLength(1);
+    expect(controller.canExpand).toBe(true);
+
+    act(() => controller.toggleExpanded());
+    expect(controller.expanded).toBe(true);
+  });
+
+  it("uses defaults for non-finite limits and never puts expanded below preview", () => {
+    render({
+      previewCount: Number.NaN,
+      expandedCount: Number.POSITIVE_INFINITY,
+    });
+    expect(controller.collapsedLimit).toBe(5);
+    expect(controller.expandedLimit).toBe(15);
+
+    render({ previewCount: 8, expandedCount: 3 });
+    expect(controller.collapsedLimit).toBe(8);
+    expect(controller.expandedLimit).toBe(8);
+  });
+
+  it("resets disclosure explicitly and when the collection becomes too short", () => {
+    render({});
+    act(() => controller.toggleExpanded());
+    expect(controller.expanded).toBe(true);
+
+    act(() => controller.resetExpanded());
+    expect(controller.expanded).toBe(false);
+
+    act(() => controller.toggleExpanded());
+    expect(controller.expanded).toBe(true);
+
+    render({ items: makeItems(3) });
+    expect(controller.expanded).toBe(false);
+    expect(controller.canExpand).toBe(false);
+    expect(controller.visibleItems).toHaveLength(3);
+  });
+
+  it("exposes view labels and the host new-chat action without UI assumptions", () => {
+    const onNewChat = vi.fn();
+    render({ onNewChat });
+
+    expect(controller.newChatLabel).toBe("New chat");
+    act(() => controller.onNewChat());
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+});

package/src/chat-history/useChatHistoryRailController.ts

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+export interface ChatHistoryRailControllerLabels {
+  newChat: string;
+  showMore: string;
+  showLess: string;
+}
+
+export interface UseChatHistoryRailControllerOptions<Item> {
+  items: readonly Item[];
+  onNewChat: () => void;
+  labels: ChatHistoryRailControllerLabels;
+  previewCount?: number;
+  expandedCount?: number;
+}
+
+export interface ChatHistoryRailController<Item> {
+  expanded: boolean;
+  collapsedLimit: number;
+  expandedLimit: number;
+  visibleItems: Item[];
+  canExpand: boolean;
+  newChatLabel: string;
+  disclosureLabel: string;
+  onNewChat: () => void;
+  toggleExpanded: () => void;
+  resetExpanded: () => void;
+}
+
+function normalizeLimit(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.floor(value));
+}
+
+export function useChatHistoryRailController<Item>({
+  items,
+  onNewChat,
+  labels,
+  previewCount,
+  expandedCount,
+}: UseChatHistoryRailControllerOptions<Item>): ChatHistoryRailController<Item> {
+  const [expandedState, setExpandedState] = useState(false);
+  const collapsedLimit = normalizeLimit(previewCount, 5);
+  const expandedLimit = Math.max(
+    collapsedLimit,
+    normalizeLimit(expandedCount, 15),
+  );
+  const canExpand = items.length > collapsedLimit;
+  const expanded = canExpand && expandedState;
+  const visibleItems = useMemo(
+    () => items.slice(0, expanded ? expandedLimit : collapsedLimit),
+    [collapsedLimit, expanded, expandedLimit, items],
+  );
+
+  useEffect(() => {
+    if (!canExpand) setExpandedState(false);
+  }, [canExpand]);
+
+  const toggleExpanded = useCallback(() => {
+    if (canExpand) setExpandedState((current) => !current);
+  }, [canExpand]);
+  const resetExpanded = useCallback(() => setExpandedState(false), []);
+
+  return {
+    expanded,
+    collapsedLimit,
+    expandedLimit,
+    visibleItems,
+    canExpand,
+    newChatLabel: labels.newChat,
+    disclosureLabel: expanded ? labels.showLess : labels.showMore,
+    onNewChat,
+    toggleExpanded,
+    resetExpanded,
+  };
+}