@agent-native/toolkit 0.211.0 → 0.212.0-nightly-20261021010049

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

@@ -0,0 +1,410 @@
+// @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 { ChatHistoryItem } from "./ChatHistoryList.js";
+import {
+  ChatHistoryRail,
+  DefaultChatHistoryRailView,
+  type ChatHistoryRailSection,
+} from "./ChatHistoryRail.js";
+
+const railLabels = {
+  newChat: "New chat",
+  showMore: "Show more chats",
+  showLess: "Show fewer chats",
+  sections: {
+    showAll: "Show all shared",
+    showLess: "Show fewer shared",
+    loadMore: "Load more shared",
+    loadingMore: "Loading shared",
+    retry: "Retry shared",
+  },
+};
+
+function makeItems(prefix: string, count: number): ChatHistoryItem[] {
+  return Array.from({ length: count }, (_, index) => ({
+    id: `${prefix}-${index + 1}`,
+    title: `${prefix} ${index + 1}`,
+    titleText: `${prefix} ${index + 1}`,
+  }));
+}
+
+describe("ChatHistoryRail sections", () => {
+  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();
+  });
+
+  function renderRail(
+    sections: ChatHistoryRailSection[],
+    extra: Record<string, unknown> = {},
+  ) {
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          sections={sections}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+          {...extra}
+        />,
+      );
+    });
+  }
+  const section = (id: string) =>
+    container.querySelector<HTMLElement>(`[data-section-id="${id}"]`)!;
+  const rows = (id: string) =>
+    section(id).querySelectorAll(".an-chat-history-row");
+  const buttonByText = (scope: ParentNode, text: string) =>
+    Array.from(scope.querySelectorAll<HTMLButtonElement>("button")).find(
+      (button) => button.textContent?.includes(text),
+    );
+
+  it("previews five shared rows, shows all of them, then collapses again", () => {
+    renderRail([
+      { id: "mine", label: "My chats", items: makeItems("mine", 3) },
+      {
+        id: "shared",
+        label: "Shared with you",
+        items: makeItems("shared", 22),
+      },
+    ]);
+
+    expect(rows("mine")).toHaveLength(3);
+    expect(rows("shared")).toHaveLength(5);
+    expect(buttonByText(section("mine"), "Show all shared")).toBeUndefined();
+
+    const toggle = buttonByText(section("shared"), "Show all shared")!;
+    expect(toggle.getAttribute("aria-expanded")).toBe("false");
+    act(() => toggle.click());
+    expect(rows("shared")).toHaveLength(22);
+    expect(toggle.getAttribute("aria-expanded")).toBe("true");
+    expect(toggle.textContent).toBe("Show fewer shared");
+    expect(rows("mine")).toHaveLength(3);
+
+    act(() => toggle.click());
+    expect(rows("shared")).toHaveLength(5);
+  });
+
+  it("expands one section without touching another long section", () => {
+    renderRail([
+      { id: "mine", items: makeItems("mine", 9) },
+      { id: "shared", items: makeItems("shared", 9) },
+    ]);
+    act(() => buttonByText(section("shared"), "Show all shared")?.click());
+    expect(rows("shared")).toHaveLength(9);
+    expect(rows("mine")).toHaveLength(5);
+  });
+
+  it("pages the server: load-more appears once disclosed and is not capped at fifteen", () => {
+    const onLoadMore = vi.fn();
+    const render = (count: number, hasMore: boolean) =>
+      renderRail([
+        {
+          id: "shared",
+          items: makeItems("shared", count),
+          hasMore,
+          onLoadMore,
+        },
+      ]);
+    render(20, true);
+
+    expect(buttonByText(section("shared"), "Load more shared")).toBeUndefined();
+    act(() => buttonByText(section("shared"), "Show all shared")?.click());
+    expect(rows("shared")).toHaveLength(20);
+
+    act(() => buttonByText(section("shared"), "Load more shared")?.click());
+    expect(onLoadMore).toHaveBeenCalledOnce();
+
+    render(40, true);
+    expect(rows("shared")).toHaveLength(40);
+
+    render(40, false);
+    expect(buttonByText(section("shared"), "Load more shared")).toBeUndefined();
+    expect(rows("shared")).toHaveLength(40);
+  });
+
+  it("offers Show all for a short first page when the server has more", () => {
+    const onLoadMore = vi.fn();
+    renderRail([
+      {
+        id: "shared",
+        items: makeItems("shared", 2),
+        hasMore: true,
+        onLoadMore,
+      },
+    ]);
+    act(() => buttonByText(section("shared"), "Show all shared")?.click());
+    act(() => buttonByText(section("shared"), "Load more shared")?.click());
+    expect(onLoadMore).toHaveBeenCalledOnce();
+  });
+
+  it("shows a pending load-more that cannot be fired twice", () => {
+    const onLoadMore = vi.fn();
+    renderRail([
+      {
+        id: "shared",
+        items: makeItems("shared", 8),
+        hasMore: true,
+        loadingMore: true,
+        onLoadMore,
+      },
+    ]);
+    act(() => buttonByText(section("shared"), "Show all shared")?.click());
+    const pending = buttonByText(section("shared"), "Loading shared")!;
+    expect(pending.disabled).toBe(true);
+    act(() => pending.click());
+    expect(onLoadMore).not.toHaveBeenCalled();
+  });
+
+  it("lets one section load, fail, or sit empty without touching the others", () => {
+    const onRetry = vi.fn();
+    renderRail([
+      { id: "mine", items: makeItems("mine", 2) },
+      { id: "shared", items: [], loading: true },
+      { id: "org", items: [], error: "Load failed", onRetry },
+      { id: "empty", items: [], emptyLabel: "Nothing here" },
+    ]);
+
+    expect(rows("mine")).toHaveLength(2);
+    expect(
+      section("shared").querySelector('[aria-busy="true"]'),
+    ).not.toBeNull();
+    expect(section("shared").textContent).not.toContain("Nothing");
+    expect(section("org").textContent).toContain("Load failed");
+    expect(section("empty").textContent).toBe("Nothing here");
+
+    act(() => buttonByText(section("org"), "Retry shared")?.click());
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+
+  it("keeps already-loaded rows visible when a later load fails", () => {
+    renderRail([
+      {
+        id: "shared",
+        items: makeItems("shared", 3),
+        error: "Load more failed",
+      },
+    ]);
+    expect(rows("shared")).toHaveLength(3);
+    expect(
+      section("shared").querySelector('[role="alert"]')?.textContent,
+    ).toContain("Load more failed");
+  });
+
+  it("does not show the global empty state while a section has a state of its own", () => {
+    renderRail([{ id: "shared", items: [], loading: true }], {
+      emptyLabel: "No chats yet",
+    });
+    expect(container.textContent).not.toContain("No chats yet");
+  });
+
+  it("shows the global empty state when every section is empty and has no state", () => {
+    renderRail(
+      [
+        { id: "mine", label: "My chats", items: [] },
+        { id: "shared", label: "Shared with you", items: [] },
+      ],
+      { emptyLabel: "No chats yet" },
+    );
+
+    expect(
+      container.querySelector(".an-chat-history__state")?.textContent,
+    ).toBe("No chats yet");
+    expect(
+      container.querySelectorAll(".an-chat-history__section-label"),
+    ).toHaveLength(0);
+  });
+
+  it("shows a section empty message instead of the global empty state", () => {
+    renderRail(
+      [
+        {
+          id: "shared",
+          label: "Shared",
+          items: [],
+          emptyLabel: "No shared chats",
+        },
+      ],
+      {
+        emptyLabel: "No chats yet",
+      },
+    );
+
+    expect(container.textContent).toContain("No shared chats");
+    expect(container.textContent).not.toContain("No chats yet");
+  });
+
+  it("keeps zero-row server paging controls reachable", () => {
+    const onLoadMore = vi.fn();
+    renderRail([
+      {
+        id: "mine",
+        label: "My chats",
+        items: [],
+        hasMore: true,
+        onLoadMore,
+      },
+    ]);
+
+    const mineSection = section("mine");
+    const showAll = buttonByText(mineSection, "Show all shared")!;
+    expect(showAll).toBeDefined();
+    act(() => showAll.click());
+
+    const loadMore = buttonByText(mineSection, "Load more shared")!;
+    expect(loadMore).toBeDefined();
+    act(() => loadMore.click());
+    expect(onLoadMore).toHaveBeenCalledOnce();
+  });
+
+  it("renders owner and access basis on a shared row", () => {
+    renderRail([
+      {
+        id: "shared",
+        items: [
+          {
+            id: "s1",
+            title: "Roadmap",
+            ownerLabel: "Pat Lee",
+            accessLabel: "Shared with your organization",
+            accessBasis: "organization",
+          },
+        ],
+      },
+    ]);
+    const access = container.querySelector(".an-chat-history-row__access");
+    expect(access?.getAttribute("data-access-basis")).toBe("organization");
+    expect(access?.textContent).toBe("Pat LeeShared with your organization");
+  });
+
+  it("selecting a section row and New chat work as in the flat rail", () => {
+    const onSelect = vi.fn();
+    const onNewChat = vi.fn();
+    const onRename = vi.fn();
+    renderRail([{ id: "mine", items: makeItems("mine", 2) }], {
+      onSelect,
+      onNewChat,
+      onRename,
+    });
+
+    act(() =>
+      container
+        .querySelectorAll<HTMLButtonElement>(".an-chat-history-row__button")[1]
+        ?.click(),
+    );
+    expect(onSelect).toHaveBeenCalledWith("mine-2");
+
+    act(() =>
+      container
+        .querySelector<HTMLButtonElement>(".an-chat-history-rail__new-chat")
+        ?.click(),
+    );
+    expect(onNewChat).toHaveBeenCalledOnce();
+    expect(onRename).not.toHaveBeenCalled();
+  });
+
+  it("renders sections and disclosures without a New chat button when showNewChat is false", () => {
+    const onNewChat = vi.fn();
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          sections={[
+            { id: "mine", label: "My chats", items: makeItems("mine", 2) },
+            { id: "shared", label: "Shared", items: makeItems("shared", 8) },
+          ]}
+          onSelect={() => {}}
+          onNewChat={onNewChat}
+          showNewChat={false}
+          railLabels={railLabels}
+          renderRail={({ controller, ...context }) => (
+            <>
+              <button
+                type="button"
+                data-custom-new-chat
+                onClick={() => controller.onNewChat()}
+              />
+              <DefaultChatHistoryRailView
+                controller={controller}
+                {...context}
+              />
+            </>
+          )}
+        />,
+      );
+    });
+
+    expect(rows("mine")).toHaveLength(2);
+    expect(rows("shared")).toHaveLength(5);
+    expect(
+      container.querySelector(".an-chat-history-rail__new-chat"),
+    ).toBeNull();
+    expect(container.querySelector(".an-chat-history-rail__footer")).toBeNull();
+    act(() => buttonByText(section("shared"), "Show all shared")?.click());
+    expect(rows("shared")).toHaveLength(8);
+
+    act(() =>
+      container
+        .querySelector<HTMLButtonElement>("[data-custom-new-chat]")
+        ?.click(),
+    );
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+
+  it("shows the New chat button on a sectioned rail by default", () => {
+    renderRail([{ id: "mine", items: makeItems("mine", 2) }]);
+    expect(
+      container.querySelector(".an-chat-history-rail__new-chat"),
+    ).not.toBeNull();
+  });
+
+  it("keeps the flat items rail on its own five/fifteen cap", () => {
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems("flat", 30)}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={{
+            newChat: "New chat",
+            showMore: "Show more chats",
+            showLess: "Show fewer chats",
+          }}
+        />,
+      );
+    });
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(5);
+    act(() =>
+      container
+        .querySelector<HTMLButtonElement>(".an-chat-history-rail__disclosure")
+        ?.click(),
+    );
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(15);
+  });
+
+  it("hands custom renderers the section controllers", () => {
+    renderRail([{ id: "shared", items: makeItems("shared", 9) }], {
+      renderRail: ({
+        sections,
+      }: {
+        sections: { controller: { visibleItems: unknown[] } }[];
+      }) => <output>{sections[0]?.controller.visibleItems.length}</output>,
+    });
+    expect(container.querySelector("output")?.textContent).toBe("5");
+  });
+});

package/src/chat-history/index.ts

@@ -1,5 +1,6 @@
 export {
   ChatHistoryList,
+  type ChatHistoryAccessBasis,
   type ChatHistoryItem,
   type ChatHistoryListLabels,
   type ChatHistoryListProps,
@@ -12,10 +13,17 @@ export {
   type ChatHistoryRailLabels,
   type ChatHistoryRailProps,
   type ChatHistoryRailRenderContext,
+  type ChatHistoryRailSection,
+  type ChatHistoryRailSectionRenderState,
 } from "./ChatHistoryRail.js";
 export {
   type ChatHistoryRailController,
   type ChatHistoryRailControllerLabels,
+  type ChatHistoryRailSectionController,
+  type ChatHistoryRailSectionControllerLabels,
+  type ChatHistoryRailSectionInput,
+  DEFAULT_SECTION_PREVIEW_COUNT,
   type UseChatHistoryRailControllerOptions,
   useChatHistoryRailController,
+  useChatHistoryRailSectionsController,
 } from "./useChatHistoryRailController.js";

package/src/chat-history/useChatHistoryRailController.ts

@@ -74,3 +74,97 @@ export function useChatHistoryRailController<Item>({
     resetExpanded,
   };
 }
+
+export interface ChatHistoryRailSectionControllerLabels {
+  showAll: string;
+  showLess: string;
+  loadMore: string;
+  loadingMore: string;
+  retry: string;
+}
+
+export interface ChatHistoryRailSectionInput<Item> {
+  id: string;
+  items: readonly Item[];
+  /** Rows shown before disclosure. Defaults to 5. */
+  previewCount?: number;
+  /**
+   * The server has more rows than `items`. Disclosed sections then offer
+   * `onLoadMore`; disclosed rows are never capped, so a loaded page is never
+   * hidden. Ignored without `onLoadMore`.
+   */
+  hasMore?: boolean;
+  loadingMore?: boolean;
+  onLoadMore?: () => void;
+  /** Overrides the rail-level section labels for this section. */
+  labels?: Partial<ChatHistoryRailSectionControllerLabels>;
+}
+
+export interface ChatHistoryRailSectionController<Item> {
+  id: string;
+  expanded: boolean;
+  previewLimit: number;
+  visibleItems: Item[];
+  /** More rows exist, loaded or on the server, than the preview shows. */
+  canExpand: boolean;
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** Present only when the section is disclosed and the server has more. */
+  loadMore: (() => void) | null;
+  toggleExpanded: () => void;
+  labels: ChatHistoryRailSectionControllerLabels;
+}
+
+export const DEFAULT_SECTION_PREVIEW_COUNT = 5;
+
+/**
+ * Independent preview/disclosure per section, keyed by section id. Disclosure
+ * state is kept here rather than in each section so a section whose rows are
+ * replaced by a refetch keeps its state.
+ */
+export function useChatHistoryRailSectionsController<Item>(
+  sections: readonly ChatHistoryRailSectionInput<Item>[],
+  sectionLabels: ChatHistoryRailSectionControllerLabels | undefined,
+): ChatHistoryRailSectionController<Item>[] {
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+  const toggle = useCallback((id: string) => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }, []);
+
+  return sections.map((section) => {
+    const previewLimit = normalizeLimit(
+      section.previewCount,
+      DEFAULT_SECTION_PREVIEW_COUNT,
+    );
+    const onLoadMore = section.onLoadMore;
+    const hasMore = Boolean(section.hasMore && onLoadMore);
+    const canExpand = section.items.length > previewLimit || hasMore;
+    const expanded = canExpand && expandedIds.has(section.id);
+    return {
+      id: section.id,
+      expanded,
+      previewLimit,
+      visibleItems: expanded
+        ? [...section.items]
+        : section.items.slice(0, previewLimit),
+      canExpand,
+      hasMore,
+      loadingMore: Boolean(section.loadingMore),
+      loadMore: expanded && hasMore && onLoadMore ? onLoadMore : null,
+      toggleExpanded: () => {
+        if (canExpand) toggle(section.id);
+      },
+      labels: {
+        ...sectionLabels,
+        ...section.labels,
+      } as ChatHistoryRailSectionControllerLabels,
+    };
+  });
+}

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

@@ -0,0 +1,133 @@
+// @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 ChatHistoryRailSectionController,
+  type ChatHistoryRailSectionControllerLabels,
+  type ChatHistoryRailSectionInput,
+  useChatHistoryRailSectionsController,
+} from "./useChatHistoryRailController.js";
+
+interface Item {
+  id: string;
+}
+
+const labels: ChatHistoryRailSectionControllerLabels = {
+  showAll: "Show all",
+  showLess: "Show less",
+  loadMore: "Load more",
+  loadingMore: "Loading more",
+  retry: "Retry",
+};
+
+function items(count: number): Item[] {
+  return Array.from({ length: count }, (_, index) => ({ id: `c${index}` }));
+}
+
+describe("useChatHistoryRailSectionsController", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let controllers: ChatHistoryRailSectionController<Item>[];
+
+  function Harness({
+    sections,
+  }: {
+    sections: ChatHistoryRailSectionInput<Item>[];
+  }) {
+    controllers = useChatHistoryRailSectionsController(sections, labels);
+    return null;
+  }
+  const render = (sections: ChatHistoryRailSectionInput<Item>[]) =>
+    act(() => root.render(<Harness sections={sections} />));
+  const byId = (id: string) => controllers.find((c) => c.id === id)!;
+
+  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.unstubAllGlobals();
+  });
+
+  it("previews five rows by default and discloses every loaded row, not fifteen", () => {
+    render([{ id: "shared", items: items(40) }]);
+    expect(byId("shared").visibleItems).toHaveLength(5);
+    expect(byId("shared").canExpand).toBe(true);
+
+    act(() => byId("shared").toggleExpanded());
+    expect(byId("shared").visibleItems).toHaveLength(40);
+
+    act(() => byId("shared").toggleExpanded());
+    expect(byId("shared").visibleItems).toHaveLength(5);
+  });
+
+  it("keeps each section's disclosure independent", () => {
+    render([
+      { id: "mine", items: items(8) },
+      { id: "shared", items: items(8) },
+    ]);
+    act(() => byId("shared").toggleExpanded());
+    expect(byId("shared").expanded).toBe(true);
+    expect(byId("mine").expanded).toBe(false);
+    expect(byId("mine").visibleItems).toHaveLength(5);
+  });
+
+  it("does not offer disclosure for a short section the server has nothing more for", () => {
+    render([{ id: "shared", items: items(5) }]);
+    expect(byId("shared").canExpand).toBe(false);
+    act(() => byId("shared").toggleExpanded());
+    expect(byId("shared").expanded).toBe(false);
+  });
+
+  it("offers disclosure and load-more for a short section with more on the server", () => {
+    const onLoadMore = vi.fn();
+    render([{ id: "shared", items: items(3), hasMore: true, onLoadMore }]);
+    expect(byId("shared").canExpand).toBe(true);
+    expect(byId("shared").loadMore).toBeNull();
+
+    act(() => byId("shared").toggleExpanded());
+    byId("shared").loadMore?.();
+    expect(onLoadMore).toHaveBeenCalledOnce();
+  });
+
+  it("treats hasMore without a loader as nothing more to show", () => {
+    render([{ id: "shared", items: items(3), hasMore: true }]);
+    expect(byId("shared").hasMore).toBe(false);
+    expect(byId("shared").canExpand).toBe(false);
+  });
+
+  it("keeps a section disclosed while its rows are replaced by a page load", () => {
+    const onLoadMore = vi.fn();
+    render([{ id: "shared", items: items(6), hasMore: true, onLoadMore }]);
+    act(() => byId("shared").toggleExpanded());
+    render([{ id: "shared", items: items(12), hasMore: true, onLoadMore }]);
+    expect(byId("shared").expanded).toBe(true);
+    expect(byId("shared").visibleItems).toHaveLength(12);
+  });
+
+  it("collapses when nothing is left to disclose", () => {
+    render([{ id: "shared", items: items(8) }]);
+    act(() => byId("shared").toggleExpanded());
+    render([{ id: "shared", items: items(2) }]);
+    expect(byId("shared").expanded).toBe(false);
+    expect(byId("shared").visibleItems).toHaveLength(2);
+  });
+
+  it("lets a section override the rail-level labels", () => {
+    render([
+      { id: "a", items: items(1) },
+      { id: "b", items: items(1), labels: { showAll: "Everything" } },
+    ]);
+    expect(byId("a").labels.showAll).toBe("Show all");
+    expect(byId("b").labels.showAll).toBe("Everything");
+    expect(byId("b").labels.loadMore).toBe("Load more");
+  });
+});

package/src/chat-history.css

@@ -57,6 +57,35 @@
   color: hsl(var(--muted-foreground));
 }
 
+.an-chat-history__skeletons {
+  display: grid;
+  gap: 6px;
+  padding: 6px 12px;
+}
+
+.an-chat-history-rail__section-footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 2px;
+  padding: 0 4px;
+}
+
+.an-chat-history-row__access {
+  display: flex;
+  gap: 6px;
+  min-width: 0;
+  margin-top: 2px;
+  font-size: 10px;
+  color: hsl(var(--muted-foreground) / 0.7);
+}
+
+.an-chat-history-row__owner {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .an-chat-history__state--error {
   color: hsl(38 92% 50%);
 }