@12-apps/ui 1.22.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.22.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. */

package/src/components/data-display/DataViews/RESPONSIVE-BEHAVIOUR.md

@@ -23,6 +23,10 @@ later; an eight-filter one degrades sooner. Both are correct.
 | small desktop | 1280 | laptop |
 | large desktop | 1600 | external monitor |
 
+The tests also pin a **crowded** row at 1024, because a small desktop no longer
+overflows at all: the rules about what happens when controls do NOT fit need a
+width where some of them do not.
+
 **These are toolbar ROW widths, not viewport widths.** The `ResizeObserver`
 watches the row, and the row is narrower than the window by whatever the page
 puts around it — around 48px in the Pedidos shell. So a 430px row is roughly a
@@ -77,8 +81,26 @@ Read this as "what the Pedidos table does", not "what the code hard-codes".
 
 | | small mobile | large mobile | tablet | small desktop | large desktop |
 | --- | --- | --- | --- | --- | --- |
-| controls on the bar | 0 | 0 | 0 | 1–2 | 3+ |
-| "Mais" present | yes | yes | yes | yes | only if something overflowed |
+| controls on the bar | 0 | 1 | 1 | all 6 | all 6 |
+| "Mais" present | yes | yes | yes | no | no |
+
+**The bar re-spends what its own collapse frees.** Rungs 2/4/5 turn 200 + 96 +
+216 of furniture into 44 + 0 + 140, and the split used to be decided once,
+against the UNCOLLAPSED row — so a phone shed all six controls to make room for
+a search box and a counter that were about to shrink, and nobody handed the
+~330px back. It showed as a 428px bar carrying a magnifier, "Mais 6", and a
+225px band of nothing. `computeSplit` now iterates to a fixed point: cheaper
+furniture buys more filters, more filters push the ladder further down, a
+further rung makes the furniture cheaper again, and the budget decreases
+monotonically until it stops moving.
+
+The furniture is also priced for what is ACTUALLY on the bar. "Exportar" exists
+only when the host passes an `exportConfig` — several screens put their export
+in the page header instead — and charging for the pair regardless billed the
+filters ~108px for a button that was never rendered.
+
+Which control survives on a phone is whichever fits the room left over, so a
+large mobile keeps a cheaper pill where a tablet affords a wider one.
 
 **An applied filter is ranked first, not exempt.** Applied controls take the
 visible slots ahead of idle ones and go into "Mais" like anything else when even
@@ -133,7 +155,12 @@ Two distinct behaviours, and conflating them was a bug:
 | --- | --- | --- | --- | --- | --- |
 | Exibir / Exportar | icon | icon | label | label | label |
 | dropdown chevron | no | no | yes | yes | yes |
-| "N de N" counter | hidden | hidden | shown | shown | shown |
+| "N de N" counter | hidden | shown | shown | shown | shown |
+
+The counter is priced at 56, not the old 96. It was measured against
+"1.234 de 5.678"; a phone reads "3 de 3" and renders at 35px, so the extra
+~60px was coming straight out of the filter budget at exactly the widths where
+that budget is scarcest.
 
 A tablet keeps the labels, which is worth stating because it is easy to assume
 otherwise. With every filter already behind "Mais" the row has room to spare
@@ -176,6 +203,13 @@ leaves the board with a single populated column, which reads as data loss.
 of the five widths and asserts the tables above. It is the executable copy of
 this document; if the two disagree, the test is right and this needs updating.
 
+`what fits follows the controls, not the width alone` guards the property the
+rest of this document depends on: the counts above are OUTCOMES of pricing one
+fixture against one row, never rules. At a single width it asserts that a table
+declaring cheaper controls keeps more of them, that one long control keeps
+none, and that the same table promotes another as its row grows — three answers
+a breakpoint could not give.
+
 Two things it cannot check, because jsdom has no layout engine: actual pixel
 overflow, and how anything looks. Those are verified in a real browser against
 the running Storybook, at 1600 / 1280 / 1024 / 900 / 768 / 600 / 500 / 430 / 390