- {children}
+
+ {(title != null || actions != null) && (
+
+ {title &&
{title}
}
+ {actions &&
{actions}
}
+
+ )}
+
{children}
);
}
diff --git a/packages/dashboard/src/ui/CodeBlock.stories.tsx b/packages/dashboard/src/ui/CodeBlock.stories.tsx
new file mode 100644
index 0000000..77b84b8
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.stories.tsx
@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CodeBlock } from "./CodeBlock";
+
+const meta = {
+ title: "Data display/CodeBlock",
+ component: CodeBlock,
+ parameters: { layout: "padded" },
+} satisfies Meta
;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Args: Story = {
+ args: { code: { to: "user@example.com", template: "welcome", attempts: 1 } },
+};
+
+export const StackTrace: Story = {
+ args: {
+ code: "Error: connection refused\n at SendEmailJob.run (jobs/send-email.ts:12:15)\n at Runner.perform (runner.ts:88:9)",
+ },
+};
diff --git a/packages/dashboard/src/ui/CodeBlock.test.tsx b/packages/dashboard/src/ui/CodeBlock.test.tsx
new file mode 100644
index 0000000..0b425bf
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { CodeBlock } from "./CodeBlock";
+
+describe("CodeBlock", () => {
+ it("renders a string verbatim with defaults", () => {
+ const { container } = render();
+
+ expect(screen.getByText("hello world")).toBeInTheDocument();
+ expect(container.querySelector(".sq-codeblock")).not.toBeNull();
+ });
+
+ it("pretty-prints an object as JSON and honors language/maxHeight/className", () => {
+ const { container } = render(
+ ,
+ );
+
+ expect(container.querySelector(".sq-codeblock")).toHaveClass("extra");
+ expect(container.querySelector("code")).toHaveAttribute("data-language", "json");
+ expect(screen.getByText(/"a": 1/)).toBeInTheDocument();
+ });
+});
diff --git a/packages/dashboard/src/ui/CodeBlock.tsx b/packages/dashboard/src/ui/CodeBlock.tsx
new file mode 100644
index 0000000..56f39c6
--- /dev/null
+++ b/packages/dashboard/src/ui/CodeBlock.tsx
@@ -0,0 +1,32 @@
+import type { CSSProperties } from "react";
+import { cn } from "./cn";
+
+/** Props for the {@link CodeBlock} monospace panel. */
+export interface CodeBlockProps {
+ /** String, or an object that will be pretty-printed as JSON. */
+ code: string | object;
+ language?: string;
+ /** @default "15rem" */
+ maxHeight?: string;
+ className?: string;
+ style?: CSSProperties;
+}
+
+/**
+ * CodeBlock — near-black monospace panel for job arguments, results, and stack traces.
+ * Pass a string, or an object which is pretty-printed as JSON.
+ */
+export function CodeBlock({ code, language, maxHeight = "15rem", className = "", style = {} }: CodeBlockProps) {
+ const text = typeof code === "string" ? code : JSON.stringify(code, null, 2);
+ return (
+
+ {text}
+
+ );
+}
diff --git a/packages/dashboard/src/ui/FormField.stories.tsx b/packages/dashboard/src/ui/FormField.stories.tsx
new file mode 100644
index 0000000..1d5eb3b
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.stories.tsx
@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FormField } from "./FormField";
+import { Input } from "./Input";
+
+const meta = {
+ title: "Forms/FormField",
+ component: FormField,
+ parameters: { layout: "padded" },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const WithInput: Story = {
+ args: {
+ label: "Job class",
+ width: "16rem",
+ children: ,
+ },
+};
+
+export const WithHint: Story = {
+ args: {
+ label: "Cron",
+ hint: "in-memory, per instance",
+ width: "16rem",
+ children: ,
+ },
+};
diff --git a/packages/dashboard/src/ui/FormField.test.tsx b/packages/dashboard/src/ui/FormField.test.tsx
new file mode 100644
index 0000000..bb41750
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { FormField } from "./FormField";
+
+describe("FormField", () => {
+ it("renders only the control when no label or hint is given", () => {
+ render(
+
+
+ ,
+ );
+
+ expect(screen.getByLabelText("bare")).toBeInTheDocument();
+ expect(screen.queryByText("Name")).toBeNull();
+ });
+
+ it("renders label, hint, fixed width and className", () => {
+ const { container } = render(
+
+
+ ,
+ );
+
+ expect(screen.getByText("Name")).toBeInTheDocument();
+ expect(screen.getByText("required")).toBeInTheDocument();
+ expect(container.querySelector(".sq-field")).toHaveClass("extra");
+ });
+});
diff --git a/packages/dashboard/src/ui/FormField.tsx b/packages/dashboard/src/ui/FormField.tsx
new file mode 100644
index 0000000..d19ce80
--- /dev/null
+++ b/packages/dashboard/src/ui/FormField.tsx
@@ -0,0 +1,34 @@
+import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
+
+/** Props for the {@link FormField} label + control wrapper. */
+export interface FormFieldProps {
+ /** Label text above the control. */
+ label?: string;
+ htmlFor?: string;
+ /** Fixed width, e.g. "12rem" (filter bars). */
+ width?: string;
+ /** Helper text below the control. */
+ hint?: string;
+ children?: ReactNode;
+ className?: string;
+ style?: CSSProperties;
+}
+
+/**
+ * FormField — label + control wrapper for filter bars and forms. Optional label above
+ * and hint below the control.
+ */
+export function FormField({ label, htmlFor, width, hint, className = "", style = {}, children }: FormFieldProps) {
+ return (
+
+ {label != null && (
+
+ )}
+ {children}
+ {hint != null && {hint}}
+
+ );
+}
diff --git a/packages/dashboard/src/ui/Icon.stories.tsx b/packages/dashboard/src/ui/Icon.stories.tsx
new file mode 100644
index 0000000..c35eae8
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.stories.tsx
@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Icon, type IconName } from "./Icon";
+
+const meta = {
+ title: "Actions/Icon",
+ component: Icon,
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Play: Story = { args: { name: "Play" } };
+
+export const Large: Story = { args: { name: "RefreshCcw", size: 32 } };
+
+const NAMES: IconName[] = ["Play", "X", "RefreshCcw", "Trash2", "Clock", "Activity", "CircleCheck", "CircleX", "Pause"];
+
+export const Gallery: Story = {
+ render: () => (
+
+ {NAMES.map((n) => (
+
+ ))}
+
+ ),
+};
diff --git a/packages/dashboard/src/ui/Icon.test.tsx b/packages/dashboard/src/ui/Icon.test.tsx
new file mode 100644
index 0000000..cfb774f
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.test.tsx
@@ -0,0 +1,29 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Icon, type IconName } from "./Icon";
+
+describe("Icon", () => {
+ it("renders a lucide glyph for a known name with defaults", () => {
+ const { container } = render();
+
+ const svg = container.querySelector("svg");
+ expect(svg).not.toBeNull();
+ expect(svg).toHaveAttribute("width", "16");
+ expect(svg).toHaveAttribute("aria-hidden", "true");
+ });
+
+ it("resolves multi-segment names and honors size/strokeWidth/rest props", () => {
+ const { container } = render();
+
+ const svg = container.querySelector("svg");
+ expect(svg).toHaveAttribute("width", "24");
+ expect(svg).toHaveAttribute("stroke-width", "3");
+ expect(svg).toHaveClass("x");
+ });
+
+ it("renders nothing for an unknown name", () => {
+ const { container } = render();
+
+ expect(container.querySelector("svg")).toBeNull();
+ });
+});
diff --git a/packages/dashboard/src/ui/Icon.tsx b/packages/dashboard/src/ui/Icon.tsx
new file mode 100644
index 0000000..382c652
--- /dev/null
+++ b/packages/dashboard/src/ui/Icon.tsx
@@ -0,0 +1,28 @@
+import { icons, type LucideProps } from "lucide-react";
+import type { ComponentType } from "react";
+
+/** A Lucide icon key, e.g. "Play", "RefreshCcw", "X". */
+export type IconName = keyof typeof icons;
+
+/** Props for the {@link Icon} component. Extends the underlying Lucide SVG props. */
+export interface IconProps extends Omit {
+ /** Lucide icon key (PascalCase, as exported by lucide-react), e.g. "Play", "RefreshCcw", "X". */
+ name: IconName;
+ /** Pixel size. @default 16 */
+ size?: number;
+ /** @default 2 */
+ strokeWidth?: number;
+}
+
+/**
+ * Icon — a Lucide glyph resolved by name (Feather's successor; the design system's
+ * iconography). Renders `currentColor`, so it inherits the surrounding text color.
+ * Returns nothing for an unknown name.
+ */
+export function Icon({ name, size = 16, strokeWidth = 2, ...rest }: IconProps) {
+ const Glyph = icons[name] as ComponentType | undefined;
+ if (!Glyph) {
+ return null;
+ }
+ return ;
+}
diff --git a/packages/dashboard/src/ui/Input.stories.tsx b/packages/dashboard/src/ui/Input.stories.tsx
new file mode 100644
index 0000000..ba57f9a
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.stories.tsx
@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Input } from "./Input";
+
+const meta = {
+ title: "Forms/Input",
+ component: Input,
+ parameters: { layout: "padded" },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = { args: { placeholder: "Search jobs…" } };
+
+export const Small: Story = { args: { size: "sm", placeholder: "Filter" } };
+
+export const Invalid: Story = { args: { invalid: true, defaultValue: "bad value" } };
diff --git a/packages/dashboard/src/ui/Input.test.tsx b/packages/dashboard/src/ui/Input.test.tsx
new file mode 100644
index 0000000..4ca3531
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.test.tsx
@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Input } from "./Input";
+
+describe("Input", () => {
+ it("renders a text input with defaults", () => {
+ render();
+
+ const input = screen.getByLabelText("name");
+ expect(input).toHaveClass("sq-input");
+ expect(input).toHaveAttribute("type", "text");
+ });
+
+ it("honors type, small size, invalid, className and style", () => {
+ render();
+
+ const input = screen.getByLabelText("age");
+ expect(input).toHaveClass("sq-input", "extra");
+ expect(input).toHaveAttribute("type", "number");
+ });
+});
diff --git a/packages/dashboard/src/ui/Input.tsx b/packages/dashboard/src/ui/Input.tsx
new file mode 100644
index 0000000..d39ab3b
--- /dev/null
+++ b/packages/dashboard/src/ui/Input.tsx
@@ -0,0 +1,29 @@
+import type { InputHTMLAttributes } from "react";
+import { cn } from "./cn";
+
+/** Props for the {@link Input} field. Extends the native `input` attributes. */
+export interface InputProps extends Omit, "size"> {
+ /** @default "md" */
+ size?: "sm" | "md";
+ /** Red border for validation errors. */
+ invalid?: boolean;
+}
+
+/**
+ * Input — text/number/datetime field, matching the dashboard's filter-bar inputs.
+ * Pair with {@link FormField} for a label.
+ */
+export function Input({ type = "text", size = "md", invalid = false, className = "", ...rest }: InputProps) {
+ return (
+
+ );
+}
diff --git a/packages/dashboard/src/ui/NavItem.stories.tsx b/packages/dashboard/src/ui/NavItem.stories.tsx
new file mode 100644
index 0000000..1122dfa
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.stories.tsx
@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { NavItem } from "./NavItem";
+
+const meta = {
+ title: "Navigation/NavItem",
+ component: NavItem,
+ parameters: { layout: "padded" },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Active: Story = { args: { label: "Dashboard", icon: "LayoutDashboard", active: true } };
+
+export const Inactive: Story = { args: { label: "Jobs", icon: "List" } };
+
+export const List: Story = {
+ render: () => (
+
+
+
+
+
+ ),
+};
diff --git a/packages/dashboard/src/ui/NavItem.test.tsx b/packages/dashboard/src/ui/NavItem.test.tsx
new file mode 100644
index 0000000..c244405
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.test.tsx
@@ -0,0 +1,32 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { NavItem } from "./NavItem";
+
+describe("NavItem", () => {
+ it("renders an inactive link with no icon by default", () => {
+ const { container } = render();
+
+ const link = screen.getByRole("link", { name: "Jobs" });
+ expect(link).toHaveClass("sq-navitem");
+ expect(link).toHaveAttribute("href", "#");
+ expect(container.querySelector("svg")).toBeNull();
+ });
+
+ it("renders an inactive link with an icon (muted icon color)", () => {
+ const { container } = render();
+
+ expect(screen.getByRole("link", { name: /Jobs/ })).toBeInTheDocument();
+ expect(container.querySelector("svg")).not.toBeNull();
+ });
+
+ it("renders an active link with an icon, href, className and style", () => {
+ const { container } = render(
+ ,
+ );
+
+ const link = screen.getByRole("link", { name: /Queues/ });
+ expect(link).toHaveClass("extra");
+ expect(link).toHaveAttribute("href", "/queues");
+ expect(container.querySelector("svg")).not.toBeNull();
+ });
+});
diff --git a/packages/dashboard/src/ui/NavItem.tsx b/packages/dashboard/src/ui/NavItem.tsx
new file mode 100644
index 0000000..ff0e415
--- /dev/null
+++ b/packages/dashboard/src/ui/NavItem.tsx
@@ -0,0 +1,39 @@
+import type { CSSProperties, MouseEvent } from "react";
+import { cn } from "./cn";
+import { Icon, type IconName } from "./Icon";
+
+/** Props for the {@link NavItem} sidebar link. */
+export interface NavItemProps {
+ label: string;
+ /** Lucide icon name. */
+ icon?: IconName;
+ active?: boolean;
+ href?: string;
+ onClick?: (e: MouseEvent) => void;
+ className?: string;
+ style?: CSSProperties;
+}
+
+/**
+ * NavItem — a single sidebar link. The active state gets a subtle raised fill and a
+ * brand left-accent; hover lightens.
+ */
+export function NavItem({ label, icon, active = false, href = "#", onClick, className = "", style = {} }: NavItemProps) {
+ return (
+
+ {icon && }
+ {label}
+
+ );
+}
diff --git a/packages/dashboard/src/ui/Pagination.stories.tsx b/packages/dashboard/src/ui/Pagination.stories.tsx
new file mode 100644
index 0000000..c46482e
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.stories.tsx
@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Pagination } from "./Pagination";
+
+const meta = {
+ title: "Data table/Pagination",
+ component: Pagination,
+ parameters: { layout: "padded" },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Middle: Story = { args: { page: 3, hasNext: true } };
+
+export const FirstPage: Story = { args: { page: 1, hasNext: true } };
+
+export const LastPage: Story = { args: { page: 9, hasNext: false } };
diff --git a/packages/dashboard/src/ui/Pagination.test.tsx b/packages/dashboard/src/ui/Pagination.test.tsx
new file mode 100644
index 0000000..93cea99
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Pagination } from "./Pagination";
+
+describe("Pagination", () => {
+ it("enables both ends when there is a previous and next page", () => {
+ render();
+
+ expect(screen.getByText("Page 2")).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "«" })).toBeEnabled();
+ expect(screen.getByRole("button", { name: "»" })).toBeEnabled();
+ });
+
+ it("disables the ends on the first page with no next, and honors className/style", () => {
+ const onPrev = vi.fn();
+ const onNext = vi.fn();
+ render();
+
+ expect(screen.getByRole("button", { name: "«" })).toBeDisabled();
+ expect(screen.getByRole("button", { name: "»" })).toBeDisabled();
+ });
+});
diff --git a/packages/dashboard/src/ui/Pagination.tsx b/packages/dashboard/src/ui/Pagination.tsx
new file mode 100644
index 0000000..3c0a553
--- /dev/null
+++ b/packages/dashboard/src/ui/Pagination.tsx
@@ -0,0 +1,41 @@
+import type { CSSProperties, ReactNode } from "react";
+import { cn } from "./cn";
+
+/** Props for the {@link Pagination} control. */
+export interface PaginationProps {
+ page: number;
+ hasNext?: boolean;
+ onPrev?: () => void;
+ onNext?: () => void;
+ className?: string;
+ style?: CSSProperties;
+}
+
+/**
+ * Pagination — the dashboard's joined prev / page / next control. Buttons abut with
+ * shared borders; the ends disable when there is no previous/next page.
+ */
+export function Pagination({ page, hasNext = false, onPrev, onNext, className = "", style = {} }: PaginationProps) {
+ const btn = (content: ReactNode, enabled: boolean, onClick: (() => void) | undefined, active: boolean) => (
+
+ );
+
+ return (
+
+ {btn("«", page > 1, onPrev, false)}
+ {btn(`Page ${page}`, false, undefined, true)}
+ {btn("»", hasNext, onNext, false)}
+
+ );
+}
diff --git a/packages/dashboard/src/ui/Select.stories.tsx b/packages/dashboard/src/ui/Select.stories.tsx
new file mode 100644
index 0000000..f2803cb
--- /dev/null
+++ b/packages/dashboard/src/ui/Select.stories.tsx
@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Select } from "./Select";
+
+const meta = {
+ title: "Forms/Select",
+ component: Select,
+ parameters: { layout: "padded" },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const States: Story = {
+ args: {
+ defaultValue: "running",
+ options: [
+ { value: "waiting", label: "Waiting" },
+ { value: "running", label: "Running" },
+ { value: "completed", label: "Completed" },
+ { value: "failed", label: "Failed" },
+ ],
+ },
+};
+
+export const Small: Story = {
+ args: {
+ size: "sm",
+ defaultValue: "default",
+ options: [
+ { value: "default", label: "default" },
+ { value: "mailers", label: "mailers" },
+ ],
+ },
+};
diff --git a/packages/dashboard/src/ui/Select.test.tsx b/packages/dashboard/src/ui/Select.test.tsx
new file mode 100644
index 0000000..591e839
--- /dev/null
+++ b/packages/dashboard/src/ui/Select.test.tsx
@@ -0,0 +1,35 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Select } from "./Select";
+
+describe("Select", () => {
+ it("renders options passed as data", () => {
+ render(
+