@12-apps/ui 1.23.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.23.0",
+  "version": "2.0.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -20,6 +20,7 @@
     "./social-login-button": "./src/social-login-button/index.ts",
     "./user-avatar": "./src/user-avatar/index.ts",
     "./utils": "./src/utils/index.ts",
+    "./tokens": "./src/tokens/scales.ts",
     "./mui/Box": "./src/mui/Box.ts",
     "./mui/Link": "./src/mui/Link.ts",
     "./mui/Stack": "./src/mui/Stack.ts",
@@ -134,6 +135,7 @@
     "./utility/AspectRatio": "./src/components/utility/AspectRatio/index.ts",
     "./utility/InfiniteScroll": "./src/components/utility/InfiniteScroll/index.ts",
     "./utility/InstallPrompt": "./src/components/utility/InstallPrompt/index.ts",
+    "./utility/Overflow": "./src/components/utility/Overflow/index.ts",
     "./utility/Portal": "./src/components/utility/Portal/index.ts",
     "./utility/Transition": "./src/components/utility/Transition/index.ts",
     "./utility/VirtualList": "./src/components/utility/VirtualList/index.ts",

package/src/components/data-display/Alert/Alert.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue } from '../../../tokens/scales';
 import type { AlertProps as MuiAlertProps } from '@mui/material';
 import type React from 'react';
 
@@ -10,7 +11,7 @@ export interface AlertProps extends Omit<MuiAlertProps, 'variant' | 'color' | 'r
   /**
    * The color of the alert (when not using variant-specific colors)
    */
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  color?: Exclude<ColorValue, 'info'>;
   
   /**
    * Whether the alert should have a glow effect

package/src/components/data-display/Avatar/Avatar.types.ts

@@ -1,7 +1,15 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { AvatarProps as MuiAvatarProps } from '@mui/material';
 import type React from 'react';
 
-export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * The house scale, EXTENDED by one stop rather than replacing it.
+ *
+ * `xxl` is real — an avatar is the one component with a portrait size above the
+ * scale's top — so it is added to `SizeValue` instead of the union being
+ * rewritten by hand. Spelling all six out again is how the copy drifts.
+ */
+export type AvatarSize = SizeValue | 'xxl';
 export type AvatarVariant = 'circle' | 'square' | 'rounded' | 'status';
 export type AvatarStatus = 'online' | 'offline' | 'away' | 'busy';
 
@@ -49,7 +57,7 @@ export interface AvatarProps extends Omit<MuiAvatarProps, 'variant'> {
   /**
    * Color of the avatar background when no image is provided
    */
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'neutral';
+  color?: Exclude<ColorValue, 'info'>;
 
   /**
    * Whether the avatar is in a loading state

package/src/components/data-display/Badge/Badge.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { BadgeProps as MuiBadgeProps } from '@mui/material';
 import type React from 'react';
 
@@ -13,7 +14,7 @@ export type BadgeVariant =
   | 'success'
   | 'warning';
 
-export type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
+export type BadgeSize = Extract<SizeValue, 'xs' | 'sm' | 'md' | 'lg'>;
 
 export interface BadgeProps extends Omit<MuiBadgeProps, 'variant' | 'color' | 'content'> {
   /**
@@ -29,7 +30,7 @@ export interface BadgeProps extends Omit<MuiBadgeProps, 'variant' | 'color' | 'c
   /**
    * The color of the badge
    */
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'neutral' | 'info';
+  color?: ColorValue;
   
   /**
    * Whether the badge should have a glow effect

package/src/components/data-display/Carousel/Carousel.parts.tsx

@@ -7,6 +7,8 @@ import React from 'react';
 
 import { withDefaults } from '../../../utils/withDefaults';
 
+import { accentFor, muiSize } from '../../../tokens/scales';
+
 import type {
   CarouselArrowsProps,
   CarouselIndicatorsProps,
@@ -69,8 +71,8 @@ const LineIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onSel
         width: isActive ? 30 : 20,
         height: 3,
         backgroundColor: isActive
-          ? theme.palette[color].main
-          : alpha(theme.palette[color].main, 0.3),
+          ? accentFor(theme, color).main
+          : alpha(accentFor(theme, color).main, 0.3),
         borderRadius: 1.5,
         transition: theme.transitions.create(['width', 'background-color']),
         cursor: 'pointer',
@@ -96,9 +98,9 @@ const NumberIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onS
         alignItems: 'center',
         justifyContent: 'center',
         borderRadius: '50%',
-        backgroundColor: isActive ? theme.palette[color].main : 'transparent',
-        color: isActive ? theme.palette[color].contrastText : theme.palette[color].main,
-        border: `1px solid ${theme.palette[color].main}`,
+        backgroundColor: isActive ? accentFor(theme, color).main : 'transparent',
+        color: isActive ? accentFor(theme, color).contrastText : accentFor(theme, color).main,
+        border: `1px solid ${accentFor(theme, color).main}`,
         fontSize: '0.75rem',
         fontWeight: isActive ? 'bold' : 'normal',
         cursor: 'pointer',
@@ -122,7 +124,7 @@ const DotIndicator: React.FC<IndicatorProps> = ({ index, isActive, color, onSele
       onClick={onSelect}
       sx={{
         p: 0.5,
-        color: isActive ? theme.palette[color].main : alpha(theme.palette[color].main, 0.3),
+        color: isActive ? accentFor(theme, color).main : alpha(accentFor(theme, color).main, 0.3),
         transform: isActive ? 'scale(1.2)' : 'scale(1)',
         transition: theme.transitions.create(['transform', 'color']),
       }}
@@ -185,7 +187,7 @@ const ARROWS_DEFAULTS = {
   disablePrev: false,
   disableNext: false,
   color: 'primary',
-  size: 'medium',
+  size: 'md',
 } satisfies Partial<CarouselArrowsProps>;
 
 /**
@@ -198,7 +200,7 @@ const arrowSx = (theme: Theme, color: Color, isOverlay: boolean): CSSObject => (
   transform: 'translateY(-50%)',
   zIndex: 3,
   backgroundColor: alpha(theme.palette.background.paper, 0.8),
-  color: theme.palette[color].main,
+  color: accentFor(theme, color).main,
   '&:disabled': { opacity: 0.3 },
   ...(isOverlay
     ? {
@@ -223,7 +225,7 @@ export const CarouselArrows: React.FC<CarouselArrowsProps> = (props) => {
       <IconButton
         onClick={onPrev}
         disabled={disabled || disablePrev}
-        size={size}
+        size={muiSize(size)}
         className={className}
         aria-label="Previous slide"
         data-testid="carousel-prev-button"
@@ -236,7 +238,7 @@ export const CarouselArrows: React.FC<CarouselArrowsProps> = (props) => {
         onClick={onNext}
         disabled={disabled || disableNext}
         aria-label="Next slide"
-        size={size}
+        size={muiSize(size)}
         className={className}
         data-testid="carousel-next-button"
         sx={{ ...sx, right: offset, ...style }}

package/src/components/data-display/Carousel/Carousel.styles.ts

@@ -2,6 +2,7 @@ import { alpha } from '@mui/material';
 import type { CSSObject, Theme } from '@mui/material';
 
 import type { CarouselProps } from './Carousel.types';
+import { accentFor } from '../../../tokens/scales';
 
 type Variant = NonNullable<CarouselProps['variant']>;
 type Size = NonNullable<CarouselProps['size']>;
@@ -39,12 +40,12 @@ const SURFACES: Record<Variant, (input: ContainerStyleInput) => CSSObject> = {
   glass: ({ theme, color, glass }) => ({
     backgroundColor: alpha(theme.palette.background.paper, glass ? 0.1 : 0.9),
     backdropFilter: 'blur(20px)',
-    border: `1px solid ${alpha(theme.palette[color].main, 0.2)}`,
+    border: `1px solid ${alpha(accentFor(theme, color).main, 0.2)}`,
   }),
 
   gradient: ({ theme, color, gradient }) => ({
     background: gradient
-      ? `linear-gradient(135deg, ${alpha(theme.palette[color].light, 0.1)}, ${alpha(theme.palette[color].dark, 0.1)})`
+      ? `linear-gradient(135deg, ${alpha(accentFor(theme, color).light, 0.1)}, ${alpha(accentFor(theme, color).dark, 0.1)})`
       : 'transparent',
   }),
 
@@ -59,7 +60,7 @@ const SURFACES: Record<Variant, (input: ContainerStyleInput) => CSSObject> = {
 
 export const containerStyles = (input: ContainerStyleInput): CSSObject => {
   const { theme, variant, size, color, height, width, glow, pulse } = input;
-  const accent = theme.palette[color].main;
+  const accent = accentFor(theme, color).main;
 
   return {
     position: 'relative' as const,

package/src/components/data-display/Carousel/Carousel.tsx

@@ -8,6 +8,7 @@ import { CarouselChrome } from './Carousel.chrome';
 import { CarouselTrack } from './Carousel.slide';
 import { containerStyles } from './Carousel.styles';
 import type { CarouselItem, CarouselProps } from './Carousel.types';
+import { muiColor } from '../../../tokens/scales';
 
 export { CarouselArrows, CarouselIndicators, CarouselThumbnails } from './Carousel.parts';
 
@@ -80,7 +81,7 @@ export const Carousel: React.FC<CarouselProps> = (props) => {
   if (loading) {
     return (
       <Box sx={{ ...frameSx, display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
-        <CircularProgress color={color} />
+        <CircularProgress color={muiColor(color, 'inherit')} />
       </Box>
     );
   }

package/src/components/data-display/Carousel/Carousel.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { CSSProperties, ReactNode } from 'react';
 
 export interface CarouselItem {
@@ -12,8 +13,8 @@ export interface CarouselItem {
 export interface CarouselProps {
   items: CarouselItem[];
   variant?: 'default' | 'glass' | 'gradient' | 'elevated' | 'minimal' | 'cards';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  color?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
+  size?: SizeValue;
+  color?: Exclude<ColorValue, 'neutral'>;
   autoPlay?: boolean;
   autoPlayInterval?: number;
   loop?: boolean;
@@ -50,7 +51,7 @@ export interface CarouselIndicatorsProps {
   activeIndex: number;
   onSelect: (index: number) => void;
   position?: 'top' | 'bottom' | 'left' | 'right';
-  color?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
+  color?: Exclude<ColorValue, 'neutral'>;
   variant?: 'dots' | 'lines' | 'numbers';
   className?: string;
   style?: CSSProperties;
@@ -63,8 +64,8 @@ export interface CarouselArrowsProps {
   disabled?: boolean;
   disablePrev?: boolean;
   disableNext?: boolean;
-  color?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
-  size?: 'small' | 'medium' | 'large';
+  color?: Exclude<ColorValue, 'neutral'>;
+  size?: Extract<SizeValue, 'sm' | 'md' | 'lg'>;
   className?: string;
   style?: CSSProperties;
 }
@@ -73,7 +74,7 @@ export interface CarouselThumbnailsProps {
   items: CarouselItem[];
   activeIndex: number;
   onSelect: (index: number) => void;
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  size?: SizeValue;
   className?: string;
   style?: CSSProperties;
 }

package/src/components/data-display/Chart/Chart.tsx

@@ -5,6 +5,7 @@ import type { ChartProps } from './Chart.types';
 import { ChartContainer } from './ChartComposables';
 import { getSizeStyles, getVariantStyles } from './chart-internals';
 import { renderChartByType } from './chart-renderers';
+import { muiColor } from '../../../tokens/scales';
 
 /**
  * Prop-driven Recharts wrapper (line/bar/area/pie/radar/scatter/composed)
@@ -70,7 +71,7 @@ export const Chart: React.FC<ChartProps> = (props) => {
         data-testid={`${dataTestId}-loading`}
         sx={{ ...styles, ...sizeStyles, display: 'flex', justifyContent: 'center', alignItems: 'center' }}
       >
-        <CircularProgress color={props.color ?? 'primary'} data-testid={`${dataTestId}-loading-spinner`} />
+        <CircularProgress color={muiColor(props.color ?? 'primary', 'inherit')} data-testid={`${dataTestId}-loading-spinner`} />
       </Paper>
     );
   }

package/src/components/data-display/Chart/Chart.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { CSSProperties } from 'react';
 
 export type ChartType = 'line' | 'bar' | 'area' | 'pie' | 'radar' | 'scatter' | 'composed';
@@ -26,8 +27,8 @@ export interface ChartProps {
   series?: ChartSeries[];
   type?: ChartType;
   variant?: 'default' | 'glass' | 'gradient' | 'elevated' | 'minimal' | 'neon';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  color?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
+  size?: SizeValue;
+  color?: Exclude<ColorValue, 'neutral'>;
   height?: number;
   width?: number | string;
   glow?: boolean;

package/src/components/data-display/Chart/ChartSpec.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue } from '../../../tokens/scales';
 /**
  * JSON-serializable chart specification — the declarative surface of the raw
  * chart library. A `ChartSpec` plus plain data rows fully describes a rendered
@@ -13,13 +14,11 @@ export type ChartSpecType = 'line' | 'bar' | 'area' | 'pie' | 'donut';
  * Semantic color token resolved against the MUI palette at render time.
  * Specs must not carry raw color values.
  */
-export type ChartSemanticColor =
-  | 'primary'
-  | 'secondary'
-  | 'success'
-  | 'warning'
-  | 'error'
-  | 'info';
+/**
+ * The house vocabulary minus `neutral`: a data series is always an accent, and
+ * an unaccented series would be indistinguishable from the grid it sits on.
+ */
+export type ChartSemanticColor = Exclude<ColorValue, 'neutral'>;
 
 /**
  * Number formatting applied to tooltip values and the y axis.

package/src/components/data-display/Chart/SpecChart.tsx

@@ -5,6 +5,7 @@ import { Chart } from './Chart';
 import type { ChartDataPoint } from './Chart.types';
 import type { ChartSemanticColor, ChartSpec } from './ChartSpec.types';
 import { CHART_SEMANTIC_COLORS, specToChartProps } from './chart-spec';
+import { accentFor } from '../../../tokens/scales';
 
 export interface SpecChartProps {
   /** Validated spec — parse untrusted JSON with `parseChartSpec` first. */
@@ -36,7 +37,7 @@ export const SpecChart: React.FC<SpecChartProps> = ({
     const scheme: readonly ChartSemanticColor[] =
       spec.colorScheme && spec.colorScheme.length > 0 ? spec.colorScheme : CHART_SEMANTIC_COLORS;
     const resolveColor = (token: ChartSemanticColor | undefined, index: number): string =>
-      theme.palette[token ?? scheme[index % scheme.length] ?? 'primary'].main;
+      accentFor(theme, token ?? scheme[index % scheme.length] ?? 'primary').main;
     return specToChartProps(spec, data, { resolveColor });
   }, [spec, data, theme]);
 

package/src/components/data-display/Chart/chart-internals.ts

@@ -2,6 +2,7 @@ import { alpha, type Theme } from '@mui/material';
 import type { CSSProperties } from 'react';
 
 import type { ChartProps, ChartSeries } from './Chart.types';
+import { accentFor} from '../../../tokens/scales';
 
 /**
  * Non-JSX internals of the prop-driven Chart: size/variant styling, palette
@@ -65,7 +66,7 @@ interface VariantOptions {
 }
 
 function effectStyles(theme: Theme, options: VariantOptions): SxStyles {
-  const accent = theme.palette[options.color].main;
+  const accent = accentFor(theme, options.color).main;
   const glow = options.glow ? { boxShadow: `0 0 30px ${alpha(accent, 0.4)}` } : {};
   const pulse = options.pulse
     ? {
@@ -91,7 +92,7 @@ function variantSurface(theme: Theme, options: VariantOptions): SxStyles {
     case 'gradient':
       return {
         background: options.gradient
-          ? `linear-gradient(135deg, ${alpha(theme.palette[options.color].light, 0.05)}, ${alpha(theme.palette[options.color].dark, 0.05)})`
+          ? `linear-gradient(135deg, ${alpha(accentFor(theme, options.color).light, 0.05)}, ${alpha(accentFor(theme, options.color).dark, 0.05)})`
           : theme.palette.background.paper,
       };
     case 'elevated':

package/src/components/data-display/Chart/chart-spec.ts

@@ -7,12 +7,22 @@ import {
   type ChartSpecRenderContext,
 } from './chart-spec-registry';
 
+/**
+ * BREAKING FOR STORED SPECS, not just for types.
+ *
+ * A chart spec is DATA — it is authored as JSON and can be persisted — and this
+ * list is validated at runtime, so a saved spec carrying `"error"` now throws
+ * `ChartSpecError` instead of silently drawing. That is the right failure (the
+ * alternative is a series quietly losing its colour), but unlike the rest of
+ * this migration a type-check will not find the affected specs: anything stored
+ * outside the repo has to be rewritten `error` → `danger`.
+ */
 export const CHART_SEMANTIC_COLORS: readonly ChartSemanticColor[] = [
   'primary',
   'secondary',
   'success',
   'warning',
-  'error',
+  'danger',
   'info',
 ];
 

package/src/components/data-display/Chip/Chip.tsx

@@ -13,6 +13,10 @@ import {
 } from './Chip.helpers';
 import type { ChipProps } from './Chip.types';
 
+/** MUI draws two chip sizes; ours are the house abbreviations for them. */
+const muiSizeFor = (size: NonNullable<ChipProps['size']>): 'small' | 'medium' =>
+  size === 'sm' ? 'small' : 'medium';
+
 type MuiChipColor =
   | 'primary'
   | 'secondary'
@@ -22,10 +26,26 @@ type MuiChipColor =
   | 'warning'
   | 'default';
 
+/**
+ * `danger` and `neutral` are ours; the rest are MUI's own names already.
+ *
+ * The same boundary translation `Button` performs, and it must stay a
+ * translation rather than a cast: a cast is what let `danger` through untouched
+ * and had MUI silently fall back to grey.
+ *
+ * `neutral` maps to `default`, not to `inherit` as it does on a button. A chip's
+ * unaccented state is a real palette entry with its own fill; `inherit` would
+ * take the surrounding text colour and paint a chip that reads as disabled.
+ */
+const muiColorFor = (color: NonNullable<ChipProps['color']>): MuiChipColor => {
+  if (color === 'danger') return 'error';
+  return color === 'neutral' ? 'default' : color;
+};
+
 export const Chip = forwardRef<HTMLDivElement, ChipProps>(({
   label,
   variant = 'filled',
-  size = 'medium',
+  size = 'md',
   color = 'primary',
   avatarSrc,
   avatar,
@@ -48,8 +68,8 @@ export const Chip = forwardRef<HTMLDivElement, ChipProps>(({
       ref={ref}
       label={<span data-testid={testId('label')}>{label}</span>}
       variant={variant}
-      size={size}
-      color={color as MuiChipColor | undefined}
+      size={muiSizeFor(size)}
+      color={muiColorFor(color)}
       avatar={avatarFor(avatar, avatarSrc)}
       icon={iconWithTestId(icon, testId('icon'))}
       onDelete={deletable ? onDelete : undefined}

package/src/components/data-display/Chip/Chip.types.ts

@@ -1,7 +1,41 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { ReactNode } from 'react';
 
 export type ChipVariant = 'filled' | 'outlined';
-export type ChipSize = 'small' | 'medium';
+
+/**
+ * The house size scale, abbreviated like every other component's.
+ *
+ * `Avatar`, `Badge`, `Progress`, `Input`, `Modal` and `Dialog` all use `sm`/`md`;
+ * this was `'small' | 'medium'`, MUI's spelling, and the sole outlier in the
+ * package. That was not merely inconsistent — callers wrote `size="sm"` because
+ * every neighbouring component taught them to, it type-checked against the old
+ * `ChipSize` nowhere and reached MUI as an unknown value, and the chip silently
+ * rendered at the default `medium`. Twelve of them are doing that today.
+ *
+ * Only two entries, because a MUI chip only draws two. Inventing `lg` here would
+ * put a size in the type that nothing can render.
+ */
+export type ChipSize = Extract<SizeValue, 'sm' | 'md'>;
+
+/**
+ * The colours a chip can draw — THE HOUSE VOCABULARY, identical to `ButtonProps`.
+ *
+ * `danger` and `neutral` are ours; the rest are MUI's own names already. That is
+ * the same sentence `Button.tsx` carries, and deliberately so: `Button`, `Alert`,
+ * `Text`, `Heading`, `Paragraph` and `Blockquote` all speak this vocabulary, so a
+ * chip is the odd one out if it does not.
+ *
+ * This prop was `string`, and the widening was not free. `danger` — the house
+ * word for the destructive meaning, and what every neighbouring component
+ * accepts — reached MUI as an unknown value and fell back to the default grey.
+ * The chip that most needed emphasis rendered without any, and nothing said so.
+ *
+ * The fix is NOT to reject `danger`. Rejecting it would punish a caller for
+ * using the vocabulary the rest of the system taught them. The fix is for the
+ * chip to speak it and translate at the MUI boundary, exactly as `Button` does.
+ */
+export type ChipColor = ColorValue;
 
 export interface ChipProps {
   /** Text content displayed in the chip */
@@ -13,8 +47,8 @@ export interface ChipProps {
   /** Size of the chip */
   size?: ChipSize;
   
-  /** Theme color token */
-  color?: string;
+  /** Theme color token. See {@link ChipColor} for why this is a closed set. */
+  color?: ChipColor;
   
   /** Source URL for avatar image */
   avatarSrc?: string;

package/src/components/data-display/Chip/chip.md

@@ -6,8 +6,12 @@
 interface ChipProps {
   label: string;
   variant?: 'filled' | 'outlined';
-  size?: 'sm' | 'md' | 'lg';
-  color?: ColorValue; // theme token
+  size?: SizeValue narrowed to 'sm' | 'md';
+  /**
+   * The house vocabulary, identical to Button's. `danger` and `neutral` are
+   * ours and are translated at the MUI boundary. See `ColorValue`.
+   */
+  color?: ColorValue;
   avatarSrc?: string; // or avatar node via `avatar`
   avatar?: React.ReactNode;
   icon?: React.ReactNode; // leading icon
@@ -296,7 +300,7 @@ test('tag removal in list', async () => {
 test('status chip with color coding', () => {
   const statuses = [
     { label: 'Success', color: 'success', testId: 'status-success' },
-    { label: 'Error', color: 'error', testId: 'status-error' },
+    { label: 'Error', color: 'danger', testId: 'status-error' },
     { label: 'Warning', color: 'warning', testId: 'status-warning' },
   ];
 

package/src/components/data-display/Chip/index.ts

@@ -1,2 +1,2 @@
 export { Chip } from './Chip';
-export type { ChipProps, ChipSize, ChipVariant } from './Chip.types';
+export type { ChipColor, ChipProps, ChipSize, ChipVariant } from './Chip.types';

package/src/components/data-display/DataViews/DataViewsGrid.tsx

@@ -5,6 +5,7 @@ import { useEffect, useRef } from "react";
 import { type SortFieldDefinition } from "../../layout/ContentToolbar";
 
 import { GridShell } from "./data-views-grid-parts";
+import type { ListGroupConfig } from "./list-card-rails";
 import type { DisplayPanelView } from "./data-views-display-panel";
 import type { BoardConfig } from "./DataViewsBoard";
 import type { DataViewExport } from "./data-views-export";
@@ -123,6 +124,15 @@ interface DataViewsGridProps<T extends Record<string, unknown>> {
    * offered, exactly as `renderCard` gates the cards.
    */
   renderListRow?: (row: T, selection: DataViewCardSelection) => React.ReactNode;
+  /**
+   * The Lista's SHARED COLUMNS — declared once for the list, obeyed by every row.
+   *
+   * This is what makes a list line up by construction rather than by convention.
+   * Omit it and each row still resolves its own tracks from its own config,
+   * which agrees with its neighbours right up until one row carries an unusually
+   * wide value.
+   */
+  listGroup?: ListGroupConfig<T>;
   /**
    * The page-level partition rendered as an exclusive tab strip above the
    * toolbar, with server-supplied counts. Requires `server`: a scope is applied

package/src/components/data-display/DataViews/DataViewsTableBase.tsx

@@ -4,6 +4,7 @@ import type { SortFieldDefinition } from "../../layout/ContentToolbar";
 import { useEffect, useMemo, useRef, useState } from "react";
 
 import { DataViewsGrid } from "./DataViewsGrid";
+import type { ListGroupConfig } from "./list-card-rails";
 import type { DisplayPanelView } from "./data-views-display-panel";
 import { viewStateKey } from "./data-views-dirty";
 import { DeleteViewDialog } from "./DeleteViewDialog";
@@ -83,6 +84,8 @@ export interface DataViewsTableBaseProps<T extends Record<string, unknown>> {
   board?: BoardConfig<T>;
   /** Opt-in "Lista" layout — one full-width, entity-rendered row per record (FUT-733). */
   renderListRow?: (row: T, selection: DataViewCardSelection) => React.ReactNode;
+  /** The Lista's shared columns, so its rows line up by construction not convention. */
+  listGroup?: ListGroupConfig<T>;
   /** The page-level partition rendered as tabs under the toolbar (server mode only). */
   scopes?: ScopeConfig[];
   /** The row field the scopes partition by — used only to reject a pill over the same field. */