@structuralists/scaffolding 0.0.1

package/src/components/Json/Json/Json.stories.tsx

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Json } from './index';
+
+const meta: Meta<typeof Json> = {
+  title: 'Json/Json',
+  component: Json,
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Json>;
+
+const sample = {
+  id: 'usr_1042',
+  name: 'Alice Park',
+  email: 'alice.park@example.com',
+  role: 'engineer',
+  team: 'Platform',
+  active: true,
+  amount: 12340,
+  createdAt: '2025-09-12T14:30:00Z',
+  tags: ['admin', 'beta', 'oncall'],
+  preferences: {
+    theme: 'dark',
+    notifications: { email: true, push: false, sms: false },
+    digest: 'weekly',
+  },
+  notes: null,
+};
+
+export const Default: Story = {
+  render: () => <Json value={sample} />,
+};

package/src/components/Json/Json/index.tsx

@@ -0,0 +1,38 @@
+import ReactJsonView from "@uiw/react-json-view";
+import type { JsonProps } from "./types";
+
+/**
+ * JSON tree viewer. Thin wrapper over `@uiw/react-json-view` with our
+ * conventions: explicit props, named `is` / `can` / `has` booleans,
+ * quote-less keys, text truncation lifted to 300 chars.
+ *
+ * Theming: uses the underlying library's default palette for v0. Token-backed
+ * colors are a follow-up when the visual mismatch against the `ui` palette
+ * becomes worth addressing.
+ */
+export const Json = (props: JsonProps) => {
+  const {
+    value,
+    isCollapsed = false,
+    collapsedDepth = 1,
+    hasSizes = false,
+    shortenTextAfterLength = 500,
+  } = props;
+
+  const collapsed = isCollapsed ? collapsedDepth : false;
+
+  return (
+    <ReactJsonView
+      value={value as object}
+      collapsed={collapsed}
+      enableClipboard={false}
+      displayDataTypes={false}
+      displayObjectSize={hasSizes}
+      shortenTextAfterLength={shortenTextAfterLength}
+    >
+      <ReactJsonView.Quote render={() => null} />
+    </ReactJsonView>
+  );
+};
+
+export type { JsonProps };

package/src/components/Json/Json/types.ts

@@ -0,0 +1,21 @@
+export type JsonProps = {
+  /** The data to render. Any JSON-serializable value, plus a few extras the underlying lib handles (Date, Map, Set, BigInt). */
+  value: unknown;
+  /**
+   * Collapse nodes at/beyond `collapsedDepth`. Top-level keys stay visible
+   * when depth is >= 1. When false (default), the whole tree is expanded.
+   */
+  isCollapsed?: boolean;
+  /** Depth at which to collapse when `isCollapsed` is true. Ignored otherwise. Default: 1. */
+  collapsedDepth?: number;
+  /** Show the copy-to-clipboard icon on each node. Default: false.
+   *  TODO: remove — implementation hard-codes `enableClipboard={false}`. */
+  canCopy?: boolean;
+  /** Display the data-type label in front of values (e.g. `string`, `int`). Default: false.
+   *  TODO: remove — implementation hard-codes `displayDataTypes={false}`. */
+  hasTypes?: boolean;
+  /** Display the size/length badge on objects and arrays (e.g. `{3}`). Default: true. */
+  hasSizes?: boolean;
+  /** Truncate string values longer than this many characters. 0 disables truncation. Default: 300. */
+  shortenTextAfterLength?: number;
+};

package/src/components/Json/JsonTable/JsonLeafNode.tsx

@@ -0,0 +1,31 @@
+import { Text } from '../../Content/Text';
+
+export type JsonLeafNodeProps = {
+  value: unknown;
+};
+
+/**
+ * Renders one value as a leaf — text only, no JSON tree viewer. Handles
+ * the primitives React can't render directly (boolean, null, undefined)
+ * and lets strings/numbers flow through as JSX children. Anything else
+ * (objects, arrays, Dates, Maps, …) currently falls through to `{value}`
+ * — that will throw at render time for non-renderable types and is the
+ * placeholder until JsonTable grows specialized renderers for them.
+ */
+export const JsonLeafNode = (props: JsonLeafNodeProps) => {
+  const { value } = props;
+
+  if (value === null) {
+    return <Text isMuted>null</Text>;
+  }
+
+  if (value === undefined) {
+    return <Text isMuted>undefined</Text>;
+  }
+
+  if (typeof value === 'boolean') {
+    return <>{String(value)}</>;
+  }
+
+  return <>{value}</>;
+};

package/src/components/Json/JsonTable/JsonTable.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { JsonTable } from './index';
+
+const meta: Meta<typeof JsonTable> = {
+  title: 'Json/JsonTable',
+  component: JsonTable,
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof JsonTable>;
+
+const sample = {
+  id: 'usr_1042',
+  name: 'Alice Park',
+  email: 'alice.park@example.com',
+  role: 'engineer',
+  team: 'Platform',
+  active: true,
+  amount: 12340,
+  createdAt: '2025-09-12T14:30:00Z',
+  tags: ['admin', 'beta', 'oncall'],
+  preferences: {
+    theme: 'dark',
+    notifications: { email: true, push: false, sms: false },
+    digest: 'weekly',
+  },
+  notes: null,
+};
+
+export const PlainObject: Story = {
+  render: () => <JsonTable value={sample} />,
+};
+
+export const WithTopLevelTitle: Story = {
+  name: 'With top-level title',
+  render: () => <JsonTable value={sample} title="User profile" />,
+};
+
+export const PrimitivesAtTopLevel: Story = {
+  name: 'Primitives at top level → JsonLeafNode',
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      <JsonTable value="just a string" />
+      <JsonTable value={42} />
+      <JsonTable value={true} />
+      <JsonTable value={false} />
+      <JsonTable value={null} />
+      <JsonTable value={undefined} />
+    </div>
+  ),
+};

package/src/components/Json/JsonTable/index.tsx

@@ -0,0 +1,33 @@
+import { QuickTable, QuickTableRow, QuickTableCell } from '../../Tables/QuickTable';
+import { JsonLeafNode } from './JsonLeafNode';
+import { isPlainObject } from './utils';
+import type { JsonTableProps } from './types';
+
+export const JsonTable = (props: JsonTableProps) => {
+  const { value, title } = props;
+
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+
+    return (
+      <QuickTable title={title} hasColumnDividers>
+        {entries.map((entry) => {
+          const [key, child] = entry;
+
+          return (
+            <QuickTableRow key={key}>
+              <QuickTableCell width={1}>{key}</QuickTableCell>
+              <QuickTableCell>
+                <JsonTable value={child} title={key} />
+              </QuickTableCell>
+            </QuickTableRow>
+          );
+        })}
+      </QuickTable>
+    );
+  }
+
+  return <JsonLeafNode value={value} />;
+};
+
+export type { JsonTableProps };

package/src/components/Json/JsonTable/types.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+
+export type JsonValue = any;
+
+export type JsonTableProps = {
+  /** Any value. JsonTable inspects shape and dispatches to a specialized
+   *  renderer; primitives and unknown shapes fall back to JsonLeafNode. */
+  value: JsonValue;
+  /** Optional caption rendered above the QuickTable when value is a plain
+   *  object. JsonTable also passes the parent key down as `title` on each
+   *  recursive call, so nested object-valued cells render a labeled table. */
+  title?: ReactNode;
+};

package/src/components/Json/JsonTable/utils.ts

@@ -0,0 +1,6 @@
+export const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+};

package/src/components/Layout/Bar/Bar.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Bar } from './index';
+import { Button } from '../../Forms/Button';
+import { Debug } from '../Debug';
+
+const meta: Meta<typeof Bar> = {
+  title: 'Layout/Bar',
+  component: Bar,
+  args: { title: 'Section title' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Bar>;
+
+export const TitleOnly: Story = {
+  render: (args) => (
+    <Debug>
+      <Bar {...args} />
+    </Debug>
+  ),
+};
+
+export const TitleAndRight: Story = {
+  args: {
+    title: 'Inbox',
+    right: (
+      <>
+        <Button size="small">Filter</Button>
+        <Button size="small" variant="primary">
+          New
+        </Button>
+      </>
+    ),
+  },
+};
+
+export const Full: Story = {
+  args: {
+    title: 'Work items',
+    left: (
+      <>
+        <Button size="small" variant="ghost">
+          All
+        </Button>
+        <Button size="small" variant="ghost">
+          Mine
+        </Button>
+      </>
+    ),
+    right: (
+      <>
+        <Button size="small">Refresh</Button>
+        <Button size="small" variant="primary">
+          New item
+        </Button>
+      </>
+    ),
+  },
+};
+
+export const NoTitle: Story = {
+  args: {
+    title: undefined,
+    left: (
+      <Button size="small" variant="ghost">
+        Back
+      </Button>
+    ),
+    right: (
+      <>
+        <Button size="small">Cancel</Button>
+        <Button size="small" variant="primary">
+          Save
+        </Button>
+      </>
+    ),
+  },
+};
+
+export const LongTitleTruncates: Story = {
+  args: {
+    title:
+      'A very long title that should truncate with an ellipsis rather than push the right-side actions off the bar',
+    right: (
+      <>
+        <Button size="small">Filter</Button>
+        <Button size="small" variant="primary">
+          New
+        </Button>
+      </>
+    ),
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: 440 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/components/Layout/Bar/index.tsx

@@ -0,0 +1,17 @@
+import type { BarProps } from './types';
+import { backgroundStyle } from '../../../tokens';
+import styles from './styles.module.css';
+
+export const Bar = (props: BarProps) => {
+  const { title, left, right, background } = props;
+
+  return (
+    <div className={styles.bar} style={backgroundStyle('--ui-bar-bg', background)}>
+      {title && <span className={styles.title}>{title}</span>}
+      {left && <div className={styles.left}>{left}</div>}
+      {right && <div className={styles.right}>{right}</div>}
+    </div>
+  );
+};
+
+export type { BarProps };

package/src/components/Layout/Bar/styles.module.css

@@ -0,0 +1,34 @@
+.bar {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-3);
+  padding: var(--ui-space-2) var(--ui-space-3);
+  background-color: var(--ui-bar-bg, transparent);
+}
+
+.title {
+  font-weight: 500;
+  color: var(--ui-foreground);
+  /* min-width: 0 lets a flex child shrink below its intrinsic content width
+     so the ellipsis actually kicks in when the bar gets narrow. */
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.left {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  min-width: 0;
+}
+
+.right {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  /* margin-left: auto pushes the right group to the end regardless of what
+     (if anything) sits to its left. */
+  margin-left: auto;
+}

package/src/components/Layout/Bar/types.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import type { BackgroundToken } from '../../../tokens';
+
+export type BarProps = {
+  title?: string;
+  left?: ReactNode;
+  right?: ReactNode;
+  /** Ramp level mapped to `--ui-background-{0..3}`. Defaults to transparent. */
+  background?: BackgroundToken;
+};

package/src/components/Layout/Debug/Debug.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Debug } from './index';
+import { Stack } from '../Stack';
+import { Text } from '../../Content/Text';
+import { Heading } from '../../Content/Heading';
+import { Card } from '../../Content/Card';
+import { Repeat } from '../../../storybook';
+
+const meta: Meta<typeof Debug> = {
+  title: 'Layout/Debug',
+  component: Debug,
+};
+
+export default meta;
+type Story = StoryObj<typeof Debug>;
+
+export const Single: Story = {
+  render: () => (
+    <Debug>
+      <Card>
+        <Stack gap={2}>
+          <Heading level={3}>Wrapped content</Heading>
+          <Text>The outline is drawn outside the debug wrapper's box.</Text>
+          <Text isMuted>No layout shift from border math.</Text>
+        </Stack>
+      </Card>
+    </Debug>
+  ),
+};
+
+export const Nested: Story = {
+  render: () => (
+    <Debug>
+      <Stack gap={3} padding={3}>
+        <Heading level={3}>Outer</Heading>
+        <Debug>
+          <Stack gap={2} padding={2}>
+            <Text>Inner section one — each mount gets its own color.</Text>
+          </Stack>
+        </Debug>
+        <Debug>
+          <Stack gap={2} padding={2}>
+            <Text>Inner section two.</Text>
+            <Debug>
+              <Text>Even deeper.</Text>
+            </Debug>
+          </Stack>
+        </Debug>
+      </Stack>
+    </Debug>
+  ),
+};
+
+export const AcrossAList: Story = {
+  render: () => (
+    <Stack gap={2}>
+      <Repeat count={8}>
+        {(i) => (
+          <Debug>
+            <Stack padding={2}>
+              <Text>Item {i + 1}</Text>
+            </Stack>
+          </Debug>
+        )}
+      </Repeat>
+    </Stack>
+  ),
+};
+
+export const Recursive: Story = {
+  render: () => (
+    <Debug isRecursive>
+      <Card>
+        <Stack gap={2}>
+          <Heading level={3}>Recursive outline</Heading>
+          <Text>Every descendant gets the same outline color.</Text>
+          <Stack direction="row" gap={2}>
+            <Text>One</Text>
+            <Text>Two</Text>
+            <Text isMuted>Three</Text>
+          </Stack>
+        </Stack>
+      </Card>
+    </Debug>
+  ),
+};

package/src/components/Layout/Debug/index.tsx

@@ -0,0 +1,41 @@
+import { useState, type CSSProperties } from 'react';
+import type { DebugProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const HEX_SEEDS = [
+  '#e6194B', '#3cb44b', '#ffe119', '#4363d8', '#f58231',
+  '#911eb4', '#42d4f4', '#f032e6', '#bfef45', '#fabed4',
+  '#469990', '#dcbeff', '#9A6324', '#800000', '#aaffc3',
+  '#808000', '#ffd8b1', '#000075', '#a9a9a9', '#008080',
+  '#e75480', '#5f9ea0', '#ff7f50', '#6b8e23', '#4682b4',
+  '#d2691e', '#da70d6', '#708090', '#2e8b57', '#cd5c5c',
+];
+
+// 50% alpha so overlapping frames from nested Debugs blend rather than
+// stack into hard lines.
+const COLORS = HEX_SEEDS.map((hex) => {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, 0.5)`;
+});
+
+export const Debug = (props: DebugProps) => {
+  const { children, isRecursive } = props;
+
+  // Color is picked once at mount via lazy initializer and held in state
+  // so React's concurrent-mode double-invocation of renderers doesn't
+  // reroll it on every render.
+  const [color] = useState(
+    () => COLORS[Math.floor(Math.random() * COLORS.length)],
+  );
+  const style = { '--debug-color': color } as CSSProperties;
+  return (
+    <div className={cx(styles.debug, isRecursive && styles.recursive)} style={style}>
+      {children}
+    </div>
+  );
+};
+
+export type { DebugProps };

package/src/components/Layout/Debug/styles.module.css

@@ -0,0 +1,13 @@
+.debug {
+  /* outline draws outside the box without taking up layout space, so wrapped
+     children render exactly as they would unwrapped — no size shift like a
+     border would cause. */
+  outline: 1px solid var(--debug-color);
+}
+
+/* Recursive: apply the same outline to every descendant. All descendants
+   share the wrapper's single picked color. If you want per-element rotation,
+   wrap individual elements in their own Debug instead. */
+.recursive * {
+  outline: 1px solid var(--debug-color);
+}

package/src/components/Layout/Debug/types.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+
+export type DebugProps = {
+  children: ReactNode;
+  /**
+   * Frame every descendant element with the same outline color, in addition
+   * to the wrapper. Useful for visualizing the layout tree under a single
+   * container (e.g. every child of a `Stack` or `Panels` region) without
+   * wrapping each one manually.
+   */
+  isRecursive?: boolean;
+};

package/src/components/Layout/Divider/Divider.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Divider } from './index';
+import { Stack } from '../Stack';
+import { Text } from '../../Content/Text';
+
+const meta: Meta<typeof Divider> = {
+  title: 'Layout/Divider',
+  component: Divider,
+};
+
+export default meta;
+type Story = StoryObj<typeof Divider>;
+
+export const Default: Story = {
+  render: () => (
+    <Stack gap={3}>
+      <Text>Section above the divider.</Text>
+      <Divider />
+      <Text>Section below the divider.</Text>
+    </Stack>
+  ),
+};

package/src/components/Layout/Divider/index.tsx

@@ -0,0 +1,3 @@
+import styles from './styles.module.css';
+
+export const Divider = () => <hr className={styles.divider} />;

package/src/components/Layout/Divider/styles.module.css

@@ -0,0 +1,6 @@
+.divider {
+  margin: 0;
+  border: 0;
+  border-top: 1px solid var(--ui-border-subtle);
+  width: 100%;
+}

package/src/components/Layout/Grid/Grid.stories.tsx

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Grid } from './index';
+import { Card } from '../../Content/Card';
+import { Text } from '../../Content/Text';
+import { Repeat } from '../../../storybook';
+
+const meta: Meta<typeof Grid> = {
+  title: 'Layout/Grid',
+  component: Grid,
+  args: { columns: 4, gap: 3 },
+};
+
+export default meta;
+type Story = StoryObj<typeof Grid>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Grid {...args}>
+      <Repeat count={8}>
+        {(i) => (
+          <Card>
+            <Text>Cell {i + 1}</Text>
+          </Card>
+        )}
+      </Repeat>
+    </Grid>
+  ),
+};

package/src/components/Layout/Grid/index.tsx

@@ -0,0 +1,29 @@
+import type { CSSProperties } from 'react';
+import type { GridGap, GridProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const GAP_MAP: Record<GridGap, string> = {
+  0: styles.gap0,
+  1: styles.gap1,
+  2: styles.gap2,
+  3: styles.gap3,
+  4: styles.gap4,
+  5: styles.gap5,
+  6: styles.gap6,
+};
+
+export const Grid = (props: GridProps) => {
+  const { children, columns, gap = 2 } = props;
+
+  // The columns count is a runtime value, so it's threaded through as a
+  // custom property rather than a discrete class-per-count.
+  const style = { '--ui-grid-columns': columns } as CSSProperties;
+  return (
+    <div className={cx(styles.grid, GAP_MAP[gap])} style={style}>
+      {children}
+    </div>
+  );
+};
+
+export type { GridProps };

package/src/components/Layout/Grid/styles.module.css

@@ -0,0 +1,12 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(var(--ui-grid-columns), minmax(0, 1fr));
+}
+
+.gap0 { gap: 0; }
+.gap1 { gap: var(--ui-space-1); }
+.gap2 { gap: var(--ui-space-2); }
+.gap3 { gap: var(--ui-space-3); }
+.gap4 { gap: var(--ui-space-4); }
+.gap5 { gap: var(--ui-space-5); }
+.gap6 { gap: var(--ui-space-6); }

package/src/components/Layout/Grid/types.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+
+export type GridGap = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export type GridProps = {
+  children: ReactNode;
+  columns: number;
+  gap?: GridGap;
+};