@stigmer/react 0.4.7 → 0.5.0

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

@@ -0,0 +1,122 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import type { BulkAction } from "../types";
+
+/** Props for {@link BulkActionBar}. */
+export interface BulkActionBarProps<TData> {
+  /** Number of selected items. */
+  readonly selectedCount: number;
+  /** The selected items to pass to action handlers. */
+  readonly selectedItems: readonly TData[];
+  /** Available bulk actions. */
+  readonly actions: readonly BulkAction<TData>[];
+  /** Called when the user clicks "Cancel" (deselect all). */
+  readonly onCancel: () => void;
+  /** Additional CSS classes for the bar. */
+  readonly className?: string;
+}
+
+/**
+ * Floating action bar that appears when items are selected in the
+ * workbench. Shows selected count, available bulk actions, and a
+ * cancel button.
+ *
+ * Uses `aria-live="polite"` so screen readers announce the selection
+ * count when it changes.
+ *
+ * @example
+ * ```tsx
+ * {selection.hasSelection && (
+ *   <BulkActionBar
+ *     selectedCount={selection.selectedCount}
+ *     selectedItems={selection.selectedItems}
+ *     actions={agentBulkActions}
+ *     onCancel={selection.clearSelection}
+ *   />
+ * )}
+ * ```
+ */
+export function BulkActionBar<TData>({
+  selectedCount,
+  selectedItems,
+  actions,
+  onCancel,
+  className,
+}: BulkActionBarProps<TData>) {
+  if (selectedCount === 0) return null;
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Bulk actions"
+      aria-live="polite"
+      className={cn(
+        "flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-2 shadow-md",
+        className,
+      )}
+    >
+      <span className="text-xs font-medium text-foreground">
+        {selectedCount} {selectedCount === 1 ? "item" : "items"} selected
+      </span>
+
+      <span className="h-4 w-px bg-border" aria-hidden="true" />
+
+      <div className="flex items-center gap-1">
+        {actions.map((action) => (
+          <BulkActionButton
+            key={action.id}
+            action={action}
+            selectedItems={selectedItems}
+          />
+        ))}
+      </div>
+
+      <button
+        type="button"
+        onClick={onCancel}
+        className={cn(
+          "ml-auto text-xs text-muted-foreground transition-colors",
+          "hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm",
+        )}
+      >
+        Cancel
+      </button>
+    </div>
+  );
+}
+
+function BulkActionButton<TData>({
+  action,
+  selectedItems,
+}: {
+  readonly action: BulkAction<TData>;
+  readonly selectedItems: readonly TData[];
+}) {
+  const isDestructive = action.variant === "destructive";
+
+  return (
+    <button
+      type="button"
+      disabled={action.disabled}
+      onClick={() => action.onAction(selectedItems)}
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "disabled:pointer-events-none disabled:opacity-50",
+        isDestructive
+          ? "text-destructive hover:bg-destructive-subtle"
+          : "text-foreground hover:bg-accent-hover",
+      )}
+    >
+      {action.icon && (
+        <span className="shrink-0" aria-hidden="true">
+          {action.icon}
+        </span>
+      )}
+      {action.label}
+    </button>
+  );
+}

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

@@ -0,0 +1,105 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { SortDirection } from "../types";
+
+/** Props for {@link ColumnHeader}. */
+export interface ColumnHeaderProps {
+  /** Column header label. */
+  readonly label: string;
+  /** Whether clicking this header toggles sort. */
+  readonly sortable: boolean;
+  /** Current sort direction for this column, or `null` if not sorted. */
+  readonly sortDirection: SortDirection | null;
+  /** Called when the user clicks a sortable header. */
+  readonly onSort?: () => void;
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+/**
+ * Sortable table column header with accessible sort indicators.
+ *
+ * Uses `aria-sort` to communicate sort state to screen readers.
+ * The sort indicator uses both an icon and text direction so the
+ * sort state is never conveyed by icon alone.
+ */
+export function ColumnHeader({
+  label,
+  sortable,
+  sortDirection,
+  onSort,
+  className,
+}: ColumnHeaderProps) {
+  const ariaSort = sortDirection === "asc"
+    ? "ascending" as const
+    : sortDirection === "desc"
+      ? "descending" as const
+      : undefined;
+
+  if (!sortable) {
+    return (
+      <th
+        scope="col"
+        className={cn(
+          "px-3 py-2 text-left text-xs font-medium text-muted-foreground",
+          className,
+        )}
+      >
+        {label}
+      </th>
+    );
+  }
+
+  return (
+    <th
+      scope="col"
+      aria-sort={ariaSort}
+      className={cn(
+        "px-3 py-2 text-left text-xs font-medium text-muted-foreground",
+        className,
+      )}
+    >
+      <button
+        type="button"
+        onClick={onSort}
+        className={cn(
+          "inline-flex items-center gap-1 rounded-sm px-0.5 py-0.5 -mx-0.5",
+          "hover:text-foreground transition-colors",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          sortDirection && "text-foreground",
+        )}
+      >
+        {label}
+        <SortIndicator direction={sortDirection} />
+      </button>
+    </th>
+  );
+}
+
+function SortIndicator({
+  direction,
+}: {
+  readonly direction: SortDirection | null;
+}) {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={cn(
+        "shrink-0 transition-transform",
+        !direction && "opacity-0 group-hover:opacity-40",
+        direction === "desc" && "rotate-180",
+      )}
+    >
+      <path d="M6 2.5v7M3 6.5l3-4 3 4" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,173 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { FilterValue, FilterDef } from "../types";
+
+/** Props for {@link FilterBar}. */
+export interface FilterBarProps {
+  /** Currently active filter values. */
+  readonly filters: readonly FilterValue[];
+  /** Available filter definitions (used to resolve labels). */
+  readonly filterDefs: readonly FilterDef[];
+  /** Called when a filter chip's "remove" button is clicked. */
+  readonly onRemoveFilter: (filterId: string) => void;
+  /** Called when the "Clear all" button is clicked. */
+  readonly onClearAll: () => void;
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+/**
+ * Displays active filters as removable chips with a "Clear all" action.
+ *
+ * The filter bar is a lightweight presentation component — filter state
+ * and mutation logic live in {@link useResourceFilters}. The parent
+ * `ResourceWorkbench` wires them together.
+ *
+ * @example
+ * ```tsx
+ * <FilterBar
+ *   filters={filtersHook.filters}
+ *   filterDefs={agentFilterDefs}
+ *   onRemoveFilter={filtersHook.removeFilter}
+ *   onClearAll={filtersHook.clearFilters}
+ * />
+ * ```
+ */
+export function FilterBar({
+  filters,
+  filterDefs,
+  onRemoveFilter,
+  onClearAll,
+  className,
+}: FilterBarProps) {
+  if (filters.length === 0) return null;
+
+  const defMap = new Map(filterDefs.map((d) => [d.id, d]));
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Active filters"
+      className={cn("flex flex-wrap items-center gap-1.5", className)}
+    >
+      {filters.map((filter) => {
+        const def = defMap.get(filter.filterId);
+        const label = def?.label ?? filter.filterId;
+        const displayValue = formatFilterValue(filter, def);
+
+        return (
+          <FilterChip
+            key={`${filter.filterId}:${filter.operator}`}
+            label={label}
+            value={displayValue}
+            onRemove={() => onRemoveFilter(filter.filterId)}
+          />
+        );
+      })}
+
+      {filters.length > 1 && (
+        <button
+          type="button"
+          onClick={onClearAll}
+          className={cn(
+            "text-xs text-muted-foreground transition-colors",
+            "hover:text-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm",
+          )}
+        >
+          Clear all
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal: Filter chip
+// ---------------------------------------------------------------------------
+
+function FilterChip({
+  label,
+  value,
+  onRemove,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly onRemove: () => void;
+}) {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1 rounded-md bg-muted px-2 py-0.5 text-xs text-muted-foreground",
+      )}
+    >
+      <span className="font-medium">{label}:</span>
+      <span>{value}</span>
+      <button
+        type="button"
+        onClick={onRemove}
+        aria-label={`Remove ${label} filter`}
+        className={cn(
+          "ml-0.5 inline-flex items-center justify-center rounded-sm p-0.5",
+          "text-muted-foreground-subtle hover:text-foreground hover:bg-accent-hover",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        )}
+      >
+        <XIcon />
+      </button>
+    </span>
+  );
+}
+
+function formatFilterValue(
+  filter: FilterValue,
+  def: FilterDef | undefined,
+): string {
+  const { value, operator } = filter;
+  if (Array.isArray(value)) {
+    // For multi-select, try to resolve option labels.
+    if (def?.options) {
+      const optMap = new Map(def.options.map((o) => [o.value, o.label]));
+      return value.map((v) => optMap.get(v) ?? v).join(", ");
+    }
+    return value.join(", ");
+  }
+  // For select with options, resolve the label.
+  if (def?.options) {
+    const opt = def.options.find((o) => o.value === value);
+    if (opt) return opt.label;
+  }
+  const prefix =
+    operator === "gt"
+      ? "> "
+      : operator === "lt"
+        ? "< "
+        : operator === "gte"
+          ? ">= "
+          : operator === "lte"
+            ? "<= "
+            : operator === "neq"
+              ? "not "
+              : operator === "contains"
+                ? "~ "
+                : "";
+  return `${prefix}${value}`;
+}
+
+function XIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 10 10"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      aria-hidden="true"
+    >
+      <path d="M2.5 2.5l5 5M7.5 2.5l-5 5" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,109 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link ResourceAvatar}. */
+export interface ResourceAvatarProps {
+  /** Display name used for the initial fallback. */
+  readonly name: string;
+  /** Slug used to derive a deterministic background color. */
+  readonly slug: string;
+  /** Icon URL from the resource's spec. Empty string means no icon. */
+  readonly iconUrl?: string;
+  /**
+   * When `true`, renders nothing — no image, no initial avatar.
+   * Used for resource types like skills that don't support icons.
+   */
+  readonly hidden?: boolean;
+  /** Size variant. @default "md" */
+  readonly size?: "sm" | "md";
+  /** Additional CSS classes. */
+  readonly className?: string;
+}
+
+const AVATAR_COLORS = [
+  "bg-[#6366f1]",
+  "bg-[#8b5cf6]",
+  "bg-[#a855f7]",
+  "bg-[#d946ef]",
+  "bg-[#ec4899]",
+  "bg-[#f43f5e]",
+  "bg-[#ef4444]",
+  "bg-[#f97316]",
+  "bg-[#eab308]",
+  "bg-[#22c55e]",
+  "bg-[#14b8a6]",
+  "bg-[#06b6d4]",
+  "bg-[#3b82f6]",
+  "bg-[#2563eb]",
+] as const;
+
+function hashSlug(slug: string): number {
+  let h = 0;
+  for (let i = 0; i < slug.length; i++) {
+    h = ((h << 5) - h + slug.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+const SIZE_CLASSES = {
+  sm: "size-6 text-[10px]",
+  md: "size-8 text-xs",
+} as const;
+
+/**
+ * Compact resource avatar for cards, rows, and detail headers.
+ *
+ * Renders one of three states:
+ * 1. **Image** — when `iconUrl` is a non-empty string
+ * 2. **Initial** — colored circle with the first letter of `name`,
+ *    deterministic color derived from `slug`
+ * 3. **Hidden** — nothing (for resource types that don't support icons)
+ */
+export function ResourceAvatar({
+  name,
+  slug,
+  iconUrl,
+  hidden,
+  size = "md",
+  className,
+}: ResourceAvatarProps) {
+  if (hidden) return null;
+
+  const sizeClass = SIZE_CLASSES[size];
+
+  if (iconUrl) {
+    return (
+      <span
+        className={cn(
+          "inline-flex shrink-0 items-center justify-center rounded-full bg-muted",
+          sizeClass,
+          className,
+        )}
+      >
+        <img
+          src={iconUrl}
+          alt=""
+          className="size-4/5 object-contain"
+        />
+      </span>
+    );
+  }
+
+  const initial = (name || slug).charAt(0).toUpperCase();
+  const colorClass = AVATAR_COLORS[hashSlug(slug) % AVATAR_COLORS.length];
+
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "inline-flex shrink-0 items-center justify-center rounded-full font-medium text-white",
+        sizeClass,
+        colorClass,
+        className,
+      )}
+    >
+      {initial}
+    </span>
+  );
+}

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

@@ -0,0 +1,126 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import { SelectionCheckbox } from "./SelectionCheckbox";
+
+/** Props for {@link ResourceCards}. */
+export interface ResourceCardsProps<TData> {
+  /** Items to render as cards. */
+  readonly items: readonly TData[];
+  /** Render function for each card's content. */
+  readonly renderCard: (item: TData, index: number) => ReactNode;
+  /** Whether selection checkboxes are shown on cards. */
+  readonly enableSelection?: boolean;
+  /** Set of selected item IDs. */
+  readonly selectedIds?: ReadonlySet<string>;
+  /** Called when an item's selection state is toggled. */
+  readonly onToggleSelection?: (id: string) => void;
+  /** Extracts a stable unique ID from an item. */
+  readonly getItemId?: (item: TData) => string;
+  /**
+   * Render function for per-card actions (e.g. an `ActionMenu`).
+   * Shown in the top-right corner of the card.
+   */
+  readonly renderCardAction?: (item: TData) => ReactNode;
+  /** Called when a card is clicked (not when a control inside is clicked). */
+  readonly onCardClick?: (item: TData) => void;
+  /** Accessible label for the card grid region. @default "Resource cards" */
+  readonly "aria-label"?: string;
+  /** Additional CSS classes for the grid container. */
+  readonly className?: string;
+}
+
+/**
+ * Card grid view for the resource workbench.
+ *
+ * Renders items as a responsive grid of cards. Each card supports an
+ * optional selection checkbox, an action slot, and click handling.
+ * Card content is fully customizable via the `renderCard` prop.
+ *
+ * This component renders **only the card grid**. Search, filters, and
+ * pagination are handled by the parent `ResourceWorkbench`.
+ */
+export function ResourceCards<TData>({
+  items,
+  renderCard,
+  enableSelection = false,
+  selectedIds,
+  onToggleSelection,
+  getItemId = defaultGetId,
+  renderCardAction,
+  onCardClick,
+  "aria-label": ariaLabel = "Resource cards",
+  className,
+}: ResourceCardsProps<TData>) {
+  return (
+    <div
+      role="list"
+      aria-label={ariaLabel}
+      className={cn(
+        "grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3",
+        className,
+      )}
+    >
+      {items.map((item, index) => {
+        const id = getItemId(item);
+        const isSelected = selectedIds?.has(id) ?? false;
+        const isClickable = !!onCardClick;
+
+        return (
+          <div
+            key={id || `card-${index}`}
+            role="listitem"
+            aria-selected={enableSelection ? isSelected : undefined}
+            onClick={
+              isClickable
+                ? (e) => {
+                    const target = e.target as HTMLElement;
+                    if (
+                      target.closest("button") ||
+                      target.closest("input") ||
+                      target.closest("[role='menu']")
+                    ) {
+                      return;
+                    }
+                    onCardClick!(item);
+                  }
+                : undefined
+            }
+            className={cn(
+              "relative flex rounded-lg border border-border bg-card p-4 transition-colors",
+              isSelected && "border-primary/40 bg-primary-subtle",
+              isClickable && "cursor-pointer hover:border-primary/40 hover:bg-accent-hover",
+              isClickable && "focus-within:ring-2 focus-within:ring-ring",
+            )}
+          >
+            {enableSelection && onToggleSelection && (
+              <div className="absolute left-2 top-2">
+                <SelectionCheckbox
+                  checked={isSelected}
+                  onChange={() => onToggleSelection(id)}
+                  aria-label={`Select item ${id}`}
+                />
+              </div>
+            )}
+            <div className={cn("min-w-0 flex-1", enableSelection && "pl-5")}>
+              {renderCard(item, index)}
+            </div>
+            {renderCardAction && (
+              <div className="ml-2 shrink-0" onClick={(e) => e.stopPropagation()}>
+                {renderCardAction(item)}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function defaultGetId<TData>(item: TData): string {
+  const r = item as Record<string, unknown>;
+  if (typeof r.id === "string") return r.id;
+  if (typeof r.slug === "string") return r.slug;
+  return "";
+}