@structuralists/scaffolding 0.0.1

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+preload = "./test-setup.ts"

package/eslint.config.mjs

@@ -0,0 +1,106 @@
+import boundaries from 'eslint-plugin-boundaries';
+import tsParser from '@typescript-eslint/parser';
+
+// Component primitives live under src/components/<Section>/<Component>/.
+// "Umbrella sections" (Modals, Chat) are themselves the primitive — their
+// sub-folders share internals and must be reached through the section barrel.
+// Plain sections (Layout, Content, Forms, ...) treat each component folder as
+// its own primitive.
+//
+// Three element types so rules can distinguish roles inside a primitive:
+//   - primitive-entry   → the barrel (`<primitive>/index.{ts,tsx}`)
+//   - primitive-dogfood → stories and tests; allowed to use their own barrel
+//                         because they demonstrate / exercise the public API
+//   - primitive         → any other file inside the primitive
+//
+// Ordering matters; more specific patterns first so they win the match.
+// `!(Modals|Chat)` is an extglob negation that excludes umbrella sections from
+// the depth-3 patterns, so files inside Modals/Chat fall through to the
+// depth-2 patterns and resolve to the umbrella as one primitive.
+export default [
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    plugins: { boundaries },
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } },
+    },
+    settings: {
+      'import/resolver': {
+        node: { extensions: ['.js', '.jsx', '.ts', '.tsx'] },
+      },
+      'boundaries/include': ['src/**/*'],
+      'boundaries/elements': [
+        // Plain-section component primitives (depth-3 under src/components)
+        {
+          type: 'primitive-entry',
+          pattern: 'src/components/!(Modals|Chat)/*/index.{ts,tsx}',
+          mode: 'full',
+          capture: ['_section', 'name'],
+        },
+        {
+          type: 'primitive-dogfood',
+          pattern: 'src/components/!(Modals|Chat)/*/**/*.{stories,test}.{ts,tsx}',
+          mode: 'full',
+          capture: ['_section', 'name'],
+        },
+        {
+          type: 'primitive',
+          pattern: 'src/components/!(Modals|Chat)/*',
+          mode: 'folder',
+          capture: ['_section', 'name'],
+        },
+        // Umbrella-section primitives (depth-2): Modals, Chat
+        {
+          type: 'primitive-entry',
+          pattern: 'src/components/*/index.{ts,tsx}',
+          mode: 'full',
+          capture: ['name'],
+        },
+        {
+          type: 'primitive-dogfood',
+          pattern: 'src/components/*/**/*.{stories,test}.{ts,tsx}',
+          mode: 'full',
+          capture: ['name'],
+        },
+        {
+          type: 'primitive',
+          pattern: 'src/components/*',
+          mode: 'folder',
+          capture: ['name'],
+        },
+      ],
+    },
+    rules: {
+      'boundaries/no-unknown': 'off',
+      'boundaries/no-unknown-files': 'off',
+      'boundaries/dependencies': [
+        'error',
+        {
+          default: 'allow',
+          rules: [
+            // External imports into a primitive must go through its barrel.
+            // Importers that aren't in the same primitive can't reach internals.
+            {
+              from: [
+                { type: 'primitive', captured: { name: '!{{ to.captured.name }}' } },
+                { type: 'primitive-entry', captured: { name: '!{{ to.captured.name }}' } },
+                { type: 'primitive-dogfood', captured: { name: '!{{ to.captured.name }}' } },
+              ],
+              disallow: [{ to: { type: 'primitive' } }],
+              message: "External imports must go through the folder's index barrel.",
+            },
+            // Inside the same primitive, files must not import their own barrel
+            // (cycle risk). Reach the neighbor directly.
+            {
+              from: [{ type: 'primitive', captured: { name: '{{ to.captured.name }}' } }],
+              disallow: [{ to: { type: 'primitive-entry' } }],
+              message:
+                "Files inside a primitive folder must not import their own index barrel; import the neighbor directly.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/index.ts

@@ -0,0 +1 @@
+export * from "./src";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@structuralists/scaffolding",
+  "version": "0.0.1",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./tokens.css": "./tokens.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "storybook dev -p 6015 --ci",
+    "storybook": "storybook dev -p 6015",
+    "build-storybook": "storybook build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@uiw/react-json-view": "^2.0.0-alpha.41",
+    "react-markdown": "^10.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.0.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0",
+    "@storybook/addon-essentials": "^8.6.0",
+    "@storybook/addon-storysource": "^8.6.0",
+    "@storybook/react": "^8.6.0",
+    "@storybook/react-vite": "^8.6.0",
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/parser": "^8.58.2",
+    "@vitejs/plugin-react": "^4.0.0",
+    "eslint": "^10.2.1",
+    "eslint-plugin-boundaries": "^6.0.2",
+    "react-router": "^7.0.0",
+    "storybook": "^8.6.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
+  }
+}

package/src/components/Chat/ChatComposer/ChatComposer.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ChatComposer } from './index';
+
+const meta: Meta<typeof ChatComposer> = {
+  title: 'Chat/ChatComposer',
+  component: ChatComposer,
+  decorators: [
+    (Story) => (
+      <div style={{ width: 720, border: '1px solid var(--ui-border)' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatComposer>;
+
+export const Default: Story = {
+  args: {
+    onSubmit: (text) => alert(`submit: ${text}`),
+  },
+};
+
+export const WithInitialValue: Story = {
+  args: {
+    initialValue: 'What does BackgroundToken accept again?',
+    onSubmit: (text) => alert(`submit: ${text}`),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    isDisabled: true,
+    initialValue: 'Waiting on the last response…',
+    onSubmit: () => {},
+  },
+};
+
+export const WithLeftControls: Story = {
+  args: {
+    onSubmit: (text) => alert(`submit: ${text}`),
+    left: (
+      <button
+        type="button"
+        style={{
+          font: 'inherit',
+          padding: '4px 8px',
+          border: '1px solid var(--ui-border)',
+          borderRadius: 'var(--ui-radius)',
+          background: 'var(--ui-background-1)',
+          color: 'var(--ui-foreground)',
+          cursor: 'pointer',
+        }}
+      >
+        📎 Attach
+      </button>
+    ),
+  },
+};
+
+export const CustomSubmitLabel: Story = {
+  args: {
+    submitLabel: 'Run',
+    placeholder: 'Type a command…',
+    onSubmit: (text) => alert(`run: ${text}`),
+  },
+};

package/src/components/Chat/ChatComposer/index.tsx

@@ -0,0 +1,74 @@
+import { useState, useRef } from 'react';
+import type { KeyboardEvent, ChangeEvent } from 'react';
+import type { ChatComposerProps } from './types';
+import styles from './styles.module.css';
+
+export const ChatComposer = (props: ChatComposerProps) => {
+  const {
+    onSubmit,
+    placeholder = 'Message…',
+    initialValue = '',
+    isDisabled = false,
+    submitLabel = 'Send',
+    left,
+    right,
+  } = props;
+
+  const [value, setValue] = useState(initialValue);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  const canSubmit = !isDisabled && value.trim().length > 0;
+
+  const submit = () => {
+    if (!canSubmit) return;
+    onSubmit(value);
+    setValue('');
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+      e.preventDefault();
+      submit();
+      return;
+    }
+    if (e.key === 'Escape') {
+      textareaRef.current?.blur();
+    }
+  };
+
+  const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(e.target.value);
+  };
+
+  return (
+    <div className={styles.composer}>
+      <textarea
+        ref={textareaRef}
+        className={styles.textarea}
+        value={value}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        placeholder={placeholder}
+        disabled={isDisabled}
+        rows={2}
+      />
+      <div className={styles.controls}>
+        {left !== undefined && <div className={styles.controlsLeft}>{left}</div>}
+        <span className={styles.hint}>Enter to send · Shift+Enter for newline</span>
+        <div className={styles.controlsRight}>
+          {right}
+          <button
+            type="button"
+            className={styles.submit}
+            onClick={submit}
+            disabled={!canSubmit}
+          >
+            {submitLabel}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export type { ChatComposerProps };

package/src/components/Chat/ChatComposer/styles.module.css

@@ -0,0 +1,88 @@
+.composer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-2);
+  padding: var(--ui-space-3) var(--ui-space-4);
+}
+
+.textarea {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  padding: var(--ui-space-2) var(--ui-space-3);
+  width: 100%;
+  resize: none;
+  /* field-sizing grows the textarea with content; floor via min-height below. */
+  field-sizing: content;
+  min-height: calc(var(--ui-text-medium) * var(--ui-line-height) * 2 + var(--ui-space-2) * 2 + 2px);
+  max-height: 240px;
+  overflow-y: auto;
+}
+
+.textarea:focus {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.textarea:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+}
+
+.controlsLeft {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+}
+
+.controlsRight {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  margin-left: auto;
+}
+
+.hint {
+  font-size: var(--ui-text-xsmall);
+  color: var(--ui-muted);
+  line-height: var(--ui-line-height-tight);
+}
+
+.submit {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-small);
+  font-weight: 600;
+  color: var(--ui-on-accent);
+  background-color: var(--ui-accent);
+  border: 1px solid var(--ui-accent);
+  border-radius: var(--ui-radius);
+  padding: var(--ui-space-1) var(--ui-space-3);
+  cursor: pointer;
+  line-height: var(--ui-line-height-tight);
+}
+
+.submit:hover:not(:disabled) {
+  background-color: var(--ui-accent-hover);
+  border-color: var(--ui-accent-hover);
+}
+
+.submit:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: 2px;
+}
+
+.submit:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/src/components/Chat/ChatComposer/types.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+
+export type ChatComposerProps = {
+  onSubmit: (text: string) => void;
+  placeholder?: string;
+  initialValue?: string;
+  isDisabled?: boolean;
+  submitLabel?: string;
+  left?: ReactNode;
+  right?: ReactNode;
+};

package/src/components/Chat/ChatMessage/ChatMessage.stories.tsx

@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ChatMessage } from './index';
+import { Stack } from '../../Layout/Stack';
+import { Badge } from '../../Content/Badge';
+import { Json } from '../../Json/Json';
+
+const meta: Meta<typeof ChatMessage> = {
+  title: 'Chat/ChatMessage',
+  component: ChatMessage,
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatMessage>;
+
+const now = new Date(2026, 3, 23, 15, 42);
+
+export const User: Story = {
+  args: {
+    role: 'user',
+    md: 'Can you summarize the last three commits on this branch?',
+    timestamp: now,
+  },
+};
+
+export const Assistant: Story = {
+  args: {
+    role: 'assistant',
+    timestamp: now,
+    md: `Sure — here's what landed:
+
+1. **\`feat:\` add ChatMessage primitive** — role-driven chrome, \`md | element\` content.
+2. **\`chore:\` bump storybook** — 8.6.14 → 8.6.18.
+3. **\`fix:\` Popover placement off-by-one** — corner math now uses \`getBoundingClientRect\`.
+
+Want me to open a PR?`,
+  },
+};
+
+export const System: Story = {
+  args: {
+    role: 'system',
+    md: 'Conversation started. Model: claude-opus-4-7. Tools: read, grep, bash.',
+  },
+};
+
+export const WithAuthorOverride: Story = {
+  args: {
+    role: 'user',
+    author: 'william.lubelski',
+    timestamp: now,
+    md: 'Override the default role label when you have a real identity to show.',
+  },
+};
+
+export const WithFooter: Story = {
+  args: {
+    role: 'assistant',
+    timestamp: now,
+    md: 'Footer slot is open for actions, token counts, tool-call summaries, whatever.',
+    footer: '42 tokens · 1.2s',
+  },
+};
+
+export const ElementContent: Story = {
+  args: {
+    role: 'assistant',
+    timestamp: now,
+    element: (
+      <Json
+        value={{ branch: 'main', ahead: 3, behind: 0, dirty: false }}
+        isCollapsed={false}
+      />
+    ),
+  },
+};
+
+export const Conversation: Story = {
+  render: () => (
+    <Stack direction="column" gap={0}>
+      <ChatMessage
+        role="system"
+        md="Conversation started. Model: claude-opus-4-7."
+      />
+      <ChatMessage
+        role="user"
+        timestamp={new Date(2026, 3, 23, 15, 40)}
+        md="What does `BackgroundToken` accept?"
+      />
+      <ChatMessage
+        role="assistant"
+        timestamp={new Date(2026, 3, 23, 15, 40)}
+        md={`Four values: \`"0" | "1" | "2" | "3"\`. They map to \`--ui-background-0\` through \`--ui-background-3\`. Components consume them via a \`backgroundStyle(varName, token)\` helper.`}
+      />
+      <ChatMessage
+        role="user"
+        timestamp={new Date(2026, 3, 23, 15, 41)}
+        md="And which primitives expose it?"
+      />
+      <ChatMessage
+        role="assistant"
+        timestamp={new Date(2026, 3, 23, 15, 41)}
+        md={`\`Bar\`, \`List\`, and \`Panels\` (per-region, via \`headerBackground\` / \`footerBackground\` / etc.).`}
+        footer={
+          <>
+            <Badge isMono>plan.md#L43</Badge> · 2 sources
+          </>
+        }
+      />
+    </Stack>
+  ),
+};

package/src/components/Chat/ChatMessage/index.tsx

@@ -0,0 +1,42 @@
+import type { ChatMessageProps, ChatMessageRole } from './types';
+import { Markdown } from '../../Content/Markdown';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const ROLE_STYLE: Record<ChatMessageRole, string> = {
+  user: styles.roleUser,
+  assistant: styles.roleAssistant,
+  system: styles.roleSystem,
+};
+
+const ROLE_LABEL: Record<ChatMessageRole, string> = {
+  user: 'You',
+  assistant: 'Assistant',
+  system: 'System',
+};
+
+const formatTimestamp = (timestamp: Date | string): string => {
+  if (typeof timestamp === 'string') return timestamp;
+  return timestamp.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+};
+
+export const ChatMessage = (props: ChatMessageProps) => {
+  const { role, author, timestamp, footer } = props;
+  const label = author ?? ROLE_LABEL[role];
+  const ts = timestamp !== undefined ? formatTimestamp(timestamp) : null;
+
+  return (
+    <div className={cx(styles.message, ROLE_STYLE[role])}>
+      <div className={styles.header}>
+        <span className={styles.author}>{label}</span>
+        {ts !== null && <span className={styles.timestamp}>{ts}</span>}
+      </div>
+      <div className={styles.content}>
+        {'md' in props ? <Markdown>{props.md}</Markdown> : props.element}
+      </div>
+      {footer !== undefined && <div className={styles.footer}>{footer}</div>}
+    </div>
+  );
+};
+
+export type { ChatMessageProps, ChatMessageRole };

package/src/components/Chat/ChatMessage/styles.module.css

@@ -0,0 +1,58 @@
+.message {
+  padding: var(--ui-space-2) var(--ui-space-3);
+  color: var(--ui-foreground);
+  line-height: var(--ui-line-height);
+  margin: var(--ui-space-2);
+  border-radius: var(--ui-radius);
+  border: 1px solid var(--ui-border-subtle);
+}
+
+.roleUser {
+  background-color: var(--ui-background-2);
+}
+
+.roleAssistant {
+  background-color: var(--ui-background-0);
+}
+
+.roleSystem {
+  background-color: transparent;
+  color: var(--ui-muted);
+  font-style: italic;
+  border: none;
+  max-width: none;
+  width: auto;
+  text-align: center;
+}
+
+.header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--ui-space-2);
+  margin-bottom: var(--ui-space-1);
+  font-size: var(--ui-text-xsmall);
+  line-height: var(--ui-line-height-tight);
+  color: var(--ui-muted);
+}
+
+.author {
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.timestamp {
+  font-variant-numeric: tabular-nums;
+}
+
+.content {
+  font-size: var(--ui-text-medium);
+}
+
+.footer {
+  margin-top: var(--ui-space-2);
+  font-size: var(--ui-text-xsmall);
+  line-height: var(--ui-line-height-tight);
+  color: var(--ui-muted);
+}

package/src/components/Chat/ChatMessage/types.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+
+export type ChatMessageRole = 'user' | 'assistant' | 'system';
+
+type ChatMessageContent = { md: string } | { element: ReactNode };
+
+type ChatMessageBase = {
+  role: ChatMessageRole;
+  author?: string;
+  timestamp?: Date | string;
+  footer?: ReactNode;
+};
+
+export type ChatMessageProps = ChatMessageBase & ChatMessageContent;