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

package/src/chat-history/ChatHistoryList.tsx

@@ -9,23 +9,48 @@ import {
 } from "@tabler/icons-react";
 import React, { useMemo, useRef, useState } from "react";
 
+import { Skeleton } from "../design-system/components.js";
 import { cn } from "../utils.js";
 
+/** How the viewer got access to a chat; the app supplies the translated copy. */
+export type ChatHistoryAccessBasis =
+  | "owner"
+  | "direct"
+  | "organization"
+  | "public";
+
 export interface ChatHistoryItem {
   id: string;
   title: React.ReactNode;
   titleText?: string;
   subtitle?: React.ReactNode;
   detail?: React.ReactNode;
+  /** Already-translated owner name, shown on shared rows. */
+  ownerLabel?: React.ReactNode;
+  /** Already-translated access description, e.g. "Shared with you". */
+  accessLabel?: React.ReactNode;
+  accessBasis?: ChatHistoryAccessBasis;
   timestamp?: React.ReactNode;
   pinned?: boolean;
   disabled?: boolean;
+  /**
+   * Presentation only: drops the row menu and context menu while the row stays
+   * selectable. The app decides which rows (e.g. not owned) get no actions.
+   */
+  hideActions?: boolean;
 }
 
 export interface ChatHistorySection {
   id: string;
   label?: React.ReactNode;
   items: ChatHistoryItem[];
+  /** Section-level states; the section stays visible while any is set. */
+  /** Initial load: skeleton rows until the first rows arrive. */
+  loading?: boolean;
+  /** Shown above any rows already loaded: a failed load never reads as empty. */
+  error?: React.ReactNode;
+  emptyLabel?: React.ReactNode;
+  footer?: React.ReactNode;
 }
 
 export interface ChatHistoryListLabels {
@@ -134,6 +159,9 @@ export function ChatHistoryList({
     0,
   );
   const hasSearchValue = Boolean(searchValue?.trim());
+  const hasSectionState = resolvedSections.some((section) =>
+    sectionHasState(section, hasSearchValue),
+  );
 
   return (
     <div
@@ -165,20 +193,54 @@ export function ChatHistoryList({
           </div>
         ) : loading ? (
           <div className="an-chat-history__state">{loadingLabel}</div>
-        ) : totalCount === 0 ? (
+        ) : totalCount === 0 && !hasSectionState ? (
           <div className="an-chat-history__state">
             {hasSearchValue ? emptySearchLabel : emptyLabel}
           </div>
         ) : (
           resolvedSections.map(
             (section) =>
-              section.items.length > 0 && (
-                <div key={section.id} className="an-chat-history__section">
+              (section.items.length > 0 ||
+                sectionHasState(section, hasSearchValue)) && (
+                <div
+                  key={section.id}
+                  className="an-chat-history__section"
+                  data-section-id={section.id}
+                >
                   {section.label && (
                     <div className="an-chat-history__section-label">
                       {section.label}
                     </div>
                   )}
+                  {section.error ? (
+                    <div
+                      className="an-chat-history__state an-chat-history__state--error"
+                      role="alert"
+                    >
+                      {section.error}
+                    </div>
+                  ) : section.loading && section.items.length === 0 ? (
+                    <div
+                      className="an-chat-history__skeletons"
+                      aria-busy="true"
+                      data-testid="chat-history-section-skeleton"
+                    >
+                      {["100%", "80%", "60%"].map((width) => (
+                        <Skeleton
+                          key={width}
+                          shape="line"
+                          width={width}
+                          height={12}
+                        />
+                      ))}
+                    </div>
+                  ) : section.items.length === 0 &&
+                    !hasSearchValue &&
+                    section.emptyLabel ? (
+                    <div className="an-chat-history__state">
+                      {section.emptyLabel}
+                    </div>
+                  ) : null}
                   {section.items.map((item) => (
                     <ChatHistoryRow
                       key={item.id}
@@ -195,6 +257,7 @@ export function ChatHistoryList({
                       labels={resolvedLabels}
                     />
                   ))}
+                  {section.footer}
                 </div>
               ),
           )
@@ -205,6 +268,18 @@ export function ChatHistoryList({
   );
 }
 
+function sectionHasState(
+  section: ChatHistorySection,
+  searching: boolean,
+): boolean {
+  return Boolean(
+    section.loading ||
+    section.error ||
+    (!searching && section.emptyLabel) ||
+    section.footer,
+  );
+}
+
 type ChatHistoryRowProps = {
   item: ChatHistoryItem;
   active: boolean;
@@ -240,13 +315,15 @@ const ChatHistoryRow = React.memo(function ChatHistoryRow({
   const [menuOpen, setMenuOpen] = useState(false);
   const renameInputRef = useRef<HTMLInputElement | null>(null);
 
-  const hasMenu = Boolean(
-    onTogglePin ||
-    onRename ||
-    onDelete ||
-    renderRowActions ||
-    renderAdditionalRowActions,
-  );
+  const hasMenu =
+    !item.hideActions &&
+    Boolean(
+      onTogglePin ||
+      onRename ||
+      onDelete ||
+      renderRowActions ||
+      renderAdditionalRowActions,
+    );
 
   function startRename() {
     setDraftTitle(item.titleText ?? "");
@@ -337,6 +414,23 @@ const ChatHistoryRow = React.memo(function ChatHistoryRow({
           {item.detail != null && (
             <div className="an-chat-history-row__detail">{item.detail}</div>
           )}
+          {(item.ownerLabel != null || item.accessLabel != null) && (
+            <div
+              className="an-chat-history-row__access"
+              data-access-basis={item.accessBasis}
+            >
+              {item.ownerLabel != null && (
+                <span className="an-chat-history-row__owner">
+                  {item.ownerLabel}
+                </span>
+              )}
+              {item.accessLabel != null && (
+                <span className="an-chat-history-row__access-label">
+                  {item.accessLabel}
+                </span>
+              )}
+            </div>
+          )}
         </button>
       )}
 

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

@@ -8,7 +8,10 @@ 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";
+import {
+  ChatHistoryRail,
+  DefaultChatHistoryRailView,
+} from "./ChatHistoryRail.js";
 
 const railLabels = {
   newChat: "New chat",
@@ -67,6 +70,24 @@ describe("ChatHistoryRail", () => {
     expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(5);
   });
 
+  it("keeps the flat rail's list-level empty state", () => {
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={[]}
+          onSelect={() => {}}
+          onNewChat={() => {}}
+          railLabels={railLabels}
+          emptyLabel="No chats yet"
+        />,
+      );
+    });
+
+    expect(
+      container.querySelector(".an-chat-history__state")?.textContent,
+    ).toBe("No chats yet");
+  });
+
   it("changes the disclosure glyph with its state, even when both labels match", () => {
     act(() => {
       root.render(
@@ -343,6 +364,34 @@ describe("ChatHistoryRail", () => {
     expect(onNewChat).toHaveBeenCalledOnce();
   });
 
+  it("renders the exported default view from the flat controller and listProps alone", () => {
+    const onNewChat = vi.fn();
+    act(() => {
+      root.render(
+        <ChatHistoryRail
+          items={makeItems(6)}
+          onSelect={() => {}}
+          onNewChat={onNewChat}
+          railLabels={railLabels}
+          renderRail={({ controller, listProps }) => (
+            <DefaultChatHistoryRailView
+              controller={controller}
+              listProps={listProps}
+            />
+          )}
+        />,
+      );
+    });
+
+    expect(container.querySelectorAll(".an-chat-history-row")).toHaveLength(5);
+    act(() =>
+      container
+        .querySelector<HTMLButtonElement>(".an-chat-history-rail__new-chat")
+        ?.click(),
+    );
+    expect(onNewChat).toHaveBeenCalledOnce();
+  });
+
   it("falls back to the default rail when a product renderer fails", () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     act(() => {

package/src/chat-history/ChatHistoryRail.tsx

@@ -7,44 +7,180 @@ import {
   ChatHistoryList,
   type ChatHistoryItem,
   type ChatHistoryListProps,
+  type ChatHistorySection,
 } from "./ChatHistoryList.js";
 import {
   type ChatHistoryRailController,
+  type ChatHistoryRailSectionController,
+  type ChatHistoryRailSectionControllerLabels,
+  type ChatHistoryRailSectionInput,
   useChatHistoryRailController,
+  useChatHistoryRailSectionsController,
 } from "./useChatHistoryRailController.js";
 
 export interface ChatHistoryRailLabels {
   newChat: string;
   showMore: string;
   showLess: string;
+  /**
+   * Translated disclosure, load-more, and retry copy for every section.
+   * Required whenever the rail is given `sections`; there are no defaults.
+   */
+  sections?: ChatHistoryRailSectionControllerLabels;
 }
 
-export interface ChatHistoryRailProps extends Omit<
+export interface ChatHistoryRailSection extends ChatHistoryRailSectionInput<ChatHistoryItem> {
+  label?: ReactNode;
+  /** Initial load: renders skeleton rows until the first rows arrive. */
+  loading?: boolean;
+  /** A failed load, shown above any rows already loaded. */
+  error?: ReactNode;
+  onRetry?: () => void;
+  emptyLabel?: ReactNode;
+}
+
+type ChatHistoryRailListProps = Omit<
   ChatHistoryListProps,
   "footer" | "items" | "sections" | "variant"
-> {
-  items: ChatHistoryItem[];
+>;
+
+interface ChatHistoryRailBaseProps extends ChatHistoryRailListProps {
   onNewChat: () => void;
-  railLabels: ChatHistoryRailLabels;
   previewCount?: number;
   expandedCount?: number;
   renderRail?: (context: ChatHistoryRailRenderContext) => ReactNode;
 }
 
+interface ChatHistoryRailFlatProps {
+  /** One flat list with a single disclosure. */
+  items?: ChatHistoryItem[];
+  sections?: undefined;
+  showNewChat?: undefined;
+  railLabels: ChatHistoryRailLabels;
+}
+
+interface ChatHistoryRailSectionedProps {
+  /**
+   * Independent sections, each with its own preview, disclosure, paging, and
+   * loading/error/empty states. The app owns which rows each section holds.
+   */
+  sections: ChatHistoryRailSection[];
+  items?: undefined;
+  /**
+   * Set false when the surrounding chrome already owns New chat. `onNewChat`
+   * stays required and callable; only the rail's own button is dropped.
+   */
+  showNewChat?: boolean;
+  railLabels: ChatHistoryRailLabels & {
+    sections: ChatHistoryRailSectionControllerLabels;
+  };
+}
+
+export type ChatHistoryRailProps = ChatHistoryRailBaseProps &
+  (ChatHistoryRailFlatProps | ChatHistoryRailSectionedProps);
+
+export interface ChatHistoryRailSectionRenderState {
+  section: ChatHistoryRailSection;
+  controller: ChatHistoryRailSectionController<ChatHistoryItem>;
+}
+
 export interface ChatHistoryRailRenderContext {
   controller: ChatHistoryRailController<ChatHistoryItem>;
-  listProps: Omit<
-    ChatHistoryListProps,
-    "footer" | "items" | "sections" | "variant"
-  >;
+  /** Empty unless the rail was given `sections`. */
+  sections: ChatHistoryRailSectionRenderState[];
+  listProps: ChatHistoryRailListProps;
+  /** Sectioned rails only; defaults to true. */
+  showNewChat?: boolean;
+}
+
+/** `sections` stays optional so views written for the flat rail keep working. */
+export type DefaultChatHistoryRailViewProps = Omit<
+  ChatHistoryRailRenderContext,
+  "sections"
+> &
+  Partial<Pick<ChatHistoryRailRenderContext, "sections">>;
+
+function SectionFooter({
+  section,
+  controller,
+}: ChatHistoryRailSectionRenderState) {
+  const { labels, loadMore } = controller;
+  if (!controller.canExpand) return null;
+  return (
+    <div className="an-chat-history-rail__section-footer">
+      <ActionButton
+        type="button"
+        className="an-chat-history-rail__section-toggle"
+        emphasis="ghost"
+        size="compact"
+        trailingIcon={
+          controller.expanded ? (
+            <IconChevronUp size={13} strokeWidth={1.8} aria-hidden="true" />
+          ) : (
+            <IconChevronDown size={13} strokeWidth={1.8} aria-hidden="true" />
+          )
+        }
+        onPress={controller.toggleExpanded}
+        aria-expanded={controller.expanded}
+        data-section-id={section.id}
+      >
+        <span>{controller.expanded ? labels.showLess : labels.showAll}</span>
+      </ActionButton>
+      {loadMore && (
+        <ActionButton
+          type="button"
+          className="an-chat-history-rail__load-more"
+          emphasis="ghost"
+          size="compact"
+          pending={controller.loadingMore}
+          disabled={controller.loadingMore}
+          onPress={loadMore}
+        >
+          <span>
+            {controller.loadingMore ? labels.loadingMore : labels.loadMore}
+          </span>
+        </ActionButton>
+      )}
+    </div>
+  );
 }
 
-export type DefaultChatHistoryRailViewProps = ChatHistoryRailRenderContext;
+function toListSection(
+  state: ChatHistoryRailSectionRenderState,
+): ChatHistorySection {
+  const { section, controller } = state;
+  return {
+    id: section.id,
+    label: section.label,
+    items: controller.visibleItems,
+    loading: section.loading,
+    error: section.error ? (
+      <>
+        <span>{section.error}</span>
+        {section.onRetry && (
+          <ActionButton
+            type="button"
+            className="an-chat-history-rail__retry"
+            emphasis="ghost"
+            size="compact"
+            onPress={section.onRetry}
+          >
+            <span>{controller.labels.retry}</span>
+          </ActionButton>
+        )}
+      </>
+    ) : undefined,
+    emptyLabel: section.emptyLabel,
+    footer: controller.canExpand ? <SectionFooter {...state} /> : undefined,
+  };
+}
 
 export function DefaultChatHistoryRailView({
   controller,
+  sections = [],
   listProps,
-}: ChatHistoryRailRenderContext) {
+  showNewChat = true,
+}: DefaultChatHistoryRailViewProps) {
   const {
     canExpand,
     disclosureLabel,
@@ -56,20 +192,22 @@ export function DefaultChatHistoryRailView({
   } = controller;
   const { className, emptyLabel, ...rest } = listProps;
 
-  const footer = (
+  const footer = (showNewChat || canExpand) && (
     <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>
+      {showNewChat && (
+        <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"
@@ -94,8 +232,10 @@ export function DefaultChatHistoryRailView({
   return (
     <ChatHistoryList
       {...rest}
-      items={visibleItems}
-      footer={footer}
+      {...(sections.length > 0
+        ? { sections: sections.map(toListSection) }
+        : { items: visibleItems })}
+      footer={footer || undefined}
       emptyLabel={emptyLabel ?? null}
       variant="rail"
       className={["an-chat-history-rail", className].filter(Boolean).join(" ")}
@@ -105,6 +245,8 @@ export function DefaultChatHistoryRailView({
 
 export function ChatHistoryRail({
   items,
+  sections: sectionInputs,
+  showNewChat,
   onNewChat,
   railLabels,
   previewCount = 5,
@@ -115,15 +257,24 @@ export function ChatHistoryRail({
   ...listProps
 }: ChatHistoryRailProps) {
   const controller = useChatHistoryRailController({
-    items,
+    items: sectionInputs ? [] : (items ?? []),
     onNewChat,
     labels: railLabels,
     previewCount,
     expandedCount,
   });
+  const sectionControllers = useChatHistoryRailSectionsController(
+    sectionInputs ?? [],
+    railLabels.sections,
+  );
   const context: ChatHistoryRailRenderContext = {
     controller,
+    sections: (sectionInputs ?? []).map((section, index) => ({
+      section,
+      controller: sectionControllers[index],
+    })),
     listProps: { ...listProps, className, emptyLabel },
+    showNewChat,
   };
   const fallback = <DefaultChatHistoryRailView {...context} />;