@grackle-ai/web-components 0.107.2

package/src/components/notifications/Callout.module.scss

@@ -0,0 +1,83 @@
+// =============================================================================
+// Callout — inline contextual alert for persistent information within a panel
+// =============================================================================
+
+.callout {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-sm);
+  padding: var(--space-sm) var(--space-md);
+  border-radius: var(--radius-md);
+  border: 1px solid transparent;
+  font-size: var(--font-size-sm);
+  line-height: var(--line-height);
+
+  // Variant: success (green)
+  &.success {
+    background: var(--accent-green-dim);
+    border-color: var(--accent-green-border);
+
+    .icon {
+      color: var(--accent-green);
+    }
+  }
+
+  // Variant: error (red)
+  &.error {
+    background: var(--accent-red-dim);
+    border-color: var(--accent-red-border);
+
+    .icon {
+      color: var(--accent-red);
+    }
+  }
+
+  // Variant: warning (yellow)
+  &.warning {
+    background: var(--accent-yellow-dim);
+    border-color: var(--accent-yellow-border);
+
+    .icon {
+      color: var(--accent-yellow);
+    }
+  }
+
+  // Variant: info (blue)
+  &.info {
+    background: var(--accent-blue-dim);
+    border-color: var(--accent-blue-border);
+
+    .icon {
+      color: var(--accent-blue);
+    }
+  }
+}
+
+.icon {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+}
+
+.content {
+  flex: 1;
+  color: var(--text-primary);
+}
+
+.close {
+  background: none;
+  border: none;
+  color: var(--text-tertiary);
+  font-size: var(--font-size-lg);
+  cursor: pointer;
+  padding: 0 var(--space-xs);
+  line-height: 1;
+  flex-shrink: 0;
+  transition: color var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+  }
+}

package/src/components/notifications/Callout.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, userEvent } from "@storybook/test";
+import { Callout } from "./Callout.js";
+
+const meta: Meta<typeof Callout> = {
+  component: Callout,
+  title: "Primitives/Notifications/Callout",
+  tags: ["autodocs"],
+  args: {
+    children: "This is a callout message.",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default info callout. */
+export const Info: Story = {
+  play: async ({ canvas }) => {
+    const callout = canvas.getByRole("status");
+    await expect(callout).toBeInTheDocument();
+    await expect(callout).toHaveTextContent("This is a callout message.");
+  },
+};
+
+/** Error callout uses alert role for screen readers. */
+export const Error: Story = {
+  args: {
+    variant: "error",
+    children: "Something went wrong.",
+  },
+  play: async ({ canvas }) => {
+    const callout = canvas.getByRole("alert");
+    await expect(callout).toBeInTheDocument();
+    await expect(callout).toHaveTextContent("Something went wrong.");
+    await expect(callout.className).toContain("error");
+  },
+};
+
+/** Warning callout uses alert role for screen readers. */
+export const Warning: Story = {
+  args: {
+    variant: "warning",
+    children: "Check your settings.",
+  },
+  play: async ({ canvas }) => {
+    const callout = canvas.getByRole("alert");
+    await expect(callout).toBeInTheDocument();
+    await expect(callout).toHaveTextContent("Check your settings.");
+    await expect(callout.className).toContain("warning");
+  },
+};
+
+/** Success callout. */
+export const Success: Story = {
+  args: {
+    variant: "success",
+    children: "Operation completed.",
+  },
+  play: async ({ canvas }) => {
+    const callout = canvas.getByRole("status");
+    await expect(callout).toBeInTheDocument();
+    await expect(callout).toHaveTextContent("Operation completed.");
+    await expect(callout.className).toContain("success");
+  },
+};
+
+/** Dismissible callout can be closed by clicking the dismiss button. */
+export const Dismissible: Story = {
+  args: {
+    dismissible: true,
+    children: "You can dismiss this.",
+  },
+  play: async ({ canvas }) => {
+    const callout = canvas.getByRole("status");
+    await expect(callout).toBeInTheDocument();
+    const dismiss = canvas.getByLabelText("Dismiss");
+    await expect(dismiss).toBeInTheDocument();
+    await userEvent.click(dismiss);
+    await expect(canvas.queryByRole("status")).not.toBeInTheDocument();
+  },
+};

package/src/components/notifications/Callout.tsx

@@ -0,0 +1,64 @@
+import { useState, type ReactNode, type JSX } from "react";
+import { AlertTriangle, Check, Info, X } from "lucide-react";
+import styles from "./Callout.module.scss";
+import { ICON_LG, ICON_MD } from "../../utils/iconSize.js";
+
+/** Visual style variant for a callout. */
+export type CalloutVariant = "success" | "error" | "warning" | "info";
+
+interface CalloutProps {
+  /** Controls color scheme and icon. Defaults to "info". */
+  variant?: CalloutVariant;
+  children: ReactNode;
+  /** Show a dismiss button. Defaults to false. */
+  dismissible?: boolean;
+  /** Optional extra class name for layout overrides. */
+  className?: string;
+}
+
+const VARIANT_ICONS: Record<CalloutVariant, ReactNode> = {
+  success: <Check size={ICON_LG} />,
+  error: <X size={ICON_LG} />,
+  warning: <AlertTriangle size={ICON_LG} />,
+  info: <Info size={ICON_LG} />,
+};
+
+/**
+ * Inline contextual alert for persistent, location-specific information.
+ * Use for things like blocked dependencies, validation errors, or
+ * status messages that belong within a specific panel rather than a toast.
+ */
+export function Callout({
+  variant = "info",
+  children,
+  dismissible = false,
+  className,
+}: CalloutProps): JSX.Element {
+  const [dismissed, setDismissed] = useState(false);
+
+  return (
+    <>
+      {!dismissed && (
+        <div
+          className={[styles.callout, styles[variant], className].filter(Boolean).join(" ")}
+          role={variant === "error" || variant === "warning" ? "alert" : "status"}
+        >
+          <span className={styles.icon} aria-hidden="true">
+            {VARIANT_ICONS[variant]}
+          </span>
+          <span className={styles.content}>{children}</span>
+          {dismissible && (
+            <button
+              type="button"
+              className={styles.close}
+              onClick={() => setDismissed(true)}
+              aria-label="Dismiss"
+            >
+              <X size={ICON_MD} aria-hidden="true" />
+            </button>
+          )}
+        </div>
+      )}
+    </>
+  );
+}

package/src/components/notifications/Toast.module.scss

@@ -0,0 +1,86 @@
+@use '../../styles/mixins' as *;
+
+// =============================================================================
+// Toast — individual transient notification badge
+// =============================================================================
+
+.toast {
+  @include surface-card;
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+  padding: var(--space-sm) var(--space-md);
+  min-width: 240px;
+  max-width: 440px;
+  border-left: 3px solid transparent;
+  box-shadow: var(--shadow-lg);
+
+  // Variant: success (green)
+  &.success {
+    border-left-color: var(--accent-green);
+    box-shadow: var(--shadow-lg);
+
+    .icon {
+      color: var(--accent-green);
+    }
+  }
+
+  // Variant: error (red)
+  &.error {
+    border-left-color: var(--accent-red);
+    box-shadow: var(--shadow-lg);
+
+    .icon {
+      color: var(--accent-red);
+    }
+  }
+
+  // Variant: warning (yellow)
+  &.warning {
+    border-left-color: var(--accent-yellow);
+
+    .icon {
+      color: var(--accent-yellow);
+    }
+  }
+
+  // Variant: info (blue)
+  &.info {
+    border-left-color: var(--accent-blue);
+
+    .icon {
+      color: var(--accent-blue);
+    }
+  }
+}
+
+.icon {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+}
+
+.message {
+  flex: 1;
+  font-size: var(--font-size-sm);
+  color: var(--text-primary);
+  line-height: var(--line-height);
+}
+
+.close {
+  background: none;
+  border: none;
+  color: var(--text-tertiary);
+  font-size: var(--font-size-lg);
+  cursor: pointer;
+  padding: 0 var(--space-xs);
+  line-height: 1;
+  flex-shrink: 0;
+  transition: color var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+  }
+}

package/src/components/notifications/Toast.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { Toast } from "./Toast.js";
+
+/** Very long duration to prevent auto-dismiss during testing. */
+const TEST_DURATION: number = 999999;
+
+const meta: Meta<typeof Toast> = {
+  component: Toast,
+  title: "Primitives/Notifications/Toast",
+  tags: ["autodocs"],
+  args: {
+    onDismiss: fn(),
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Info toast notification. */
+export const Info: Story = {
+  args: {
+    toast: { id: "t-info", message: "Something happened", variant: "info", duration: TEST_DURATION },
+  },
+  play: async ({ canvas }) => {
+    const toast = canvas.getByRole("status");
+    await expect(toast).toBeInTheDocument();
+    await expect(toast).toHaveTextContent("Something happened");
+    // Verify dismiss button exists
+    const dismiss = canvas.getByLabelText("Dismiss notification");
+    await expect(dismiss).toBeInTheDocument();
+  },
+};
+
+/** Success toast notification. */
+export const Success: Story = {
+  args: {
+    toast: { id: "t-success", message: "Changes saved", variant: "success", duration: TEST_DURATION },
+  },
+  play: async ({ canvas }) => {
+    const toast = canvas.getByRole("status");
+    await expect(toast).toBeInTheDocument();
+    await expect(toast).toHaveTextContent("Changes saved");
+    await expect(toast.className).toContain("success");
+  },
+};
+
+/** Error toast notification. */
+export const Error: Story = {
+  args: {
+    toast: { id: "t-error", message: "Failed to save", variant: "error", duration: TEST_DURATION },
+  },
+  play: async ({ canvas }) => {
+    const toast = canvas.getByRole("status");
+    await expect(toast).toBeInTheDocument();
+    await expect(toast).toHaveTextContent("Failed to save");
+    await expect(toast.className).toContain("error");
+  },
+};
+
+/** Warning toast notification. */
+export const Warning: Story = {
+  args: {
+    toast: { id: "t-warn", message: "Connection unstable", variant: "warning", duration: TEST_DURATION },
+  },
+  play: async ({ canvas }) => {
+    const toast = canvas.getByRole("status");
+    await expect(toast).toBeInTheDocument();
+    await expect(toast).toHaveTextContent("Connection unstable");
+    await expect(toast.className).toContain("warning");
+  },
+};

package/src/components/notifications/Toast.tsx

@@ -0,0 +1,51 @@
+import { useEffect, type ReactNode, type JSX } from "react";
+import { AlertTriangle, Check, Info, X } from "lucide-react";
+import { motion } from "motion/react";
+import type { ToastItem } from "../../context/ToastContext.js";
+import styles from "./Toast.module.scss";
+import { ICON_LG, ICON_MD } from "../../utils/iconSize.js";
+
+const VARIANT_ICONS: Record<ToastItem["variant"], ReactNode> = {
+  success: <Check size={ICON_LG} />,
+  error: <X size={ICON_LG} />,
+  warning: <AlertTriangle size={ICON_LG} />,
+  info: <Info size={ICON_LG} />,
+};
+
+interface ToastProps {
+  toast: ToastItem;
+  onDismiss: (id: string) => void;
+}
+
+/** Animated individual toast notification. Auto-dismisses after toast.duration ms. */
+export function Toast({ toast, onDismiss }: ToastProps): JSX.Element {
+  useEffect(() => {
+    const timer = setTimeout(() => onDismiss(toast.id), toast.duration);
+    return () => clearTimeout(timer);
+  }, [toast.id, toast.duration, onDismiss]);
+
+  return (
+    <motion.div
+      className={`${styles.toast} ${styles[toast.variant]}`}
+      role="status"
+      initial={{ opacity: 0, y: -16, scale: 0.94 }}
+      animate={{ opacity: 1, y: 0, scale: 1 }}
+      exit={{ opacity: 0, y: -8, scale: 0.94 }}
+      transition={{ duration: 0.2, ease: "easeOut" }}
+      layout
+    >
+      <span className={styles.icon} aria-hidden="true">
+        {VARIANT_ICONS[toast.variant]}
+      </span>
+      <span className={styles.message}>{toast.message}</span>
+      <button
+        type="button"
+        className={styles.close}
+        onClick={() => onDismiss(toast.id)}
+        aria-label="Dismiss notification"
+      >
+        <X size={ICON_MD} aria-hidden="true" />
+      </button>
+    </motion.div>
+  );
+}

package/src/components/notifications/ToastContainer.module.scss

@@ -0,0 +1,23 @@
+// =============================================================================
+// ToastContainer — fixed overlay at top-center for stacking toast notifications
+// =============================================================================
+
+.container {
+  position: fixed;
+  top: var(--space-xl);
+  left: 50%;
+  transform: translateX(-50%);
+  // Keep below ConfirmDialog modal overlay (z-index: 1000) so toasts cannot
+  // be interacted with while a blocking modal is open.
+  z-index: 900;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+  align-items: center;
+  // Container itself is transparent to mouse events; individual toasts are not
+  pointer-events: none;
+
+  > * {
+    pointer-events: auto;
+  }
+}

package/src/components/notifications/ToastContainer.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { ToastContainer } from "./ToastContainer.js";
+
+/** Very long duration to prevent auto-dismiss during testing. */
+const TEST_DURATION: number = 999999;
+
+const meta: Meta<typeof ToastContainer> = {
+  component: ToastContainer,
+  title: "Primitives/Notifications/ToastContainer",
+  tags: ["autodocs"],
+  args: {
+    onDismiss: fn(),
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Empty container with no toasts. */
+export const Empty: Story = {
+  args: {
+    toasts: [],
+  },
+  play: async ({ canvas }) => {
+    const container = canvas.getByTestId("toast-container");
+    await expect(container).toBeInTheDocument();
+    // No toast items visible
+    const statuses = canvas.queryAllByRole("status");
+    await expect(statuses.length).toBe(0);
+  },
+};
+
+/** Container with a single toast. */
+export const SingleToast: Story = {
+  args: {
+    toasts: [
+      { id: "t1", message: "File saved", variant: "success", duration: TEST_DURATION },
+    ],
+  },
+  play: async ({ canvas }) => {
+    const container = canvas.getByTestId("toast-container");
+    await expect(container).toBeInTheDocument();
+    const toast = canvas.getByRole("status");
+    await expect(toast).toHaveTextContent("File saved");
+  },
+};
+
+/** Container rendering multiple toasts simultaneously. */
+export const MultipleToasts: Story = {
+  args: {
+    toasts: [
+      { id: "t1", message: "First toast", variant: "info", duration: TEST_DURATION },
+      { id: "t2", message: "Second toast", variant: "success", duration: TEST_DURATION },
+      { id: "t3", message: "Third toast", variant: "error", duration: TEST_DURATION },
+    ],
+  },
+  play: async ({ canvas }) => {
+    const container = canvas.getByTestId("toast-container");
+    await expect(container).toBeInTheDocument();
+    const statuses = canvas.getAllByRole("status");
+    await expect(statuses.length).toBe(3);
+    await expect(canvas.getByText("First toast")).toBeInTheDocument();
+    await expect(canvas.getByText("Second toast")).toBeInTheDocument();
+    await expect(canvas.getByText("Third toast")).toBeInTheDocument();
+  },
+};

package/src/components/notifications/ToastContainer.tsx

@@ -0,0 +1,29 @@
+import { AnimatePresence } from "motion/react";
+import type { JSX } from "react";
+import type { ToastItem } from "../../context/ToastContext.js";
+import { Toast } from "./Toast.js";
+import styles from "./ToastContainer.module.scss";
+
+/** Props for the ToastContainer component. */
+export interface ToastContainerProps {
+  /** Active toast notifications to render. */
+  toasts: ToastItem[];
+  /** Callback to dismiss a toast by id. */
+  onDismiss: (id: string) => void;
+}
+
+/**
+ * Fixed overlay that renders all active toasts at the top-center of the viewport.
+ * Mount this once alongside your main app layout and pass toasts from context.
+ */
+export function ToastContainer({ toasts, onDismiss }: ToastContainerProps): JSX.Element {
+  return (
+    <div className={styles.container} data-testid="toast-container">
+      <AnimatePresence>
+        {toasts.map((toast) => (
+          <Toast key={toast.id} toast={toast} onDismiss={onDismiss} />
+        ))}
+      </AnimatePresence>
+    </div>
+  );
+}

package/src/components/notifications/UpdateBanner.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, userEvent, within } from "@storybook/test";
+import { UpdateBanner } from "./UpdateBanner.js";
+
+const meta: Meta<typeof UpdateBanner> = {
+  title: "App/Notifications/UpdateBanner",
+  component: UpdateBanner,
+};
+
+export default meta;
+type Story = StoryObj<typeof UpdateBanner>;
+
+/** npm user sees an update available with install instructions. */
+export const NpmUpdate: Story = {
+  args: {
+    currentVersion: "0.76.0",
+    latestVersion: "0.77.0",
+    updateAvailable: true,
+    isDocker: false,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId("update-banner")).toBeInTheDocument();
+    await expect(canvas.getByText(/npm install/)).toBeInTheDocument();
+  },
+};
+
+/** Docker user sees an update available with pull instructions. */
+export const DockerUpdate: Story = {
+  args: {
+    currentVersion: "0.76.0",
+    latestVersion: "0.77.0",
+    updateAvailable: true,
+    isDocker: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId("update-banner")).toBeInTheDocument();
+    await expect(canvas.getByText(/docker pull/)).toBeInTheDocument();
+  },
+};
+
+/** No update available — banner is hidden. */
+export const NoUpdate: Story = {
+  args: {
+    currentVersion: "0.76.0",
+    latestVersion: "0.76.0",
+    updateAvailable: false,
+    isDocker: false,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByTestId("update-banner")).not.toBeInTheDocument();
+  },
+};
+
+/** User dismisses the banner — Callout hides its content after clicking the close button. */
+export const Dismissed: Story = {
+  args: {
+    currentVersion: "0.76.0",
+    latestVersion: "0.77.0",
+    updateAvailable: true,
+    isDocker: false,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const banner = canvas.getByTestId("update-banner");
+    await expect(banner).toBeInTheDocument();
+
+    // Click dismiss — Callout hides its content via internal state
+    const dismissButton = canvas.getByLabelText("Dismiss");
+    await userEvent.click(dismissButton);
+
+    // After dismiss, the Callout renders empty — verify the info text is gone
+    await expect(canvas.queryByText(/0\.77\.0/)).toBeNull();
+  },
+};