@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+export type StackDirection = 'row' | 'column';
+export type StackGap = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type StackPadding = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch';
+export type StackJustify = 'start' | 'center' | 'end' | 'between';
+
+export type StackProps = {
+  children: ReactNode;
+  direction?: StackDirection;
+  gap?: StackGap;
+  padding?: StackPadding;
+  align?: StackAlign;
+  justify?: StackJustify;
+  isWrap?: boolean;
+};

package/src/components/Modals/ConfirmModal/ConfirmModal.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ConfirmModal } from './index';
+import { Toggle } from '../../../storybook';
+
+const meta: Meta<typeof ConfirmModal> = {
+  title: 'Modals/ConfirmModal',
+  component: ConfirmModal,
+};
+
+export default meta;
+type Story = StoryObj<typeof ConfirmModal>;
+
+type HarnessProps = {
+  isDanger?: boolean;
+  title: string;
+  description?: string;
+  confirmLabel?: string;
+  initialOpen?: boolean;
+};
+
+const Harness = ({
+  isDanger,
+  title,
+  description,
+  confirmLabel,
+  initialOpen = false,
+}: HarnessProps) => (
+  <Toggle defaultOn={initialOpen}>
+    {({ isOn, on, off }) => (
+      <>
+        <button type="button" onClick={on}>Open</button>
+        <ConfirmModal
+          isOpen={isOn}
+          onCancel={off}
+          onConfirm={async () => {
+            await new Promise((r) => setTimeout(r, 500));
+            off();
+          }}
+          title={title}
+          description={description}
+          confirmLabel={confirmLabel}
+          isDanger={isDanger}
+        />
+      </>
+    )}
+  </Toggle>
+);
+
+export const Default: Story = {
+  render: () => (
+    <Harness
+      initialOpen
+      title="Archive this work item?"
+      description="It will move to the archive and stop appearing in the active board."
+      confirmLabel="Archive"
+    />
+  ),
+};
+
+export const Danger: Story = {
+  render: () => (
+    <Harness
+      isDanger
+      title="Delete this actor?"
+      description="Their agent runs will be orphaned. This cannot be undone."
+      confirmLabel="Delete"
+    />
+  ),
+};
+
+export const NoDescription: Story = {
+  render: () => <Harness title="Continue?" />,
+};

package/src/components/Modals/ConfirmModal/index.tsx

@@ -0,0 +1,72 @@
+import { useState } from 'react';
+import { cx } from '../../../utils';
+import { ModalShell } from '../internal/ModalShell';
+import type { ConfirmModalProps } from './types';
+import styles from './styles.module.css';
+
+export const ConfirmModal = (props: ConfirmModalProps) => {
+  const {
+    isOpen,
+    onConfirm,
+    onCancel,
+    title,
+    description,
+    confirmLabel = 'Confirm',
+    cancelLabel = 'Cancel',
+    isDanger = false,
+  } = props;
+
+  const [isWorking, setIsWorking] = useState(false);
+
+  const handleConfirm = async () => {
+    try {
+      setIsWorking(true);
+      await onConfirm();
+    } finally {
+      setIsWorking(false);
+    }
+  };
+
+  // Block backdrop, Esc, and the close X from cancelling while in-flight.
+  const handleClose = () => {
+    if (!isWorking) onCancel();
+  };
+
+  return (
+    <ModalShell
+      isOpen={isOpen}
+      onClose={handleClose}
+      title={title}
+      dialogClassName={styles.dialog}
+      bodyClassName={styles.body}
+      footer={
+        <>
+          <button
+            type="button"
+            className={cx(styles.button, styles.cancelButton)}
+            onClick={onCancel}
+            disabled={isWorking}
+            autoFocus
+          >
+            {cancelLabel}
+          </button>
+          <button
+            type="button"
+            className={cx(
+              styles.button,
+              isDanger ? styles.dangerButton : styles.confirmButton,
+            )}
+            onClick={handleConfirm}
+            disabled={isWorking}
+          >
+            {isWorking ? 'Working…' : confirmLabel}
+          </button>
+        </>
+      }
+    >
+      {description && <div className={styles.description}>{description}</div>}
+    </ModalShell>
+  );
+};
+
+export type { ConfirmModalProps };

package/src/components/Modals/ConfirmModal/styles.module.css

@@ -0,0 +1,62 @@
+.dialog {
+  min-width: 360px;
+  max-width: 480px;
+}
+
+.body {
+  min-height: 120px;
+}
+
+.description {
+  margin: 0;
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  color: var(--ui-muted);
+}
+
+.button {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-medium);
+  font-weight: 500;
+  line-height: 1;
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  padding: 6px 14px;
+  cursor: pointer;
+}
+
+.button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.cancelButton {
+  background-color: var(--ui-background-0);
+  color: var(--ui-foreground);
+}
+
+.cancelButton:hover:not(:disabled) {
+  background-color: var(--ui-background-1);
+}
+
+.confirmButton {
+  background-color: var(--ui-accent);
+  color: var(--ui-on-accent);
+  border-color: var(--ui-accent);
+}
+
+.confirmButton:hover:not(:disabled) {
+  background-color: var(--ui-accent-hover);
+  border-color: var(--ui-accent-hover);
+}
+
+.dangerButton {
+  background-color: var(--ui-danger);
+  color: var(--ui-on-danger);
+  border-color: var(--ui-danger);
+}
+
+.dangerButton:hover:not(:disabled) {
+  background-color: var(--ui-danger-hover);
+  border-color: var(--ui-danger-hover);
+}

package/src/components/Modals/ConfirmModal/types.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+
+export type ConfirmModalProps = {
+  isOpen: boolean;
+  onConfirm: () => void | Promise<void>;
+  onCancel: () => void;
+  title: string;
+  /** Body content. String for simple prose, ReactNode when formatting or emphasis is needed. */
+  description?: ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Styles the confirm button as destructive (danger palette). */
+  isDanger?: boolean;
+};

package/src/components/Modals/LargeModal/LargeModal.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { LargeModal } from './index';
+import { Button } from '../../Forms/Button';
+import { Stack } from '../../Layout/Stack';
+import { Text } from '../../Content/Text';
+import { Lorem, Toggle } from '../../../storybook';
+
+const meta: Meta<typeof LargeModal> = {
+  title: 'Modals/LargeModal',
+  component: LargeModal,
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj<typeof LargeModal>;
+
+export const Default: Story = {
+  render: () => (
+    <Toggle defaultOn>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>Open large modal</Button>
+          <LargeModal
+            isOpen={isOn}
+            onClose={off}
+            title="Workspace detail"
+            footer={
+              <Button variant="primary" onClick={off}>
+                Done
+              </Button>
+            }
+          >
+            <Stack gap={3}>
+              <Text>
+                Large modals take up 90% of the viewport width and height — suited to
+                immersive content: long forms, detail views, editors.
+              </Text>
+              <Lorem paragraphs={20} as={Text} />
+            </Stack>
+          </LargeModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};
+
+export const FullBleed: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>Open full-bleed large modal</Button>
+          <LargeModal
+            isOpen={isOn}
+            onClose={off}
+            disableContentPadding
+            title="Custom layout"
+            footer={
+              <Button variant="primary" onClick={off}>
+                Close
+              </Button>
+            }
+          >
+            <div style={{ padding: 32, background: 'var(--ui-background-2)', flex: 1 }}>
+              <Text>
+                With `disableContentPadding`, children sit flush — useful when the
+                callee brings its own layout (split panes, tables, full-bleed media).
+              </Text>
+            </div>
+          </LargeModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};

package/src/components/Modals/LargeModal/index.tsx

@@ -0,0 +1,9 @@
+import type { LargeModalProps } from './types';
+import { ModalShell } from '../internal/ModalShell';
+import styles from './styles.module.css';
+
+export const LargeModal = (props: LargeModalProps) => (
+  <ModalShell {...props} dialogClassName={styles.dialog} />
+);
+
+export type { LargeModalProps };

package/src/components/Modals/LargeModal/styles.module.css

@@ -0,0 +1,6 @@
+.dialog {
+  width: 90vw;
+  height: 90vh;
+  max-width: none;
+  max-height: none;
+}

package/src/components/Modals/LargeModal/types.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+
+export type LargeModalProps = {
+  isOpen: boolean;
+  onClose: () => void;
+  title?: string;
+  /** Optional secondary header strips rendered between the title bar and
+   *  the body. Each entry is wrapped in a div with the same divider style
+   *  so they stack as distinct rows (recipients editor, breadcrumbs,
+   *  filter bar, etc.). Each entry must carry a `key` prop —
+   *  `react/jsx-key` will flag any array element without one. */
+  subHeaders?: ReactNode[];
+  children: ReactNode;
+  footer?: ReactNode;
+  /** Opt out of the default body padding for full-bleed content. */
+  disableContentPadding?: boolean;
+  contentBackgroundOffsetColor?: boolean;
+};

package/src/components/Modals/MediumModal/MediumModal.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MediumModal } from './index';
+import { Button } from '../../Forms/Button';
+import { Field } from '../../Forms/Field';
+import { Input } from '../../Forms/Input';
+import { Stack } from '../../Layout/Stack';
+import { Text } from '../../Content/Text';
+import { Lorem, Toggle } from '../../../storybook';
+
+const meta: Meta<typeof MediumModal> = {
+  title: 'Modals/MediumModal',
+  component: MediumModal,
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj<typeof MediumModal>;
+
+export const Default: Story = {
+  render: () => (
+    <Toggle defaultOn>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>Open modal</Button>
+          <MediumModal
+            isOpen={isOn}
+            onClose={off}
+            title="Confirm action"
+            footer={
+              <>
+                <Button onClick={off}>Cancel</Button>
+                <Button variant="primary" onClick={off}>Confirm</Button>
+              </>
+            }
+          >
+            <Text>Are you sure you want to proceed? This action cannot be undone.</Text>
+          </MediumModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};
+
+export const WithForm: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>New item…</Button>
+          <MediumModal
+            isOpen={isOn}
+            onClose={off}
+            contentBackgroundOffsetColor
+            title="Create item"
+            footer={
+              <>
+                <Button onClick={off}>Cancel</Button>
+                <Button variant="primary" onClick={off}>Create</Button>
+              </>
+            }
+          >
+            <Stack gap={3}>
+              <Field label="Title">
+                <Input placeholder="Title" />
+              </Field>
+              <Field label="Description" hint="Optional">
+                <Input placeholder="Short description" />
+              </Field>
+            </Stack>
+          </MediumModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};
+
+export const LongContent: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>View release notes</Button>
+          <MediumModal
+            isOpen={isOn}
+            onClose={off}
+            title="Release notes"
+            footer={
+              <>
+                <Button onClick={off}>Close</Button>
+                <Button variant="primary" onClick={off}>Acknowledge</Button>
+              </>
+            }
+          >
+            <Stack gap={3}>
+              <Lorem paragraphs={30} as={Text} />
+            </Stack>
+          </MediumModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};
+
+export const NoTitle: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>Open untitled modal</Button>
+          <MediumModal
+            isOpen={isOn}
+            onClose={off}
+            footer={<Button variant="primary" onClick={off}>Done</Button>}
+          >
+            <Text>A modal without a title still shows the close affordance in the header.</Text>
+          </MediumModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};

package/src/components/Modals/MediumModal/MediumModal.test.tsx

@@ -0,0 +1,48 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { render, fireEvent, cleanup } from '@testing-library/react';
+import { MediumModal } from './index';
+
+// happy-dom implements showMediumModal/close but we call cleanup between tests
+// manually (bun:test has no afterEach-by-default in this setup).
+const setup = (props: Partial<React.ComponentProps<typeof MediumModal>> = {}) => {
+  const onClose = mock(() => {});
+  const utils = render(
+    <MediumModal isOpen onClose={onClose} title="Settings" {...props}>
+      <button type="button">inside</button>
+    </MediumModal>,
+  );
+  const dialog = utils.container.ownerDocument.querySelector('dialog');
+  if (!dialog) throw new Error('dialog not rendered');
+  return { ...utils, onClose, dialog };
+};
+
+describe('MediumModal', () => {
+  test('renders title and children when open', () => {
+    const { getByText } = setup();
+    expect(getByText('Settings')).toBeTruthy();
+    expect(getByText('inside')).toBeTruthy();
+    cleanup();
+  });
+
+  test('calls onClose when the backdrop (the dialog itself) is clicked', () => {
+    const { onClose, dialog } = setup();
+    fireEvent.click(dialog);
+    expect(onClose).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+
+  test('does not call onClose when clicking inside the content', () => {
+    const { onClose, getByText } = setup();
+    fireEvent.click(getByText('inside'));
+    expect(onClose).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('calls onClose on the native cancel event (Escape)', () => {
+    const { onClose, dialog } = setup();
+    const cancel = new Event('cancel', { cancelable: true });
+    dialog.dispatchEvent(cancel);
+    expect(onClose).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+});

package/src/components/Modals/MediumModal/index.tsx

@@ -0,0 +1,9 @@
+import type { MediumModalProps } from './types';
+import { ModalShell } from '../internal/ModalShell';
+import styles from './styles.module.css';
+
+export const MediumModal = (props: MediumModalProps) => (
+  <ModalShell {...props} dialogClassName={styles.dialog} />
+);
+
+export type { MediumModalProps };

package/src/components/Modals/MediumModal/styles.module.css

@@ -0,0 +1,5 @@
+.dialog {
+  width: min(90vw, 768px);
+  min-height: 576px;
+  max-height: 85vh;
+}

package/src/components/Modals/MediumModal/types.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+
+export type MediumModalProps = {
+  isOpen: boolean;
+  onClose: () => void;
+  title?: string;
+  /** Optional secondary header strips rendered between the title bar and
+   *  the body. Each entry is wrapped in a div with the same divider style
+   *  so they stack as distinct rows (recipients editor, breadcrumbs,
+   *  filter bar, etc.). Each entry must carry a `key` prop —
+   *  `react/jsx-key` will flag any array element without one. */
+  subHeaders?: ReactNode[];
+  children: ReactNode;
+  footer?: ReactNode;
+  /** Opt out of the default body padding for full-bleed content. */
+  disableContentPadding?: boolean;
+  contentBackgroundOffsetColor?: boolean;
+};

package/src/components/Modals/index.ts

@@ -0,0 +1,3 @@
+export { MediumModal, type MediumModalProps } from './MediumModal';
+export { LargeModal, type LargeModalProps } from './LargeModal';
+export { ConfirmModal, type ConfirmModalProps } from './ConfirmModal';

package/src/components/Modals/internal/ModalBody.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+type Props = {
+  children: ReactNode;
+  /** Opt out of the default body padding for full-bleed content
+   *  (split panes, tables, custom layouts that bring their own). */
+  disableContentPadding?: boolean;
+  className?: string;
+};
+
+export const ModalBody = (props: Props) => {
+  const { children, disableContentPadding = false, className } = props;
+
+  return (
+    <div className={cx(styles.body, !disableContentPadding && styles.bodyPadded, className)}>
+      {children}
+    </div>
+  );
+};

package/src/components/Modals/internal/ModalFooter.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import styles from './styles.module.css';
+
+type Props = {
+  children: ReactNode;
+};
+
+export const ModalFooter = (props: Props) => {
+  const { children } = props;
+
+  return <footer className={styles.footer}>{children}</footer>;
+};

package/src/components/Modals/internal/ModalHeader.tsx

@@ -0,0 +1,27 @@
+import { IconButton } from '../../Forms/IconButton';
+import styles from './styles.module.css';
+
+type Props = {
+  title?: string;
+  onClose: () => void;
+};
+
+export const ModalHeader = (props: Props) => {
+  const { title, onClose } = props;
+
+  return (
+    <header className={styles.header}>
+      {title ? <h2 className={styles.title}>{title}</h2> : <span />}
+      <IconButton ariaLabel="Close" size="small" onClick={onClose}>
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+          <path
+            d="M4 4 L12 12 M12 4 L4 12"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeLinecap="round"
+          />
+        </svg>
+      </IconButton>
+    </header>
+  );
+};