@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,145 @@
+import { useState, type ComponentType } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ChatRecipientsHeader } from './index';
+import type { PillComboboxOption } from '../PillCombobox/types';
+import { Stack } from '../../Layout/Stack';
+import { Textarea } from '../../Forms/Textarea';
+import { Input } from '../../Forms/Input';
+import { Field } from '../../Forms/Field';
+import { Button } from '../../Forms/Button';
+import { MediumModal } from '../../Modals';
+import { Toggle } from '../../../storybook';
+
+const meta: Meta<typeof ChatRecipientsHeader> = {
+  title: 'Chat/ChatRecipientsHeader',
+  component: ChatRecipientsHeader,
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatRecipientsHeader>;
+
+const actorOptions: PillComboboxOption<string>[] = [
+  { value: 'alice', label: 'Alice' },
+  { value: 'bob', label: 'Bob' },
+  { value: 'carol', label: 'Carol' },
+  { value: 'dave', label: 'Dave' },
+  { value: 'eve', label: 'Eve' },
+  { value: 'mallory', label: 'Mallory' },
+];
+
+const Harness = ({
+  initial = [],
+  isDisabled,
+  label,
+}: {
+  initial?: string[];
+  isDisabled?: boolean;
+  label?: string;
+}) => {
+  const [values, setValues] = useState<string[]>(initial);
+  return (
+    <ChatRecipientsHeader
+      options={actorOptions}
+      values={values}
+      onChange={setValues}
+      ariaLabel="Recipients"
+      placeholder="Add people…"
+      isDisabled={isDisabled}
+      label={label}
+    />
+  );
+};
+
+const widthDecorator = (Story: ComponentType) => (
+  <div style={{ width: 560 }}>
+    <Story />
+  </div>
+);
+
+// Plain — flush header in a fixed-width container so the bottom-rule and
+// inset focus highlight read clearly.
+export const Default: Story = {
+  decorators: [widthDecorator],
+  render: () => <Harness />,
+};
+
+export const WithSelections: Story = {
+  decorators: [widthDecorator],
+  render: () => <Harness initial={['alice', 'bob']} />,
+};
+
+export const CustomLabel: Story = {
+  decorators: [widthDecorator],
+  render: () => <Harness label="Cc" initial={['carol']} />,
+};
+
+export const Disabled: Story = {
+  decorators: [widthDecorator],
+  render: () => <Harness initial={['alice']} isDisabled />,
+};
+
+// Canonical use: dropped into the modal's `subHeaders` slot, sitting flush
+// under the title bar with the slot's divider separating it from the body.
+// The body keeps its default padding for the rest of the form.
+export const InComposeModal: Story = {
+  parameters: { layout: 'centered' },
+  render: () => (
+    <Toggle defaultOn>
+      {({ isOn, on, off }) => {
+        const [recipients, setRecipients] = useState<string[]>(['alice']);
+        const [title, setTitle] = useState('');
+        const [body, setBody] = useState('');
+        return (
+          <>
+            <Button onClick={on}>Open compose…</Button>
+            <MediumModal
+              isOpen={isOn}
+              onClose={off}
+              title="New conversation"
+              subHeaders={[
+                <ChatRecipientsHeader
+                  key="recipients"
+                  options={actorOptions}
+                  values={recipients}
+                  onChange={setRecipients}
+                  ariaLabel="Recipients"
+                  placeholder="Add people…"
+                />,
+              ]}
+              footer={
+                <Stack direction="row" justify="end" gap={2}>
+                  <Button variant="ghost" onClick={off}>
+                    Cancel
+                  </Button>
+                  <Button variant="primary" onClick={off}>
+                    Send
+                  </Button>
+                </Stack>
+              }
+            >
+              <Stack gap={3}>
+                <Field label="Title" htmlFor="story-title">
+                  <Input
+                    id="story-title"
+                    value={title}
+                    onChange={(e) => setTitle(e.target.value)}
+                    placeholder="What's this about?"
+                  />
+                </Field>
+                <Field label="Message" htmlFor="story-body">
+                  <Textarea
+                    id="story-body"
+                    value={body}
+                    onChange={(e) => setBody(e.target.value)}
+                    placeholder="Type your first message…"
+                    rows={4}
+                  />
+                </Field>
+              </Stack>
+            </MediumModal>
+          </>
+        );
+      }}
+    </Toggle>
+  ),
+};

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

@@ -0,0 +1,29 @@
+import { cx } from '../../../utils';
+import { PillComboboxCore } from '../PillComboboxCore/Core';
+import type {
+  ChatRecipientsHeaderProps,
+  PillComboboxOption,
+} from './types';
+import styles from './styles.module.css';
+
+// Flush header packaging of the chat combobox. Same engine as
+// PillCombobox, but renders without a bordered shell — meant to sit edge-
+// to-edge at the top of a compose modal or panel, with an inline "To"
+// label.
+export const ChatRecipientsHeader = <T extends string,>({
+  label = 'To',
+  ...rest
+}: ChatRecipientsHeaderProps<T>) => (
+  <PillComboboxCore
+    {...rest}
+    shellClassName={cx(styles.shell, rest.isDisabled && styles.shellDisabled)}
+    rowClassName={cx(styles.row, rest.isDisabled && styles.rowDisabled)}
+    leadingSlot={
+      <span className={styles.label} aria-hidden="true">
+        {label}
+      </span>
+    }
+  />
+);
+
+export type { ChatRecipientsHeaderProps, PillComboboxOption };

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

@@ -0,0 +1,48 @@
+/* Outer carries the resting "header zone" tint and lays out the leading
+   label beside the focusable row. The container's subHeader slot is
+   responsible for the divider above/below. */
+.shell {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-1);
+  padding: var(--ui-space-1);
+  padding-left: calc(var(--ui-space-5) + var(--ui-space-1));
+  background-color: var(--ui-background-1);
+}
+
+.shellDisabled {
+  opacity: 0.5;
+}
+
+.label {
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  color: var(--ui-muted);
+  user-select: none;
+}
+
+/* Inner: the focusable row. Transparent at rest (inherits the outer's
+   tint); on focus, lifts to the content surface and shows an accent ring
+   around the entire row. */
+.row {
+  flex: 1 1 0;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--ui-space-1);
+  padding: 2px var(--ui-space-2);
+  border-radius: var(--ui-radius);
+  cursor: text;
+  min-height: calc(var(--ui-text-medium) * var(--ui-line-height) + var(--ui-space-1) * 2);
+  transition: background-color 80ms ease;
+}
+
+.shell:focus-within .row {
+  background-color: var(--ui-background-0);
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+}
+
+.rowDisabled {
+  cursor: not-allowed;
+}

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

@@ -0,0 +1,26 @@
+import type { PillComboboxOption } from '../PillCombobox/types';
+
+/**
+ * Header-shaped recipients editor: flush with its container, leading inline
+ * label ("To" by default), bottom rule. Designed to sit at the top of a
+ * compose modal or panel — not inside a Field. Shares the underlying
+ * combobox with PillCombobox; differs only in chrome.
+ *
+ * The flush look assumes the parent suppresses its own gutter padding —
+ * inside a Modal, that means `disableContentPadding` on the body. The
+ * header then bleeds edge-to-edge under the modal title.
+ */
+export type ChatRecipientsHeaderProps<T extends string> = {
+  options: PillComboboxOption<T>[];
+  values: T[];
+  onChange: (next: T[]) => void;
+  /** Accessible name for the underlying combobox input. */
+  ariaLabel: string;
+  /** Inline label rendered to the left of the pills. Defaults to "To". */
+  label?: string;
+  placeholder?: string;
+  isDisabled?: boolean;
+  emptyHint?: string;
+};
+
+export type { PillComboboxOption };

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

@@ -0,0 +1,203 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { ChatShell } from './index';
+import { ChatMessage } from '../ChatMessage';
+import { ChatComposer } from '../ChatComposer';
+import { Bar } from '../../Layout/Bar';
+import { Heading } from '../../Content/Heading';
+import { Text } from '../../Content/Text';
+import { Badge } from '../../Content/Badge';
+import { Panels } from '../../Layout/Panels';
+import { Stack } from '../../Layout/Stack';
+
+const meta: Meta<typeof ChatShell> = {
+  title: 'Chat/ChatShell',
+  component: ChatShell,
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    (Story) => (
+      <div style={{ height: '100vh' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatShell>;
+
+type Msg = { id: string; role: 'user' | 'assistant' | 'system'; md: string; timestamp: Date };
+
+const seedConversation = (): Msg[] => [
+  {
+    id: '0',
+    role: 'system',
+    md: 'Conversation started. Model: claude-opus-4-7.',
+    timestamp: new Date(2026, 3, 23, 15, 39),
+  },
+  {
+    id: '1',
+    role: 'user',
+    md: 'What does `BackgroundToken` accept?',
+    timestamp: new Date(2026, 3, 23, 15, 40),
+  },
+  {
+    id: '2',
+    role: 'assistant',
+    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 that sets a component-scoped CSS custom property so nested overrides don't bleed through the cascade.`,
+    timestamp: new Date(2026, 3, 23, 15, 40),
+  },
+  {
+    id: '3',
+    role: 'user',
+    md: 'And which primitives expose it?',
+    timestamp: new Date(2026, 3, 23, 15, 41),
+  },
+  {
+    id: '4',
+    role: 'assistant',
+    md: `\`Bar\`, \`List\`, and \`Panels\` (per-region, via \`headerBackground\` / \`footerBackground\` / \`leftSidebarBackground\` / \`rightSidebarBackground\` / \`mainContentBackground\`).`,
+    timestamp: new Date(2026, 3, 23, 15, 41),
+  },
+];
+
+const useChatState = () => {
+  const [messages, setMessages] = useState<Msg[]>(seedConversation());
+
+  const append = (text: string) => {
+    setMessages((prev) => [
+      ...prev,
+      { id: String(prev.length), role: 'user', md: text, timestamp: new Date() },
+      {
+        id: String(prev.length + 1),
+        role: 'assistant',
+        md: `_(echo)_ ${text}`,
+        timestamp: new Date(),
+      },
+    ]);
+  };
+
+  return { messages, append };
+};
+
+export const Default: Story = {
+  render: () => {
+    const { messages, append } = useChatState();
+
+    return (
+      <ChatShell
+        header={<Bar title="Conversation" />}
+        composer={<ChatComposer onSubmit={append} placeholder="Reply…" />}
+      >
+        {messages.map((m) => (
+          <ChatMessage key={m.id} role={m.role} md={m.md} timestamp={m.timestamp} />
+        ))}
+      </ChatShell>
+    );
+  },
+};
+
+export const NoHeader: Story = {
+  render: () => {
+    const { messages, append } = useChatState();
+
+    return (
+      <ChatShell composer={<ChatComposer onSubmit={append} placeholder="Reply…" />}>
+        {messages.map((m) => (
+          <ChatMessage key={m.id} role={m.role} md={m.md} timestamp={m.timestamp} />
+        ))}
+      </ChatShell>
+    );
+  },
+};
+
+export const RichHeader: Story = {
+  render: () => {
+    const { messages, append } = useChatState();
+
+    return (
+      <ChatShell
+        header={
+          <Bar
+            title="Planning session"
+            right={
+              <Stack direction="row" gap={2} align="center">
+                <Badge isMono>claude-opus-4-7</Badge>
+                <Text isMuted size="small">
+                  1,842 tokens
+                </Text>
+              </Stack>
+            }
+          />
+        }
+        composer={<ChatComposer onSubmit={append} placeholder="Reply…" />}
+      >
+        {messages.map((m) => (
+          <ChatMessage key={m.id} role={m.role} md={m.md} timestamp={m.timestamp} />
+        ))}
+      </ChatShell>
+    );
+  },
+};
+
+export const LongTranscript: Story = {
+  render: () => {
+    const { append } = useChatState();
+
+    const manyMessages: Msg[] = Array.from({ length: 30 }, (_, i) => ({
+      id: String(i),
+      role: i % 2 === 0 ? 'user' : 'assistant',
+      md:
+        i % 2 === 0
+          ? `Turn ${i}: a question about the library.`
+          : `Turn ${i}: a reply with some **markdown** and \`code\`.`,
+      timestamp: new Date(2026, 3, 23, 14, i),
+    }));
+
+    return (
+      <ChatShell
+        header={<Bar title="Long scroll test" />}
+        composer={<ChatComposer onSubmit={append} placeholder="Reply…" />}
+      >
+        {manyMessages.map((m) => (
+          <ChatMessage key={m.id} role={m.role} md={m.md} timestamp={m.timestamp} />
+        ))}
+      </ChatShell>
+    );
+  },
+};
+
+export const InPanels: Story = {
+  render: () => {
+    const { messages, append } = useChatState();
+
+    return (
+      <Panels
+        header={<Bar title="Workbench" />}
+        leftSidebar={
+          <Stack gap={2} padding={3}>
+            <Heading level={3}>Threads</Heading>
+            <Text isMuted size="small">
+              Planning session
+            </Text>
+            <Text isMuted size="small">
+              Bug triage
+            </Text>
+            <Text isMuted size="small">
+              Design review
+            </Text>
+          </Stack>
+        }
+        leftSidebarWidth={200}
+      >
+        <ChatShell
+          composer={<ChatComposer onSubmit={append} placeholder="Reply…" />}
+        >
+          {messages.map((m) => (
+            <ChatMessage key={m.id} role={m.role} md={m.md} timestamp={m.timestamp} />
+          ))}
+        </ChatShell>
+      </Panels>
+    );
+  },
+};

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

@@ -0,0 +1,16 @@
+import type { ChatShellProps } from './types';
+import styles from './styles.module.css';
+
+export const ChatShell = (props: ChatShellProps) => {
+  const { header, composer, children } = props;
+
+  return (
+    <div className={styles.shell}>
+      {header !== undefined && <div className={styles.header}>{header}</div>}
+      <div className={styles.transcript}>{children}</div>
+      <div className={styles.composer}>{composer}</div>
+    </div>
+  );
+};
+
+export type { ChatShellProps };

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

@@ -0,0 +1,27 @@
+.shell {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+  background-color: var(--ui-background-0);
+}
+
+.header {
+  flex-shrink: 0;
+  background-color: var(--ui-background-2);
+  border-bottom: 1px solid var(--ui-border);
+}
+
+.transcript {
+  flex: 1 1 0;
+  overflow: auto;
+  /* min-height: 0 lets the flex child establish its own scroll context
+     instead of stretching to intrinsic content height. */
+  min-height: 0;
+}
+
+.composer {
+  flex-shrink: 0;
+  border-top: 1px solid var(--ui-border);
+  background-color: var(--ui-background-0);
+}

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

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+
+export type ChatShellProps = {
+  header?: ReactNode;
+  composer: ReactNode;
+  children: ReactNode;
+};

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

@@ -0,0 +1,59 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { PillCombobox, type PillComboboxOption } from './index';
+
+const meta: Meta<typeof PillCombobox> = {
+  title: 'Chat/PillCombobox',
+  component: PillCombobox,
+  decorators: [
+    (Story) => (
+      <div style={{ width: 480, padding: 16 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof PillCombobox>;
+
+const actorOptions: PillComboboxOption<string>[] = [
+  { value: 'alice', label: 'Alice' },
+  { value: 'bob', label: 'Bob' },
+  { value: 'carol', label: 'Carol' },
+  { value: 'dave', label: 'Dave' },
+  { value: 'eve', label: 'Eve' },
+  { value: 'mallory', label: 'Mallory' },
+];
+
+const Harness = ({
+  initial = [],
+  isDisabled,
+}: {
+  initial?: string[];
+  isDisabled?: boolean;
+}) => {
+  const [values, setValues] = useState<string[]>(initial);
+  return (
+    <PillCombobox
+      options={actorOptions}
+      values={values}
+      onChange={setValues}
+      ariaLabel="Recipients"
+      placeholder="Type a name…"
+      isDisabled={isDisabled}
+    />
+  );
+};
+
+export const Empty: Story = {
+  render: () => <Harness />,
+};
+
+export const WithSelections: Story = {
+  render: () => <Harness initial={['alice', 'bob']} />,
+};
+
+export const Disabled: Story = {
+  render: () => <Harness initial={['alice']} isDisabled />,
+};

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

@@ -0,0 +1,17 @@
+import { cx } from '../../../utils';
+import { PillComboboxCore } from '../PillComboboxCore/Core';
+import type { PillComboboxOption, PillComboboxProps } from './types';
+import styles from './styles.module.css';
+
+// Bordered, form-element variant. Drops into a Field like a fancy Select.
+// For a flush, modal-header packaging of the same combobox, see
+// `ChatRecipientsHeader`.
+export const PillCombobox = <T extends string,>(props: PillComboboxProps<T>) => (
+  <PillComboboxCore
+    {...props}
+    shellClassName={cx(styles.shell, props.isDisabled && styles.shellDisabled)}
+    rowClassName={cx(styles.row, props.isDisabled && styles.rowDisabled)}
+  />
+);
+
+export type { PillComboboxOption, PillComboboxProps };

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

@@ -0,0 +1,29 @@
+.shell {
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  background-color: var(--ui-background-0);
+}
+
+.shell:focus-within {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: -1px;
+  border-color: var(--ui-accent);
+}
+
+.shellDisabled {
+  opacity: 0.5;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--ui-space-1);
+  padding: var(--ui-space-1) var(--ui-space-2);
+  cursor: text;
+  min-height: calc(var(--ui-text-medium) * var(--ui-line-height) + var(--ui-space-2) * 2);
+}
+
+.rowDisabled {
+  cursor: not-allowed;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * A single selectable option. `value` is the stable key (e.g. an actor id
+ * stringified, a slug); `label` is what the user sees in pills and the
+ * dropdown.
+ */
+export type PillComboboxOption<T extends string> = {
+  value: T;
+  label: string;
+};
+
+/**
+ * Gmail-style "type to search, select adds a pill" combobox. Generic by
+ * value type. Lives in the Chat namespace for now; built to general
+ * ui-component standards so it can graduate when a second consumer
+ * arrives.
+ */
+export type PillComboboxProps<T extends string> = {
+  options: PillComboboxOption<T>[];
+  values: T[];
+  onChange: (next: T[]) => void;
+  /** Accessible name for the underlying combobox input. */
+  ariaLabel: string;
+  /** Shown when no pills are selected and the input is empty. */
+  placeholder?: string;
+  isDisabled?: boolean;
+  /** Shown in the dropdown when the typed query has no matches. */
+  emptyHint?: string;
+};