@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,54 @@
+.container {
+  position: relative;
+}
+
+/* Wraps the consumer's children so we can apply `inert` without leaking it
+   to the overlay siblings. No visual styles — children flow naturally. */
+.content {
+  /* intentionally empty */
+}
+
+.overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Theme-aware translucent frost — lightens (or darkens, depending on theme)
+     the content beneath by mixing the primary surface with transparency. */
+  background-color: color-mix(in srgb, var(--ui-background-0) 70%, transparent);
+  z-index: 1;
+}
+
+.spinner {
+  width: 32px;
+  height: 32px;
+  border: 3px solid var(--ui-border);
+  border-top-color: var(--ui-accent);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Respect the OS-level reduced-motion preference — slow the spinner rather
+   than remove it entirely so the loading signal is still visible. */
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation-duration: 4s;
+  }
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type LoadingContainerProps = {
+  children: ReactNode;
+  isLoading: boolean;
+  /** Accessible label announced when the overlay appears. Default: "Loading". */
+  label?: string;
+};

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

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Markdown } from './index';
+
+const sample = `# Heading 1
+
+A paragraph with **bold** text, *italic*, and \`inline code\`. Here's a [link](https://example.com).
+
+## Heading 2
+
+- Bullet one
+- Bullet two with some \`code\`
+- Bullet three
+
+\`\`\`ts
+const greeting = 'hello';
+console.log(greeting);
+\`\`\`
+
+> A blockquote with some thoughtful text.
+`;
+
+const meta: Meta<typeof Markdown> = {
+  title: 'Content/Markdown',
+  component: Markdown,
+};
+
+export default meta;
+type Story = StoryObj<typeof Markdown>;
+
+export const Default: Story = {
+  args: { children: sample },
+};
+
+export const Inline: Story = {
+  args: {
+    isInline: true,
+    children: 'Inline markdown with `code` and a [link](https://example.com).',
+  },
+};

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

@@ -0,0 +1,28 @@
+import ReactMarkdown from 'react-markdown';
+import type { MarkdownProps } from './types';
+import styles from './styles.module.css';
+
+const InlineParagraph = (props: { children?: React.ReactNode }) => {
+  const { children } = props;
+
+  return <>{children}</>;
+};
+
+const INLINE_COMPONENTS = {
+  p: InlineParagraph,
+};
+
+export const Markdown = (props: MarkdownProps) => {
+  const { children, isInline } = props;
+
+  if (isInline) {
+    return <ReactMarkdown components={INLINE_COMPONENTS}>{children}</ReactMarkdown>;
+  }
+  return (
+    <div className={styles.markdown}>
+      <ReactMarkdown>{children}</ReactMarkdown>
+    </div>
+  );
+};
+
+export type { MarkdownProps };

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

@@ -0,0 +1,79 @@
+.markdown {
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  color: var(--ui-foreground);
+}
+
+.markdown :global(h1),
+.markdown :global(h2),
+.markdown :global(h3),
+.markdown :global(h4) {
+  font-weight: 600;
+  line-height: var(--ui-line-height-tight);
+  margin-top: var(--ui-space-4);
+  margin-bottom: var(--ui-space-2);
+}
+
+.markdown :global(h1) { font-size: var(--ui-heading-1); }
+.markdown :global(h2) { font-size: var(--ui-heading-2); }
+.markdown :global(h3),
+.markdown :global(h4) { font-size: var(--ui-heading-3); }
+
+.markdown :global(p) { margin-bottom: var(--ui-space-3); }
+.markdown :global(p):last-child { margin-bottom: 0; }
+
+.markdown :global(ul),
+.markdown :global(ol) {
+  margin-bottom: var(--ui-space-3);
+  padding-left: 1.25rem;
+}
+
+.markdown :global(li) { margin-bottom: var(--ui-space-1); }
+
+.markdown :global(code) {
+  font-family: var(--ui-font-mono);
+  font-size: 0.9em;
+  background-color: var(--ui-background-2);
+  padding: 1px 4px;
+  border-radius: var(--ui-radius);
+}
+
+.markdown :global(pre) {
+  background-color: var(--ui-background-2);
+  padding: var(--ui-space-3);
+  border-radius: var(--ui-radius);
+  overflow-x: auto;
+  margin-bottom: var(--ui-space-3);
+}
+
+.markdown :global(pre code) {
+  background-color: transparent;
+  padding: 0;
+  font-size: var(--ui-text-small);
+}
+
+.markdown :global(a) {
+  color: var(--ui-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.markdown :global(a):hover {
+  color: var(--ui-accent-hover);
+}
+
+.markdown :global(img) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: var(--ui-space-2) 0;
+  border-radius: var(--ui-radius);
+  border: 1px solid var(--ui-border-subtle);
+}
+
+.markdown :global(blockquote) {
+  border-left: 3px solid var(--ui-border);
+  padding-left: var(--ui-space-3);
+  color: var(--ui-muted);
+  margin-bottom: var(--ui-space-3);
+}

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

@@ -0,0 +1,8 @@
+export type MarkdownProps = {
+  children: string;
+  /**
+   * Render as inline markdown — strips the default paragraph wrapper so
+   * the output can sit inside a heading, link, or other inline context.
+   */
+  isInline?: boolean;
+};

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

@@ -0,0 +1,186 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Menu } from './index';
+import type { MenuItem } from './types';
+
+const log = (label: string) => () => console.log('selected:', label);
+
+const flatItems: MenuItem[] = [
+  { label: 'Refresh', onSelect: log('Refresh') },
+  { label: 'Full sync', onSelect: log('Full sync') },
+  { label: 'Settings', onSelect: log('Settings') },
+];
+
+const nestedItems: MenuItem[] = [
+  { label: 'Settings', onSelect: log('Settings') },
+  {
+    label: 'Linear',
+    items: [
+      { label: 'Refresh', onSelect: log('Linear: Refresh') },
+      { label: 'Full sync', onSelect: log('Linear: Full sync') },
+      {
+        label: 'Viewer',
+        items: [
+          { label: 'Show me', onSelect: log('Viewer: Show me') },
+          { label: 'Clear', onSelect: log('Viewer: Clear') },
+        ],
+      },
+    ],
+  },
+  {
+    label: 'Database',
+    items: [
+      { label: 'Export work items', onSelect: log('DB: Export') },
+      { label: 'Reset (archives first)', onSelect: log('DB: Reset') },
+    ],
+  },
+  { label: 'About', onSelect: log('About') },
+];
+
+const meta: Meta<typeof Menu> = {
+  title: 'Content/Menu',
+  component: Menu,
+  args: {
+    trigger: '⋯',
+    ariaLabel: 'More',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Menu>;
+
+export const Flat: Story = {
+  args: { items: flatItems },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 48, display: 'flex', justifyContent: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const WithTitle: Story = {
+  args: { items: flatItems, title: 'Actions' },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 48, display: 'flex', justifyContent: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+const activeItems: MenuItem[] = [
+  { label: 'Light', onSelect: log('Light') },
+  { label: 'Dark', isActive: true, onSelect: log('Dark') },
+  { label: 'System', onSelect: log('System') },
+];
+
+export const WithActiveItem: Story = {
+  args: { items: activeItems, title: 'Dark Mode' },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 48, display: 'flex', justifyContent: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const Nested: Story = {
+  args: { items: nestedItems },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 48, display: 'flex', justifyContent: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+// Each trigger is pinned to one corner of a viewport-filling box so the
+// auto-placement picks a different quadrant to open into. Inner submenus
+// should also flip direction automatically based on the parent item's
+// position on screen.
+export const Corners: Story = {
+  parameters: { layout: 'fullscreen' },
+  args: { items: nestedItems },
+  render: (args) => (
+    <div
+      style={{
+        position: 'relative',
+        height: '100vh',
+        width: '100%',
+      }}
+    >
+      <div style={{ position: 'absolute', top: 16, left: 16 }}>
+        <Menu {...args} trigger="⋯ TL" ariaLabel="Top left" />
+      </div>
+      <div style={{ position: 'absolute', top: 16, right: 16 }}>
+        <Menu {...args} trigger="⋯ TR" ariaLabel="Top right" />
+      </div>
+      <div style={{ position: 'absolute', bottom: 16, left: 16 }}>
+        <Menu {...args} trigger="⋯ BL" ariaLabel="Bottom left" />
+      </div>
+      <div style={{ position: 'absolute', bottom: 16, right: 16 }}>
+        <Menu {...args} trigger="⋯ BR" ariaLabel="Bottom right" />
+      </div>
+    </div>
+  ),
+};
+
+const inCorner = (
+  corner: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right',
+): React.CSSProperties => ({
+  position: 'absolute',
+  ...(corner.startsWith('top') ? { top: 16 } : { bottom: 16 }),
+  ...(corner.endsWith('left') ? { left: 16 } : { right: 16 }),
+});
+
+export const TopLeft: Story = {
+  parameters: { layout: 'fullscreen' },
+  args: { items: nestedItems, trigger: '⋯ TL' },
+  render: (args) => (
+    <div style={{ position: 'relative', height: '100vh' }}>
+      <div style={inCorner('top-left')}>
+        <Menu {...args} />
+      </div>
+    </div>
+  ),
+};
+
+export const TopRight: Story = {
+  parameters: { layout: 'fullscreen' },
+  args: { items: nestedItems, trigger: '⋯ TR' },
+  render: (args) => (
+    <div style={{ position: 'relative', height: '100vh' }}>
+      <div style={inCorner('top-right')}>
+        <Menu {...args} />
+      </div>
+    </div>
+  ),
+};
+
+export const BottomLeft: Story = {
+  parameters: { layout: 'fullscreen' },
+  args: { items: nestedItems, trigger: '⋯ BL' },
+  render: (args) => (
+    <div style={{ position: 'relative', height: '100vh' }}>
+      <div style={inCorner('bottom-left')}>
+        <Menu {...args} />
+      </div>
+    </div>
+  ),
+};
+
+export const BottomRight: Story = {
+  parameters: { layout: 'fullscreen' },
+  args: { items: nestedItems, trigger: '⋯ BR' },
+  render: (args) => (
+    <div style={{ position: 'relative', height: '100vh' }}>
+      <div style={inCorner('bottom-right')}>
+        <Menu {...args} />
+      </div>
+    </div>
+  ),
+};

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

@@ -0,0 +1,259 @@
+import {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+} from 'react';
+import { createPortal } from 'react-dom';
+import type { MenuItem, MenuProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const isBranch = (
+  item: MenuItem,
+): item is { label: string; items: MenuItem[] } => 'items' in item;
+
+type RootPosition = {
+  top: number;
+  left: number;
+};
+
+type SubmenuPlacement = {
+  h: 'subOpenRight' | 'subOpenLeft';
+  v: 'subAlignTop' | 'subAlignBottom';
+};
+
+const GAP = 4;
+
+// Rough sizing estimates used to decide direction without pre-measuring the
+// actual panel. If the real panel ends up taller/wider than these, it can
+// still overflow — acceptable for v0.1.
+const SUBMENU_EST_WIDTH = 180;
+const ITEM_EST_HEIGHT = 34;
+const PANEL_EST_PADDING = 8;
+
+const computeRootPosition = (
+  trigger: DOMRect,
+  panel: DOMRect,
+): RootPosition => {
+  const winW = window.innerWidth;
+  const winH = window.innerHeight;
+  const openRight = winW - trigger.right >= trigger.left;
+  const openDown = winH - trigger.bottom >= trigger.top;
+  return {
+    top: openDown ? trigger.bottom + GAP : trigger.top - panel.height - GAP,
+    left: openRight ? trigger.left : trigger.right - panel.width,
+  };
+};
+
+const computeSubmenuPlacement = (
+  itemRect: DOMRect,
+  childItemCount: number,
+): SubmenuPlacement => {
+  const winW = window.innerWidth;
+  const winH = window.innerHeight;
+  const submenuH = childItemCount * ITEM_EST_HEIGHT + PANEL_EST_PADDING * 2;
+  return {
+    h:
+      itemRect.right + SUBMENU_EST_WIDTH <= winW ? 'subOpenRight' : 'subOpenLeft',
+    v: itemRect.top + submenuH <= winH ? 'subAlignTop' : 'subAlignBottom',
+  };
+};
+
+type RootPanelProps = {
+  isRoot: true;
+  panelRef: React.RefObject<HTMLDivElement | null>;
+  position: RootPosition | null;
+  items: MenuItem[];
+  title?: string;
+  onCloseAll: () => void;
+};
+
+type SubPanelProps = {
+  isRoot: false;
+  placement: SubmenuPlacement;
+  items: MenuItem[];
+  onCloseAll: () => void;
+};
+
+type PanelProps = RootPanelProps | SubPanelProps;
+
+const Panel = (props: PanelProps) => {
+  const { items, onCloseAll } = props;
+  const titleId = useId();
+  const [submenu, setSubmenu] = useState<{
+    index: number;
+    placement: SubmenuPlacement;
+  } | null>(null);
+
+  const handleBranchEnter = (
+    e: React.MouseEvent<HTMLDivElement>,
+    i: number,
+    branchItems: MenuItem[],
+  ) => {
+    const rect = e.currentTarget.getBoundingClientRect();
+    setSubmenu({
+      index: i,
+      placement: computeSubmenuPlacement(rect, branchItems.length),
+    });
+  };
+
+  const rootStyle: CSSProperties | undefined = props.isRoot
+    ? props.position
+      ? { top: props.position.top, left: props.position.left }
+      : { top: 0, left: 0, visibility: 'hidden' }
+    : undefined;
+
+  const className = props.isRoot
+    ? cx(styles.panel, styles.panelRoot)
+    : cx(
+        styles.panel,
+        styles.panelSubmenu,
+        styles[props.placement.h],
+        styles[props.placement.v],
+      );
+
+  return (
+    <div
+      ref={props.isRoot ? props.panelRef : undefined}
+      className={className}
+      style={rootStyle}
+      role="menu"
+      aria-labelledby={props.isRoot && props.title ? titleId : undefined}
+    >
+      {props.isRoot && props.title && (
+        <div id={titleId} className={styles.title}>
+          {props.title}
+        </div>
+      )}
+      {items.map((item, i) => {
+        const branch = isBranch(item);
+        return (
+          <div key={i} className={styles.itemWrapper}>
+            {branch ? (
+              <>
+                <div
+                  className={cx(styles.item, styles.branchItem)}
+                  role="menuitem"
+                  aria-haspopup="menu"
+                  aria-expanded={submenu?.index === i}
+                  onMouseEnter={(e) => handleBranchEnter(e, i, item.items)}
+                >
+                  <span>{item.label}</span>
+                  <span className={styles.caret}>▸</span>
+                </div>
+                {submenu?.index === i && (
+                  <Panel
+                    isRoot={false}
+                    placement={submenu.placement}
+                    items={item.items}
+                    onCloseAll={onCloseAll}
+                  />
+                )}
+              </>
+            ) : (
+              <button
+                type="button"
+                className={cx(
+                  styles.item,
+                  item.isDisabled && styles.itemDisabled,
+                )}
+                role="menuitem"
+                aria-checked={item.isActive ? true : undefined}
+                aria-disabled={item.isDisabled ? true : undefined}
+                disabled={item.isDisabled}
+                onMouseEnter={() => setSubmenu(null)}
+                onClick={() => {
+                  if (item.isDisabled) return;
+                  item.onSelect();
+                  onCloseAll();
+                }}
+              >
+                <span>{item.label}</span>
+                {item.isActive && <span className={styles.check}>✓</span>}
+              </button>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+export const Menu = (props: MenuProps) => {
+  const { trigger, ariaLabel, items, title } = props;
+
+  const [open, setOpen] = useState(false);
+  const [position, setPosition] = useState<RootPosition | null>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  const handleToggle = () => setOpen((v) => !v);
+
+  useLayoutEffect(() => {
+    if (!open) {
+      setPosition(null);
+      return;
+    }
+    const trig = triggerRef.current;
+    const panel = panelRef.current;
+    if (!trig || !panel) return;
+    setPosition(
+      computeRootPosition(trig.getBoundingClientRect(), panel.getBoundingClientRect()),
+    );
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+
+    const handleMouseDown = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (triggerRef.current?.contains(target)) return;
+      if (panelRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+
+    window.addEventListener('mousedown', handleMouseDown);
+    window.addEventListener('keydown', handleKey);
+    return () => {
+      window.removeEventListener('mousedown', handleMouseDown);
+      window.removeEventListener('keydown', handleKey);
+    };
+  }, [open]);
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        className={styles.trigger}
+        aria-label={ariaLabel}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={handleToggle}
+      >
+        {trigger}
+      </button>
+      {open &&
+        createPortal(
+          <Panel
+            isRoot
+            panelRef={panelRef}
+            position={position}
+            items={items}
+            title={title}
+            onCloseAll={() => setOpen(false)}
+          />,
+          document.body,
+        )}
+    </>
+  );
+};
+
+export type { MenuProps };