@grackle-ai/web-components 0.107.2

package/src/components/display/SessionPicker.tsx

@@ -0,0 +1,214 @@
+/**
+ * Session picker dialog for forwarding messages.
+ *
+ * Displays a filterable list of active sessions (excluding the current one)
+ * so the user can choose a target for a forwarded message.
+ * Pure presentational component -- no useGrackle().
+ */
+
+import { useEffect, useRef, useState, type JSX } from "react";
+import { X, Search } from "lucide-react";
+import { AnimatePresence, motion } from "motion/react";
+import type { Session, Environment, PersonaData } from "../../hooks/types.js";
+import { ICON_SM, ICON_MD } from "../../utils/iconSize.js";
+import styles from "./SessionPicker.module.scss";
+
+/** A session entry enriched with its environment display name. */
+export interface SessionPickerEntry {
+  /** The session. */
+  session: Session;
+  /** Display name of the session's environment. */
+  environmentName: string;
+}
+
+/** Props for the SessionPicker component. */
+export interface SessionPickerProps {
+  /** Whether the picker is visible. */
+  isOpen: boolean;
+  /** Active sessions to display (already filtered: active status, not current session). */
+  sessions: Session[];
+  /** Environments for name lookup. */
+  environments: Environment[];
+  /** Personas for name lookup (optional — persona name is shown when available). */
+  personas?: PersonaData[];
+  /** Called when the user selects a target session. */
+  onSelect: (sessionId: string) => void;
+  /** Called when the user dismisses the picker without selecting. */
+  onCancel: () => void;
+}
+
+/** Returns a short status badge label for a session. */
+function statusLabel(status: string): string {
+  if (status === "running") {
+    return "running";
+  }
+  if (status === "idle") {
+    return "idle";
+  }
+  return status;
+}
+
+/**
+ * Modal dialog listing active sessions for the forward-message feature.
+ *
+ * The list is filterable by environment name or prompt snippet. If there are
+ * no active sessions the picker is not rendered (parent should keep it closed).
+ */
+export function SessionPicker({
+  isOpen,
+  sessions,
+  environments,
+  personas,
+  onSelect,
+  onCancel,
+}: SessionPickerProps): JSX.Element {
+  const [filter, setFilter] = useState("");
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+
+  // Focus the dialog when it opens so Escape is reliably captured
+  useEffect(() => {
+    if (isOpen) {
+      // Filter input has autoFocus when shown; otherwise fall back to close button
+      if (sessions.length <= 4) {
+        closeButtonRef.current?.focus();
+      }
+    }
+  }, [isOpen, sessions.length]);
+
+  // Build lookup for environment names
+  const envNameById = new Map<string, string>(
+    environments.map((e) => [e.id, e.displayName]),
+  );
+
+  // Build lookup for persona names
+  const personaNameById = new Map<string, string>(
+    (personas ?? []).map((p) => [p.id, p.name]),
+  );
+
+  const entries: SessionPickerEntry[] = sessions.map((s) => ({
+    session: s,
+    environmentName: envNameById.get(s.environmentId) ?? s.environmentId,
+  }));
+
+  const showFilter = sessions.length > 4;
+
+  const filtered = filter.trim()
+    ? entries.filter(
+        ({ session, environmentName }) =>
+          environmentName.toLowerCase().includes(filter.toLowerCase()) ||
+          session.prompt.toLowerCase().includes(filter.toLowerCase()),
+      )
+    : entries;
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.div
+          className={styles.overlay}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={{ duration: 0.15 }}
+          onClick={onCancel}
+          onKeyDown={(e) => { if (e.key === "Escape") { onCancel(); } }}
+          role="dialog"
+          aria-modal="true"
+          aria-label="Forward to session"
+          data-testid="session-picker-overlay"
+        >
+          <motion.div
+            ref={dialogRef}
+            className={styles.dialog}
+            initial={{ opacity: 0, scale: 0.93, y: -10 }}
+            animate={{ opacity: 1, scale: 1, y: 0 }}
+            exit={{ opacity: 0, scale: 0.93, y: -10 }}
+            transition={{ duration: 0.15, ease: [0.16, 1, 0.3, 1] }}
+            onClick={(e) => { e.stopPropagation(); }}
+            data-testid="session-picker-dialog"
+          >
+            <div className={styles.header}>
+              <h3 className={styles.title}>Forward to session</h3>
+              <button
+                ref={closeButtonRef}
+                type="button"
+                className={styles.closeButton}
+                onClick={onCancel}
+                aria-label="Close session picker"
+                data-testid="session-picker-close"
+              >
+                <X size={ICON_SM} aria-hidden="true" />
+              </button>
+            </div>
+
+            {showFilter && (
+              <div className={styles.filterRow}>
+                <Search size={ICON_SM} className={styles.searchIcon} aria-hidden="true" />
+                <input
+                  type="text"
+                  className={styles.filterInput}
+                  placeholder="Filter sessions..."
+                  value={filter}
+                  onChange={(e) => { setFilter(e.target.value); }}
+                  data-testid="session-picker-filter"
+                  autoFocus
+                />
+              </div>
+            )}
+
+            {sessions.length === 0 ? (
+              <div className={styles.noSessions} data-testid="session-picker-no-sessions">
+                <Search size={ICON_MD} aria-hidden="true" />
+                <p>No active sessions to forward to.</p>
+              </div>
+            ) : (
+              <ul className={styles.list} data-testid="session-picker-list">
+                {filtered.length === 0 ? (
+                  <li className={styles.emptyItem} data-testid="session-picker-empty">
+                    No matching sessions
+                  </li>
+                ) : (
+                  filtered.map(({ session, environmentName }) => {
+                    const personaName = session.personaId
+                      ? (personaNameById.get(session.personaId) ?? undefined)
+                      : undefined;
+                    return (
+                      <li key={session.id}>
+                        <button
+                          type="button"
+                          className={styles.sessionRow}
+                          onClick={() => { onSelect(session.id); }}
+                          data-testid={`session-picker-item-${session.id}`}
+                        >
+                          <div className={styles.sessionMain}>
+                            <span className={styles.envName}>{environmentName}</span>
+                            {personaName !== undefined && (
+                              <span className={styles.personaName} data-testid={`session-picker-persona-${session.id}`}>
+                                {personaName}
+                              </span>
+                            )}
+                            <span
+                              className={`${styles.statusBadge} ${styles[`status_${session.status}`] ?? styles.status_other}`}
+                              data-testid={`session-picker-status-${session.id}`}
+                            >
+                              {statusLabel(session.status)}
+                            </span>
+                          </div>
+                          <div className={styles.sessionPrompt}>
+                            {session.prompt.length > 80
+                              ? `${session.prompt.slice(0, 80)}...`
+                              : session.prompt}
+                          </div>
+                        </button>
+                      </li>
+                    );
+                  })
+                )}
+              </ul>
+            )}
+          </motion.div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}

package/src/components/display/Skeleton.module.scss

@@ -0,0 +1,58 @@
+// =============================================================================
+// Skeleton — shimmer loading placeholders
+// =============================================================================
+
+@use '../../styles/mixins' as *;
+
+// ─── Base shimmer block ──────────────────────────────────────────────────────
+
+@keyframes shimmer {
+  0% {
+    background-position: -200% 0;
+  }
+
+  100% {
+    background-position: 200% 0;
+  }
+}
+
+.skeleton {
+  display: block;
+  background: linear-gradient(
+    90deg,
+    var(--bg-inset) 25%,
+    var(--bg-surface) 50%,
+    var(--bg-inset) 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+  border-radius: var(--radius-sm);
+}
+
+.circular {
+  border-radius: 50%;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+  }
+}
+
+// ─── SkeletonText ────────────────────────────────────────────────────────────
+
+.textContainer {
+  display: flex;
+  flex-direction: column;
+}
+
+// ─── SkeletonCard ────────────────────────────────────────────────────────────
+
+.card {
+  @include surface-card;
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-md);
+  padding: var(--space-lg);
+}

package/src/components/display/Skeleton.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect } from "@storybook/test";
+import { Skeleton, SkeletonText, SkeletonCard } from "./Skeleton.js";
+
+// ─── Skeleton (base) ─────────────────────────────────────────────────────────
+
+const skeletonMeta: Meta<typeof Skeleton> = {
+  component: Skeleton,
+  title: "Primitives/Display/Skeleton",
+  tags: ["autodocs"],
+};
+export default skeletonMeta;
+type Story = StoryObj<typeof skeletonMeta>;
+
+/** Default full-width skeleton block. */
+export const Default: Story = {
+  play: async ({ canvas }) => {
+    const el = canvas.getByTestId("skeleton");
+    await expect(el).toBeInTheDocument();
+    await expect(el).toHaveAttribute("aria-hidden", "true");
+    await expect(el.className).toContain("skeleton");
+  },
+};
+
+/** Circular skeleton (avatar placeholder). */
+export const Circular: Story = {
+  args: { variant: "circular", width: "48px", height: "48px" },
+  play: async ({ canvas }) => {
+    const el = canvas.getByTestId("skeleton");
+    await expect(el.className).toContain("circular");
+  },
+};
+
+/** Custom width and height. */
+export const CustomSize: Story = {
+  args: { width: "200px", height: "2rem" },
+  play: async ({ canvas }) => {
+    const el = canvas.getByTestId("skeleton");
+    await expect(el.style.width).toBe("200px");
+    await expect(el.style.height).toBe("2rem");
+  },
+};
+
+// ─── SkeletonText ────────────────────────────────────────────────────────────
+
+/** Multi-line text placeholder (3 lines, last line shorter). */
+export const Text: Story = {
+  render: (args) => <SkeletonText {...args} />,
+  play: async ({ canvas }) => {
+    const container = canvas.getByTestId("skeleton-text");
+    await expect(container).toBeInTheDocument();
+    const lines = container.querySelectorAll("[data-testid='skeleton']");
+    await expect(lines.length).toBe(3);
+  },
+};
+
+/** Single-line text placeholder. */
+export const TextSingleLine: Story = {
+  render: () => <SkeletonText lines={1} />,
+  play: async ({ canvas }) => {
+    const container = canvas.getByTestId("skeleton-text");
+    const lines = container.querySelectorAll("[data-testid='skeleton']");
+    await expect(lines.length).toBe(1);
+  },
+};
+
+// ─── SkeletonCard ────────────────────────────────────────────────────────────
+
+/** Card-shaped skeleton with title and body text. */
+export const Card: Story = {
+  render: (args) => <SkeletonCard {...args} />,
+  play: async ({ canvas }) => {
+    const card = canvas.getByTestId("skeleton-card");
+    await expect(card).toBeInTheDocument();
+    // Title skeleton + text container with 2 lines = 3 skeleton elements total
+    const skeletons = card.querySelectorAll("[data-testid='skeleton']");
+    await expect(skeletons.length).toBe(3);
+  },
+};
+
+/** Grid of skeleton cards (composition demo). */
+export const CardGrid: Story = {
+  render: () => (
+    <div style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: "var(--space-lg)" }}>
+      <SkeletonCard />
+      <SkeletonCard />
+      <SkeletonCard />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const cards = canvas.getAllByTestId("skeleton-card");
+    await expect(cards.length).toBe(3);
+  },
+};

package/src/components/display/Skeleton.tsx

@@ -0,0 +1,127 @@
+import type { JSX } from "react";
+import styles from "./Skeleton.module.scss";
+
+// ─── Skeleton (base shimmer block) ───────────────────────────────────────────
+
+/** Shape variant for the Skeleton component. */
+type SkeletonVariant = "rectangular" | "circular";
+
+/** Props for the {@link Skeleton} component. */
+interface SkeletonProps {
+  /** CSS width. Defaults to `"100%"`. */
+  width?: string;
+  /** CSS height. Defaults to `"1rem"`. */
+  height?: string;
+  /** CSS border-radius override. Ignored when `variant` is `"circular"`. */
+  borderRadius?: string;
+  /** Shape variant. `"circular"` forces 50% border-radius. Defaults to `"rectangular"`. */
+  variant?: SkeletonVariant;
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+/**
+ * Animated shimmer placeholder that indicates loading content.
+ * Renders a decorative `<div>` with a gradient sweep animation.
+ */
+export function Skeleton({
+  width = "100%",
+  height = "1rem",
+  borderRadius,
+  variant = "rectangular",
+  className,
+}: SkeletonProps): JSX.Element {
+  const classNames = [
+    styles.skeleton,
+    variant === "circular" ? styles.circular : "",
+    className ?? "",
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div
+      className={classNames}
+      style={{
+        width,
+        height,
+        ...(borderRadius && variant !== "circular" ? { borderRadius } : {}),
+      }}
+      aria-hidden="true"
+      data-testid="skeleton"
+    />
+  );
+}
+
+// ─── SkeletonText (multi-line text placeholder) ──────────────────────────────
+
+/** Props for the {@link SkeletonText} component. */
+interface SkeletonTextProps {
+  /** Number of text lines. Defaults to `3`. */
+  lines?: number;
+  /** Width of the last line. Defaults to `"60%"`. */
+  lastLineWidth?: string;
+  /** Height of each line. Defaults to `"0.75rem"`. */
+  lineHeight?: string;
+  /** Gap between lines. Defaults to `"var(--space-sm)"`. */
+  gap?: string;
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+/**
+ * Multi-line skeleton text placeholder. Renders `lines` shimmer blocks
+ * with the last line at a shorter width to simulate trailing text.
+ */
+export function SkeletonText({
+  lines = 3,
+  lastLineWidth = "60%",
+  lineHeight = "0.75rem",
+  gap = "var(--space-sm)",
+  className,
+}: SkeletonTextProps): JSX.Element {
+  return (
+    <div
+      className={`${styles.textContainer} ${className ?? ""}`}
+      style={{ gap }}
+      aria-hidden="true"
+      data-testid="skeleton-text"
+    >
+      {Array.from({ length: lines }, (_, i) => (
+        <Skeleton
+          key={i}
+          width={i === lines - 1 && lines > 1 ? lastLineWidth : "100%"}
+          height={lineHeight}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ─── SkeletonCard (card-shaped placeholder) ──────────────────────────────────
+
+/** Props for the {@link SkeletonCard} component. */
+interface SkeletonCardProps {
+  /** Number of body text lines inside the card. Defaults to `2`. */
+  lines?: number;
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+/**
+ * Card-shaped skeleton placeholder matching the standard card layout.
+ * Contains a title-width shimmer block and body text lines.
+ */
+export function SkeletonCard({
+  lines = 2,
+  className,
+}: SkeletonCardProps): JSX.Element {
+  return (
+    <div
+      className={`${styles.card} ${className ?? ""}`}
+      aria-hidden="true"
+      data-testid="skeleton-card"
+    >
+      <Skeleton width="40%" height="1.25rem" />
+      <SkeletonText lines={lines} />
+    </div>
+  );
+}

package/src/components/display/Spinner.module.scss

@@ -0,0 +1,41 @@
+// =============================================================================
+// Spinner — inline loading indicator
+// =============================================================================
+
+.spinner {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 2px solid transparent;
+  border-top-color: currentColor;
+  border-right-color: currentColor;
+  border-radius: 50%;
+  animation: spin 0.7s linear infinite;
+  vertical-align: middle;
+  flex-shrink: 0;
+}
+
+// Size variants
+.sm {
+  width: 10px;
+  height: 10px;
+  border-width: 1.5px;
+}
+
+.md {
+  width: 12px;
+  height: 12px;
+  border-width: 2px;
+}
+
+.lg {
+  width: 16px;
+  height: 16px;
+  border-width: 2px;
+}
+
+.xl {
+  width: 48px;
+  height: 48px;
+  border-width: 4px;
+}

package/src/components/display/Spinner.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect } from "@storybook/test";
+import { Spinner } from "./Spinner.js";
+
+const meta: Meta<typeof Spinner> = {
+  component: Spinner,
+  title: "Primitives/Display/Spinner",
+  tags: ["autodocs"],
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default medium spinner. */
+export const Default: Story = {
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByLabelText("Loading");
+    await expect(spinner).toBeInTheDocument();
+    await expect(spinner.className).toContain("md");
+  },
+};
+
+/** Small spinner. */
+export const Small: Story = {
+  args: { size: "sm" },
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByLabelText("Loading");
+    await expect(spinner.className).toContain("sm");
+  },
+};
+
+/** Large spinner. */
+export const Large: Story = {
+  args: { size: "lg" },
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByLabelText("Loading");
+    await expect(spinner.className).toContain("lg");
+  },
+};
+
+/** Extra large spinner. */
+export const ExtraLarge: Story = {
+  args: { size: "xl" },
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByLabelText("Loading");
+    await expect(spinner.className).toContain("xl");
+  },
+};
+
+/** Spinner with a custom accessible label. */
+export const WithLabel: Story = {
+  args: { label: "Saving changes" },
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByLabelText("Saving changes");
+    await expect(spinner).toBeInTheDocument();
+  },
+};
+
+/** Spinner as a live region announces changes to screen readers. */
+export const LiveRegion: Story = {
+  args: { liveRegion: true, label: "Processing" },
+  play: async ({ canvas }) => {
+    const spinner = canvas.getByRole("status");
+    await expect(spinner).toBeInTheDocument();
+    await expect(spinner).toHaveAttribute("aria-label", "Processing");
+  },
+};

package/src/components/display/Spinner.tsx

@@ -0,0 +1,32 @@
+import type { JSX } from "react";
+import styles from "./Spinner.module.scss";
+
+/** Size variants for the Spinner component. */
+type SpinnerSize = "sm" | "md" | "lg" | "xl";
+
+/** Props for the Spinner component. */
+interface Props {
+  /** Size of the spinner. Defaults to "md". */
+  size?: SpinnerSize;
+  /** Additional CSS class name. */
+  className?: string;
+  /** Accessible label for screen readers. Defaults to "Loading". */
+  label?: string;
+  /** Whether this spinner is the primary live region. Defaults to false to avoid multiple live regions. */
+  liveRegion?: boolean;
+}
+
+/**
+ * Inline spinning loader that inherits the current text color.
+ * Use alongside disabled buttons or hint text to signal in-flight async operations.
+ */
+export function Spinner({ size = "md", className, label = "Loading", liveRegion = false }: Props): JSX.Element {
+  return (
+    <span
+      className={`${styles.spinner} ${styles[size]} ${className ?? ""}`}
+      role={liveRegion ? "status" : undefined}
+      aria-label={label}
+      aria-hidden={liveRegion ? undefined : true}
+    />
+  );
+}

package/src/components/display/SplashScreen.module.scss

@@ -0,0 +1,20 @@
+// =============================================================================
+// SplashScreen — full-viewport loading state shown before initial data arrives
+// =============================================================================
+
+.splash {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-lg);
+  background: var(--bg-base);
+}
+
+.logo {
+  display: block;
+  width: 128px;
+  height: 128px;
+  object-fit: contain;
+}

package/src/components/display/SplashScreen.stories.tsx

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect } from "@storybook/test";
+import { SplashScreen } from "./SplashScreen.js";
+
+const meta: Meta<typeof SplashScreen> = {
+  component: SplashScreen,
+  title: "Primitives/Display/SplashScreen",
+  tags: ["autodocs"],
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default splash screen with logo and spinner. */
+export const Default: Story = {
+  play: async ({ canvas }) => {
+    const splash = canvas.getByTestId("splash-screen");
+    await expect(splash).toBeInTheDocument();
+    // Should contain the logo image
+    const logo = canvas.getByAltText("Grackle");
+    await expect(logo).toBeInTheDocument();
+    // Should contain a spinner with live region
+    const spinner = canvas.getByRole("status");
+    await expect(spinner).toBeInTheDocument();
+    await expect(spinner).toHaveAttribute("aria-label", "Loading Grackle");
+  },
+};