@checkstack/ui 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @checkstack/ui
 
+## 1.10.0
+
+### Minor Changes
+
+- f23f3c9: Add five additive shared UI primitives for list / query state surfaces:
+
+  - `ListEmptyState` - thin wrapper around `EmptyState` with the
+    canonical `"No {resource} yet"` headline and an `Inbox` default icon.
+  - `QueryErrorState` - inline error UI for failed queries; renders an
+    `error`-variant `Alert` with `extractErrorMessage` + a Retry button.
+  - `Skeleton` - pulsing placeholder block that drops its animation when
+    `usePerformance().isLowPower` is true.
+  - `ResponsiveTable` + `MobileCardList` - dual-layout pair for tabular
+    data that swaps to a stacked card layout below the `sm` breakpoint
+    (pure CSS, no JS media-query gating).
+  - `toastSuccess` / `toastError` - canonical verb-phrase and
+    `{action}: {message}` (truncated at 100 chars) toast helpers.
+
+  Each primitive ships with Storybook stories and unit tests. No
+  existing component or behaviour is changed - Phases 5-7 of the v1
+  polishing plan will retrofit consumer pages onto these primitives in
+  follow-up PRs. Phase 7 will use the existing `usePerformance()` hook
+  directly for low-power gating rather than introducing a separate
+  className-composition helper.
+
+### Patch Changes
+
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+  - @checkstack/common@0.11.0
+  - @checkstack/frontend-api@0.5.2
+
 ## 1.9.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ui",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",

package/src/components/ListEmptyState.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { Inbox } from "lucide-react";
+import { EmptyState } from "./EmptyState";
+
+interface ListEmptyStateProps {
+  /**
+   * The name of the resource type the list would display (e.g. `"checks"`,
+   * `"incidents"`). Drives the default `"No {resource} yet"` headline.
+   */
+  resource: string;
+  /**
+   * Optional supplemental description rendered beneath the headline.
+   */
+  description?: React.ReactNode;
+  /**
+   * Optional action area, typically a primary CTA button such as
+   * "Create your first check".
+   */
+  actions?: React.ReactNode;
+  /**
+   * Optional icon override. Defaults to the lucide `Inbox` glyph so callers
+   * don't have to pick one for every list.
+   */
+  icon?: React.ReactNode;
+}
+
+/**
+ * ListEmptyState - the canonical empty state for a list-shaped resource.
+ *
+ * Thin wrapper around {@link EmptyState} that supplies a consistent
+ * "No {resource} yet" headline and a sensible default icon. Use this on
+ * any page that renders a list and may have zero items so the UX stays
+ * uniform across plugins.
+ */
+export const ListEmptyState: React.FC<ListEmptyStateProps> = ({
+  resource,
+  description,
+  actions,
+  icon,
+}) => {
+  const resolvedIcon = icon ?? <Inbox className="h-10 w-10" />;
+
+  return (
+    <EmptyState
+      title={`No ${resource} yet`}
+      description={description}
+      icon={resolvedIcon}
+      actions={actions}
+    />
+  );
+};

package/src/components/QueryErrorState.tsx

@@ -0,0 +1,64 @@
+import React from "react";
+import { AlertCircle } from "lucide-react";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  Alert,
+  AlertContent,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+} from "./Alert";
+import { Button } from "./Button";
+
+interface QueryErrorStateProps {
+  /**
+   * The error captured from a failed query (e.g. TanStack Query's `error`).
+   * Funnelled through {@link extractErrorMessage} so callers don't have to
+   * narrow the type at every call site.
+   */
+  error: unknown;
+  /**
+   * Invoked when the user clicks the "Retry" button. Wire this to the
+   * underlying `refetch()` of the failing query.
+   */
+  onRetry: () => void;
+  /**
+   * Optional resource name to personalise the headline, e.g.
+   * `resource="checks"` -> "Could not load checks".
+   */
+  resource?: string;
+}
+
+/**
+ * QueryErrorState - canonical inline error UI for failed list / detail
+ * queries. Renders an `error`-variant {@link Alert} with the extracted
+ * error message and a Retry button.
+ */
+export const QueryErrorState: React.FC<QueryErrorStateProps> = ({
+  error,
+  onRetry,
+  resource,
+}) => {
+  const message = extractErrorMessage(error);
+  const title = resource ? `Could not load ${resource}` : "Something went wrong";
+
+  return (
+    <Alert variant="error">
+      <AlertIcon>
+        <AlertCircle className="h-4 w-4" />
+      </AlertIcon>
+      <AlertContent>
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </AlertContent>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={onRetry}
+        className="shrink-0"
+      >
+        Retry
+      </Button>
+    </Alert>
+  );
+};

package/src/components/ResponsiveTable.tsx

@@ -0,0 +1,92 @@
+/**
+ * ResponsiveTable - dual-layout primitive for tabular data that must
+ * degrade gracefully on narrow viewports.
+ *
+ * # API decision
+ *
+ * The original plan considered a context-driven `priority` prop on a
+ * special `ResponsiveTableHead` so cells could declare which columns
+ * disappear on mobile. Implementing that without `any` requires either
+ * (a) cloning every `TableCell` child to inject a context-derived
+ * `data-priority` attribute, or (b) maintaining a parallel index of
+ * `TableHead` children to wire their priorities into the cells by
+ * position. Both shapes leak the matching responsibility into the
+ * primitive and produce gnarly typings around the `Table*` re-exports.
+ *
+ * Instead this file ships the simpler, fully type-safe fallback:
+ *
+ *   - `<ResponsiveTable>` - a wrapper that renders its children inside
+ *     the standard {@link Table} layout on `sm` viewports and up, and
+ *     hides them on smaller screens.
+ *   - `<MobileCardList>` - a sibling wrapper consumers render alongside
+ *     the table. It is only visible below `sm`, so callers compose the
+ *     two side-by-side and decide per-row what the mobile presentation
+ *     looks like (typically a stacked card with high-priority fields).
+ *
+ * The two wrappers use Tailwind's `hidden sm:block` / `sm:hidden`
+ * utilities, so they swap purely in CSS - no JS media-query gating, no
+ * SSR/CSR mismatch risk, and consumers keep full control over which
+ * fields surface on mobile.
+ *
+ * Re-export the standard `Table*` primitives from `@checkstack/ui` for
+ * the desktop branch; do NOT use `<table>` markup inside
+ * `<MobileCardList>`.
+ */
+import React from "react";
+import { cn } from "../utils";
+
+interface ResponsiveTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The desktop tabular layout. Compose with the existing `Table`,
+   * `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`
+   * primitives.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Desktop branch of the dual-layout pattern. Hidden below the `sm`
+ * breakpoint; render a {@link MobileCardList} alongside it to cover
+ * narrow viewports.
+ */
+export const ResponsiveTable = React.forwardRef<
+  HTMLDivElement,
+  ResponsiveTableProps
+>(({ children, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("hidden sm:block", className)}
+    {...props}
+  >
+    {children}
+  </div>
+));
+
+ResponsiveTable.displayName = "ResponsiveTable";
+
+interface MobileCardListProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The stacked, card-shaped layout for narrow viewports. One item per
+   * row; consumers decide which fields are surfaced.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Mobile branch of the dual-layout pattern. Visible only below the `sm`
+ * breakpoint. Pairs with {@link ResponsiveTable}.
+ */
+export const MobileCardList = React.forwardRef<
+  HTMLDivElement,
+  MobileCardListProps
+>(({ children, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col gap-2 sm:hidden", className)}
+    {...props}
+  >
+    {children}
+  </div>
+));
+
+MobileCardList.displayName = "MobileCardList";

package/src/components/Skeleton.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+import { cn } from "../utils";
+import { usePerformance } from "./PerformanceProvider";
+
+interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Override the default sizing / shape. The component already renders a
+   * muted background; pass dimensions via classes like `h-4 w-32 rounded`.
+   */
+  className?: string;
+}
+
+/**
+ * Skeleton - a pulsing placeholder block for loading states.
+ *
+ * Honours {@link usePerformance}: when `isLowPower` is true the pulse
+ * animation is dropped, leaving a static `bg-muted` block so low-power
+ * devices aren't forced through an infinite animation loop.
+ */
+export const Skeleton = React.forwardRef<HTMLDivElement, SkeletonProps>(
+  ({ className, ...props }, ref) => {
+    const { isLowPower } = usePerformance();
+
+    return (
+      <div
+        ref={ref}
+        aria-hidden="true"
+        className={cn(
+          "rounded-md bg-muted",
+          !isLowPower && "animate-pulse",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+Skeleton.displayName = "Skeleton";

package/src/index.ts

@@ -64,3 +64,8 @@ export * from "./components/Sheet";
 export * from "./components/Popover";
 export * from "./hooks/useIsMobile";
 export * from "./hooks/useInitOnceForKey";
+export * from "./components/ListEmptyState";
+export * from "./components/QueryErrorState";
+export * from "./components/Skeleton";
+export * from "./components/ResponsiveTable";
+export * from "./utils/toastTemplates";

package/src/utils/toastTemplates.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, mock, beforeEach } from "bun:test";
+import {
+  toastError,
+  toastSuccess,
+  type ToastApi,
+} from "./toastTemplates";
+
+const makeToastMock = (): ToastApi => ({
+  show: mock(),
+  success: mock(),
+  error: mock(),
+  warning: mock(),
+  info: mock(),
+});
+
+describe("toastSuccess", () => {
+  let toast: ToastApi;
+
+  beforeEach(() => {
+    toast = makeToastMock();
+  });
+
+  it("passes the action through to toast.success", () => {
+    toastSuccess(toast, "Check created");
+
+    expect(toast.success).toHaveBeenCalledTimes(1);
+    expect(toast.success).toHaveBeenCalledWith("Check created");
+  });
+});
+
+describe("toastError", () => {
+  let toast: ToastApi;
+
+  beforeEach(() => {
+    toast = makeToastMock();
+  });
+
+  it("prefixes the action and includes the extracted error message", () => {
+    toastError(toast, "Failed to create check", new Error("Backend unreachable"));
+
+    expect(toast.error).toHaveBeenCalledTimes(1);
+    expect(toast.error).toHaveBeenCalledWith(
+      "Failed to create check: Backend unreachable",
+    );
+  });
+
+  it("uses the fallback message when error is not an Error or string", () => {
+    toastError(toast, "Failed to delete check", null);
+
+    expect(toast.error).toHaveBeenCalledWith(
+      "Failed to delete check: An error occurred",
+    );
+  });
+
+  it("accepts a string error and includes it verbatim", () => {
+    toastError(toast, "Save failed", "validation: bad payload");
+
+    expect(toast.error).toHaveBeenCalledWith(
+      "Save failed: validation: bad payload",
+    );
+  });
+
+  it("truncates the message to 100 characters with an ellipsis", () => {
+    const longMessage = "x".repeat(200);
+    toastError(toast, "Failed", new Error(longMessage));
+
+    const mockedError = toast.error as ReturnType<typeof mock>;
+    const call = mockedError.mock.calls[0];
+    const arg = call[0];
+    expect(typeof arg).toBe("string");
+    if (typeof arg !== "string") throw new Error("expected string toast message");
+    expect(arg.length).toBe(100);
+    expect(arg.endsWith("…")).toBe(true);
+  });
+
+  it("leaves messages at or under 100 characters intact", () => {
+    const shortMessage = "boom";
+    toastError(toast, "Failed", new Error(shortMessage));
+
+    expect(toast.error).toHaveBeenCalledWith("Failed: boom");
+  });
+});

package/src/utils/toastTemplates.ts

@@ -0,0 +1,47 @@
+import { extractErrorMessage } from "@checkstack/common";
+import type { useToast } from "../components/ToastProvider";
+
+/**
+ * Shape of the toast API exposed by {@link useToast}. Re-derived from
+ * the hook's return type so the helpers stay in lock-step with any
+ * future additions to the toast surface.
+ */
+export type ToastApi = ReturnType<typeof useToast>;
+
+const MAX_TOAST_MESSAGE_LENGTH = 100;
+
+/**
+ * Truncate `message` to `MAX_TOAST_MESSAGE_LENGTH` characters, replacing
+ * the tail with an ellipsis. Used to keep error toasts readable when
+ * upstream payloads carry verbose stack traces.
+ */
+function truncate(message: string): string {
+  if (message.length <= MAX_TOAST_MESSAGE_LENGTH) return message;
+  return `${message.slice(0, MAX_TOAST_MESSAGE_LENGTH - 1)}…`;
+}
+
+/**
+ * toastSuccess - shorthand for `toast.success(action)`.
+ *
+ * Use a verb-phrase for `action` so the toast reads naturally, e.g.
+ * `"Check created"`, `"Configuration saved"`.
+ */
+export function toastSuccess(toast: ToastApi, action: string): void {
+  toast.success(action);
+}
+
+/**
+ * toastError - render an error toast in the canonical
+ * `"{action}: {message}"` format, truncated to 100 characters.
+ *
+ * Funnels the unknown `error` through {@link extractErrorMessage} so
+ * callers don't have to narrow at every call site.
+ */
+export function toastError(
+  toast: ToastApi,
+  action: string,
+  error: unknown,
+): void {
+  const message = extractErrorMessage(error);
+  toast.error(truncate(`${action}: ${message}`));
+}

package/stories/ListEmptyState.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Plus, ServerCog } from "lucide-react";
+import { Button } from "../src/components/Button";
+import { ListEmptyState } from "../src/components/ListEmptyState";
+
+const meta: Meta<typeof ListEmptyState> = {
+  title: "Components/Feedback/ListEmptyState",
+  component: ListEmptyState,
+  tags: ["autodocs"],
+  args: {
+    resource: "checks",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListEmptyState>;
+
+export const Default: Story = {};
+
+export const WithDescription: Story = {
+  args: {
+    resource: "incidents",
+    description:
+      "Incidents are reported by operators and tracked through resolution updates.",
+  },
+};
+
+export const WithAction: Story = {
+  args: {
+    resource: "checks",
+    description:
+      "Create a health check to start monitoring an endpoint.",
+    actions: (
+      <Button>
+        <Plus className="h-4 w-4 mr-2" />
+        Create your first check
+      </Button>
+    ),
+  },
+};
+
+export const CustomIcon: Story = {
+  args: {
+    resource: "satellites",
+    description: "Satellites probe remote networks Checkstack can't reach directly.",
+    icon: <ServerCog className="h-10 w-10" />,
+  },
+};

package/stories/QueryErrorState.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { QueryErrorState } from "../src/components/QueryErrorState";
+
+const meta: Meta<typeof QueryErrorState> = {
+  title: "Components/Feedback/QueryErrorState",
+  component: QueryErrorState,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof QueryErrorState>;
+
+export const Default: Story = {
+  args: {
+    error: new Error("Failed to reach the backend at /api/health-checks"),
+    onRetry: () => {
+      // Storybook noop - wires up to a real refetch() in the app
+      console.log("retry clicked");
+    },
+  },
+};
+
+export const WithResource: Story = {
+  args: {
+    error: new Error("Network request failed (504)"),
+    resource: "checks",
+    onRetry: () => {
+      console.log("retry clicked");
+    },
+  },
+};
+
+export const NonErrorPayload: Story = {
+  args: {
+    error: null,
+    onRetry: () => {
+      console.log("retry clicked");
+    },
+  },
+};

package/stories/ResponsiveTable.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Badge } from "../src/components/Badge";
+import {
+  MobileCardList,
+  ResponsiveTable,
+} from "../src/components/ResponsiveTable";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "../src/components/Table";
+
+const meta: Meta = {
+  title: "Components/Data/ResponsiveTable",
+};
+
+export default meta;
+type Story = StoryObj;
+
+interface Row {
+  name: string;
+  strategy: string;
+  status: "healthy" | "degraded" | "down";
+  latency: string;
+}
+
+const rows: Row[] = [
+  { name: "api.checkstack.io", strategy: "HTTP probe", status: "healthy", latency: "42 ms" },
+  { name: "db-primary", strategy: "TCP probe", status: "degraded", latency: "340 ms" },
+  { name: "cache", strategy: "HTTP probe", status: "down", latency: "—" },
+];
+
+const variantFor = (status: Row["status"]) => {
+  if (status === "healthy") return "success" as const;
+  if (status === "degraded") return "warning" as const;
+  return "destructive" as const;
+};
+
+export const DualLayout: Story = {
+  render: () => (
+    <div className="w-full">
+      <ResponsiveTable>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead>Strategy</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead className="text-right">Latency</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map((row) => (
+              <TableRow key={row.name}>
+                <TableCell>{row.name}</TableCell>
+                <TableCell>{row.strategy}</TableCell>
+                <TableCell>
+                  <Badge variant={variantFor(row.status)}>{row.status}</Badge>
+                </TableCell>
+                <TableCell className="text-right">{row.latency}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </ResponsiveTable>
+
+      <MobileCardList>
+        {rows.map((row) => (
+          <div
+            key={row.name}
+            className="rounded-md border border-border bg-card p-3 flex flex-col gap-1"
+          >
+            <div className="flex items-center justify-between">
+              <span className="font-medium">{row.name}</span>
+              <Badge variant={variantFor(row.status)}>{row.status}</Badge>
+            </div>
+            <div className="text-xs text-muted-foreground">
+              {row.strategy} · {row.latency}
+            </div>
+          </div>
+        ))}
+      </MobileCardList>
+
+      <p className="text-xs text-muted-foreground mt-4">
+        Resize the viewport: the table appears on <code>sm</code> and up, the
+        stacked card list shows on smaller screens.
+      </p>
+    </div>
+  ),
+};

package/stories/Skeleton.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Skeleton } from "../src/components/Skeleton";
+
+const meta: Meta<typeof Skeleton> = {
+  title: "Components/Feedback/Skeleton",
+  component: Skeleton,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Skeleton>;
+
+export const Default: Story = {
+  args: {
+    className: "h-4 w-48",
+  },
+};
+
+export const TextBlock: Story = {
+  render: () => (
+    <div className="space-y-2 max-w-md">
+      <Skeleton className="h-4 w-3/4" />
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-5/6" />
+    </div>
+  ),
+};
+
+export const ListRow: Story = {
+  render: () => (
+    <div className="flex items-center gap-3 max-w-md">
+      <Skeleton className="h-10 w-10 rounded-full" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-4 w-1/2" />
+        <Skeleton className="h-3 w-1/3" />
+      </div>
+    </div>
+  ),
+};
+
+export const CardGrid: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-3 max-w-xl">
+      {Array.from({ length: 4 }, (_, index) => (
+        <div key={index} className="rounded-md border border-border p-4 space-y-3">
+          <Skeleton className="h-5 w-2/3" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-5/6" />
+        </div>
+      ))}
+    </div>
+  ),
+};

package/stories/toastTemplates.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "../src/components/Button";
+import { useToast } from "../src/components/ToastProvider";
+import { toastError, toastSuccess } from "../src/utils/toastTemplates";
+
+const meta: Meta = {
+  title: "Foundations/toastTemplates",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const Demo = () => {
+  const toast = useToast();
+
+  return (
+    <div className="space-y-3 max-w-md">
+      <p className="text-sm text-muted-foreground">
+        Fire the canonical success / error toasts. The error helper
+        prefixes the action and truncates long messages to 100 characters.
+      </p>
+
+      <div className="flex flex-wrap gap-2">
+        <Button onClick={() => toastSuccess(toast, "Check created")}>
+          Fire success
+        </Button>
+
+        <Button
+          variant="destructive"
+          onClick={() =>
+            toastError(
+              toast,
+              "Failed to create check",
+              new Error("Backend unreachable"),
+            )
+          }
+        >
+          Fire error
+        </Button>
+
+        <Button
+          variant="outline"
+          onClick={() =>
+            toastError(
+              toast,
+              "Failed to import config",
+              new Error(
+                "Validation failed: " + "x".repeat(300),
+              ),
+            )
+          }
+        >
+          Fire truncated error
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const Helpers: Story = { render: () => <Demo /> };