@structuralists/scaffolding 0.0.1

package/src/components/Chat/PillComboboxCore/Core.tsx

@@ -0,0 +1,235 @@
+import {
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import { Popover } from '../../Overlays/Popover';
+import { cx } from '../../../utils';
+import type { PillComboboxOption } from '../PillCombobox/types';
+import styles from './styles.module.css';
+
+// Internal core for the chat combobox family. Owns all behavior (keyboard,
+// popover, query/filter state, pill rendering). Variants — `PillCombobox`
+// (bordered form element) and `ChatRecipientsHeader` (flush header) — wrap
+// this and supply their own chrome via `shellClassName` (outer) +
+// `rowClassName` (inner).
+//
+// The two-element shape is what lets a flush variant render a visible
+// focus state: outer takes any small padding (so the inner has room to
+// inset), and inner takes the focus-within visual (background tint, ring,
+// etc.) without bleeding to the modal's edges.
+export type PillComboboxCoreProps<T extends string> = {
+  options: PillComboboxOption<T>[];
+  values: T[];
+  onChange: (next: T[]) => void;
+  ariaLabel: string;
+  placeholder?: string;
+  isDisabled?: boolean;
+  emptyHint?: string;
+  /** Outer wrapper className. Anchors the popover; owns edge chrome
+   *  (border/radius for bordered, bottom-rule for flush). */
+  shellClassName: string;
+  /** Inner row className. Owns layout (flex, gap, padding) and the
+   *  focus-within visual feedback. */
+  rowClassName: string;
+  /** Optional content rendered as a sibling of the inner row, before
+   *  it — e.g. an inline "To" label in the header variant. Sits in the
+   *  outer shell so it isn't covered by the row's focus visual. */
+  leadingSlot?: ReactNode;
+};
+
+export const PillComboboxCore = <T extends string,>({
+  options,
+  values,
+  onChange,
+  ariaLabel,
+  placeholder,
+  isDisabled,
+  emptyHint = 'No matches.',
+  shellClassName,
+  rowClassName,
+  leadingSlot,
+}: PillComboboxCoreProps<T>) => {
+  const shellRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listId = useId();
+
+  const [query, setQuery] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+  const [focusIndex, setFocusIndex] = useState(0);
+
+  const labelByValue = useMemo(() => {
+    const m = new Map<T, string>();
+    for (const o of options) m.set(o.value, o.label);
+    return m;
+  }, [options]);
+
+  const filtered = useMemo(() => {
+    const selectedSet = new Set(values);
+    const q = query.trim().toLowerCase();
+    return options.filter(
+      (o) =>
+        !selectedSet.has(o.value) &&
+        (q === '' || o.label.toLowerCase().includes(q)),
+    );
+  }, [options, values, query]);
+
+  // Keep focusIndex in range when filtered shrinks (e.g. after a select).
+  useEffect(() => {
+    setFocusIndex((i) => (filtered.length === 0 ? 0 : Math.min(i, filtered.length - 1)));
+  }, [filtered.length]);
+
+  const open = () => {
+    if (!isDisabled) setIsOpen(true);
+  };
+  const close = () => setIsOpen(false);
+
+  const select = (option: PillComboboxOption<T>) => {
+    onChange([...values, option.value]);
+    setQuery('');
+    setFocusIndex(0);
+    inputRef.current?.focus();
+    // popover stays open for rapid-fire add
+  };
+
+  const removeAt = (index: number) => {
+    if (isDisabled) return;
+    const next = values.slice();
+    next.splice(index, 1);
+    onChange(next);
+    inputRef.current?.focus();
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (isDisabled) return;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      open();
+      setFocusIndex((i) =>
+        filtered.length === 0 ? 0 : (i + 1) % filtered.length,
+      );
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      open();
+      setFocusIndex((i) =>
+        filtered.length === 0 ? 0 : (i - 1 + filtered.length) % filtered.length,
+      );
+    } else if (e.key === 'Enter') {
+      if (isOpen && filtered.length > 0) {
+        e.preventDefault();
+        const focused = filtered[focusIndex];
+        if (focused) select(focused);
+      }
+    } else if (e.key === 'Escape') {
+      if (isOpen) {
+        e.preventDefault();
+        close();
+      }
+    } else if (e.key === 'Backspace') {
+      if (query === '' && values.length > 0) {
+        e.preventDefault();
+        removeAt(values.length - 1);
+      }
+    }
+  };
+
+  const handleRowMouseDown = (e: MouseEvent<HTMLDivElement>) => {
+    // Clicking empty row space focuses the input. Clicks on pills, the
+    // remove button, the leadingSlot, or the input itself bubble through
+    // and handle themselves.
+    if (e.target === e.currentTarget) {
+      e.preventDefault();
+      inputRef.current?.focus();
+    }
+  };
+
+  const showInputPlaceholder = values.length === 0 && query === '';
+
+  return (
+    <>
+      <div ref={shellRef} className={shellClassName}>
+        {leadingSlot}
+        <div className={rowClassName} onMouseDown={handleRowMouseDown}>
+          {values.map((value, i) => {
+            const label = labelByValue.get(value) ?? value;
+            return (
+              <span key={value} className={styles.pill}>
+                <span>{label}</span>
+                <button
+                  type="button"
+                  className={styles.pillRemove}
+                  aria-label={`Remove ${label}`}
+                  onClick={() => removeAt(i)}
+                  disabled={isDisabled}
+                >
+                  ×
+                </button>
+              </span>
+            );
+          })}
+          <input
+            ref={inputRef}
+            type="text"
+            role="combobox"
+            aria-expanded={isOpen}
+            aria-controls={listId}
+            aria-autocomplete="list"
+            aria-label={ariaLabel}
+            className={styles.input}
+            value={query}
+            onChange={(e) => {
+              setQuery(e.target.value);
+              open();
+            }}
+            onFocus={open}
+            onKeyDown={handleKeyDown}
+            placeholder={showInputPlaceholder ? placeholder : undefined}
+            disabled={isDisabled}
+          />
+        </div>
+      </div>
+      <Popover
+        anchorRef={shellRef}
+        isOpen={isOpen && !isDisabled}
+        onClose={close}
+        ariaLabel={ariaLabel}
+        matchAnchorWidth
+        hasBodyPadding={false}
+      >
+        <div id={listId} role="listbox" className={styles.list}>
+          {filtered.length === 0 ? (
+            <div className={styles.empty}>{emptyHint}</div>
+          ) : (
+            filtered.map((option, i) => {
+              const focused = i === focusIndex;
+              return (
+                <div
+                  key={option.value}
+                  role="option"
+                  aria-selected={focused}
+                  className={cx(
+                    styles.option,
+                    focused && styles.optionFocused,
+                  )}
+                  onMouseEnter={() => setFocusIndex(i)}
+                  onMouseDown={(e) => {
+                    // Prevent input blur; commit on click.
+                    e.preventDefault();
+                  }}
+                  onClick={() => select(option)}
+                >
+                  <span>{option.label}</span>
+                </div>
+              );
+            })
+          )}
+        </div>
+      </Popover>
+    </>
+  );
+};

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

@@ -0,0 +1,79 @@
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ui-space-1);
+  padding: 2px var(--ui-space-1) 2px var(--ui-space-2);
+  background-color: var(--ui-background-2);
+  border: 1px solid var(--ui-border-subtle);
+  border-radius: var(--ui-radius);
+  font-size: var(--ui-text-small);
+  line-height: var(--ui-line-height-tight);
+  color: var(--ui-foreground);
+}
+
+.pillRemove {
+  font: inherit;
+  font-size: var(--ui-text-small);
+  line-height: 1;
+  padding: 0 var(--ui-space-1);
+  background: transparent;
+  border: 0;
+  color: var(--ui-muted);
+  cursor: pointer;
+  border-radius: var(--ui-radius);
+}
+
+.pillRemove:hover:not(:disabled) {
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-1);
+}
+
+.pillRemove:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: 1px;
+}
+
+.input {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  color: var(--ui-foreground);
+  background: transparent;
+  border: 0;
+  outline: none;
+  flex: 1 1 8rem;
+  min-width: 6rem;
+  padding: var(--ui-space-1) 0;
+}
+
+.input:disabled {
+  cursor: not-allowed;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  max-height: 240px;
+  overflow-y: auto;
+}
+
+.option {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: var(--ui-space-2) var(--ui-space-3);
+  cursor: pointer;
+  color: var(--ui-foreground);
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height-tight);
+}
+
+.optionFocused {
+  background-color: var(--ui-background-1);
+}
+
+.empty {
+  padding: var(--ui-space-2) var(--ui-space-3);
+  color: var(--ui-muted);
+  font-size: var(--ui-text-small);
+}

package/src/components/Chat/index.ts

@@ -0,0 +1,12 @@
+export { ChatMessage, type ChatMessageProps, type ChatMessageRole } from './ChatMessage';
+export { ChatShell, type ChatShellProps } from './ChatShell';
+export { ChatComposer, type ChatComposerProps } from './ChatComposer';
+export {
+  PillCombobox,
+  type PillComboboxOption,
+  type PillComboboxProps,
+} from './PillCombobox';
+export {
+  ChatRecipientsHeader,
+  type ChatRecipientsHeaderProps,
+} from './ChatRecipientsHeader';

package/src/components/Content/Badge/Badge.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Badge } from './index';
+import { Stack } from '../../Layout/Stack';
+
+const meta: Meta<typeof Badge> = {
+  title: 'Content/Badge',
+  component: Badge,
+  args: { children: 'draft' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Badge>;
+
+export const Default: Story = {};
+
+export const Mono: Story = { args: { isMono: true, children: 'SPM-2816' } };
+
+export const Clickable: Story = {
+  args: { isMono: true, children: 'ENG-4412', onClick: () => alert('clicked') },
+};
+
+export const Cluster: Story = {
+  render: () => (
+    <Stack direction="row" gap={1} isWrap>
+      <Badge>open</Badge>
+      <Badge>in progress</Badge>
+      <Badge isMono>SPM-2816</Badge>
+      <Badge isMono>ENG-4412</Badge>
+    </Stack>
+  ),
+};

package/src/components/Content/Badge/index.tsx

@@ -0,0 +1,22 @@
+import type { BadgeProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+export const Badge = (props: BadgeProps) => {
+  const { children, isMono, onClick } = props;
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        className={cx(styles.badge, styles.clickable, isMono && styles.mono)}
+      >
+        {children}
+      </button>
+    );
+  }
+  return <span className={cx(styles.badge, isMono && styles.mono)}>{children}</span>;
+};
+
+export type { BadgeProps };

package/src/components/Content/Badge/styles.module.css

@@ -0,0 +1,25 @@
+.badge {
+  display: inline-flex;
+  align-items: center;
+  font-size: var(--ui-text-xsmall);
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-3);
+  padding: 2px 6px;
+  border-radius: var(--ui-radius);
+  line-height: 1.2;
+  border: 0;
+  font-family: inherit;
+}
+
+.mono {
+  font-family: var(--ui-font-mono);
+}
+
+.clickable {
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.clickable:hover {
+  background-color: var(--ui-border-subtle);
+}

package/src/components/Content/Badge/types.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+
+export type BadgeProps = {
+  children: ReactNode;
+  isMono?: boolean;
+  onClick?: () => void;
+};

package/src/components/Content/Card/Card.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Card } from './index';
+import { Heading } from '../Heading';
+import { Stack } from '../../Layout/Stack';
+import { Text } from '../Text';
+
+const meta: Meta<typeof Card> = {
+  title: 'Content/Card',
+  component: Card,
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  render: () => (
+    <Card>
+      <Stack gap={2}>
+        <Heading level={3}>Card title</Heading>
+        <Text>Cards are simple bordered containers for grouped content.</Text>
+      </Stack>
+    </Card>
+  ),
+};

package/src/components/Content/Card/index.tsx

@@ -0,0 +1,21 @@
+import type { CardPadding, CardProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const PADDING_MAP: Record<CardPadding, string> = {
+  0: styles.padding0,
+  1: styles.padding1,
+  2: styles.padding2,
+  3: styles.padding3,
+  4: styles.padding4,
+  5: styles.padding5,
+  6: styles.padding6,
+};
+
+export const Card = (props: CardProps) => {
+  const { children, padding = 3 } = props;
+
+  return <div className={cx(styles.card, PADDING_MAP[padding])}>{children}</div>;
+};
+
+export type { CardProps };

package/src/components/Content/Card/styles.module.css

@@ -0,0 +1,13 @@
+.card {
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+}
+
+.padding0 { padding: 0; }
+.padding1 { padding: var(--ui-space-1); }
+.padding2 { padding: var(--ui-space-2); }
+.padding3 { padding: var(--ui-space-3); }
+.padding4 { padding: var(--ui-space-4); }
+.padding5 { padding: var(--ui-space-5); }
+.padding6 { padding: var(--ui-space-6); }

package/src/components/Content/Card/types.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type CardPadding = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export type CardProps = {
+  children: ReactNode;
+  padding?: CardPadding;
+};

package/src/components/Content/EditableMarkdown/EditableMarkdown.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { EditableMarkdown } from './index';
+
+const sample = `# Project notes
+
+A paragraph with **bold** text, *italic*, and \`inline code\`.
+
+- First point
+- Second point with a [link](https://example.com)
+- Third point
+
+\`\`\`ts
+const greeting = 'hello';
+\`\`\`
+
+> A passing thought, set aside.
+`;
+
+const Harness = ({ initial }: { initial: string }) => {
+  const [value, setValue] = useState(initial);
+  return (
+    <div style={{ width: 640 }}>
+      <EditableMarkdown
+        value={value}
+        label="description"
+        onSave={async (next) => {
+          await new Promise((r) => setTimeout(r, 400));
+          setValue(next);
+        }}
+      />
+    </div>
+  );
+};
+
+const meta: Meta<typeof EditableMarkdown> = {
+  title: 'Content/EditableMarkdown',
+  component: EditableMarkdown,
+};
+
+export default meta;
+type Story = StoryObj<typeof EditableMarkdown>;
+
+export const WithContent: Story = {
+  render: () => <Harness initial={sample} />,
+};
+
+export const Empty: Story = {
+  render: () => <Harness initial="" />,
+};
+
+export const ReadOnly: Story = {
+  render: () => (
+    <div style={{ width: 640 }}>
+      <EditableMarkdown value={sample} canEdit={false} onSave={() => {}} />
+    </div>
+  ),
+};

package/src/components/Content/EditableMarkdown/index.tsx

@@ -0,0 +1,140 @@
+import { useEffect, useRef, useState } from 'react';
+import ReactMarkdown from 'react-markdown';
+import { cx } from '../../../utils';
+import type { EditableMarkdownProps } from './types';
+import styles from './styles.module.css';
+
+type Tab = 'write' | 'preview';
+
+export const EditableMarkdown = (props: EditableMarkdownProps) => {
+  const {
+    value,
+    onSave,
+    onCancel,
+    canEdit = true,
+    placeholder = 'No content',
+    label,
+  } = props;
+
+  const [isEditing, setIsEditing] = useState(false);
+  const [activeTab, setActiveTab] = useState<Tab>('write');
+  const [draft, setDraft] = useState('');
+  const [isSaving, setIsSaving] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Refocus the textarea when entering edit mode or switching back to Write.
+  // Keeps the native selection/cursor intact across tab toggles because the
+  // textarea stays mounted (display:none) when Preview is active.
+  useEffect(() => {
+    if (isEditing && activeTab === 'write') {
+      textareaRef.current?.focus();
+    }
+  }, [isEditing, activeTab]);
+
+  const enterEdit = () => {
+    setDraft(value);
+    setActiveTab('write');
+    setIsEditing(true);
+  };
+
+  const handleCancel = () => {
+    setIsEditing(false);
+    onCancel?.();
+  };
+
+  const handleSave = async () => {
+    try {
+      setIsSaving(true);
+      await onSave(draft);
+      setIsEditing(false);
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  if (!isEditing) {
+    return (
+      <div className={styles.container}>
+        {value ? (
+          <div className={styles.markdown}>
+            <ReactMarkdown>{value}</ReactMarkdown>
+          </div>
+        ) : (
+          <div className={styles.empty}>{placeholder}</div>
+        )}
+        {canEdit && (
+          <button
+            type="button"
+            className={styles.editButton}
+            onClick={enterEdit}
+            aria-label={label ? `Edit ${label}` : 'Edit'}
+          >
+            Edit
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.editor}>
+      <div className={styles.tabs} role="tablist">
+        <button
+          type="button"
+          role="tab"
+          aria-selected={activeTab === 'write'}
+          className={cx(styles.tab, activeTab === 'write' && styles.tabActive)}
+          onClick={() => setActiveTab('write')}
+        >
+          Write
+        </button>
+        <button
+          type="button"
+          role="tab"
+          aria-selected={activeTab === 'preview'}
+          className={cx(styles.tab, activeTab === 'preview' && styles.tabActive)}
+          onClick={() => setActiveTab('preview')}
+        >
+          Preview
+        </button>
+      </div>
+      <div className={styles.body}>
+        <textarea
+          ref={textareaRef}
+          className={cx(styles.textarea, activeTab !== 'write' && styles.hidden)}
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+        />
+        <div className={cx(styles.preview, activeTab !== 'preview' && styles.hidden)}>
+          {draft ? (
+            <div className={styles.markdown}>
+              <ReactMarkdown>{draft}</ReactMarkdown>
+            </div>
+          ) : (
+            <div className={styles.empty}>Nothing to preview</div>
+          )}
+        </div>
+      </div>
+      <div className={styles.actions}>
+        <button
+          type="button"
+          className={cx(styles.actionButton, styles.cancelButton)}
+          onClick={handleCancel}
+          disabled={isSaving}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className={cx(styles.actionButton, styles.saveButton)}
+          onClick={handleSave}
+          disabled={isSaving}
+        >
+          {isSaving ? 'Saving…' : 'Save'}
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export type { EditableMarkdownProps };