@structuralists/scaffolding 0.0.1

package/src/components/Tables/BigTable/index.tsx

@@ -0,0 +1,104 @@
+import type { CSSProperties, MouseEvent } from 'react';
+import { cx } from '../../../utils';
+import type { BigTableProps, ColumnAlign } from './types';
+import styles from './styles.module.css';
+
+const INTERACTIVE_CHILD_SELECTOR =
+  'a, button, input, select, textarea, label, [role="button"]';
+
+const alignClass = (align: ColumnAlign | undefined): string | undefined => {
+  if (align === 'right') return styles.alignRight;
+  if (align === 'center') return styles.alignCenter;
+  return undefined;
+};
+
+const widthStyle = (
+  width: number | string | undefined,
+  minWidth: number | undefined,
+): CSSProperties | undefined => {
+  if (width == null && minWidth == null) return undefined;
+  const style: CSSProperties = {};
+  if (width != null) style.width = typeof width === 'number' ? `${width}px` : width;
+  if (minWidth != null) style.minWidth = `${minWidth}px`;
+  return style;
+};
+
+export const BigTable = <T,>(props: BigTableProps<T>) => {
+  const { data, columnDefs, getRowKey, hasStickyFirstColumn, onRowClick } = props;
+
+  const handleRowClick = onRowClick
+    ? (row: T) => (e: MouseEvent<HTMLTableRowElement>) => {
+        const target = e.target as HTMLElement;
+        if (target.closest(INTERACTIVE_CHILD_SELECTOR)) return;
+        onRowClick(row);
+      }
+    : undefined;
+
+  return (
+    <div className={styles.shell}>
+      <table className={styles.table}>
+        <thead>
+          <tr>
+            {columnDefs.map((col, i) => {
+              const isSticky = hasStickyFirstColumn && i === 0;
+
+              return (
+                <th
+                  key={col.id}
+                  className={cx(
+                    styles.headerCell,
+                    alignClass(col.align),
+                    isSticky && styles.stickyColumn,
+                  )}
+                  style={widthStyle(col.width, col.minWidth)}
+                >
+                  {col.header}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {data.map((row) => (
+            <tr
+              key={getRowKey(row)}
+              className={cx(styles.row, handleRowClick && styles.rowClickable)}
+              onClick={handleRowClick?.(row)}
+            >
+              {columnDefs.map((col, colIndex) => {
+                const isSticky = hasStickyFirstColumn && colIndex === 0;
+
+                return (
+                  <td
+                    key={col.id}
+                    className={cx(
+                      styles.cell,
+                      alignClass(col.align),
+                      isSticky && styles.stickyColumn,
+                    )}
+                    style={widthStyle(col.width, col.minWidth)}
+                  >
+                    {col.cell(row)}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+};
+
+export type { BigTableProps, ColumnDef, ColumnAlign } from './types';
+export {
+  textColumn,
+  numberColumn,
+  currencyColumn,
+  dateColumn,
+  relativeDateColumn,
+  badgeColumn,
+  booleanColumn,
+  linkColumn,
+  idColumn,
+} from './columnDefs';

package/src/components/Tables/BigTable/styles.module.css

@@ -0,0 +1,83 @@
+.shell {
+  width: 100%;
+  height: 100%;
+  overflow: auto;
+  background-color: var(--ui-background-0);
+}
+
+.table {
+  border-collapse: separate;
+  border-spacing: 0;
+  min-width: max-content;
+  width: 100%;
+  font-size: var(--ui-text-small);
+  color: var(--ui-foreground);
+}
+
+.headerCell {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background-color: var(--ui-background-1);
+  text-align: left;
+  vertical-align: middle;
+  font-weight: 500;
+  color: var(--ui-muted);
+  font-size: var(--ui-text-xsmall);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  padding: var(--ui-space-2);
+  border-bottom: 1px solid var(--ui-border);
+  white-space: nowrap;
+}
+
+.cell {
+  text-align: left;
+  vertical-align: middle;
+  padding: var(--ui-space-2);
+  line-height: var(--ui-line-height-tight);
+  border-bottom: 1px solid var(--ui-border-subtle);
+  background-color: var(--ui-background-0);
+  white-space: nowrap;
+}
+
+.row:nth-child(even) .cell {
+  background-color: var(--ui-background-0-offset);
+}
+
+.rowClickable {
+  cursor: pointer;
+}
+
+.rowClickable:hover .cell,
+.rowClickable:nth-child(even):hover .cell {
+  background-color: var(--ui-background-1);
+}
+
+.alignRight {
+  text-align: right;
+}
+
+.alignCenter {
+  text-align: center;
+}
+
+.stickyColumn {
+  position: sticky;
+  left: 0;
+  z-index: 1;
+  border-right: 1px solid var(--ui-border-subtle);
+}
+
+.headerCell.stickyColumn {
+  z-index: 3;
+}
+
+.cellMono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: var(--ui-muted);
+}
+
+.cellMuted {
+  color: var(--ui-muted);
+}

package/src/components/Tables/BigTable/types.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+
+export type ColumnAlign = 'left' | 'right' | 'center';
+
+export type ColumnDef<T> = {
+  id: string;
+  header: ReactNode;
+  cell: (row: T) => ReactNode;
+  align?: ColumnAlign;
+  width?: number | string;
+  minWidth?: number;
+};
+
+export type BigTableProps<T> = {
+  data: T[];
+  columnDefs: ColumnDef<T>[];
+  getRowKey: (row: T) => string | number;
+  hasStickyFirstColumn?: boolean;
+  onRowClick?: (row: T) => void;
+};

package/src/components/Tables/QuickTable/CLAUDE.md

@@ -0,0 +1,118 @@
+# QuickTable — read this before editing
+
+**This primitive deliberately violates the typed-data-driven table pattern you'd default to.** It accepts JSX children, not `rows` / `columns` props. Do not "fix" it.
+
+## What it is
+
+`QuickTable` is for throwaway tables — admin surfaces, debug views, quick-and-dirty lists. The API reads like the `<table><tr><td>…</td></tr></table>` DOM it produces, but elides the boilerplate.
+
+```tsx
+<QuickTable headerCells={['Name', 'Role', 'Amount']}>
+  {rows.map((r) => (
+    <QuickTableRow key={r.id}>
+      {r.name}
+      {r.role}
+      {r.amount.toLocaleString()}
+    </QuickTableRow>
+  ))}
+</QuickTable>
+```
+
+Every child that isn't already a row gets auto-wrapped into one. Every child of a row that isn't already a cell gets auto-wrapped into one. That's it.
+
+## What it is NOT
+
+- **Not a data-driven table.** There is no `rows: T[]` prop. There is no `columns: ColumnDef<T>[]` prop. Do not add one. If you want that, build a separate primitive (eventually `Table/DataTable`, react-table-backed).
+- **Not for production tables with sorting / filtering / selection / virtualization / sticky headers / server-side pagination.** Those are a different primitive, not yet built.
+- **Not exhaustive or type-safe across columns.** The caller can emit a row with the wrong number of cells and the table will render it. That's acceptable for "quick."
+
+If you feel the pull to add `sortable`, `onRowClick`, `selectable`, `stickyHeader`, `virtualized`, `pageSize`, or `columnDef` — stop. That's the signal to build a new primitive (e.g. `DataTable`), not to grow this one.
+
+## Why the JSX-children pattern
+
+Two reasons:
+
+1. **Reads like DOM.** A reader understands what renders without translating a column config in their head. `<QuickTableRow>{a}{b}</QuickTableRow>` is one line; the data-driven equivalent is a column array plus a row array plus a render function.
+2. **Zero friction for ad-hoc content.** Mixing literal strings, `<Badge>` components, `<em>` tags, and formatted numbers in the same row is just JSX. No `render: (row) => …` callbacks, no column configs.
+
+The cost (no per-column typing, no shared formatting) is the right trade-off for quick tables. The upgrade path when the cost stops being worth it is "reach for a different primitive," not "grow this one."
+
+## Auto-wrap mechanics
+
+`wrapList(children, Wrapper)` iterates children and:
+
+- Keeps nodes that are already the right wrapper (matched by either reference equality on `element.type`, or by a symbol-brand fallback that survives re-export / HOC wrapping).
+- Wraps everything else into `<Wrapper>` with the iteration index as `key`.
+
+Applied at two levels:
+
+- Inside `QuickTable`: `wrapList(children, QuickTableRow)` — raw children become rows.
+- Inside `QuickTableRow`: `wrapList(children, QuickTableCell)` — raw children become cells.
+
+Applied once on the header side:
+
+- Inside `QuickTableHeaderRow`: `wrapList(children, QuickTableHeaderCell)` — raw children become header cells. The `headerCells` prop on `QuickTable` is sugar for wrapping an array inside a `QuickTableHeaderRow`.
+
+Every wrapper (`QuickTableRow`, `QuickTableCell`, `QuickTableHeaderRow`, `QuickTableHeaderCell`) is branded on export via `brandQuickTableType`. Keep that call when adding new wrappers — without it, re-exports through a barrel or a `React.memo` wrapper break the "already-the-right-thing" check and the component gets re-wrapped into another layer of itself (which renders as an invalid table).
+
+## Four valid forms
+
+All of these produce the same 3-row × 2-column body:
+
+```tsx
+// Fully verbose
+<QuickTable>
+  <QuickTableRow>
+    <QuickTableCell>Alice</QuickTableCell>
+    <QuickTableCell>12000</QuickTableCell>
+  </QuickTableRow>
+  {/* … */}
+</QuickTable>
+
+// Cells auto-wrap
+<QuickTable>
+  <QuickTableRow>Alice{12000}</QuickTableRow>
+  {/* … */}
+</QuickTable>
+
+// Mix: one explicit cell (for align/width), one auto-wrapped
+<QuickTable>
+  <QuickTableRow>
+    Alice
+    <QuickTableCell align="right">12000</QuickTableCell>
+  </QuickTableRow>
+  {/* … */}
+</QuickTable>
+
+// Single-cell rows via table-level auto-wrap (each child becomes a 1-cell row)
+<QuickTable>{['Alice', 'Bob', 'Charlie']}</QuickTable>
+```
+
+## React.Children.map flattening caveat
+
+`wrapList` uses `React.Children.map`, which flattens nested arrays and fragments. Consequence:
+
+```tsx
+// DOES NOT produce a row of [Alice, 12000]. The outer array flattens.
+<QuickTable>{[['Alice', 12000], ['Bob', 8500]]}</QuickTable>
+// Renders 4 single-cell rows: Alice / 12000 / Bob / 8500
+```
+
+To get multi-cell rows from raw data, wrap each row in `QuickTableRow` explicitly (as in the verbose / sugar forms above). This is a deliberate limitation — if you're already writing nested arrays, you've likely outgrown `QuickTable`.
+
+## What you can add safely
+
+Stay in the "reads like DOM" spirit. Props that describe one cell / one row / the table as a whole are fine:
+
+- Per-cell: `width`, `align`, `colSpan`, `rowSpan` (if needed).
+- Per-row: `onClick`, `isSelected`, `tone` (if needed).
+- Table-level: styling knobs (`background` via `BackgroundToken`, `density`) — but only if a concrete use case demands them. Already shipped: `title` (rendered as `<caption>`), `hasColumnDividers` (border-left between cells via adjacent-sibling CSS).
+
+What's NOT safe to add: anything shaped like "configure N columns in one place" (`columnAlign: ('left' | 'right')[]`, `columnWidths: number[]`, `columnRenderers: {…}`). Those betray the premise. If a caller needs column-level control, they can set `align` / `width` on each `QuickTableHeaderCell` and each `QuickTableCell` directly — verbose, but honest.
+
+## Style rules (inherited from ui-components)
+
+- No `className` prop, no HTML attribute pass-through, no `aria-*` at call sites.
+- Booleans use `is*` / `can*` / `has*`.
+- CSS module only; colors via `--ui-*` tokens.
+- Barrel is `src/Table/QuickTable/index.tsx`. External imports go through `@teamwork/ui-components` (or `../Table/QuickTable` within the package); siblings inside this folder import each other directly, not through the barrel.

package/src/components/Tables/QuickTable/QuickTable.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  QuickTable,
+  QuickTableCell,
+  QuickTableHeaderCell,
+  QuickTableHeaderRow,
+  QuickTableRow,
+} from './index';
+
+const meta: Meta<typeof QuickTable> = {
+  title: 'Tables/QuickTable',
+  component: QuickTable,
+};
+
+export default meta;
+type Story = StoryObj<typeof QuickTable>;
+
+const rows = [
+  { id: 'a', name: 'Alice',   role: 'Engineer',  amount: 12_000 },
+  { id: 'b', name: 'Bob',     role: 'Designer',  amount: 8_500 },
+  { id: 'c', name: 'Charlie', role: 'PM',        amount: 15_250 },
+];
+
+export const Verbose: Story = {
+  name: 'Verbose — one cell per td',
+  render: () => (
+    <QuickTable
+      headerRow={
+        <QuickTableHeaderRow>
+          <QuickTableHeaderCell>Name</QuickTableHeaderCell>
+          <QuickTableHeaderCell>Role</QuickTableHeaderCell>
+          <QuickTableHeaderCell align="right">Amount</QuickTableHeaderCell>
+        </QuickTableHeaderRow>
+      }
+    >
+      {rows.map((r) => (
+        <QuickTableRow key={r.id}>
+          <QuickTableCell>{r.name}</QuickTableCell>
+          <QuickTableCell>{r.role}</QuickTableCell>
+          <QuickTableCell align="right">{r.amount.toLocaleString()}</QuickTableCell>
+        </QuickTableRow>
+      ))}
+    </QuickTable>
+  ),
+};
+
+export const HeaderCellsSugar: Story = {
+  name: 'headerCells sugar + cell auto-wrap',
+  render: () => (
+    <QuickTable headerCells={['Name', 'Role', 'Amount']}>
+      {rows.map((r) => (
+        <QuickTableRow key={r.id}>
+          {r.name}
+          {r.role}
+          {r.amount.toLocaleString()}
+        </QuickTableRow>
+      ))}
+    </QuickTable>
+  ),
+};
+
+export const AutoWrapEverything: Story = {
+  name: 'Fully terse — row auto-wrap and cell auto-wrap',
+  render: () => (
+    <QuickTable headerCells={['id', 'name']}>
+      {rows.map((r) => (
+        <QuickTableRow key={r.id}>
+          {r.id}
+          {r.name}
+        </QuickTableRow>
+      ))}
+    </QuickTable>
+  ),
+};
+
+export const MixedLiteralAndWrapper: Story = {
+  name: 'Mix: some cells wrapped explicitly, others auto-wrapped',
+  render: () => (
+    <QuickTable headerCells={['Name', 'Role', 'Amount']}>
+      {rows.map((r) => (
+        <QuickTableRow key={r.id}>
+          {r.name}
+          <QuickTableCell>
+            <em>{r.role}</em>
+          </QuickTableCell>
+          <QuickTableCell align="right">
+            ${r.amount.toLocaleString()}
+          </QuickTableCell>
+        </QuickTableRow>
+      ))}
+    </QuickTable>
+  ),
+};
+
+export const SingleCellRow: Story = {
+  name: 'Single-cell rows via direct table children',
+  render: () => (
+    <QuickTable headerCells={['Notice']}>
+      {rows.map((r) => r.name)}
+    </QuickTable>
+  ),
+};
+
+export const TitleAndColumnDividers: Story = {
+  name: 'title + hasColumnDividers',
+  render: () => (
+    <QuickTable
+      title="Q3 totals"
+      hasColumnDividers
+      headerCells={['Name', 'Role', 'Amount']}
+    >
+      {rows.map((r) => (
+        <QuickTableRow key={r.id}>
+          {r.name}
+          {r.role}
+          <QuickTableCell align="right">{r.amount.toLocaleString()}</QuickTableCell>
+        </QuickTableRow>
+      ))}
+    </QuickTable>
+  ),
+};

package/src/components/Tables/QuickTable/index.tsx

@@ -0,0 +1,86 @@
+import type { CSSProperties } from 'react';
+import { brandQuickTableType, wrapList } from './internal';
+import type {
+  QuickTableCellAlign,
+  QuickTableCellProps,
+  QuickTableHeaderCellProps,
+  QuickTableHeaderRowProps,
+  QuickTableProps,
+  QuickTableRowProps,
+} from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const alignClass = (align: QuickTableCellAlign | undefined): string | undefined => {
+  if (align === 'right') return styles.alignRight;
+  if (align === 'center') return styles.alignCenter;
+  return undefined;
+};
+
+const widthStyle = (
+  width: string | number | undefined,
+): CSSProperties | undefined => {
+  if (width == null) return undefined;
+  return { width: typeof width === 'number' ? `${width}px` : width };
+};
+
+export const QuickTableCell = (props: QuickTableCellProps) => {
+  const { children, width, align } = props;
+
+  return (
+    <td className={cx(styles.cell, alignClass(align))} style={widthStyle(width)}>
+      {children}
+    </td>
+  );
+};
+brandQuickTableType(QuickTableCell, 'QuickTableCell');
+
+export const QuickTableRow = (props: QuickTableRowProps) => {
+  const { children } = props;
+
+  return <tr className={styles.row}>{wrapList(children, QuickTableCell)}</tr>;
+};
+brandQuickTableType(QuickTableRow, 'QuickTableRow');
+
+export const QuickTableHeaderCell = (props: QuickTableHeaderCellProps) => {
+  const { children, width, align } = props;
+
+  return (
+    <th className={cx(styles.headerCell, alignClass(align))} style={widthStyle(width)}>
+      {children}
+    </th>
+  );
+};
+brandQuickTableType(QuickTableHeaderCell, 'QuickTableHeaderCell');
+
+export const QuickTableHeaderRow = (props: QuickTableHeaderRowProps) => {
+  const { children } = props;
+
+  return <tr className={styles.headerRow}>{wrapList(children, QuickTableHeaderCell)}</tr>;
+};
+brandQuickTableType(QuickTableHeaderRow, 'QuickTableHeaderRow');
+
+export const QuickTable = (props: QuickTableProps) => {
+  const { children, headerCells, headerRow, title, hasColumnDividers } = props;
+
+  const header =
+    headerRow ??
+    (headerCells ? <QuickTableHeaderRow>{headerCells}</QuickTableHeaderRow> : undefined);
+
+  return (
+    <table className={cx(styles.table, hasColumnDividers && styles.tableWithColumnDividers)}>
+      {title ? <caption className={styles.caption}>{title}</caption> : null}
+      {header ? <thead>{header}</thead> : null}
+      <tbody>{wrapList(children, QuickTableRow)}</tbody>
+    </table>
+  );
+};
+
+export type {
+  QuickTableProps,
+  QuickTableRowProps,
+  QuickTableCellProps,
+  QuickTableHeaderRowProps,
+  QuickTableHeaderCellProps,
+  QuickTableCellAlign,
+};

package/src/components/Tables/QuickTable/internal.tsx

@@ -0,0 +1,48 @@
+import { Children, isValidElement } from 'react';
+import type { ComponentType, ReactNode } from 'react';
+
+// Each wrapper component carries a string tag at this symbol. Auto-wrap
+// uses either reference equality on the component type (the common case)
+// or tag equality (survives barrel re-export / HOC wrapping that breaks
+// reference identity).
+const BRAND = Symbol('ui-components.QuickTable.brand');
+
+export const brandQuickTableType = <T,>(component: T, tag: string): T => {
+  if (component) {
+    (component as unknown as Record<symbol, string>)[BRAND] = tag;
+  }
+  return component;
+};
+
+const readBrand = (value: unknown): string | undefined => {
+  if (!value || (typeof value !== 'function' && typeof value !== 'object')) {
+    return undefined;
+  }
+  return (value as Record<symbol, string | undefined>)[BRAND];
+};
+
+const isAlready = (
+  element: unknown,
+  Wrapper: ComponentType<{ children: ReactNode }>,
+): boolean => {
+  if (!isValidElement(element)) return false;
+  if (element.type === Wrapper) return true;
+  const elementBrand = readBrand(element.type);
+  if (!elementBrand) return false;
+  return elementBrand === readBrand(Wrapper);
+};
+
+/**
+ * Iterates `children` and wraps any node that isn't already a `Wrapper` into
+ * one. This is what lets callers write `<QuickTableRow>{a}{b}</QuickTableRow>`
+ * instead of `<QuickTableRow><QuickTableCell>{a}</QuickTableCell>...`.
+ */
+export const wrapList = (
+  children: ReactNode,
+  Wrapper: ComponentType<{ children: ReactNode }>,
+): ReactNode => {
+  return Children.map(children, (child, index) => {
+    if (isAlready(child, Wrapper)) return child;
+    return <Wrapper key={index}>{child}</Wrapper>;
+  });
+};

package/src/components/Tables/QuickTable/styles.module.css

@@ -0,0 +1,65 @@
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--ui-text-small);
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border-subtle);
+}
+
+.headerRow {
+  background-color: var(--ui-background-1);
+  border-bottom: 1px solid var(--ui-border);
+}
+
+.headerCell {
+  text-align: left;
+  vertical-align: top;
+  font-weight: 500;
+  color: var(--ui-muted);
+  font-size: var(--ui-text-xsmall);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  padding: var(--ui-space-1) var(--ui-space-2);
+  white-space: nowrap;
+}
+
+.row {
+  border-bottom: 1px solid var(--ui-border-subtle);
+}
+
+.row:nth-child(even) {
+  background-color: var(--ui-background-0-offset);
+}
+
+.row:last-child {
+  border-bottom: none;
+}
+
+.cell {
+  text-align: left;
+  vertical-align: top;
+  padding: var(--ui-space-1) var(--ui-space-2);
+  line-height: var(--ui-line-height-tight);
+}
+
+.alignRight {
+  text-align: right;
+}
+
+.alignCenter {
+  text-align: center;
+}
+
+.caption {
+  caption-side: top;
+  text-align: left;
+  padding: var(--ui-space-1) var(--ui-space-2);
+  color: var(--ui-foreground);
+  font-weight: 500;
+}
+
+.tableWithColumnDividers .cell + .cell,
+.tableWithColumnDividers .headerCell + .headerCell {
+  border-left: 1px solid var(--ui-border-subtle);
+}

package/src/components/Tables/QuickTable/types.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+
+export type QuickTableCellAlign = 'left' | 'right' | 'center';
+
+export type QuickTableProps = {
+  children: ReactNode;
+  /**
+   * Sugar for the most common header shape: an array of cell contents. Each
+   * entry is wrapped into a `QuickTableHeaderCell` inside a
+   * `QuickTableHeaderRow`. For a custom row (column spans, per-cell widths,
+   * actions), pass `headerRow` instead.
+   */
+  headerCells?: ReactNode[];
+  /** Full control over the header row. Overrides `headerCells` when both are set. */
+  headerRow?: ReactNode;
+  /** Optional title rendered above the table as a `<caption>` element. */
+  title?: ReactNode;
+  /** Draw vertical divider lines between columns. Default: false. */
+  hasColumnDividers?: boolean;
+};
+
+export type QuickTableRowProps = {
+  children: ReactNode;
+};
+
+export type QuickTableCellProps = {
+  children: ReactNode;
+  width?: string | number;
+  align?: QuickTableCellAlign;
+};
+
+export type QuickTableHeaderRowProps = {
+  children: ReactNode;
+};
+
+export type QuickTableHeaderCellProps = {
+  children: ReactNode;
+  width?: string | number;
+  align?: QuickTableCellAlign;
+};

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}