@structuralists/scaffolding 0.0.1

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

@@ -0,0 +1,221 @@
+/* Display mode ------------------------------------------------------------ */
+
+.container {
+  position: relative;
+}
+
+.editButton {
+  position: absolute;
+  top: 0;
+  right: 0;
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--ui-muted);
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-small);
+  padding: 4px 8px;
+  border-radius: var(--ui-radius);
+  cursor: pointer;
+  line-height: 1;
+}
+
+.editButton:hover {
+  background-color: var(--ui-background-3);
+  color: var(--ui-foreground);
+}
+
+.empty {
+  color: var(--ui-muted);
+  font-style: italic;
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+}
+
+/* Edit mode --------------------------------------------------------------- */
+
+.editor {
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  background-color: var(--ui-background-0);
+  overflow: hidden;
+}
+
+.tabs {
+  display: flex;
+  border-bottom: 1px solid var(--ui-border);
+  background-color: var(--ui-background-2);
+}
+
+.tab {
+  background: transparent;
+  border: none;
+  border-bottom: 2px solid transparent;
+  padding: 8px 14px;
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-small);
+  font-weight: 500;
+  color: var(--ui-muted);
+  cursor: pointer;
+  /* pull bottom border down 1px to overlap the tab-strip border */
+  margin-bottom: -1px;
+}
+
+.tab:hover {
+  color: var(--ui-foreground);
+}
+
+.tabActive {
+  color: var(--ui-foreground);
+  border-bottom-color: var(--ui-accent);
+}
+
+.body {
+  position: relative;
+}
+
+.textarea {
+  display: block;
+  width: 100%;
+  border: none;
+  background-color: var(--ui-background-0);
+  color: var(--ui-foreground);
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-medium);
+  line-height: var(--ui-line-height);
+  padding: var(--ui-space-3);
+  resize: vertical;
+  min-height: 160px;
+  box-sizing: border-box;
+}
+
+.textarea:focus {
+  outline: none;
+}
+
+.preview {
+  padding: var(--ui-space-3);
+  min-height: 160px;
+}
+
+.hidden {
+  display: none;
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--ui-space-2);
+  padding: var(--ui-space-2) var(--ui-space-3);
+  border-top: 1px solid var(--ui-border);
+  background-color: var(--ui-background-1);
+}
+
+.actionButton {
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-small);
+  font-weight: 500;
+  padding: 6px 12px;
+  border-radius: var(--ui-radius);
+  cursor: pointer;
+  line-height: 1;
+}
+
+.cancelButton {
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--ui-foreground);
+}
+
+.cancelButton:hover:not(:disabled) {
+  background-color: var(--ui-background-3);
+}
+
+.saveButton {
+  background-color: var(--ui-accent);
+  color: var(--ui-on-accent);
+  border: 1px solid var(--ui-accent);
+}
+
+.saveButton:hover:not(:disabled) {
+  background-color: var(--ui-accent-hover);
+  border-color: var(--ui-accent-hover);
+}
+
+.actionButton:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Rendered markdown (duplicated from Markdown primitive so this component
+   can evolve its typography independently). */
+
+.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(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/EditableMarkdown/types.ts

@@ -0,0 +1,11 @@
+export type EditableMarkdownProps = {
+  value: string;
+  onSave: (next: string) => void | Promise<void>;
+  onCancel?: () => void;
+  /** Default true. When false, renders display mode with no edit affordance. */
+  canEdit?: boolean;
+  /** Shown in display mode when `value` is empty. */
+  placeholder?: string;
+  /** Accessible name for the edit control. Used as "Edit {label}". */
+  label?: string;
+};

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

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Heading } from './index';
+
+const meta: Meta<typeof Heading> = {
+  title: 'Content/Heading',
+  component: Heading,
+  argTypes: {
+    level: { control: 'inline-radio', options: [1, 2, 3] },
+  },
+  args: { children: 'Section heading', level: 1 },
+};
+
+export default meta;
+type Story = StoryObj<typeof Heading>;
+
+export const Default: Story = {};
+
+export const AllLevels: Story = {
+  render: () => (
+    <>
+      <Heading level={1}>Heading level 1</Heading>
+      <Heading level={2}>Heading level 2</Heading>
+      <Heading level={3}>Heading level 3</Heading>
+    </>
+  ),
+};

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

@@ -0,0 +1,20 @@
+import type { HeadingProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const LEVEL_MAP = {
+  1: styles.h1,
+  2: styles.h2,
+  3: styles.h3,
+};
+
+export const Heading = (props: HeadingProps) => {
+  const { children, level } = props;
+
+  const Tag = `h${level}` as const;
+  return (
+    <Tag className={cx(styles.heading, LEVEL_MAP[level])}>{children}</Tag>
+  );
+};
+
+export type { HeadingProps };

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

@@ -0,0 +1,19 @@
+.heading {
+  margin: 0;
+  font-family: var(--ui-font);
+  font-weight: 600;
+  line-height: var(--ui-line-height-tight);
+  color: var(--ui-foreground);
+}
+
+.h1 {
+  font-size: var(--ui-heading-1);
+}
+
+.h2 {
+  font-size: var(--ui-heading-2);
+}
+
+.h3 {
+  font-size: var(--ui-heading-3);
+}

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type HeadingLevel = 1 | 2 | 3;
+
+export type HeadingProps = {
+  children: ReactNode;
+  level: HeadingLevel;
+};

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

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Link } from './index';
+
+const meta: Meta<typeof Link> = {
+  title: 'Content/Link',
+  component: Link,
+  args: { children: 'Go somewhere', href: '#' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Link>;
+
+export const Default: Story = {};
+
+export const External: Story = {
+  args: {
+    isExternal: true,
+    href: 'https://example.com',
+    children: 'Open external site',
+  },
+};

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

@@ -0,0 +1,19 @@
+import type { LinkProps } from './types';
+import styles from './styles.module.css';
+
+export const Link = (props: LinkProps) => {
+  const { children, href, isExternal, onClick } = props;
+
+  return (
+    <a
+      href={href}
+      className={styles.link}
+      onClick={onClick}
+      {...(isExternal ? { target: '_blank', rel: 'noreferrer noopener' } : {})}
+    >
+      {children}
+    </a>
+  );
+};
+
+export type { LinkProps };

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

@@ -0,0 +1,11 @@
+.link {
+  color: var(--ui-accent);
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+
+.link:hover {
+  color: var(--ui-accent-hover);
+}

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type LinkProps = {
+  children: ReactNode;
+  href: string;
+  isExternal?: boolean;
+  onClick?: () => void;
+};

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

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { List, ListItem } from './index';
+
+const meta: Meta<typeof List> = {
+  title: 'Content/List',
+  component: List,
+};
+
+export default meta;
+type Story = StoryObj<typeof List>;
+
+const items = [
+  { id: 1, name: 'First item', meta: 'Queue' },
+  { id: 2, name: 'A much longer item name that should truncate', meta: 'Active · Plan' },
+  { id: 3, name: 'Third item', meta: 'Done' },
+  { id: 4, name: 'Fourth item', meta: 'Queue' },
+];
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ width: '20rem', border: '1px solid #ccc' }}>
+      <List>
+        {items.map((it) => (
+          <ListItem key={it.id} isSelected={it.id === 2}>
+            <a href="#" style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+              <span>{it.name}</span>
+              <span style={{ fontSize: 12, color: '#888' }}>{it.meta}</span>
+            </a>
+          </ListItem>
+        ))}
+      </List>
+    </div>
+  ),
+};
+
+export const WithButtonItems: Story = {
+  render: () => (
+    <div style={{ width: '20rem', border: '1px solid #ccc' }}>
+      <List>
+        {items.map((it) => (
+          <ListItem key={it.id} isSelected={it.id === 1}>
+            <button
+              type="button"
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 2,
+                background: 'transparent',
+                border: 0,
+                textAlign: 'left',
+                font: 'inherit',
+              }}
+            >
+              <span>{it.name}</span>
+              <span style={{ fontSize: 12, color: '#888' }}>{it.meta}</span>
+            </button>
+          </ListItem>
+        ))}
+      </List>
+    </div>
+  ),
+};

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

@@ -0,0 +1,26 @@
+import { cx } from '../../../utils';
+import { backgroundStyle } from '../../../tokens';
+import type { ListProps, ListItemProps } from './types';
+import styles from './styles.module.css';
+
+export const List = (props: ListProps) => {
+  const { children, background } = props;
+
+  return (
+    <ul className={styles.list} style={backgroundStyle('--ui-list-bg', background)}>
+      {children}
+    </ul>
+  );
+};
+
+export const ListItem = (props: ListItemProps) => {
+  const { children, isSelected } = props;
+
+  return (
+    <li className={cx(styles.item, isSelected && styles.itemSelected)}>
+      {children}
+    </li>
+  );
+};
+
+export type { ListProps, ListItemProps };

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

@@ -0,0 +1,41 @@
+.list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  /* Overflow guard: a long child can't push the list (or its scroll
+     ancestor) to side-scroll. */
+  overflow-x: hidden;
+  background-color: var(--ui-list-bg, transparent);
+}
+
+.item {
+  list-style: none;
+  /* The 4px breathing room so a focused inner element's outline stays
+     inside the list's scrolling ancestor instead of getting clipped. */
+  padding: 4px;
+  border-bottom: 1px solid var(--ui-border-subtle);
+}
+
+/* Hover + selected paint the full-bleed outer background. The 4px
+   padding frames the inner content but doesn't break the fill. */
+.item:hover {
+  background-color: var(--ui-background-1);
+}
+
+.itemSelected,
+.itemSelected:hover {
+  background-color: var(--ui-background-3);
+}
+
+/* Style the inner clickable. `:where()` drops the specificity of this
+   selector to zero so consumer classes on the inner element win — the
+   consumer sets layout (display:flex, gap, etc.), we set the reset. */
+:where(.item) > :where(:first-child) {
+  display: block;
+  padding: var(--ui-space-2) var(--ui-space-3);
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+  overflow: hidden;
+  min-width: 0;
+}

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

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import type { BackgroundToken } from '../../../tokens';
+
+/**
+ * A simple sidebar-style list container. Renders a <ul> with markers off
+ * and `overflow-x: hidden` so a long child (a URL, a mono id, etc.) can't
+ * push horizontal scroll.
+ */
+export type ListProps = {
+  children: ReactNode;
+  /** Ramp level mapped to `--ui-background-{0..3}`. Defaults to transparent. */
+  background?: BackgroundToken;
+};
+
+/**
+ * A row in a List. Owns the outer shell:
+ *   - 4px padding all around so a focused child's outline doesn't get
+ *     clipped by an ancestor scroll container
+ *   - a full-width bottom separator
+ *   - hover / selected background on the inner clickable
+ *   - overflow guards (min-width: 0, overflow: hidden) so long content
+ *     truncates instead of side-scrolling
+ *
+ * Pass a single direct child — typically a <Link>, <button>, or <div>.
+ * The primitive styles that child via `:where()` so the selectors have
+ * zero specificity: the consumer's own className wins for layout
+ * (display, gap, etc.) while the clickable reset (color: inherit,
+ * text-decoration: none, hover bg) still applies.
+ */
+export type ListItemProps = {
+  children: ReactNode;
+  isSelected?: boolean;
+};

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

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { LoadingContainer } from './index';
+import { Toggle } from '../../../storybook';
+
+const Panel = ({ tone, children }: { tone: '0' | '1'; children: React.ReactNode }) => (
+  <div
+    style={{
+      padding: 24,
+      background: `var(--ui-background-${tone})`,
+      border: '1px solid var(--ui-border)',
+      borderRadius: 'var(--ui-radius)',
+    }}
+  >
+    {children}
+  </div>
+);
+
+const meta: Meta<typeof LoadingContainer> = {
+  title: 'Content/LoadingContainer',
+  component: LoadingContainer,
+};
+
+export default meta;
+type Story = StoryObj<typeof LoadingContainer>;
+
+export const Idle: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      <LoadingContainer isLoading={false}>
+        <Panel tone="0">
+          <p>Some content that's not loading.</p>
+          <p>Tab focus flows through normally.</p>
+          <button type="button">Focusable</button>
+        </Panel>
+      </LoadingContainer>
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      <LoadingContainer isLoading>
+        <Panel tone="0">
+          <p>Content is being refreshed.</p>
+          <p>Try tabbing — this button is inert.</p>
+          <button type="button">Not focusable while loading</button>
+        </Panel>
+      </LoadingContainer>
+    </div>
+  ),
+};
+
+export const Toggleable: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, toggle }) => (
+        <div style={{ width: 400 }}>
+          <div style={{ marginBottom: 16 }}>
+            <button type="button" onClick={toggle}>
+              Loading: {isOn ? 'loading' : 'idle'}
+            </button>
+          </div>
+          <LoadingContainer isLoading={isOn}>
+            <Panel tone="0">
+              <p>Flip the button above.</p>
+              <button type="button">Focusable when idle</button>
+            </Panel>
+          </LoadingContainer>
+        </div>
+      )}
+    </Toggle>
+  ),
+};
+
+export const Nested: Story = {
+  render: () => {
+    // Two independent booleans — Toggle's render-prop shape would nest awkwardly here.
+    const [outer, setOuter] = useState(false);
+    const [inner, setInner] = useState(false);
+    return (
+      <div style={{ width: 500 }}>
+        <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
+          <button type="button" onClick={() => setOuter((v) => !v)}>
+            Outer: {outer ? 'loading' : 'idle'}
+          </button>
+          <button type="button" onClick={() => setInner((v) => !v)}>
+            Inner: {inner ? 'loading' : 'idle'}
+          </button>
+        </div>
+        <LoadingContainer isLoading={outer}>
+          <Panel tone="1">
+            <p>Outer container</p>
+            <LoadingContainer isLoading={inner}>
+              <Panel tone="0">
+                <p>Inner container — suppresses its own overlay when outer is painting.</p>
+              </Panel>
+            </LoadingContainer>
+          </Panel>
+        </LoadingContainer>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,36 @@
+import { createContext, useContext } from 'react';
+import type { LoadingContainerProps } from './types';
+import styles from './styles.module.css';
+
+/**
+ * Tracks whether an ancestor LoadingContainer is already painting an overlay
+ * over this subtree. When true, descendants suppress their own overlays —
+ * the ancestor's frost and `inert` already cover them.
+ */
+const LoadingAncestorContext = createContext(false);
+
+export const LoadingContainer = (props: LoadingContainerProps) => {
+  const { children, isLoading, label = 'Loading' } = props;
+
+  const ancestorIsCovering = useContext(LoadingAncestorContext);
+  const shouldPaint = isLoading && !ancestorIsCovering;
+  const isCoveredNow = ancestorIsCovering || isLoading;
+
+  return (
+    <LoadingAncestorContext.Provider value={isCoveredNow}>
+      <div className={styles.container} aria-busy={isLoading || undefined}>
+        <div className={styles.content} inert={shouldPaint || undefined}>
+          {children}
+        </div>
+        {shouldPaint && (
+          <div className={styles.overlay} role="status">
+            <span className={styles.srOnly}>{label}</span>
+            <div className={styles.spinner} aria-hidden />
+          </div>
+        )}
+      </div>
+    </LoadingAncestorContext.Provider>
+  );
+};
+
+export type { LoadingContainerProps };