@checkstack/ui 1.7.1 → 1.8.1

package/stories/InstanceScopeBanner.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { InstanceScopeBanner } from "../src/components/InstanceScopeBanner";
+
+const meta: Meta<typeof InstanceScopeBanner> = {
+  title: "Components/Feedback/InstanceScopeBanner",
+  component: InstanceScopeBanner,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof InstanceScopeBanner>;
+
+export const InstanceScope: Story = {
+  args: {
+    scope: "instance",
+    subject: "Queue",
+    recommendation: "Switch to a Redis-backed queue to see cluster-wide totals.",
+  },
+};
+
+export const ClusterScope: Story = {
+  args: {
+    scope: "cluster",
+    subject: "Queue",
+    recommendation: "Banner is hidden when scope is 'cluster'.",
+  },
+  render: (args) => (
+    <div>
+      <InstanceScopeBanner {...args} />
+      <p className="text-sm text-muted-foreground">
+        Renders nothing — confirm by inspecting the DOM.
+      </p>
+    </div>
+  ),
+};

package/stories/Introduction.mdx

@@ -0,0 +1,50 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction" />
+
+# Checkstack UI
+
+This is the component library for Checkstack plugin developers. Every primitive
+exported from `@checkstack/ui` is intended to be safe for plugin use — both in
+core plugins shipped in this repo and in third-party plugins published to npm.
+
+## Why this exists
+
+Plugins ship their own React components but render *inside* the host frontend's
+React tree, so they must use the host's design tokens, theme, and spacing scale.
+The `@checkstack/ui` package is the public surface for that. If a primitive
+isn't documented here, treat it as an internal implementation detail.
+
+## How to use
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent } from "@checkstack/ui";
+
+export function MyPanel() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>My Plugin</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button variant="primary">Do the thing</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Theming
+
+All components consume CSS custom properties defined in `themes.css`. The host
+frontend wraps the entire app in `ThemeProvider`, so plugins automatically
+inherit light/dark mode. Use semantic Tailwind classes (`bg-primary`,
+`text-muted-foreground`, …) — never hardcoded colors.
+
+## Accessibility & performance
+
+- Components are built on Radix primitives where keyboard / focus / ARIA
+  behavior is non-trivial.
+- Animation-heavy components respect the `usePerformance` hook's `isLowPower`
+  flag — see [the performance rule](https://github.com/enyineer/checkstack/blob/main/.agent/rules/performance.md)
+  for the full contract plugins are expected to follow.

package/stories/Label.stories.tsx

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Input } from "../src/components/Input";
+import { Label } from "../src/components/Label";
+
+const meta: Meta<typeof Label> = {
+  title: "Components/Inputs/Label",
+  component: Label,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="space-y-2 max-w-sm">
+      <Label htmlFor="email">Email</Label>
+      <Input id="email" type="email" placeholder="you@example.com" />
+    </div>
+  ),
+};

package/stories/LinksEditor.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { LinksEditor, type HotLink } from "../src/components/LinksEditor";
+
+const meta: Meta = {
+  title: "Components/Inputs/LinksEditor",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const Demo = ({ canManage }: { canManage: boolean }) => {
+  const [links, setLinks] = useState<HotLink[]>([
+    { id: "1", label: "Runbook", url: "https://example.com/runbook" },
+    { id: "2", label: null, url: "https://example.com/dashboards/api" },
+  ]);
+  return (
+    <div className="max-w-md">
+      <LinksEditor
+        links={links}
+        canManage={canManage}
+        onAdd={({ label, url }) => {
+          setLinks((prev) => [
+            ...prev,
+            { id: String(prev.length + 1), label: label ?? null, url },
+          ]);
+        }}
+        onRemove={(link) => {
+          setLinks((prev) => prev.filter((l) => l.id !== link.id));
+        }}
+      />
+    </div>
+  );
+};
+
+export const Editable: Story = { render: () => <Demo canManage /> };
+export const ReadOnly: Story = { render: () => <Demo canManage={false} /> };

package/stories/Markdown.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Markdown, MarkdownBlock } from "../src/components/Markdown";
+
+const meta: Meta = {
+  title: "Components/Display/Markdown",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Inline: Story = {
+  render: () => (
+    <p>
+      <Markdown>
+        {"Build **fast**, ship **safe**. See the [docs](https://example.com)."}
+      </Markdown>
+    </p>
+  ),
+};
+
+export const Block: Story = {
+  render: () => (
+    <MarkdownBlock>
+      {`# Health checks
+
+A *health check* probes a system and asserts an outcome.
+
+- HTTP probes
+- TCP probes
+- Custom strategies
+
+Read more in the [strategies guide](https://example.com).`}
+    </MarkdownBlock>
+  ),
+};

package/stories/Menu.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { LogOut, Settings, User } from "lucide-react";
+import {
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from "../src/components/Menu";
+
+const meta: Meta = {
+  title: "Components/Overlays/Menu (Dropdown items)",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Items: Story = {
+  render: () => (
+    <div className="w-64 rounded-md border border-border bg-popover p-1 shadow-md">
+      <DropdownMenuLabel>Account</DropdownMenuLabel>
+      <DropdownMenuItem icon={<User className="h-4 w-4" />}>
+        Profile
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        icon={<Settings className="h-4 w-4" />}
+        description="Theme, notifications, integrations"
+      >
+        Settings
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem icon={<LogOut className="h-4 w-4" />}>
+        Sign out
+      </DropdownMenuItem>
+    </div>
+  ),
+};

package/stories/MetricTile.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Activity, Cpu, MemoryStick, Network } from "lucide-react";
+import { MetricTile } from "../src/components/MetricTile";
+
+const meta: Meta<typeof MetricTile> = {
+  title: "Components/Display/MetricTile",
+  component: MetricTile,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof MetricTile>;
+
+export const Single: Story = {
+  args: {
+    icon: Activity,
+    label: "Throughput",
+    value: "1.2k req/s",
+  },
+};
+
+export const Grid: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-3 max-w-3xl">
+      <MetricTile icon={Cpu} label="CPU" value="42%" subtitle="across 4 cores" />
+      <MetricTile icon={MemoryStick} label="Memory" value="3.1 GB" variant="warning" />
+      <MetricTile icon={Network} label="Network" value="220 Mbps" variant="success" />
+      <MetricTile icon={Activity} label="Errors" value="14" variant="destructive" />
+    </div>
+  ),
+};

package/stories/NavItem.stories.tsx

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Activity, Bell, Cog } from "lucide-react";
+import { NavItem } from "../src/components/NavItem";
+
+const meta: Meta<typeof NavItem> = {
+  title: "Components/Navigation/NavItem",
+  component: NavItem,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof NavItem>;
+
+export const TopLevel: Story = {
+  args: {
+    to: "/health",
+    label: "Health",
+    icon: <Activity className="h-4 w-4" />,
+  },
+};
+
+export const Nested: Story = {
+  render: () => (
+    <NavItem label="Settings" icon={<Cog className="h-4 w-4" />}>
+      <NavItem to="/settings/notifications" label="Notifications" icon={<Bell className="h-4 w-4" />} />
+      <NavItem to="/settings/general" label="General" icon={<Cog className="h-4 w-4" />} />
+    </NavItem>
+  ),
+};

package/stories/NotFound.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { NotFound } from "../src/components/NotFound";
+
+const meta: Meta<typeof NotFound> = {
+  title: "Components/Feedback/NotFound",
+  component: NotFound,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof NotFound>;
+
+export const Default: Story = {};
+
+export const CustomMessage: Story = {
+  args: { message: "We couldn't find the catalog system you requested." },
+};

package/stories/Page.stories.tsx

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Activity } from "lucide-react";
+import { Button } from "../src/components/Button";
+import { Page, PageContent, PageHeader } from "../src/components/Page";
+
+const meta: Meta = {
+  title: "Components/Layout/Page",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Page className="h-[60vh]">
+      <PageHeader
+        title="Health"
+        subtitle="Live system signals across all environments."
+        icon={Activity}
+        actions={<Button>New check</Button>}
+      />
+      <PageContent>
+        <p className="text-sm text-muted-foreground">
+          Page content scrolls independently of the header.
+        </p>
+      </PageContent>
+    </Page>
+  ),
+};

package/stories/PageLayout.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ShieldCheck } from "lucide-react";
+import { Button } from "../src/components/Button";
+import { PageLayout } from "../src/components/PageLayout";
+
+const meta: Meta<typeof PageLayout> = {
+  title: "Components/Layout/PageLayout",
+  component: PageLayout,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof PageLayout>;
+
+export const Allowed: Story = {
+  render: () => (
+    <div className="h-[60vh]">
+      <PageLayout
+        title="Access rules"
+        subtitle="Define who can do what."
+        icon={ShieldCheck}
+        allowed
+        actions={<Button>New rule</Button>}
+      >
+        <p className="text-sm text-muted-foreground">Rules table…</p>
+      </PageLayout>
+    </div>
+  ),
+};
+
+export const Denied: Story = {
+  render: () => (
+    <div className="h-[60vh]">
+      <PageLayout
+        title="Access rules"
+        subtitle="Define who can do what."
+        icon={ShieldCheck}
+        allowed={false}
+      >
+        <p>(Hidden)</p>
+      </PageLayout>
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <div className="h-[60vh]">
+      <PageLayout
+        title="Access rules"
+        subtitle="Define who can do what."
+        icon={ShieldCheck}
+        loading
+      >
+        <p>(Hidden while loading)</p>
+      </PageLayout>
+    </div>
+  ),
+};

package/stories/PaginatedList.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useEffect, useMemo } from "react";
+import { PaginatedList } from "../src/components/PaginatedList";
+import { usePagination } from "../src/hooks/usePagination";
+
+const meta: Meta = {
+  title: "Components/Data/PaginatedList",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const ITEMS = Array.from({ length: 73 }, (_, i) => ({
+  id: String(i + 1),
+  name: `System ${i + 1}`,
+}));
+
+const Demo = () => {
+  const pagination = usePagination({ defaultLimit: 10 });
+  useEffect(() => {
+    pagination.setTotal(ITEMS.length);
+  }, [pagination]);
+  const slice = useMemo(
+    () => ITEMS.slice(pagination.offset, pagination.offset + pagination.limit),
+    [pagination.offset, pagination.limit],
+  );
+  return (
+    <div className="max-w-md">
+      <PaginatedList items={slice} loading={false} pagination={pagination}>
+        {(items) => (
+          <ul className="divide-y rounded-md border border-border">
+            {items.map((item) => (
+              <li key={item.id} className="px-3 py-2 text-sm">
+                {item.name}
+              </li>
+            ))}
+          </ul>
+        )}
+      </PaginatedList>
+    </div>
+  );
+};
+
+export const Default: Story = { render: () => <Demo /> };

package/stories/Pagination.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Pagination } from "../src/components/Pagination";
+
+const meta: Meta<typeof Pagination> = {
+  title: "Components/Navigation/Pagination",
+  component: Pagination,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Pagination>;
+
+const Demo = () => {
+  const [page, setPage] = useState(1);
+  const [limit, setLimit] = useState(20);
+  return (
+    <Pagination
+      page={page}
+      totalPages={12}
+      onPageChange={setPage}
+      total={234}
+      limit={limit}
+      onPageSizeChange={setLimit}
+      showPageSize
+      showTotal
+    />
+  );
+};
+
+export const Default: Story = { render: () => <Demo /> };

package/stories/PerformanceProvider.stories.tsx

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "../src/components/Button";
+import { usePerformance } from "../src/components/PerformanceProvider";
+
+const meta: Meta = {
+  title: "Foundations/PerformanceProvider",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const Demo = () => {
+  const { isLowPower, manualLowPower, toggleManualLowPower } = usePerformance();
+  return (
+    <div className="space-y-3 max-w-md">
+      <p className="text-sm">
+        <code>isLowPower</code>: <strong>{String(isLowPower)}</strong>
+      </p>
+      <p className="text-sm">
+        <code>manualLowPower</code>: <strong>{String(manualLowPower)}</strong>
+      </p>
+      <Button onClick={toggleManualLowPower}>
+        Toggle low-power mode
+      </Button>
+      <p className="text-xs text-muted-foreground">
+        Plugins should consume <code>usePerformance().isLowPower</code> to
+        disable expensive animations / blurs.
+      </p>
+    </div>
+  );
+};
+
+export const Toggle: Story = { render: () => <Demo /> };

package/stories/PluginConfigForm.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import {
+  PluginConfigForm,
+  type PluginOption,
+} from "../src/components/PluginConfigForm";
+
+const meta: Meta = {
+  title: "Components/Forms/PluginConfigForm",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const plugins: PluginOption[] = [
+  {
+    id: "http-probe",
+    displayName: "HTTP Probe",
+    description: "Probes a public HTTP endpoint and asserts a 2xx response.",
+    configSchema: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: { type: "string", title: "URL", format: "uri" },
+        timeoutMs: { type: "number", title: "Timeout (ms)", default: 5000 },
+      },
+    },
+  },
+  {
+    id: "tcp-probe",
+    displayName: "TCP Probe",
+    description: "Opens a TCP connection to verify the port is reachable.",
+    configSchema: {
+      type: "object",
+      required: ["host", "port"],
+      properties: {
+        host: { type: "string", title: "Host" },
+        port: { type: "number", title: "Port" },
+      },
+    },
+  },
+];
+
+const Demo = () => {
+  const [pluginId, setPluginId] = useState("http-probe");
+  const [config, setConfig] = useState<Record<string, unknown>>({});
+  return (
+    <div className="max-w-xl">
+      <PluginConfigForm
+        label="Strategy"
+        plugins={plugins}
+        selectedPluginId={pluginId}
+        onPluginChange={(id) => {
+          setPluginId(id);
+          setConfig({});
+        }}
+        config={config}
+        onConfigChange={setConfig}
+      />
+    </div>
+  );
+};
+
+export const Default: Story = { render: () => <Demo /> };

package/stories/Popover.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "../src/components/Button";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "../src/components/Popover";
+
+const meta: Meta = {
+  title: "Components/Overlays/Popover",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Open popover</Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-80 p-4">
+        <h4 className="font-medium leading-none mb-2">Filter</h4>
+        <p className="text-sm text-muted-foreground">
+          Use this for filter chips, info hovers, or quick edits.
+        </p>
+      </PopoverContent>
+    </Popover>
+  ),
+};

package/stories/SectionHeader.stories.tsx

@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Activity } from "lucide-react";
+import { SectionHeader } from "../src/components/SectionHeader";
+
+const meta: Meta<typeof SectionHeader> = {
+  title: "Components/Layout/SectionHeader",
+  component: SectionHeader,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof SectionHeader>;
+
+export const Default: Story = {
+  args: {
+    title: "Recent activity",
+    description: "Last 24 hours of health-check transitions.",
+    icon: <Activity className="h-5 w-5" />,
+  },
+};

package/stories/Select.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../src/components/Select";
+
+const meta: Meta = {
+  title: "Components/Inputs/Select",
+};
+
+export default meta;
+type Story = StoryObj;
+
+const Demo = () => {
+  const [value, setValue] = useState("");
+  return (
+    <div className="max-w-xs">
+      <Select value={value} onValueChange={setValue}>
+        <SelectTrigger>
+          <SelectValue placeholder="Pick an environment" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="prod">Production</SelectItem>
+          <SelectItem value="staging">Staging</SelectItem>
+          <SelectItem value="dev">Development</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+};
+
+export const Default: Story = { render: () => <Demo /> };