@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/explorer-body.tsx

@@ -0,0 +1,239 @@
+/**
+ * The explorer's directory body: the empty-state ladder, the card grid and the
+ * scrolling table (folders sorted above items in both), and the page footer. The
+ * pagination MATH lives in `ExplorerView`; this renders the result.
+ */
+import type { ReactNode } from 'react';
+
+import { EntityCardGrid } from './entity-card-grid';
+import { PAGE_SIZES } from './explorer-page-size';
+import type { ExplorerColumn, ExplorerEmptyStates } from './explorer-view';
+import { type Folder, FolderRow } from './folder-nav';
+import { type OpenTargetProps } from './open-target';
+import { Button, Card, EmptyState } from './primitives';
+import { ScrollRegion } from './scroll-region';
+import { Select } from './select';
+import { Table, TBody, TD, TH, THead, TR } from './table';
+import type { ViewMode } from './view-toggle';
+
+/** One page entry: a subfolder (sorted first) or a filtered item, in one array. */
+export type ExplorerEntry<T> =
+  | { readonly kind: 'folder'; readonly folder: Folder }
+  | { readonly kind: 'item'; readonly item: T };
+
+/** A first-class folder entry — a `FolderRow` (icon + name, navigates inward)
+ *  beside its optional actions, in the layout shared by the row cell and the card. */
+function FolderEntry({
+  folder,
+  onNavigate,
+  renderFolderActions,
+}: {
+  readonly folder: Folder;
+  readonly onNavigate: (folderId: string | null) => void;
+  readonly renderFolderActions: ((folder: Folder) => ReactNode) | undefined;
+}): ReactNode {
+  return (
+    <div className="tai-explorer-folder">
+      <FolderRow folder={folder} onOpen={onNavigate} />
+      {renderFolderActions ? renderFolderActions(folder) : null}
+    </div>
+  );
+}
+
+interface ExplorerPagerProps {
+  readonly label: string;
+  readonly pageStart: number;
+  readonly pageSize: number;
+  readonly total: number;
+  readonly effectivePage: number;
+  readonly pageCount: number;
+  readonly onPageChange: (page: number) => void;
+  readonly onPageSizeChange: (size: number) => void;
+}
+
+function ExplorerPager({
+  label,
+  pageStart,
+  pageSize,
+  total,
+  effectivePage,
+  pageCount,
+  onPageChange,
+  onPageSizeChange,
+}: ExplorerPagerProps): ReactNode {
+  return (
+    <nav className="tai-explorer-pagination" aria-label={`${label} pagination`}>
+      {/* The pager counts ENTRIES — subfolders plus filtered items in the
+          current directory — which is a different unit from the header's total
+          item count across every folder. Naming the unit keeps the two honest:
+          "1–4 of 4 entries" here versus "7 templates" above. */}
+      <span className="tai-muted">{`${String(pageStart + 1)}–${String(Math.min(pageStart + pageSize, total))} of ${String(total)} entries`}</span>
+      <div className="tai-row">
+        <Select
+          aria-label="Items per page"
+          value={String(pageSize)}
+          onValueChange={(value) => {
+            onPageSizeChange(Number(value));
+          }}
+          options={PAGE_SIZES.map((size) => ({
+            value: String(size),
+            label: `${String(size)} per page`,
+          }))}
+        />
+        {/* aria-disabled, never the disabled attribute: a button removed from
+            the tab order at the bound drops focus to the body (WCAG 2.4.3).
+            The click guard makes activation at the bound an inert no-op. */}
+        <Button
+          variant="ghost"
+          aria-label="Previous page"
+          aria-disabled={effectivePage <= 1}
+          onClick={() => {
+            if (effectivePage <= 1) return;
+            onPageChange(effectivePage - 1);
+          }}
+        >
+          Prev
+        </Button>
+        <Button
+          variant="ghost"
+          aria-label="Next page"
+          aria-disabled={effectivePage >= pageCount}
+          onClick={() => {
+            if (effectivePage >= pageCount) return;
+            onPageChange(effectivePage + 1);
+          }}
+        >
+          Next
+        </Button>
+        <span className="tai-muted">{`Page ${String(effectivePage)} of ${String(pageCount)}`}</span>
+      </div>
+    </nav>
+  );
+}
+
+export interface ExplorerBodyProps<T> {
+  readonly hasEntries: boolean;
+  /** Items in the current folder before filtering, so the empty ladder can tell
+   *  "filter emptied it" (>0 → no-match) from "genuinely empty". */
+  readonly inFolderCount: number;
+  readonly emptyStates: ExplorerEmptyStates;
+  readonly viewMode: ViewMode;
+  readonly label: string;
+  readonly columns: readonly ExplorerColumn[];
+  readonly pageEntries: readonly ExplorerEntry<T>[];
+  readonly getItemKey: (item: T) => string;
+  readonly renderRow: (item: T) => ReactNode;
+  readonly renderCard: (item: T) => ReactNode;
+  readonly openProps: (item: T) => OpenTargetProps;
+  readonly onNavigate: (folderId: string | null) => void;
+  readonly renderFolderActions: ((folder: Folder) => ReactNode) | undefined;
+  readonly pager: ExplorerPagerProps;
+}
+
+/** A card entry (folder card or item card) for the grid view. */
+function CardEntry<T>(
+  props: ExplorerBodyProps<T> & { readonly entry: ExplorerEntry<T> },
+): ReactNode {
+  const { entry, onNavigate, renderFolderActions, getItemKey, renderCard, openProps } = props;
+  if (entry.kind === 'folder') {
+    return (
+      <div role="listitem" key={`folder:${entry.folder.id}`}>
+        <Card interactive>
+          <FolderEntry
+            folder={entry.folder}
+            onNavigate={onNavigate}
+            renderFolderActions={renderFolderActions}
+          />
+        </Card>
+      </div>
+    );
+  }
+  return (
+    <div role="listitem" key={`item:${getItemKey(entry.item)}`} {...openProps(entry.item)}>
+      {renderCard(entry.item)}
+    </div>
+  );
+}
+
+/** A table row (folder row spanning all columns, or item row) for the list view. */
+function RowEntry<T>(
+  props: ExplorerBodyProps<T> & { readonly entry: ExplorerEntry<T> },
+): ReactNode {
+  const { entry, columns, onNavigate, renderFolderActions, getItemKey, renderRow, openProps } =
+    props;
+  if (entry.kind === 'folder') {
+    return (
+      <TR key={`folder:${entry.folder.id}`}>
+        <TD colSpan={columns.length}>
+          <FolderEntry
+            folder={entry.folder}
+            onNavigate={onNavigate}
+            renderFolderActions={renderFolderActions}
+          />
+        </TD>
+      </TR>
+    );
+  }
+  return (
+    <TR key={`item:${getItemKey(entry.item)}`} {...openProps(entry.item)}>
+      {renderRow(entry.item)}
+    </TR>
+  );
+}
+
+export function ExplorerBody<T>(props: ExplorerBodyProps<T>): ReactNode {
+  const { hasEntries, inFolderCount, emptyStates, viewMode, label, columns, pageEntries, pager } =
+    props;
+
+  if (!hasEntries) {
+    // The current folder renders nothing. A filter emptied it (`inFolderCount` > 0)
+    // → "no match"; otherwise the folder is genuinely empty. The ladder decides on
+    // the full, unsliced sets, never on a page.
+    return <EmptyState {...(inFolderCount > 0 ? emptyStates.noMatch : emptyStates.emptyFolder)} />;
+  }
+
+  if (viewMode === 'cards') {
+    return (
+      <>
+        <EntityCardGrid aria-label={label}>
+          {pageEntries.map((entry) => (
+            <CardEntry key={entryKey(entry, props.getItemKey)} {...props} entry={entry} />
+          ))}
+        </EntityCardGrid>
+        <ExplorerPager {...pager} />
+      </>
+    );
+  }
+
+  // Folder rows share the item table, spanning every column, sorted above items —
+  // so a folder-with-only-subfolders is folder ROWS, never a header-only table.
+  // A too-wide table scrolls inside its own box rather than widening the page.
+  return (
+    <>
+      <ScrollRegion label={label}>
+        <Table>
+          <THead>
+            <TR>
+              {columns.map((column) => (
+                <TH key={column.key} numeric={column.numeric}>
+                  {column.header}
+                </TH>
+              ))}
+            </TR>
+          </THead>
+          <TBody>
+            {pageEntries.map((entry) => (
+              <RowEntry key={entryKey(entry, props.getItemKey)} {...props} entry={entry} />
+            ))}
+          </TBody>
+        </Table>
+      </ScrollRegion>
+      <ExplorerPager {...pager} />
+    </>
+  );
+}
+
+/** The stable React key for a page entry, folder or item. */
+function entryKey<T>(entry: ExplorerEntry<T>, getItemKey: (item: T) => string): string {
+  return entry.kind === 'folder' ? `folder:${entry.folder.id}` : `item:${getItemKey(entry.item)}`;
+}

package/src/components/explorer-page-size.ts

@@ -0,0 +1,39 @@
+/**
+ * The explorer's persisted page size, per view surface. Mirrors `useViewMode`: an
+ * invalid or absent stored value degrades to the default, and a storage failure
+ * degrades to in-memory only — never a thrown boot.
+ */
+import { useCallback, useState } from 'react';
+
+/** The page-size choices, and the default. */
+export const PAGE_SIZES = [12, 24, 48, 96] as const;
+const DEFAULT_PAGE_SIZE = 24;
+
+const PAGE_SIZE_STORAGE_PREFIX = 'tai-studio.page-size.';
+
+function readStoredPageSize(surface: string): number {
+  try {
+    const raw = globalThis.localStorage.getItem(PAGE_SIZE_STORAGE_PREFIX + surface);
+    const parsed = raw === null ? Number.NaN : Number(raw);
+    if ((PAGE_SIZES as readonly number[]).includes(parsed)) return parsed;
+  } catch {
+    // No storage (private mode / non-browser) — fall back to the default.
+  }
+  return DEFAULT_PAGE_SIZE;
+}
+
+export function usePageSize(surface: string): readonly [number, (size: number) => void] {
+  const [size, setSizeState] = useState<number>(() => readStoredPageSize(surface));
+  const setSize = useCallback(
+    (next: number) => {
+      setSizeState(next);
+      try {
+        globalThis.localStorage.setItem(PAGE_SIZE_STORAGE_PREFIX + surface, String(next));
+      } catch {
+        // Storage unavailable — the choice still applies for this session.
+      }
+    },
+    [surface],
+  );
+  return [size, setSize];
+}

package/src/components/explorer-tag-filter.tsx

@@ -0,0 +1,80 @@
+/**
+ * The explorer's tag filter row: a togglable chip per vocabulary entry, with the
+ * unselected chips beyond the cap collapsed into a static "+N more" count.
+ */
+import type { ReactNode } from 'react';
+
+import type { TagVocabularyEntry } from './explorer-tags';
+
+/** A togglable tag chip; `aria-pressed` reflects whether the tag filters the list. */
+function TagChip({
+  entry,
+  active,
+  onToggle,
+}: {
+  readonly entry: TagVocabularyEntry;
+  readonly active: boolean;
+  readonly onToggle: () => void;
+}): ReactNode {
+  return (
+    <button
+      type="button"
+      className="tai-chip"
+      aria-pressed={active}
+      aria-label={`${entry.label} (${String(entry.count)})`}
+      onClick={onToggle}
+    >
+      <span>{entry.label}</span>
+      <span>{entry.count}</span>
+    </button>
+  );
+}
+
+/** The filter row: every selected chip plus as many unselected chips as fit under
+ *  the cap, with the remainder collapsed into a STATIC "+N more" count. An unset
+ *  cap shows every chip. */
+export function TagFilterRow({
+  vocabulary,
+  selectedSet,
+  onToggle,
+  filterLabel,
+  maxVisibleTags,
+}: {
+  readonly vocabulary: readonly TagVocabularyEntry[];
+  readonly selectedSet: ReadonlySet<string>;
+  readonly onToggle: (token: string) => void;
+  readonly filterLabel: string;
+  readonly maxVisibleTags: number | undefined;
+}): ReactNode {
+  const visible: TagVocabularyEntry[] = [];
+  let hidden = 0;
+  let unselectedShown = 0;
+  for (const entry of vocabulary) {
+    if (selectedSet.has(entry.token)) {
+      visible.push(entry);
+    } else if (maxVisibleTags === undefined || unselectedShown < maxVisibleTags) {
+      visible.push(entry);
+      unselectedShown += 1;
+    } else {
+      hidden += 1;
+    }
+  }
+
+  return (
+    <div role="group" aria-label={filterLabel} className="tai-row">
+      {visible.map((entry) => (
+        <TagChip
+          key={entry.token}
+          entry={entry}
+          active={selectedSet.has(entry.token)}
+          onToggle={() => {
+            onToggle(entry.token);
+          }}
+        />
+      ))}
+      {hidden > 0 ? (
+        <span className="tai-chip tai-chip-static">{`+${String(hidden)} more`}</span>
+      ) : null}
+    </div>
+  );
+}

package/src/components/explorer-tags.ts

@@ -0,0 +1,64 @@
+/**
+ * The tag glue every explorer screen shares: the untagged sentinel, the tag
+ * vocabulary builder, and the OR-match rule — one vocabulary/untagged/OR
+ * definition rather than a copy per screen.
+ */
+
+/** Reserved filter token for items carrying NO tag; namespaced so it never
+ *  collides with a real tag. */
+export const UNTAGGED_TOKEN = '__untagged__';
+
+export interface TagVocabularyEntry {
+  readonly token: string;
+  readonly label: string;
+  readonly count: number;
+}
+
+/** The tag vocabulary over `items`, name-sorted, plus an untagged pseudo-tag
+ *  (labelled `untaggedLabel`) when any item is untagged; a selected token whose
+ *  items vanished still appears (count 0) so it can be cleared. */
+export function buildTagVocabulary<T>(
+  items: readonly T[],
+  getTags: (item: T) => readonly string[],
+  selectedTags: readonly string[],
+  untaggedLabel: string,
+): TagVocabularyEntry[] {
+  const counts = new Map<string, number>();
+  let untagged = 0;
+  for (const item of items) {
+    const tags = getTags(item);
+    if (tags.length === 0) {
+      untagged += 1;
+      continue;
+    }
+    for (const tag of tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+  const vocabulary: TagVocabularyEntry[] = [...counts.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([label, count]) => ({ token: label, label, count }));
+  if (untagged > 0) {
+    vocabulary.push({ token: UNTAGGED_TOKEN, label: untaggedLabel, count: untagged });
+  }
+  for (const token of selectedTags) {
+    if (!vocabulary.some((entry) => entry.token === token)) {
+      vocabulary.push({
+        token,
+        label: token === UNTAGGED_TOKEN ? untaggedLabel : token,
+        count: 0,
+      });
+    }
+  }
+  return vocabulary;
+}
+
+/** OR semantics: an empty selection matches everything; otherwise an item
+ *  matches when it carries any selected tag, or is untagged and UNTAGGED_TOKEN
+ *  is selected. */
+export function matchesSelectedTags(
+  itemTags: readonly string[],
+  selected: ReadonlySet<string>,
+): boolean {
+  if (selected.size === 0) return true;
+  if (itemTags.length === 0) return selected.has(UNTAGGED_TOKEN);
+  return itemTags.some((tag) => selected.has(tag));
+}