@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/dist/Table/TableHeaderCell.js

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableHeaderCell.tsx
+ * @input React, StyleX, TableContext, theme tokens, useTableCellStyles
+ * @output Exports TableHeaderCell component, TableHeaderCellProps
+ * @position Sub-component; used inside Table for header cells
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Table/Table.doc.mjs
+ * - /packages/core/src/Table/index.ts
+ * - /packages/cli/templates/blocks/components/Table/ (showcase blocks)
+ */
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, fontWeightVars, typeScaleVars, borderVars } from "../theme/tokens.stylex.js";
+import { overflowStyles, containerEdgeStyles } from "./table.stylex.js";
+import { useTableContext, mergeXStyle } from "./useTableCellStyles.js";
+import { mergeProps } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+
+/** Props for TableHeaderCell — `<th>` wrapper with context-aware styling */
+import { jsx as _jsx } from "react/jsx-runtime";
+const densityStyles = {
+  compact: {
+    k8WAf4: "xu0wf1k",
+    kg3NbH: "xf314gf",
+    kGuDYH: "xcr08ib",
+    kB7OPa: "x9f619",
+    $$css: true
+  },
+  balanced: {
+    k8WAf4: "xce4md1",
+    kg3NbH: "xrrkdod",
+    kGuDYH: "xcr08ib",
+    kB7OPa: "x9f619",
+    $$css: true
+  },
+  spacious: {
+    k8WAf4: "x8o8v82",
+    kg3NbH: "x1pzlopt",
+    kGuDYH: "xcr08ib",
+    kB7OPa: "x9f619",
+    $$css: true
+  }
+};
+const headerStyles = {
+  cell: {
+    k63SB2: "x2mo6ok",
+    kMwMTN: "xv1l7n4",
+    k9WMMc: "x1yc453h",
+    $$css: true
+  }
+};
+const headerDividerStyles = {
+  cell: {
+    kt9PQ7: "x92x3c3",
+    kfdmCh: "x1q0q8m5",
+    kL6WhQ: "xw8gpjh",
+    $$css: true
+  }
+};
+const dividerColumnStyles = {
+  cell: {
+    kWqL5O: "x1pcaw5z x1lpyac",
+    kSWEuD: "x32b0ac",
+    k26BEO: "xtgwc6q",
+    $$css: true
+  }
+};
+
+/**
+ * TableHeaderCell — a `<th>` wrapper for header cells.
+ *
+ * When used inside `<Table>`, inherits styling from the table context
+ * (density padding, header font weight/color, divider borders).
+ * When used standalone, renders a plain `<th>`.
+ *
+ * Accepts `xstyle` for plugin-provided styles that merge on top.
+ *
+ * @example
+ * ```
+ * <thead>
+ *   <tr>
+ *     <TableHeaderCell>Name</TableHeaderCell>
+ *     <TableHeaderCell>Age</TableHeaderCell>
+ *   </tr>
+ * </thead>
+ * ```
+ */
+export function TableHeaderCell({
+  children,
+  xstyle,
+  ref,
+  className: incomingClassName,
+  style: incomingStyle,
+  ...props
+}) {
+  const ctx = useTableContext();
+  if (!ctx) {
+    return /*#__PURE__*/_jsx("th", {
+      ref: ref,
+      ...props,
+      ...mergeProps(themeProps('table-header-cell'), stylex.props(xstyle), incomingClassName, incomingStyle),
+      children: children
+    });
+  }
+
+  // Header cells always get the bottom divider (separates header from body).
+  // Column dividers use the shared buildDividerStyles — but only for
+  // the column axis, since the row divider is the headerDividerStyles.
+  const cellStyles = [headerStyles.cell, densityStyles[ctx.density], headerDividerStyles.cell, overflowStyles.cell, containerEdgeStyles[ctx.density]];
+
+  // Only add column dividers from the shared builder
+  if (ctx.dividers === 'columns' || ctx.dividers === 'grid') {
+    cellStyles.push(dividerColumnStyles.cell);
+  }
+  return /*#__PURE__*/_jsx("th", {
+    ref: ref,
+    ...props,
+    ...mergeProps(themeProps('table-header-cell'), stylex.props(...mergeXStyle(cellStyles, xstyle)), incomingClassName, incomingStyle),
+    children: children
+  });
+}
+TableHeaderCell.displayName = 'TableHeaderCell';

package/dist/Table/TableRow.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file TableRow.tsx
+ * @input React, StyleX, TableContext, theme tokens
+ * @output Exports TableRow component, TableRowProps
+ * @position Sub-component; used inside Table children mode
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Table/Table.doc.mjs
+ * - /packages/core/src/Table/index.ts
+ * - /packages/cli/templates/blocks/components/Table/ (showcase blocks)
+ */
+import { type ReactNode } from 'react';
+import type { BaseProps } from '../BaseProps';
+import type { StyleXStyles } from '../theme/types';
+/** Props for TableRow — thin `<tr>` wrapper */
+export interface TableRowProps extends BaseProps<HTMLTableRowElement> {
+    /** Ref forwarded to the root element */
+    ref?: React.Ref<HTMLTableRowElement>;
+    children: ReactNode;
+    /**
+     * StyleX styles for layout customization (margins, positioning, sizing).
+     * Must be a `stylex.create()` value — not an inline style object.
+     */
+    xstyle?: StyleXStyles[];
+}
+/**
+ * TableRow — a `<tr>` wrapper for children/streaming mode.
+ *
+ * When used inside `<Table>`, inherits styling from the table context
+ * (striped, hover, divider overrides). When used standalone, renders a plain `<tr>`.
+ *
+ * @example
+ * ```
+ * <Table>
+ *   <TableRow>
+ *     <TableCell>Alice</TableCell>
+ *     <TableCell>30</TableCell>
+ *   </TableRow>
+ * </Table>
+ * ```
+ */
+export declare function TableRow({ children, xstyle, ref, ...props }: TableRowProps): import("react").JSX.Element;
+export declare namespace TableRow {
+    var displayName: string;
+}
+//# sourceMappingURL=TableRow.d.ts.map

package/dist/Table/TableRow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableRow.d.ts","sourceRoot":"","sources":["../../src/Table/TableRow.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAM,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAMjD,+CAA+C;AAC/C,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,mBAAmB,CAAC;IACnE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB;AAwCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,MAAM,EACN,GAAG,EACH,GAAG,KAAK,EACT,EAAE,aAAa,+BAgDf;yBArDe,QAAQ"}

package/dist/Table/TableRow.js

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TableRow.tsx
+ * @input React, StyleX, TableContext, theme tokens
+ * @output Exports TableRow component, TableRowProps
+ * @position Sub-component; used inside Table children mode
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Table/Table.doc.mjs
+ * - /packages/core/src/Table/index.ts
+ * - /packages/cli/templates/blocks/components/Table/ (showcase blocks)
+ */
+import { use } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
+import { tableRowMarker } from "./table.stylex.js";
+import { TableContext } from "./TableContext.js";
+import { mergeProps } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+
+/** Props for TableRow — thin `<tr>` wrapper */
+import { jsx as _jsx } from "react/jsx-runtime";
+const stripedRowStyles = {
+  row: {
+    kWkggS: "x1dnou9g",
+    $$css: true
+  }
+};
+const hoverRowStyles = {
+  row: {
+    kWkggS: "xe9uy6x",
+    k1ekBW: "x15406qy",
+    kIyJzY: "xuedmi6",
+    kAMwcw: "xlr8y92",
+    $$css: true
+  }
+};
+const stripedHoverRowStyles = {
+  row: {
+    kWkggS: "x1dnou9g xe9uy6x",
+    k1ekBW: "x15406qy",
+    kIyJzY: "xuedmi6",
+    kAMwcw: "xlr8y92",
+    $$css: true
+  }
+};
+
+/**
+ * TableRow — a `<tr>` wrapper for children/streaming mode.
+ *
+ * When used inside `<Table>`, inherits styling from the table context
+ * (striped, hover, divider overrides). When used standalone, renders a plain `<tr>`.
+ *
+ * @example
+ * ```
+ * <Table>
+ *   <TableRow>
+ *     <TableCell>Alice</TableCell>
+ *     <TableCell>30</TableCell>
+ *   </TableRow>
+ * </Table>
+ * ```
+ */
+export function TableRow({
+  children,
+  xstyle,
+  ref,
+  ...props
+}) {
+  const ctx = use(TableContext);
+  if (!ctx) {
+    return /*#__PURE__*/_jsx("tr", {
+      ref: ref,
+      ...props,
+      ...mergeProps(themeProps('table-row'), stylex.props(tableRowMarker, xstyle)),
+      children: children
+    });
+  }
+  const rowStyles = [];
+
+  // Handle striped + hover combination to avoid backgroundColor conflicts
+  if (ctx.isStriped && ctx.hasHover) {
+    rowStyles.push(stripedHoverRowStyles.row);
+  } else if (ctx.isStriped) {
+    rowStyles.push(stripedRowStyles.row);
+  } else if (ctx.hasHover) {
+    rowStyles.push(hoverRowStyles.row);
+  }
+  if (ctx.dividers === 'rows' || ctx.dividers === 'grid') {
+    // Note: last-body-row border removal is handled by TableCell
+    // to avoid affecting the header row in <thead>.
+  }
+  if (xstyle) {
+    rowStyles.push(...xstyle);
+  }
+  return /*#__PURE__*/_jsx("tr", {
+    ref: ref,
+    ...props,
+    ...mergeProps(themeProps('table-row'), stylex.props(tableRowMarker, ...rowStyles)),
+    children: children
+  });
+}
+TableRow.displayName = 'TableRow';

package/dist/Table/columnUtils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file columnUtils.ts
+ * @input TableColumn types from types.ts
+ * @output Pure utility functions for column width, layout resolution, and auto-generation
+ * @position Utility layer; consumed by BaseTable.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/Table.doc.mjs (utility descriptions)
+ * - /packages/core/src/Table/index.ts (exports if functions change)
+ */
+import type { CSSProperties, ReactNode } from 'react';
+import type { TableColumn, ProportionalWidth, PixelWidth } from './types';
+/** Default minimum width (in px) for proportional columns. */
+export declare const DEFAULT_MIN_COLUMN_WIDTH = 120;
+/**
+ * Pre-computed width information for a single column.
+ * Produced by `resolveColumnWidths()`, consumed by header cell rendering.
+ */
+export interface ResolvedColumnWidth {
+    /** Inline style to apply on the `<th>` for this column. */
+    style: CSSProperties;
+}
+/**
+ * Result of `resolveColumnWidths()` — contains per-column width styles
+ * and the aggregate table min-width. Computed once and shared between
+ * the table min-width calculation and header cell rendering.
+ */
+export interface ResolvedColumnWidths {
+    /** Per-column width styles, indexed by column key. */
+    columns: Map<string, ResolvedColumnWidth>;
+    /** Minimum table width (px) to prevent proportional columns from shrinking below their minWidth. */
+    tableMinWidth: number;
+}
+/**
+ * Resolve column widths for the entire table in a single pass.
+ *
+ * Computes:
+ * - Per-column inline styles (`width`, `minWidth`) for `<th>` elements
+ * - Aggregate `tableMinWidth` for the `<table>` element
+ *
+ * This consolidates width logic that was previously duplicated between
+ * the `tableMinWidth` IIFE and the header cell rendering loop.
+ *
+ * @param columns - Resolved column definitions (after auto-generation)
+ * @returns Pre-computed widths for each column and the table minimum width
+ */
+export declare function resolveColumnWidths<T extends Record<string, unknown>>(columns: TableColumn<T>[]): ResolvedColumnWidths;
+/**
+ * Create a proportional column width (fr-like).
+ * Columns share available space proportionally.
+ * Applies `DEFAULT_MIN_COLUMN_WIDTH` when no explicit minWidth is provided.
+ *
+ * @example
+ * ```
+ * proportional(2) // twice as wide as proportional(1)
+ * proportional(1, { minWidth: 200 }) // explicit min
+ * ```
+ */
+export declare function proportional(value?: number, options?: {
+    minWidth?: number;
+}): ProportionalWidth;
+/**
+ * Create a fixed pixel column width.
+ *
+ * @example
+ * ```
+ * pixel(200) // exactly 200px wide
+ * ```
+ */
+export declare function pixel(value: number): PixelWidth;
+/**
+ * Capitalize the first letter of a string.
+ * Used for auto-generating header text from data keys.
+ */
+export declare function capitalize(str: string): string;
+/**
+ * Default cell renderer — converts the value at `item[key]` to a string.
+ */
+export declare function defaultCellRenderer<T extends Record<string, unknown>>(item: T, key: string): ReactNode;
+/**
+ * Auto-generate column definitions from the keys of the first data item.
+ * Derives content-proportional widths by analyzing the header and first
+ * few rows of data. Min-width is based on the longer of: header text
+ * or the longest single word in values.
+ */
+export declare function generateColumns<T extends Record<string, unknown>>(data: T[]): TableColumn<T>[];
+//# sourceMappingURL=columnUtils.d.ts.map

package/dist/Table/columnUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnUtils.d.ts","sourceRoot":"","sources":["../../src/Table/columnUtils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAC,WAAW,EAAE,iBAAiB,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AAExE,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAM5C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC1C,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,GACxB,oBAAoB,CAmEtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,GAAE,MAAU,EACjB,OAAO,CAAC,EAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAC,GAC5B,iBAAiB,CAMnB;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAE/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,IAAI,EAAE,CAAC,EACP,GAAG,EAAE,MAAM,GACV,SAAS,CAiBX;AA+DD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,CAAC,EAAE,GACR,WAAW,CAAC,CAAC,CAAC,EAAE,CAmDlB"}

package/dist/Table/columnUtils.js

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file columnUtils.ts
+ * @input TableColumn types from types.ts
+ * @output Pure utility functions for column width, layout resolution, and auto-generation
+ * @position Utility layer; consumed by BaseTable.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/Table.doc.mjs (utility descriptions)
+ * - /packages/core/src/Table/index.ts (exports if functions change)
+ */
+
+/** Default minimum width (in px) for proportional columns. */
+export const DEFAULT_MIN_COLUMN_WIDTH = 120;
+
+// =============================================================================
+// Resolved Column Widths
+// =============================================================================
+
+/**
+ * Pre-computed width information for a single column.
+ * Produced by `resolveColumnWidths()`, consumed by header cell rendering.
+ */
+
+/**
+ * Result of `resolveColumnWidths()` — contains per-column width styles
+ * and the aggregate table min-width. Computed once and shared between
+ * the table min-width calculation and header cell rendering.
+ */
+
+/**
+ * Resolve column widths for the entire table in a single pass.
+ *
+ * Computes:
+ * - Per-column inline styles (`width`, `minWidth`) for `<th>` elements
+ * - Aggregate `tableMinWidth` for the `<table>` element
+ *
+ * This consolidates width logic that was previously duplicated between
+ * the `tableMinWidth` IIFE and the header cell rendering loop.
+ *
+ * @param columns - Resolved column definitions (after auto-generation)
+ * @returns Pre-computed widths for each column and the table minimum width
+ */
+export function resolveColumnWidths(columns) {
+  // --- Pass 1: Categorize columns and compute totals ---
+  let totalProportion = 0;
+  let pixelTotal = 0;
+  const proportionalCols = [];
+  for (const col of columns) {
+    const w = col.width;
+    if (w?.type === 'pixel') {
+      pixelTotal += w.value;
+    } else {
+      const proportion = w?.value ?? 1;
+      // Only count minWidth for columns that explicitly used proportional().
+      // Columns with no width set (w === undefined) have no minimum —
+      // they flex freely and the scroll wrapper handles overflow.
+      const minW = w != null ? w.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH : 0;
+      totalProportion += proportion;
+      proportionalCols.push({
+        key: col.key,
+        proportion,
+        minWidth: minW
+      });
+    }
+  }
+
+  // --- Pass 2: Compute table min-width ---
+  let maxProportionalSpace = 0;
+  if (totalProportion > 0) {
+    for (const col of proportionalCols) {
+      const required = col.minWidth * totalProportion / col.proportion;
+      if (required > maxProportionalSpace) {
+        maxProportionalSpace = required;
+      }
+    }
+  }
+  const tableMinWidth = pixelTotal + maxProportionalSpace;
+
+  // --- Pass 3: Build per-column styles ---
+  const result = new Map();
+  for (const col of columns) {
+    const w = col.width;
+    const style = {};
+    if (w?.type === 'pixel') {
+      // Fixed pixel width — set both width and minWidth to prevent shrinking
+      style.width = `${w.value}px`;
+      style.minWidth = `${w.value}px`;
+    } else {
+      // Proportional width — compute percentage from total proportional units.
+      const proportion = w?.value ?? 1;
+      if (totalProportion > 0) {
+        style.width = `${proportion / totalProportion * 100}%`;
+      }
+      // Only apply minWidth if the column explicitly used proportional().
+      // Columns with no width set (w === undefined) have no minimum —
+      // they flex freely and the scroll wrapper handles overflow.
+      if (w != null) {
+        const minW = w.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH;
+        style.minWidth = `${minW}px`;
+      }
+    }
+    result.set(col.key, {
+      style
+    });
+  }
+  return {
+    columns: result,
+    tableMinWidth
+  };
+}
+
+/**
+ * Create a proportional column width (fr-like).
+ * Columns share available space proportionally.
+ * Applies `DEFAULT_MIN_COLUMN_WIDTH` when no explicit minWidth is provided.
+ *
+ * @example
+ * ```
+ * proportional(2) // twice as wide as proportional(1)
+ * proportional(1, { minWidth: 200 }) // explicit min
+ * ```
+ */
+export function proportional(value = 1, options) {
+  return {
+    type: 'proportional',
+    value,
+    minWidth: options?.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH
+  };
+}
+
+/**
+ * Create a fixed pixel column width.
+ *
+ * @example
+ * ```
+ * pixel(200) // exactly 200px wide
+ * ```
+ */
+export function pixel(value) {
+  return {
+    type: 'pixel',
+    value
+  };
+}
+
+/**
+ * Capitalize the first letter of a string.
+ * Used for auto-generating header text from data keys.
+ */
+export function capitalize(str) {
+  if (str.length === 0) {
+    return str;
+  }
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Default cell renderer — converts the value at `item[key]` to a string.
+ */
+export function defaultCellRenderer(item, key) {
+  const value = item[key];
+  if (value == null) {
+    return '';
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value);
+  }
+  return '';
+}
+
+/**
+ * Estimate the display width of a value in characters.
+ * Only measures string and number values — objects, arrays, and other
+ * complex types return 0 (fall back to equal proportioning for that cell).
+ */
+function estimateContentLength(value) {
+  if (value == null) {
+    return 0;
+  }
+  if (typeof value === 'string') {
+    return value.length;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value).length;
+  }
+  return 0;
+}
+
+/**
+ * Find the longest single word in a value (for min-width estimation).
+ * A "word" is a contiguous non-whitespace sequence.
+ * Only measures string and number values — complex types return 0.
+ */
+function longestWord(value) {
+  if (value == null) {
+    return 0;
+  }
+  if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+    return 0;
+  }
+  const str = String(value);
+  let max = 0;
+  let current = 0;
+  for (let i = 0; i <= str.length; i++) {
+    if (i === str.length || str[i] === ' ' || str[i] === '\t' || str[i] === '\n') {
+      if (current > max) {
+        max = current;
+      }
+      current = 0;
+    } else {
+      current++;
+    }
+  }
+  return max;
+}
+
+/** Minimum floor for any column (px). Prevents collapse on narrow viewports. */
+const MIN_COLUMN_FLOOR = 60;
+
+/** Scale factor: approximate px per character for min-width calculation. */
+const PX_PER_CHAR = 8;
+
+/**
+ * Auto-generate column definitions from the keys of the first data item.
+ * Derives content-proportional widths by analyzing the header and first
+ * few rows of data. Min-width is based on the longer of: header text
+ * or the longest single word in values.
+ */
+export function generateColumns(data) {
+  if (data.length === 0) {
+    return [];
+  }
+  const firstItem = data[0];
+  const keys = Object.keys(firstItem);
+
+  // Sample first few rows for content analysis
+  const sampleRows = data.slice(0, Math.min(5, data.length));
+
+  // Measure each column
+  const measurements = keys.map(key => {
+    const headerLen = capitalize(key).length;
+    let maxContentLen = headerLen;
+    let maxWordLen = headerLen; // header is a single "word" for min-width purposes
+
+    for (const row of sampleRows) {
+      const contentLen = estimateContentLength(row[key]);
+      if (contentLen > maxContentLen) {
+        maxContentLen = contentLen;
+      }
+      const wordLen = longestWord(row[key]);
+      if (wordLen > maxWordLen) {
+        maxWordLen = wordLen;
+      }
+    }
+    return {
+      key,
+      headerLen,
+      maxContentLen,
+      maxWordLen
+    };
+  });
+  return measurements.map(m => {
+    // Bucket content length into proportional tiers:
+    // 1 = short (≤6 chars: IDs, ages, booleans, status)
+    // 2 = medium (7–15 chars: names, dates, short strings)
+    // 3 = long (>15 chars: emails, URLs, descriptions)
+    const proportion = m.maxContentLen <= 6 ? 1 : m.maxContentLen <= 15 ? 2 : 3;
+
+    // Min-width: enough to fit header or longest word without wrapping
+    const minWidth = Math.max(Math.max(m.headerLen, m.maxWordLen) * PX_PER_CHAR, MIN_COLUMN_FLOOR);
+    return {
+      key: m.key,
+      header: capitalize(m.key),
+      width: proportional(proportion, {
+        minWidth
+      })
+    };
+  });
+}