@stigmer/react 0.4.8 → 0.5.0

package/src/resource-workbench/components/SelectionCheckbox.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link SelectionCheckbox}. */
+export interface SelectionCheckboxProps {
+  /** Whether the checkbox is checked. */
+  readonly checked: boolean;
+  /**
+   * Indeterminate state (e.g. header checkbox when some but not all
+   * rows are selected). Overrides `checked` visually.
+   */
+  readonly indeterminate?: boolean;
+  /** Called when the user toggles the checkbox. */
+  readonly onChange: (checked: boolean) => void;
+  /** Accessible label for the checkbox. */
+  readonly "aria-label": string;
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+/**
+ * Accessible checkbox for row/card selection and "select all" headers.
+ *
+ * Uses a native `<input type="checkbox">` with the `indeterminate`
+ * property set via ref for proper browser + screen reader support.
+ */
+export function SelectionCheckbox({
+  checked,
+  indeterminate = false,
+  onChange,
+  "aria-label": ariaLabel,
+  className,
+}: SelectionCheckboxProps) {
+  return (
+    <input
+      type="checkbox"
+      role="checkbox"
+      checked={checked}
+      ref={(el) => {
+        if (el) el.indeterminate = indeterminate;
+      }}
+      onChange={(e) => onChange(e.target.checked)}
+      aria-label={ariaLabel}
+      className={cn(
+        "size-3.5 shrink-0 cursor-pointer rounded border border-input accent-primary",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+        className,
+      )}
+    />
+  );
+}

package/src/resource-workbench/components/StatusBadge.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { StatusPhase } from "../types";
+
+/** Props for {@link StatusBadge}. */
+export interface StatusBadgeProps {
+  /** The status phase to display. Maps to `--stgm-status-*` tokens. */
+  readonly phase: StatusPhase;
+  /**
+   * Optional human-readable label override. When omitted, the phase
+   * name is title-cased (e.g. "ready" becomes "Ready").
+   */
+  readonly label?: string;
+  /** Tooltip text shown on hover. When omitted, no tooltip renders. */
+  readonly tooltip?: string;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+const PHASE_LABELS: Record<StatusPhase, string> = {
+  ready: "Ready",
+  running: "Running",
+  pending: "Pending",
+  degraded: "Degraded",
+  failed: "Failed",
+  disabled: "Disabled",
+  draft: "Draft",
+};
+
+/**
+ * Accessible status indicator that combines a color dot with a text label.
+ *
+ * Never communicates status through color alone — the text label is always
+ * present (WCAG 1.4.1). Colors come from `--stgm-status-*` design tokens
+ * defined in `@stigmer/theme`, ensuring correct appearance in both light
+ * and dark modes.
+ *
+ * @example
+ * ```tsx
+ * <StatusBadge phase="ready" />
+ * <StatusBadge phase="failed" label="Unreachable" tooltip="Last checked 2m ago" />
+ * ```
+ */
+export function StatusBadge({
+  phase,
+  label,
+  tooltip,
+  className,
+}: StatusBadgeProps) {
+  const displayLabel = label ?? PHASE_LABELS[phase];
+
+  const badge = (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-full px-2 py-0.5 text-[11px] font-medium leading-none",
+        statusClasses(phase),
+        className,
+      )}
+    >
+      <span
+        className={cn("size-1.5 shrink-0 rounded-full", dotClasses(phase))}
+        aria-hidden="true"
+      />
+      {displayLabel}
+    </span>
+  );
+
+  if (!tooltip) return badge;
+
+  return (
+    <span title={tooltip} className="inline-flex">
+      {badge}
+    </span>
+  );
+}
+
+/**
+ * Maps a status phase to Tailwind classes using `--stgm-status-*` tokens.
+ * Background uses the `-subtle` variant; text uses the main status color.
+ */
+function statusClasses(phase: StatusPhase): string {
+  switch (phase) {
+    case "ready":
+      return "bg-[var(--stgm-status-ready-subtle)] text-[var(--stgm-status-ready)]";
+    case "running":
+      return "bg-[var(--stgm-status-running-subtle)] text-[var(--stgm-status-running)]";
+    case "pending":
+      return "bg-[var(--stgm-status-pending-subtle)] text-[var(--stgm-status-pending)]";
+    case "degraded":
+      return "bg-[var(--stgm-status-degraded-subtle)] text-[var(--stgm-status-degraded)]";
+    case "failed":
+      return "bg-[var(--stgm-status-failed-subtle)] text-[var(--stgm-status-failed)]";
+    case "disabled":
+      return "bg-[var(--stgm-status-disabled-subtle)] text-[var(--stgm-status-disabled)]";
+    case "draft":
+      return "bg-[var(--stgm-status-draft-subtle)] text-[var(--stgm-status-draft)]";
+  }
+}
+
+/** Maps a status phase to the dot's background color (the main token). */
+function dotClasses(phase: StatusPhase): string {
+  switch (phase) {
+    case "ready":
+      return "bg-[var(--stgm-status-ready)]";
+    case "running":
+      return "bg-[var(--stgm-status-running)]";
+    case "pending":
+      return "bg-[var(--stgm-status-pending)]";
+    case "degraded":
+      return "bg-[var(--stgm-status-degraded)]";
+    case "failed":
+      return "bg-[var(--stgm-status-failed)]";
+    case "disabled":
+      return "bg-[var(--stgm-status-disabled)]";
+    case "draft":
+      return "bg-[var(--stgm-status-draft)]";
+  }
+}

package/src/resource-workbench/components/ViewSwitcher.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { ViewMode } from "../types";
+
+/** Props for {@link ViewSwitcher}. */
+export interface ViewSwitcherProps {
+  /** Currently active view mode. */
+  readonly value: ViewMode;
+  /** Called when the user selects a different view mode. */
+  readonly onChange: (mode: ViewMode) => void;
+  /** Which view modes to show. @default ["table", "cards", "list"] */
+  readonly modes?: readonly ViewMode[];
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+const MODE_META: Record<ViewMode, { label: string; icon: () => React.JSX.Element }> = {
+  table: { label: "Table view", icon: TableIcon },
+  cards: { label: "Card view", icon: CardsIcon },
+  list: { label: "List view", icon: ListIcon },
+};
+
+/**
+ * Toggle button group for switching between table, cards, and list views.
+ *
+ * Uses `role="radiogroup"` with `role="radio"` children for accessible
+ * view switching. Each button shows an icon and is labeled for screen
+ * readers.
+ */
+export function ViewSwitcher({
+  value,
+  onChange,
+  modes = ["table", "cards", "list"],
+  className,
+}: ViewSwitcherProps) {
+  return (
+    <div
+      role="radiogroup"
+      aria-label="View mode"
+      className={cn("inline-flex rounded-md border border-input", className)}
+    >
+      {modes.map((mode) => {
+        const { label, icon: Icon } = MODE_META[mode];
+        const isActive = value === mode;
+        return (
+          <button
+            key={mode}
+            type="button"
+            role="radio"
+            aria-checked={isActive}
+            aria-label={label}
+            onClick={() => onChange(mode)}
+            className={cn(
+              "inline-flex items-center justify-center px-2 py-1.5 transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:z-10",
+              "first:rounded-l-[calc(var(--stgm-radius)-1px)] last:rounded-r-[calc(var(--stgm-radius)-1px)]",
+              "border-r border-input last:border-r-0",
+              isActive
+                ? "bg-accent text-accent-foreground"
+                : "text-muted-foreground hover:text-foreground hover:bg-accent-hover",
+            )}
+          >
+            <Icon />
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons (inline SVGs matching the SDK's icon pattern)
+// ---------------------------------------------------------------------------
+
+function TableIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.25"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="1.5" y="1.5" width="11" height="11" rx="1.5" />
+      <path d="M1.5 5.5h11M1.5 9h11M5.5 5.5v6" />
+    </svg>
+  );
+}
+
+function CardsIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.25"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="1.5" y="1.5" width="4.5" height="4.5" rx="1" />
+      <rect x="8" y="1.5" width="4.5" height="4.5" rx="1" />
+      <rect x="1.5" y="8" width="4.5" height="4.5" rx="1" />
+      <rect x="8" y="8" width="4.5" height="4.5" rx="1" />
+    </svg>
+  );
+}
+
+function ListIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.25"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4.5 3h8M4.5 7h8M4.5 11h8" />
+      <circle cx="2" cy="3" r="0.75" fill="currentColor" stroke="none" />
+      <circle cx="2" cy="7" r="0.75" fill="currentColor" stroke="none" />
+      <circle cx="2" cy="11" r="0.75" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}

package/src/resource-workbench/hooks/useResourceCollection.ts

@@ -0,0 +1,261 @@
+"use client";
+
+import { useMemo, useCallback, useState, useRef, useEffect } from "react";
+import {
+  getCoreRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type SortingState,
+  type RowSelectionState,
+  type Table,
+} from "@tanstack/react-table";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type { ListParams, ListResult } from "@stigmer/sdk";
+import { useFetch } from "../../internal/useFetch";
+import type {
+  WorkbenchColumnDef,
+  SortValue,
+  SortDirection,
+} from "../types";
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for {@link useResourceCollection}. */
+export interface UseResourceCollectionOptions<TData = SearchResult> {
+  /**
+   * Async function that fetches a page of resources.
+   * The hook passes `ListParams` (org, query, page, scope) and expects
+   * `ListResult` back. Pass `null` to disable fetching (idle state).
+   */
+  readonly listFn: ((params: ListParams) => Promise<ListResult>) | null;
+  /** Organization slug to scope the query. Pass `null` to disable fetching. */
+  readonly org: string | null;
+  /** Text search query. No debouncing is applied — the consumer controls timing. */
+  readonly query?: string;
+  /**
+   * Scope for resource visibility.
+   * - `"org"` — resources owned by the active organization.
+   * - `"all"` — includes public resources from other organizations.
+   * @default "org"
+   */
+  readonly scope?: "org" | "all";
+  /** Current page number (1-indexed). @default 1 */
+  readonly page?: number;
+  /** Page size. @default 20 */
+  readonly pageSize?: number;
+  /** Active sort. When provided, the column header shows the sort indicator. */
+  readonly sort?: SortValue | null;
+  /** Called when the user changes the sort via a column header click. */
+  readonly onSortChange?: (sort: SortValue | null) => void;
+  /**
+   * Column definitions for the table view. These are converted to
+   * TanStack Table column defs internally.
+   */
+  readonly columns?: readonly WorkbenchColumnDef<TData>[];
+  /** Enable row selection state tracking. @default false */
+  readonly enableSelection?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Return value
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useResourceCollection}. */
+export interface UseResourceCollectionReturn<TData = SearchResult> {
+  /** The fetched data items for the current page. */
+  readonly items: readonly TData[];
+  /** Total number of matching items across all pages. */
+  readonly totalCount: number;
+  /** Total number of pages. */
+  readonly totalPages: number;
+  /** The current page number (mirrors input). */
+  readonly currentPage: number;
+  /** `true` during the initial data fetch (no data yet). */
+  readonly isLoading: boolean;
+  /** `true` during a background refetch while stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed fetch, or `null`. */
+  readonly error: Error | null;
+  /** Imperatively trigger a refetch. */
+  readonly refetch: () => void;
+  /**
+   * The TanStack Table instance. Available for advanced consumers who
+   * need direct table API access (e.g. custom renderers). `null` when
+   * no columns are provided.
+   */
+  readonly table: Table<TData> | null;
+  /** Current row selection state (item ID -> selected). */
+  readonly rowSelection: RowSelectionState;
+  /** Update row selection state directly. */
+  readonly setRowSelection: React.Dispatch<React.SetStateAction<RowSelectionState>>;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PAGE_SIZE = 20;
+
+interface CollectionData {
+  entries: readonly SearchResult[];
+  totalCount: number;
+  totalPages: number;
+}
+
+const INITIAL_DATA: CollectionData = {
+  entries: [],
+  totalCount: 0,
+  totalPages: 0,
+};
+
+/**
+ * Headless hook that manages resource collection state: data fetching,
+ * sorting, selection, and pagination.
+ *
+ * Wraps `useFetch` for data and `@tanstack/react-table` for table state
+ * (sorting, selection, column visibility). The hook itself produces no
+ * DOM — it returns data, state, and a TanStack Table instance that view
+ * components (`ResourceTable`, `ResourceCards`, `ResourceList`) consume.
+ *
+ * Platform builders who want full rendering control use this hook
+ * directly. The `ResourceWorkbench` shell composes it internally.
+ *
+ * @example
+ * ```tsx
+ * const collection = useResourceCollection({
+ *   listFn: (params) => stigmer.agent.list(params),
+ *   org: "acme",
+ *   query: debouncedQuery,
+ *   page: 1,
+ *   columns: agentColumns,
+ * });
+ * ```
+ */
+export function useResourceCollection<TData = SearchResult>(
+  options: UseResourceCollectionOptions<TData>,
+): UseResourceCollectionReturn<TData> {
+  const {
+    listFn,
+    org,
+    query = "",
+    scope = "org",
+    page = 1,
+    pageSize = DEFAULT_PAGE_SIZE,
+    sort = null,
+    onSortChange,
+    columns = [],
+    enableSelection = false,
+  } = options;
+
+  // --- Data fetching via useFetch -----------------------------------------
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<CollectionData>(
+    listFn && org
+      ? async () => {
+          const params: ListParams = {
+            org,
+            query: query || undefined,
+            excludePublic: false,
+            crossOrgPublic: scope === "all",
+            page: { num: page, size: pageSize },
+          };
+          const result = await listFn(params as Parameters<typeof listFn>[0]);
+          return {
+            entries: [...result.entries],
+            totalCount: result.totalCount,
+            totalPages: result.totalPages,
+          };
+        }
+      : null,
+    [listFn, org, query, scope, page, pageSize],
+    INITIAL_DATA,
+  );
+
+  const items = data.entries as unknown as readonly TData[];
+
+  // --- TanStack Table sorting bridge --------------------------------------
+  const sortingState: SortingState = useMemo(() => {
+    if (!sort) return [];
+    return [{ id: sort.id, desc: sort.direction === "desc" }];
+  }, [sort]);
+
+  const onSortChangeRef = useRef(onSortChange);
+  onSortChangeRef.current = onSortChange;
+
+  const handleSortingChange = useCallback(
+    (updater: SortingState | ((prev: SortingState) => SortingState)) => {
+      const next = typeof updater === "function" ? updater(sortingState) : updater;
+      if (next.length === 0) {
+        onSortChangeRef.current?.(null);
+      } else {
+        const col = next[0];
+        onSortChangeRef.current?.({
+          id: col.id,
+          direction: (col.desc ? "desc" : "asc") as SortDirection,
+        });
+      }
+    },
+    [sortingState],
+  );
+
+  // --- Row selection state ------------------------------------------------
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+
+  // Clear selection when page, query, or scope changes to prevent stale refs.
+  const clearKey = `${page}-${query}-${scope}`;
+  const prevClearKey = useRef(clearKey);
+  useEffect(() => {
+    if (prevClearKey.current !== clearKey) {
+      prevClearKey.current = clearKey;
+      setRowSelection({});
+    }
+  }, [clearKey]);
+
+  // --- TanStack Table column conversion -----------------------------------
+  const tanstackColumns = useMemo<ColumnDef<TData, unknown>[]>(() => {
+    return columns.map((col) => ({
+      id: col.id,
+      header: col.header,
+      cell: (info) => col.cell(info.row.original),
+      enableSorting: col.sortable ?? false,
+      size: col.minWidth,
+      minSize: col.minWidth,
+    }));
+  }, [columns]);
+
+  // --- TanStack Table instance -------------------------------------------
+  const table = useReactTable<TData>({
+    data: items as TData[],
+    columns: tanstackColumns,
+    state: {
+      sorting: sortingState,
+      rowSelection,
+    },
+    onSortingChange: handleSortingChange,
+    onRowSelectionChange: enableSelection ? setRowSelection : undefined,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getRowId: (row) => (row as SearchResult).id ?? String(items.indexOf(row as TData)),
+    manualPagination: true,
+    manualSorting: true,
+    enableRowSelection: enableSelection,
+  });
+
+  const tableOrNull = tanstackColumns.length > 0 ? table : null;
+
+  return {
+    items,
+    totalCount: data.totalCount,
+    totalPages: data.totalPages,
+    currentPage: page,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+    table: tableOrNull,
+    rowSelection,
+    setRowSelection,
+  };
+}