@checkstack/ui 1.8.3 → 1.10.0

package/src/hooks/useInitOnceForKey.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import { shouldInitForKey } from "./useInitOnceForKey";
+
+/**
+ * Regression suite for the form-preservation bug in the healthcheck editor.
+ *
+ * Before this hook existed, the page had:
+ *
+ *   useEffect(() => {
+ *     if (existingConfig) setFormState({ … });
+ *   }, [existingConfig]);
+ *
+ * That fires on every refetch — including the refetches triggered by the
+ * realtime `HEALTH_CHECK_RUN_COMPLETED` signal — so the user's in-progress
+ * edits got wiped every time a healthcheck run completed anywhere on the
+ * platform.
+ *
+ * The hook delegates its decision to the pure `shouldInitForKey` function
+ * tested below. The hook is a thin React wrapper around two refs and a
+ * `useEffect` — testing the decision function gives full coverage of the
+ * logic without needing a DOM.
+ */
+
+describe("shouldInitForKey", () => {
+  it("returns true the first time value+key are defined and no key has been initialised", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false when value is undefined (query still loading)", () => {
+    expect(
+      shouldInitForKey({
+        value: undefined,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when value is null", () => {
+    expect(
+      shouldInitForKey({
+        value: null,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is undefined (no discriminator yet)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: undefined,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is null (record-not-found path)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: null,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false on a background refetch (same key already initialised)", () => {
+    // THE regression case: react-query refetched the same record after an
+    // invalidation, handing us a new `value` object reference. The
+    // `initialisedKey` already matches the new key, so we must not re-fire.
+    expect(
+      shouldInitForKey({
+        value: { name: "A (refetched)" },
+        key: "id-1",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true when the key changes (user navigated to a different record)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "B" },
+        key: "id-2",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true when we're returning to a previously-seen key from a different one", () => {
+    // The hook only stores the LAST initialised key, so flipping between
+    // two records re-initialises each time. That's the correct behaviour:
+    // each visit shows fresh server data.
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: "id-2",
+      }),
+    ).toBe(true);
+  });
+
+  it("treats numeric keys correctly (different number → re-init)", () => {
+    expect(
+      shouldInitForKey({ value: "any", key: 1, initialisedKey: 1 }),
+    ).toBe(false);
+    expect(
+      shouldInitForKey({ value: "any", key: 2, initialisedKey: 1 }),
+    ).toBe(true);
+  });
+
+  it("treats string vs number keys as different (no implicit coercion)", () => {
+    // If a caller starts passing IDs as numbers after passing strings (or
+    // vice versa) we'd rather re-init than miss an update; strict !== handles it.
+    expect(
+      shouldInitForKey({ value: "any", key: "1", initialisedKey: 1 }),
+    ).toBe(true);
+  });
+});

package/src/hooks/useInitOnceForKey.ts

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Pure decision function powering {@link useInitOnceForKey}. Extracted so
+ * it can be unit-tested without a DOM (the hook itself wraps this with
+ * a `useRef` + `useEffect`).
+ *
+ * Returns `true` iff the caller should run their initialiser:
+ *
+ *  - `value` is defined (the query has finished loading), AND
+ *  - `key` is defined (we have a discriminator to track init-per-record),
+ *    AND
+ *  - we haven't yet initialised for this key (i.e. `initialisedKey !== key`).
+ *
+ * Background refetches of the same record produce a new `value` reference
+ * but the same `key`, so the function returns `false` for them — that's
+ * the whole point.
+ */
+export function shouldInitForKey({
+  value,
+  key,
+  initialisedKey,
+}: {
+  value: unknown;
+  key: string | number | null | undefined;
+  initialisedKey: string | number | null | undefined;
+}): boolean {
+  if (value === undefined || value === null) return false;
+  if (key === undefined || key === null) return false;
+  return initialisedKey !== key;
+}
+
+/**
+ * Run a one-shot initialiser exactly once per `key`, ignoring subsequent
+ * `value` changes that keep the same key.
+ *
+ * Built for forms that need to seed local state from a react-query result
+ * but **must not** reset that state when the query refetches in the
+ * background. The canonical use case is the healthcheck editor: a realtime
+ * `HEALTH_CHECK_RUN_COMPLETED` signal invalidates the configuration query
+ * on every run, which would otherwise wipe the user's in-progress edits
+ * via a naive `useEffect([data], () => setState(data))`.
+ *
+ * Behaviour:
+ *  - Calls `onInit(value)` the first time `value` is defined for a given
+ *    `key`.
+ *  - **Does NOT** call it again if `value` changes but `key` stays the
+ *    same. Background refetches keep the same key (= the same record's
+ *    primary id) and therefore don't re-run the initialiser.
+ *  - **Does** call it again when `key` changes — e.g. when the user
+ *    navigates to a different record without unmounting the page.
+ *  - Skips initialisation entirely while either `value` or `key` is
+ *    `undefined`/`null`.
+ *
+ * `onInit` is read from a ref so callers can safely pass a fresh closure
+ * each render without re-firing the effect.
+ *
+ * @example
+ *   useInitOnceForKey(existingConfig, existingConfig?.id, (config) => {
+ *     setFormState({
+ *       name: config.name,
+ *       collectors: config.collectors ?? [],
+ *     });
+ *   });
+ */
+export function useInitOnceForKey<T>(
+  value: T | undefined | null,
+  key: string | number | null | undefined,
+  onInit: (value: T) => void,
+): void {
+  const initialisedKeyRef = useRef<string | number | null | undefined>(undefined);
+  const onInitRef = useRef(onInit);
+
+  // Keep the latest callback in a ref so a fresh closure each render doesn't
+  // re-trigger the effect; only `value` and `key` should drive it.
+  useEffect(() => {
+    onInitRef.current = onInit;
+  });
+
+  useEffect(() => {
+    if (!shouldInitForKey({ value, key, initialisedKey: initialisedKeyRef.current })) {
+      return;
+    }
+    initialisedKeyRef.current = key;
+    onInitRef.current(value as T);
+  }, [value, key]);
+}

package/src/index.ts

@@ -63,3 +63,9 @@ export * from "./components/MetricTile";
 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 /> };

package/tsconfig.json

@@ -1,7 +1,9 @@
 {
   "extends": "@checkstack/tsconfig/frontend.json",
   "include": [
-    "src"
+    "src",
+    "src/components/CodeEditor/generated/stdlib-types.json",
+    "scripts"
   ],
   "references": [
     {