@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,287 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Panels } from './index';
+import { Bar } from '../Bar';
+import { Button } from '../../Forms/Button';
+import { Text } from '../../Content/Text';
+import { Heading } from '../../Content/Heading';
+import { Stack } from '../Stack';
+import { Lorem } from '../../../storybook';
+
+const meta: Meta<typeof Panels> = {
+  title: 'Layout/Panels',
+  component: Panels,
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    (Story) => (
+      <div style={{ height: '100vh' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Panels>;
+
+const LeftSidebarContent = () => (
+  <Stack gap={2}>
+    {['Inbox', 'Today', 'Upcoming', 'Archive'].map((label) => (
+      <Text key={label}>{label}</Text>
+    ))}
+  </Stack>
+);
+
+const RightSidebarContent = () => (
+  <Stack gap={2}>
+    <Heading level={3}>Details</Heading>
+    <Text isMuted size="small">
+      Select something to inspect.
+    </Text>
+  </Stack>
+);
+
+const LongMain = () => (
+  <Stack gap={3}>
+    <Heading level={2}>Main content</Heading>
+    <Lorem paragraphs={40} as={Text} />
+  </Stack>
+);
+
+// Inline padding for main/sidebar slot content; Bar handles its own padding
+// so header/footer slots pass a Bar directly instead of going through this.
+const slot = (children: React.ReactNode, width?: number) => (
+  <div style={{ padding: 16, ...(width ? { width } : {}) }}>{children}</div>
+);
+
+export const Full: Story = {
+  render: () => (
+    <Panels
+      header={
+        <Bar
+          title="Workbench"
+          right={
+            <Text isMuted size="small">
+              v0.1
+            </Text>
+          }
+        />
+      }
+      footer={<Bar title="Ready." />}
+      leftSidebar={slot(<LeftSidebarContent />, 200)}
+      rightSidebar={slot(<RightSidebarContent />, 260)}
+    >
+      {slot(<LongMain />)}
+    </Panels>
+  ),
+};
+
+export const HeaderAndMain: Story = {
+  render: () => (
+    <Panels header={<Bar title="Workbench" />}>{slot(<LongMain />)}</Panels>
+  ),
+};
+
+export const LeftSidebarOnly: Story = {
+  render: () => (
+    <Panels leftSidebar={slot(<LeftSidebarContent />, 200)}>
+      {slot(<LongMain />)}
+    </Panels>
+  ),
+};
+
+export const MainOnly: Story = {
+  render: () => <Panels>{slot(<LongMain />)}</Panels>,
+};
+
+// rightOverlay slides in from the right, bounded by header/footer so the
+// app nav and footer remain visible and interactive. Open state lives in
+// the parent — passing `null` triggers the slide-out animation.
+export const RightOverlay: Story = {
+  render: () => {
+    const RightOverlayDemo = () => {
+      const [selected, setSelected] = useState<string | null>(null);
+
+      return (
+        <Panels
+          header={
+            <Bar
+              title="Workbench"
+              right={
+                <Text isMuted size="small">
+                  v0.1
+                </Text>
+              }
+            />
+          }
+          footer={<Bar title="Ready." />}
+          leftSidebar={slot(<LeftSidebarContent />, 200)}
+          rightOverlay={
+            selected
+              ? slot(
+                  <Stack gap={3}>
+                    <Heading level={3}>{selected}</Heading>
+                    <Text isMuted size="small">
+                      Detail for {selected}. Header and left nav remain
+                      interactive while this is open.
+                    </Text>
+                    <Button onClick={() => setSelected(null)}>Close</Button>
+                  </Stack>,
+                )
+              : null
+          }
+        >
+          {slot(
+            <Stack gap={3}>
+              <Heading level={2}>Items</Heading>
+              {['Alpha', 'Beta', 'Gamma'].map((name) => (
+                <Button
+                  key={name}
+                  onClick={() =>
+                    setSelected((prev) => (prev === name ? null : name))
+                  }
+                >
+                  {selected === name ? `Close ${name}` : `Open ${name}`}
+                </Button>
+              ))}
+              <Lorem paragraphs={20} as={Text} />
+            </Stack>,
+          )}
+        </Panels>
+      );
+    };
+
+    return <RightOverlayDemo />;
+  },
+};
+
+// The overlay's content is itself a Panels — header/footer stay pinned
+// while the body scrolls. The header carries the title and an X close
+// button; the outer layout is intentionally minimal (no sidebars) to
+// keep the focus on the overlay shape.
+const CloseX = ({ onClick }: { onClick: () => void }) => (
+  <button
+    type="button"
+    aria-label="Close"
+    onClick={onClick}
+    style={{
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: 28,
+      height: 28,
+      padding: 0,
+      background: 'transparent',
+      border: 'none',
+      borderRadius: 4,
+      color: 'var(--ui-muted)',
+      cursor: 'pointer',
+    }}
+  >
+    <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>
+  </button>
+);
+
+export const RightOverlayWithNestedPanels: Story = {
+  render: () => {
+    const Demo = () => {
+      const [isOpen, setIsOpen] = useState(false);
+
+      return (
+        <Panels
+          header={<Bar title="Workbench" />}
+          rightOverlayWidth={420}
+          rightOverlay={
+            isOpen ? (
+              <Panels
+                header={
+                  <Bar
+                    title="Detail"
+                    right={<CloseX onClick={() => setIsOpen(false)} />}
+                  />
+                }
+                footer={
+                  <Bar
+                    right={
+                      <Button variant="primary" onClick={() => setIsOpen(false)}>
+                        Done
+                      </Button>
+                    }
+                  />
+                }
+              >
+                {slot(
+                  <Stack gap={3}>
+                    <Heading level={3}>Long content</Heading>
+                    <Text isMuted size="small">
+                      Body scrolls; header and footer stay pinned.
+                    </Text>
+                    <Lorem paragraphs={30} as={Text} />
+                  </Stack>,
+                )}
+              </Panels>
+            ) : null
+          }
+        >
+          {slot(
+            <Stack gap={3}>
+              <Heading level={2}>Main</Heading>
+              <Button onClick={() => setIsOpen((prev) => !prev)}>
+                {isOpen ? 'Close detail' : 'Open detail'}
+              </Button>
+            </Stack>,
+          )}
+        </Panels>
+      );
+    };
+
+    return <Demo />;
+  },
+};
+
+// The "fixed strip above a nested Panels" recipe. The outer Panels' main
+// area hosts a flex column: an intro strip on top (intrinsic height) and
+// a flex-1 area that contains another Panels. The column's `min-height: 0`
+// is what lets the inner Panels resolve its own `height: 100%` without
+// spilling past the outer scroll region.
+//
+// Copy this layout when a detail view needs a non-scrolling header above
+// a list/detail pair that scrolls independently.
+export const NestedFullHeight: Story = {
+  render: () => (
+    <Panels header={<Bar title="Outer" />}>
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          height: '100%',
+          minHeight: 0,
+        }}
+      >
+        <div style={{ flex: '0 0 auto', padding: 16 }}>
+          <Heading level={3}>Intro strip</Heading>
+          <Text size="small" isMuted>
+            Fixed height above an inner Panels. Does not scroll.
+          </Text>
+        </div>
+        <div style={{ flex: '1 1 0', minHeight: 0, display: 'flex' }}>
+          <div style={{ width: '100%' }}>
+            <Panels
+              header={<Bar title="Inner" />}
+              leftSidebar={slot(<LeftSidebarContent />, 180)}
+            >
+              {slot(<LongMain />)}
+            </Panels>
+          </div>
+        </div>
+      </div>
+    </Panels>
+  ),
+};

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

@@ -0,0 +1,119 @@
+import { useEffect, useState, type CSSProperties, type ReactNode } from 'react';
+import { backgroundStyle } from '../../../tokens';
+import { cx } from '../../../utils';
+import type { PanelsProps } from './types';
+import styles from './styles.module.css';
+
+// Matches the keyframe duration in styles.module.css. Kept in JS so the
+// overlay stays mounted long enough for the slide-out animation to play.
+const OVERLAY_CLOSE_ANIMATION_MS = 200;
+
+export const Panels = (props: PanelsProps) => {
+  const {
+    header,
+    subHeaders,
+    footer,
+    leftSidebar,
+    rightSidebar,
+    rightOverlay,
+    leftSidebarWidth,
+    rightSidebarWidth,
+    rightOverlayWidth,
+    headerBackground,
+    footerBackground,
+    leftSidebarBackground,
+    rightSidebarBackground,
+    mainContentBackground,
+    children,
+  } = props;
+
+  const leftSidebarStyle: CSSProperties | undefined =
+    leftSidebarWidth != null || leftSidebarBackground != null
+      ? {
+          ...(leftSidebarWidth != null ? { width: leftSidebarWidth } : null),
+          ...(backgroundStyle('--ui-panels-left-bg', leftSidebarBackground) ?? null),
+        }
+      : undefined;
+
+  const rightSidebarStyle: CSSProperties | undefined =
+    rightSidebarWidth != null || rightSidebarBackground != null
+      ? {
+          ...(rightSidebarWidth != null ? { width: rightSidebarWidth } : null),
+          ...(backgroundStyle('--ui-panels-right-bg', rightSidebarBackground) ?? null),
+        }
+      : undefined;
+
+  const [renderedOverlay, setRenderedOverlay] = useState<ReactNode>(rightOverlay ?? null);
+  const [isOverlayClosing, setIsOverlayClosing] = useState(false);
+
+  useEffect(() => {
+    if (rightOverlay != null) {
+      setRenderedOverlay(rightOverlay);
+      setIsOverlayClosing(false);
+      return;
+    }
+    setIsOverlayClosing(true);
+    const timer = setTimeout(() => {
+      setRenderedOverlay(null);
+      setIsOverlayClosing(false);
+    }, OVERLAY_CLOSE_ANIMATION_MS);
+    return () => clearTimeout(timer);
+  }, [rightOverlay]);
+
+  const rightOverlayStyle: CSSProperties | undefined =
+    rightOverlayWidth != null ? { width: rightOverlayWidth } : undefined;
+
+  return (
+    <div className={styles.panels}>
+      {header && (
+        <div
+          className={styles.header}
+          style={backgroundStyle('--ui-panels-header-bg', headerBackground)}
+        >
+          {header}
+        </div>
+      )}
+      {subHeaders?.map((child, i) => (
+        <div key={i} className={styles.subHeader}>
+          {child}
+        </div>
+      ))}
+      <div className={styles.middle}>
+        {leftSidebar && (
+          <div className={styles.leftSidebar} style={leftSidebarStyle}>
+            {leftSidebar}
+          </div>
+        )}
+        <div
+          className={styles.main}
+          style={backgroundStyle('--ui-panels-main-bg', mainContentBackground)}
+        >
+          {children}
+        </div>
+        {rightSidebar && (
+          <div className={styles.rightSidebar} style={rightSidebarStyle}>
+            {rightSidebar}
+          </div>
+        )}
+        {renderedOverlay != null && (
+          <div
+            className={cx(styles.rightOverlay, isOverlayClosing && styles.closing)}
+            style={rightOverlayStyle}
+          >
+            {renderedOverlay}
+          </div>
+        )}
+      </div>
+      {footer && (
+        <div
+          className={styles.footer}
+          style={backgroundStyle('--ui-panels-footer-bg', footerBackground)}
+        >
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export type { PanelsProps };

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

@@ -0,0 +1,103 @@
+.panels {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+}
+
+.header {
+  flex-shrink: 0;
+  background-color: var(--ui-panels-header-bg, var(--ui-background-2));
+  border-bottom: 1px solid var(--ui-border);
+}
+
+.subHeader {
+  flex-shrink: 0;
+  background-color: var(--ui-background-1);
+  border-bottom: 1px solid var(--ui-border);
+}
+
+.footer {
+  flex-shrink: 0;
+  background-color: var(--ui-panels-footer-bg, var(--ui-background-2));
+  border-top: 1px solid var(--ui-border);
+}
+
+.middle {
+  display: flex;
+  flex-direction: row;
+  flex: 1 1 0;
+  /* min-height: 0 lets flex children establish their own scroll contexts
+     instead of stretching the row to their intrinsic content height. */
+  min-height: 0;
+  /* Anchor for the absolutely-positioned rightOverlay. */
+  position: relative;
+  /* Clip the rightOverlay during its slide animation so its off-screen
+     start/end position can't induce a scrollbar on the page. Inner regions
+     (main, sidebars) manage their own overflow. */
+  overflow: hidden;
+}
+
+.leftSidebar {
+  flex-shrink: 0;
+  overflow: auto;
+  background-color: var(--ui-panels-left-bg, var(--ui-background-1));
+  border-right: 1px solid var(--ui-border);
+}
+
+.rightSidebar {
+  flex-shrink: 0;
+  overflow: auto;
+  background-color: var(--ui-panels-right-bg, var(--ui-background-1));
+  border-left: 1px solid var(--ui-border);
+}
+
+.main {
+  flex: 1 1 0;
+  overflow: auto;
+  background-color: var(--ui-panels-main-bg, var(--ui-background-0));
+  /* min-width: 0 is the row-direction counterpart — without it, overflowing
+     main content pushes the layout wider than the viewport. */
+  min-width: 0;
+  /* Contain z-indexes from descendants (e.g. sticky table headers) so they
+     can't paint above the rightOverlay or other chrome that lives in the
+     parent stacking context. */
+  isolation: isolate;
+}
+
+.rightOverlay {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  right: 0;
+  width: 360px;
+  display: flex;
+  flex-direction: column;
+  overflow: auto;
+  background-color: var(--ui-background-0);
+  border-left: 1px solid var(--ui-border);
+  box-shadow: -4px 0 20px var(--ui-shadow);
+  z-index: 1;
+  animation: panels-overlay-in 200ms ease-out;
+}
+
+.rightOverlay.closing {
+  animation: panels-overlay-out 200ms ease-in forwards;
+}
+
+@keyframes panels-overlay-in {
+  from { transform: translateX(100%); }
+  to { transform: translateX(0); }
+}
+
+@keyframes panels-overlay-out {
+  from { transform: translateX(0); }
+  to { transform: translateX(100%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rightOverlay,
+  .rightOverlay.closing {
+    animation: none;
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import type { BackgroundToken } from '../../../tokens';
+
+export type PanelsProps = {
+  header?: ReactNode;
+  /** Optional secondary header strips rendered directly below `header`.
+   *  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[];
+  footer?: ReactNode;
+  leftSidebar?: ReactNode;
+  rightSidebar?: ReactNode;
+  /** Transient overlay anchored to the right edge of the middle region,
+   *  bounded vertically by header/footer so app nav stays visible. Open
+   *  when truthy, animates out when set back to `null`/`undefined`.
+   *  Parent owns the open state and renders its own close affordance —
+   *  there is no backdrop scrim or built-in dismissal. */
+  rightOverlay?: ReactNode;
+  /** Fixed width for the left sidebar. Numbers → px, strings pass through
+   *  (`"22rem"`, `"25%"`, etc). Defaults to content-sized. */
+  leftSidebarWidth?: number | string;
+  /** Fixed width for the right sidebar. Same shape as leftSidebarWidth. */
+  rightSidebarWidth?: number | string;
+  /** Width of the right overlay. Same shape as the sidebar widths.
+   *  Defaults to 360px. */
+  rightOverlayWidth?: number | string;
+  /** Per-region background ramp. Each defaults to the region's stock tone. */
+  headerBackground?: BackgroundToken;
+  footerBackground?: BackgroundToken;
+  leftSidebarBackground?: BackgroundToken;
+  rightSidebarBackground?: BackgroundToken;
+  mainContentBackground?: BackgroundToken;
+  children?: ReactNode;
+};

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

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Stack } from './index';
+import { Button } from '../../Forms/Button';
+
+const meta: Meta<typeof Stack> = {
+  title: 'Layout/Stack',
+  component: Stack,
+  argTypes: {
+    direction: { control: 'inline-radio', options: ['row', 'column'] },
+    gap: { control: { type: 'range', min: 0, max: 6, step: 1 } },
+    align: { control: 'inline-radio', options: ['start', 'center', 'end', 'stretch'] },
+    justify: { control: 'inline-radio', options: ['start', 'center', 'end', 'between'] },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stack>;
+
+const demoChildren = (
+  <>
+    <Button>One</Button>
+    <Button>Two</Button>
+    <Button>Three</Button>
+  </>
+);
+
+export const Column: Story = {
+  args: { direction: 'column', gap: 3 },
+  render: (args) => <Stack {...args}>{demoChildren}</Stack>,
+};
+
+export const Row: Story = {
+  args: { direction: 'row', gap: 2 },
+  render: (args) => <Stack {...args}>{demoChildren}</Stack>,
+};
+
+export const RowSpaceBetween: Story = {
+  args: { direction: 'row', justify: 'between' },
+  render: (args) => (
+    <Stack {...args}>
+      <Button>Left</Button>
+      <Button>Right</Button>
+    </Stack>
+  ),
+};

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

@@ -0,0 +1,73 @@
+import type {
+  StackAlign,
+  StackGap,
+  StackJustify,
+  StackPadding,
+  StackProps,
+} from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const GAP_MAP: Record<StackGap, string> = {
+  0: styles.gap0,
+  1: styles.gap1,
+  2: styles.gap2,
+  3: styles.gap3,
+  4: styles.gap4,
+  5: styles.gap5,
+  6: styles.gap6,
+};
+
+const PADDING_MAP: Record<StackPadding, string> = {
+  0: styles.padding0,
+  1: styles.padding1,
+  2: styles.padding2,
+  3: styles.padding3,
+  4: styles.padding4,
+  5: styles.padding5,
+  6: styles.padding6,
+};
+
+const ALIGN_MAP: Record<StackAlign, string> = {
+  start: styles.alignStart,
+  center: styles.alignCenter,
+  end: styles.alignEnd,
+  stretch: styles.alignStretch,
+};
+
+const JUSTIFY_MAP: Record<StackJustify, string> = {
+  start: styles.justifyStart,
+  center: styles.justifyCenter,
+  end: styles.justifyEnd,
+  between: styles.justifyBetween,
+};
+
+export const Stack = (props: StackProps) => {
+  const {
+    children,
+    direction = 'column',
+    gap = 2,
+    padding,
+    align,
+    justify,
+    isWrap,
+  } = props;
+
+  return (
+    <div
+      className={cx(
+        styles.stack,
+        direction === 'row' ? styles.row : styles.column,
+        GAP_MAP[gap],
+        padding !== undefined && PADDING_MAP[padding],
+        align && ALIGN_MAP[align],
+        justify && JUSTIFY_MAP[justify],
+        isWrap && styles.wrap,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export type { StackProps };

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

@@ -0,0 +1,41 @@
+.stack {
+  display: flex;
+}
+
+.row {
+  flex-direction: row;
+}
+
+.column {
+  flex-direction: column;
+}
+
+.wrap {
+  flex-wrap: wrap;
+}
+
+.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); }
+
+.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); }
+
+.alignStart { align-items: flex-start; }
+.alignCenter { align-items: center; }
+.alignEnd { align-items: flex-end; }
+.alignStretch { align-items: stretch; }
+
+.justifyStart { justify-content: flex-start; }
+.justifyCenter { justify-content: center; }
+.justifyEnd { justify-content: flex-end; }
+.justifyBetween { justify-content: space-between; }