npm - @terpjs/react-core - Versions diffs - 0.1.0 - Mend

@terpjs/react-core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (154) hide show

package/README.md +190 -0
package/package.json +44 -0
package/src/AppShell.test.tsx +152 -0
package/src/AppShell.tsx +554 -0
package/src/Authorized.test.tsx +60 -0
package/src/Authorized.tsx +21 -0
package/src/Breadcrumbs.test.tsx +45 -0
package/src/Breadcrumbs.tsx +110 -0
package/src/ConfirmDialog.tsx +170 -0
package/src/DetailPage.tsx +28 -0
package/src/EmptyState.tsx +74 -0
package/src/ErrorState.tsx +108 -0
package/src/Field.test.tsx +53 -0
package/src/Field.tsx +51 -0
package/src/HubPage.test.tsx +108 -0
package/src/HubPage.tsx +204 -0
package/src/LoadingState.test.tsx +40 -0
package/src/LoadingState.tsx +96 -0
package/src/LoginView.test.tsx +57 -0
package/src/LoginView.tsx +203 -0
package/src/ModuleNav.test.tsx +96 -0
package/src/ModuleNav.tsx +88 -0
package/src/OverviewPage.tsx +26 -0
package/src/Page.test.tsx +147 -0
package/src/Page.tsx +158 -0
package/src/PageActions.test.tsx +104 -0
package/src/PageActions.tsx +72 -0
package/src/ProfileView.test.tsx +112 -0
package/src/ProfileView.tsx +84 -0
package/src/RequireAuth.test.tsx +89 -0
package/src/RequireAuth.tsx +22 -0
package/src/ResourceList.test.tsx +176 -0
package/src/ResourceList.tsx +123 -0
package/src/TerpProvider.tsx +320 -0
package/src/UserMenu.test.tsx +166 -0
package/src/UserMenu.tsx +125 -0
package/src/admin/AdminHub.tsx +108 -0
package/src/admin/AuditLogAdmin.tsx +116 -0
package/src/admin/GroupCreate.tsx +90 -0
package/src/admin/GroupDetail.tsx +446 -0
package/src/admin/GroupsAdmin.tsx +109 -0
package/src/admin/UserCreate.tsx +115 -0
package/src/admin/UserDetail.tsx +228 -0
package/src/admin/UsersAdmin.tsx +111 -0
package/src/admin/admin.test.tsx +537 -0
package/src/admin/crumbs.tsx +14 -0
package/src/admin/module.tsx +51 -0
package/src/admin/roles.ts +19 -0
package/src/bootstrap.test.tsx +67 -0
package/src/bootstrap.tsx +270 -0
package/src/capabilities.test.ts +24 -0
package/src/capabilities.ts +26 -0
package/src/createAuthClient.test.ts +176 -0
package/src/createAuthClient.ts +105 -0
package/src/dataview/DataView.test.tsx +392 -0
package/src/dataview/DataView.tsx +467 -0
package/src/dataview/DataViewCardList.tsx +189 -0
package/src/dataview/DataViewColumnSettings.tsx +118 -0
package/src/dataview/DataViewExpandableRow.tsx +67 -0
package/src/dataview/DataViewPagination.tsx +113 -0
package/src/dataview/DataViewRowActions.tsx +131 -0
package/src/dataview/DataViewTable.tsx +359 -0
package/src/dataview/DataViewToolbar.tsx +260 -0
package/src/dataview/README.md +138 -0
package/src/dataview/glyphs.tsx +175 -0
package/src/dataview/hooks/hooks.test.tsx +240 -0
package/src/dataview/hooks/useDataViewQuery.ts +72 -0
package/src/dataview/hooks/useDataViewState.ts +310 -0
package/src/dataview/hooks/useServerDataView.ts +154 -0
package/src/dataview/hooks/useViewSearch.ts +68 -0
package/src/dataview/index.ts +62 -0
package/src/dataview/internal.tsx +96 -0
package/src/dataview/repositories/HttpDataViewRepository.ts +110 -0
package/src/dataview/repositories/InMemoryDataViewRepository.ts +145 -0
package/src/dataview/repositories/repositories.test.ts +158 -0
package/src/dataview/repositories/viewState.test.ts +90 -0
package/src/dataview/repositories/viewState.ts +128 -0
package/src/dataview/types.ts +249 -0
package/src/errorMessages.test.tsx +83 -0
package/src/errorMessages.tsx +79 -0
package/src/feedback.test.tsx +167 -0
package/src/files.test.tsx +142 -0
package/src/files.tsx +174 -0
package/src/icons.test.tsx +46 -0
package/src/icons.tsx +533 -0
package/src/index.ts +155 -0
package/src/layout.test.tsx +72 -0
package/src/layout.tsx +90 -0
package/src/layoutContract.test.tsx +179 -0
package/src/layoutContract.ts +137 -0
package/src/locale.test.tsx +97 -0
package/src/locale.tsx +246 -0
package/src/nav.test.ts +21 -0
package/src/nav.ts +13 -0
package/src/pageMarker.ts +15 -0
package/src/raw.d.ts +7 -0
package/src/realtime-hook.test.tsx +226 -0
package/src/realtime.test.ts +44 -0
package/src/realtime.ts +307 -0
package/src/refresh-session.test.tsx +114 -0
package/src/revocation.test.tsx +81 -0
package/src/router.test.tsx +307 -0
package/src/router.tsx +222 -0
package/src/sso.test.tsx +128 -0
package/src/sso.ts +142 -0
package/src/ssr.test.tsx +45 -0
package/src/styles.test.ts +21 -0
package/src/styles.ts +302 -0
package/src/theme.test.tsx +74 -0
package/src/theme.tsx +143 -0
package/src/toast.test.tsx +94 -0
package/src/toast.tsx +214 -0
package/src/tokens.guard.test.ts +51 -0
package/src/ui/Alert.test.tsx +19 -0
package/src/ui/Alert.tsx +115 -0
package/src/ui/Badge.test.tsx +14 -0
package/src/ui/Badge.tsx +48 -0
package/src/ui/Button.test.tsx +36 -0
package/src/ui/Button.tsx +95 -0
package/src/ui/Card.test.tsx +40 -0
package/src/ui/Card.tsx +92 -0
package/src/ui/Checkbox.test.tsx +17 -0
package/src/ui/Checkbox.tsx +51 -0
package/src/ui/Combobox.test.tsx +58 -0
package/src/ui/Combobox.tsx +313 -0
package/src/ui/DatePicker.test.tsx +60 -0
package/src/ui/DatePicker.tsx +421 -0
package/src/ui/Input.tsx +30 -0
package/src/ui/Markdown.test.tsx +32 -0
package/src/ui/Markdown.tsx +213 -0
package/src/ui/Menu.test.tsx +85 -0
package/src/ui/Menu.tsx +216 -0
package/src/ui/Popover.tsx +218 -0
package/src/ui/Radio.test.tsx +29 -0
package/src/ui/Radio.tsx +127 -0
package/src/ui/Select.tsx +40 -0
package/src/ui/Switch.test.tsx +17 -0
package/src/ui/Switch.tsx +53 -0
package/src/ui/Tabs.test.tsx +29 -0
package/src/ui/Tabs.tsx +128 -0
package/src/ui/Textarea.tsx +27 -0
package/src/ui/Tooltip.test.tsx +28 -0
package/src/ui/Tooltip.tsx +67 -0
package/src/ui/controlStyles.ts +9 -0
package/src/uiText.test.tsx +93 -0
package/src/uiText.tsx +342 -0
package/src/unwrap.test.ts +67 -0
package/src/unwrap.ts +101 -0
package/src/useResource.test.tsx +118 -0
package/src/useResource.ts +110 -0
package/src/useTerpClient.test.ts +35 -0
package/tsconfig.json +17 -0
package/vite.config.ts +14 -0
package/vitest.setup.ts +58 -0

package/src/theme.tsx ADDED Viewed

@@ -0,0 +1,143 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { Icon } from "./icons";
+import { Menu, MenuItem } from "./ui/Menu";
+import { useStrings } from "./uiText";
+/**
+ * The visual theme: an explicit choice, or "system" to follow the OS preference.
+ * The token stylesheet (`@terpjs/contract/tokens.css`) carries both palettes: it applies
+ * the dark colours under `<html data-theme="dark">` and — with no attribute — under
+ * `@media (prefers-color-scheme: dark)`, so "system" simply removes the attribute.
+ */
+export type Theme = "light" | "dark" | "system";
+const THEMES: readonly Theme[] = ["light", "dark", "system"];
+const THEME_ICONS: Record<Theme, string> = {
+  light: "sun",
+  dark: "moon",
+  system: "monitor",
+};
+/** The `localStorage` key {@link ThemeProvider} persists the choice under. */
+export const THEME_STORAGE_KEY = "terp.theme";
+interface ThemeContextValue {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+}
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+function readStoredTheme(): Theme {
+  try {
+    const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+    return THEMES.includes(stored as Theme) ? (stored as Theme) : "system";
+  } catch {
+    return "system";
+  }
+}
+export interface ThemeProviderProps {
+  /** Starting theme when the user has not chosen one yet; default "system". */
+  defaultTheme?: Theme;
+  children: ReactNode;
+}
+/**
+ * Owns the light/dark theme choice: applies it as `data-theme` on `<html>` (the token
+ * stylesheet does the rest — no component changes anywhere) and persists it in
+ * `localStorage`. `renderTerpApp` mounts one for every app; pair with {@link ThemeToggle}
+ * (the default {@link UserMenu} already includes it).
+ */
+export function ThemeProvider({ defaultTheme = "system", children }: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    const stored = readStoredTheme();
+    return stored === "system" ? defaultTheme : stored;
+  });
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === "system") {
+      root.removeAttribute("data-theme");
+    } else {
+      root.setAttribute("data-theme", theme);
+    }
+  }, [theme]);
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next);
+    try {
+      window.localStorage.setItem(THEME_STORAGE_KEY, next);
+    } catch {
+      // Private mode / quota: the choice still applies for this session.
+    }
+  }, []);
+  const value = useMemo(() => ({ theme, setTheme }), [theme, setTheme]);
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+/** The active theme + setter, or `null` outside a {@link ThemeProvider}. */
+export function useTheme(): ThemeContextValue | null {
+  return useContext(ThemeContext);
+}
+export interface ThemeToggleProps {
+  /**
+   * `"stacked"` (default) renders a labelled icon menu for settings panels;
+   * `"inline"` renders only the compact icon trigger used by the shell header.
+   */
+  variant?: "stacked" | "inline";
+}
+/**
+ * The standard theme control: a token-themed light/dark/system menu. Renders nothing
+ * outside a {@link ThemeProvider}, so shared chrome (the shell header) can
+ * include it unconditionally.
+ */
+export function ThemeToggle({ variant = "stacked" }: ThemeToggleProps) {
+  const context = useTheme();
+  const strings = useStrings();
+  if (context === null) {
+    return null;
+  }
+  const labels: Record<Theme, string> = {
+    light: strings.themeLight,
+    dark: strings.themeDark,
+    system: strings.themeSystem,
+  };
+  const menu = (
+    <Menu
+      trigger={<Icon name={THEME_ICONS[context.theme]} size="1.15rem" />}
+      triggerLabel={strings.theme}
+    >
+      {({ close }) => (
+        <>
+          {THEMES.map((theme) => (
+            <MenuItem
+              key={theme}
+              label={labels[theme]}
+              icon={<Icon name={THEME_ICONS[theme]} />}
+              selected={theme === context.theme}
+              onSelect={() => {
+                context.setTheme(theme);
+                close(true);
+              }}
+            />
+          ))}
+        </>
+      )}
+    </Menu>
+  );
+  if (variant === "inline") {
+    return menu;
+  }
+  return (
+    <div style={{ display: "grid", justifyItems: "start", gap: "var(--space-1)", fontSize: "var(--font-size-sm)" }}>
+      <span style={{ color: "var(--color-neutral-600)" }}>{strings.theme}</span>
+      {menu}
+    </div>
+  );
+}

package/src/toast.test.tsx ADDED Viewed

@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ToastProvider, useToast } from "./toast";
+import { UiTextProvider } from "./uiText";
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+function Trigger() {
+  const toast = useToast();
+  return (
+    <div>
+      <button onClick={() => toast.success("Task created.")}>success</button>
+      <button onClick={() => toast.error("Save failed.")}>error</button>
+      <button onClick={() => toast.warning("Rows skipped.", { durationMs: 1000 })}>
+        warning
+      </button>
+    </div>
+  );
+}
+describe("useToast / ToastProvider", () => {
+  it("throws without a provider (fail closed)", () => {
+    expect(() => render(<Trigger />)).toThrow(/ToastProvider/);
+  });
+  it("shows a polite success toast with the default title", () => {
+    render(
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>,
+    );
+    fireEvent.click(screen.getByText("success"));
+    const toast = screen.getByRole("status");
+    expect(toast).toHaveTextContent("Success");
+    expect(toast).toHaveTextContent("Task created.");
+  });
+  it("announces error and warning toasts assertively with localisable titles", () => {
+    render(
+      <UiTextProvider strings={{ errorTitle: "Mislukt", warningTitle: "Waarschuwing" }}>
+        <ToastProvider>
+          <Trigger />
+        </ToastProvider>
+      </UiTextProvider>,
+    );
+    fireEvent.click(screen.getByText("error"));
+    fireEvent.click(screen.getByText("warning"));
+    const alerts = screen.getAllByRole("alert");
+    expect(alerts[0]).toHaveTextContent("Mislukt");
+    expect(alerts[0]).toHaveTextContent("Save failed.");
+    expect(alerts[1]).toHaveTextContent("Waarschuwing");
+    expect(alerts[1]).toHaveTextContent("Rows skipped.");
+  });
+  it("dismisses via the dismiss button", () => {
+    render(
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>,
+    );
+    fireEvent.click(screen.getByText("success"));
+    fireEvent.click(screen.getByLabelText("Dismiss"));
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+  it("auto-dismisses after the configured duration", () => {
+    vi.useFakeTimers();
+    render(
+      <ToastProvider>
+        <Trigger />
+      </ToastProvider>,
+    );
+    fireEvent.click(screen.getByText("warning"));
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+});

package/src/toast.tsx ADDED Viewed

@@ -0,0 +1,214 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import type { CSSProperties, ReactNode } from "react";
+import { Icon } from "./icons";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+export type ToastVariant = "success" | "error" | "warning";
+export interface ToastOptions {
+  /** Override the variant's default title string. */
+  title?: UiText;
+  /** Auto-dismiss delay in milliseconds; default 5000. */
+  durationMs?: number;
+}
+/** Imperative toast API returned by {@link useToast}. */
+export interface ToastApi {
+  /** Confirmation after a mutation settles ("Task created."). */
+  success: (description: ReactNode, options?: ToastOptions) => void;
+  /** Failure of a background or submitted action. */
+  error: (description: ReactNode, options?: ToastOptions) => void;
+  /** Non-blocking caution ("Some rows were skipped."). */
+  warning: (description: ReactNode, options?: ToastOptions) => void;
+}
+interface ToastItem {
+  id: number;
+  variant: ToastVariant;
+  title: UiText | undefined;
+  description: ReactNode;
+  durationMs: number;
+}
+const ToastContext = createContext<ToastApi | null>(null);
+const DEFAULT_DURATION_MS = 5000;
+const viewportStyle: CSSProperties = {
+  position: "fixed",
+  bottom: "var(--space-4)",
+  right: "var(--space-4)",
+  display: "grid",
+  gap: "var(--space-2)",
+  zIndex: 100,
+  maxWidth: "min(22.5rem, calc(100vw - 2 * var(--space-4)))",
+};
+const toastStyle = (variant: ToastVariant): CSSProperties => ({
+  display: "grid",
+  gridTemplateColumns: "auto 1fr auto",
+  alignItems: "start",
+  gap: "var(--space-2)",
+  padding: "var(--space-3) var(--space-4)",
+  borderRadius: "var(--radius-md)",
+  border: `1px solid ${borderColor[variant]}`,
+  borderInlineStart: `3px solid ${titleColor[variant]}`,
+  background: "var(--color-neutral-0)",
+  color: "var(--color-neutral-900)",
+  fontSize: "var(--font-size-sm)",
+  boxShadow: "var(--shadow-md)",
+});
+const titleColor: Record<ToastVariant, string> = {
+  success: "var(--color-status-success)",
+  error: "var(--color-status-danger)",
+  warning: "var(--color-status-warning)",
+};
+const borderColor: Record<ToastVariant, string> = {
+  success: "var(--color-status-success-soft)",
+  error: "var(--color-status-danger-soft)",
+  warning: "var(--color-status-warning-soft)",
+};
+const iconName: Record<ToastVariant, string> = {
+  success: "check",
+  error: "x",
+  warning: "bell",
+};
+const iconWrapStyle = (variant: ToastVariant): CSSProperties => ({
+  color: titleColor[variant],
+  display: "inline-flex",
+  alignItems: "center",
+  paddingTop: "2px",
+});
+const dismissStyle: CSSProperties = {
+  border: "none",
+  background: "none",
+  padding: "var(--space-1)",
+  cursor: "pointer",
+  color: "var(--color-neutral-500)",
+  fontSize: "var(--font-size-base)",
+  lineHeight: 1,
+  borderRadius: "var(--radius-sm)",
+};
+function ToastCard({ toast, onDismiss }: { toast: ToastItem; onDismiss: () => void }) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  const defaultTitle: Record<ToastVariant, string> = {
+    success: strings.successTitle,
+    error: strings.errorTitle,
+    warning: strings.warningTitle,
+  };
+  return (
+    <div role={toast.variant === "success" ? "status" : "alert"} style={toastStyle(toast.variant)}>
+      <span aria-hidden="true" style={iconWrapStyle(toast.variant)}>
+        <Icon name={iconName[toast.variant]} size="1.1rem" />
+      </span>
+      <div style={{ display: "grid", gap: "var(--space-1)" }}>
+        <strong
+          style={{
+            color: titleColor[toast.variant],
+            fontWeight: "var(--font-weight-semibold)" as never,
+          }}
+        >
+          {resolve(toast.title ?? defaultTitle[toast.variant])}
+        </strong>
+        {toast.description !== null && toast.description !== undefined && (
+          <div>{toast.description}</div>
+        )}
+      </div>
+      <button
+        type="button"
+        data-terp="iconbutton"
+        aria-label={strings.dismiss}
+        style={dismissStyle}
+        onClick={onDismiss}
+      >
+        ×
+      </button>
+    </div>
+  );
+}
+export interface ToastProviderProps {
+  children: ReactNode;
+}
+/**
+ * Hosts the toast queue and renders the fixed viewport. `renderTerpApp` mounts
+ * one automatically; wrap your tree yourself when composing providers manually.
+ * Toasts auto-dismiss (default 5s) and can always be dismissed by hand; success
+ * announces politely (`status`), error and warning assertively (`alert`).
+ */
+export function ToastProvider({ children }: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const nextId = useRef(0);
+  const timers = useRef(new Map<number, ReturnType<typeof setTimeout>>());
+  const dismiss = useCallback((id: number) => {
+    const timer = timers.current.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timers.current.delete(id);
+    }
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, []);
+  const push = useCallback(
+    (variant: ToastVariant, description: ReactNode, options?: ToastOptions) => {
+      const id = nextId.current++;
+      const durationMs = options?.durationMs ?? DEFAULT_DURATION_MS;
+      setToasts((current) => [
+        ...current,
+        { id, variant, title: options?.title, description, durationMs },
+      ]);
+      timers.current.set(
+        id,
+        setTimeout(() => dismiss(id), durationMs),
+      );
+    },
+    [dismiss],
+  );
+  const api = useMemo<ToastApi>(
+    () => ({
+      success: (description, options) => push("success", description, options),
+      error: (description, options) => push("error", description, options),
+      warning: (description, options) => push("warning", description, options),
+    }),
+    [push],
+  );
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      {toasts.length > 0 && (
+        <div style={viewportStyle}>
+          {toasts.map((toast) => (
+            <ToastCard key={toast.id} toast={toast} onDismiss={() => dismiss(toast.id)} />
+          ))}
+        </div>
+      )}
+    </ToastContext.Provider>
+  );
+}
+/**
+ * The standard transient-feedback channel: call after mutations settle instead
+ * of ad-hoc banners or `alert()`. Titles default to the framework strings
+ * (`successTitle` / `errorTitle` / `warningTitle`) so feedback reads the same
+ * platform-wide. Throws when no {@link ToastProvider} is mounted (fail closed).
+ */
+export function useToast(): ToastApi {
+  const api = useContext(ToastContext);
+  if (api === null) {
+    throw new Error("useToast must be used within a <ToastProvider>.");
+  }
+  return api;
+}

package/src/tokens.guard.test.ts ADDED Viewed

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+// Vitest stubs .css imports to empty modules, so the sheet is read from disk.
+const tokensCss = readFileSync(
+  new URL("../../contract/src/tokens.css", import.meta.url),
+  "utf-8",
+);
+// Typed locally so the package keeps its deliberate `"types": []` isolation:
+// react-core source must never see ambient Node globals. The source scan uses
+// Vite's raw glob; only the CSS sheet needs fs (declared minimally in raw.d.ts).
+declare global {
+  interface ImportMeta {
+    glob: (
+      pattern: string,
+      options: { query: "?raw"; import: "default"; eager: true },
+    ) => Record<string, string>;
+  }
+}
+const sources = import.meta.glob("./**/*.{ts,tsx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+});
+/** Every custom property the token sheet declares (any palette block). */
+const declared = new Set(
+  [...tokensCss.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1]!),
+);
+describe("design tokens", () => {
+  it("only references custom properties the contract token sheet declares", () => {
+    // A fallback-less var() against an undeclared token silently computes to the
+    // inherited/initial value — the exact class of bug this guard pins down
+    // (e.g. a font-weight token typo reintroducing parent-font inheritance).
+    expect(declared.size).toBeGreaterThan(0);
+    expect(Object.keys(sources).length).toBeGreaterThan(0);
+    const offenders: string[] = [];
+    for (const [file, text] of Object.entries(sources)) {
+      for (const match of text.matchAll(/var\((--[a-z0-9-]+)\)/g)) {
+        const token = match[1]!;
+        if (!declared.has(token)) {
+          offenders.push(`${file}: ${token}`);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/ui/Alert.test.tsx ADDED Viewed

@@ -0,0 +1,19 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { Alert } from "./Alert";
+afterEach(cleanup);
+describe("Alert", () => {
+  it("uses status for informational banners", () => {
+    render(<Alert title="Saved">All changes persisted.</Alert>);
+    expect(screen.getByRole("status")).toHaveTextContent("Saved");
+  });
+  it("uses alert for dangerous banners", () => {
+    render(<Alert tone="danger">Delete failed.</Alert>);
+    expect(screen.getByRole("alert")).toHaveTextContent("Delete failed.");
+  });
+});

package/src/ui/Alert.tsx ADDED Viewed

@@ -0,0 +1,115 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+import type { BadgeTone } from "./Badge";
+export type AlertTone = BadgeTone;
+export interface AlertProps {
+  tone?: AlertTone;
+  title?: UiText;
+  children: ReactNode;
+}
+const toneColor: Record<AlertTone, string> = {
+  neutral: "var(--color-neutral-600)",
+  info: "var(--color-status-info)",
+  success: "var(--color-status-success)",
+  warning: "var(--color-status-warning)",
+  danger: "var(--color-status-danger)",
+};
+const toneSoft: Record<AlertTone, string> = {
+  neutral: "var(--color-neutral-50)",
+  info: "var(--color-status-info-soft)",
+  success: "var(--color-status-success-soft)",
+  warning: "var(--color-status-warning-soft)",
+  danger: "var(--color-status-danger-soft)",
+};
+const alertStyle = (tone: AlertTone): CSSProperties => ({
+  display: "grid",
+  gridTemplateColumns: "auto 1fr",
+  gap: "var(--space-3)",
+  padding: "var(--space-3) var(--space-4)",
+  border: `1px solid ${toneColor[tone]}`,
+  borderRadius: "var(--radius-md)",
+  color: "var(--color-neutral-900)",
+  background: toneSoft[tone],
+});
+const iconWrapStyle = (tone: AlertTone): CSSProperties => ({
+  color: toneColor[tone],
+  display: "inline-flex",
+  alignItems: "flex-start",
+  paddingTop: "2px",
+});
+const bodyStyle: CSSProperties = { display: "grid", gap: "var(--space-1)", minWidth: 0 };
+const titleStyle: CSSProperties = { fontWeight: "var(--font-weight-semibold)" as never };
+const glyphProps = {
+  width: 20,
+  height: 20,
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 1.8,
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  "aria-hidden": true,
+  focusable: false,
+} as const;
+const toneIcon: Record<AlertTone, ReactNode> = {
+  neutral: (
+    <svg {...glyphProps}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 8h.01M11 12h1v5h1" />
+    </svg>
+  ),
+  info: (
+    <svg {...glyphProps}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 8h.01M11 12h1v5h1" />
+    </svg>
+  ),
+  success: (
+    <svg {...glyphProps}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="m8 12 3 3 5-6" />
+    </svg>
+  ),
+  warning: (
+    <svg {...glyphProps}>
+      <path d="M12 3 2.5 20.5h19L12 3Z" />
+      <path d="M12 10v5M12 18h.01" />
+    </svg>
+  ),
+  danger: (
+    <svg {...glyphProps}>
+      <path d="M17.5 3.5H6.5L3 7v10l3.5 3.5h11L21 17V7l-3.5-3.5Z" />
+      <path d="M12 8v5M12 16h.01" />
+    </svg>
+  ),
+};
+/** Inline banner for persistent feedback; warnings and errors announce as alerts. */
+export function Alert({ tone = "info", title, children }: AlertProps) {
+  const resolve = useUiText();
+  return (
+    <div
+      role={tone === "warning" || tone === "danger" ? "alert" : "status"}
+      data-terp="alert"
+      style={alertStyle(tone)}
+    >
+      <span style={iconWrapStyle(tone)}>{toneIcon[tone]}</span>
+      <div style={bodyStyle}>
+        {title !== undefined && <strong style={titleStyle}>{resolve(title)}</strong>}
+        <div>{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/ui/Badge.test.tsx ADDED Viewed

@@ -0,0 +1,14 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { Badge } from "./Badge";
+afterEach(cleanup);
+describe("Badge", () => {
+  it("renders a token-styled status pill", () => {
+    render(<Badge label="Active" tone="success" />);
+    expect(screen.getByText("Active").style.color).toContain("var(--color-status-success)");
+  });
+});