@12-apps/ui 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",

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

@@ -93,7 +93,7 @@ export const Chart: React.FC<ChartProps> = (props) => {
       <ChartContainer
         responsive={props.responsive ?? true}
         width={props.width ?? '100%'}
-        height={sizeStyles.height}
+        height={props.fillHeight === true ? '100%' : sizeStyles.height}
         data-testid={`${dataTestId}-container`}
       >
         {renderChartByType(props, theme)}

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

@@ -83,6 +83,16 @@ export interface ChartProps {
   maxCategoryTicks?: number;
   /** Category tick labels longer than this are truncated with an ellipsis. Default 12. */
   tickLabelMaxChars?: number;
+  /**
+   * Take the height of the box this chart is placed in, rather than the size
+   * preset's fixed one.
+   *
+   * For a host that has already sized the chart's container — a dashboard cell
+   * with a chosen height, say. The preset is a sensible default precisely
+   * because most callers have NOT sized anything, so this is opt-in: without
+   * it a chart in a box with no definite height would collapse to nothing.
+   */
+  fillHeight?: boolean;
   /** Bar corner radius in px (top corners only; stacked segments stay square). Default 3. */
   barRadius?: number;
   /**

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

@@ -15,7 +15,16 @@ export const ChartTooltip = Tooltip;
 export const ChartLegend = Legend;
 
 export interface ChartContainerProps {
-  height: number;
+  /**
+   * A number of pixels, or a PERCENTAGE of the box this container is given.
+   *
+   * The difference is not cosmetic: Recharts sizes the chart from the number
+   * when it is one and only MEASURES its own box when it is a percentage
+   * (`calculateChartDimensions`). So a container stretched by its parent's
+   * layout goes on drawing a 300px chart inside a 600px box — visibly, as
+   * blank space under the plot — until the height is handed over as a percent.
+   */
+  height: number | `${number}%`;
   width?: number | string;
   responsive?: boolean;
   children: React.ReactElement;

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

@@ -12,6 +12,8 @@ export interface SpecChartProps {
   spec: ChartSpec;
   data: ChartDataPoint[];
   size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Take the height of the box this chart is placed in — see `ChartProps`. */
+  fillHeight?: boolean;
   loading?: boolean;
   className?: string;
   onClick?: (point: ChartDataPoint) => void;
@@ -27,6 +29,7 @@ export const SpecChart: React.FC<SpecChartProps> = ({
   spec,
   data,
   size,
+  fillHeight,
   loading,
   className,
   onClick,
@@ -45,6 +48,7 @@ export const SpecChart: React.FC<SpecChartProps> = ({
     <Chart
       {...chartProps}
       size={size}
+      fillHeight={fillHeight}
       loading={loading}
       className={className}
       onClick={onClick}

package/src/components/data-display/DataViews/data-views-display-tabs.tsx

@@ -2,6 +2,8 @@
 
 import ArrowDownwardRoundedIcon from "@mui/icons-material/ArrowDownwardRounded";
 import ArrowUpwardRoundedIcon from "@mui/icons-material/ArrowUpwardRounded";
+import useMediaQuery from "@mui/material/useMediaQuery";
+import type { Theme } from "@mui/material/styles";
 
 import type { SortFieldDefinition } from "../../layout/ContentToolbar";
 import { Box } from "../../../mui/Box";
@@ -286,9 +288,44 @@ const LAYOUT_TILE_LABELS: Record<DataViewsLayout, string> = {
  * `data-views-glyphs.tsx` for why. A layout this table cannot render is simply
  * not offered, and the panel says why rather than leaving a gap.
  */
+/**
+ * The three density tiles — or, on a phone, a line saying why there are none:
+ * the card grid is `1fr` there, so all three would draw one card per row. Says
+ * so rather than vanishing, for the same reason as the board note below it.
+ */
+function DensityTiles({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element {
+  const { layout, density, setDensity } = useDataViewsLayout();
+  // Matches the card grid's own `xs: "1fr"` track, so the control and the thing
+  // it controls agree on where density stops meaning anything.
+  const isOneColumn = useMediaQuery((t: Theme) => t.breakpoints.down("sm"));
+  if (layout === "cards" && isOneColumn) {
+    return (
+      <Text variant="caption" as="p">
+        <Box component="span" sx={{ px: 0.5, pt: 0.5, display: "block", color: "text.disabled" }}>
+          Um card por linha nesta largura — a densidade volta em telas maiores.
+        </Box>
+      </Text>
+    );
+  }
+  return (
+    <Box sx={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 0.75, mt: 0.5 }}>
+      {densityTiles(layout).map((tile) => (
+        <Tile
+          key={tile.value}
+          active={density === tile.value}
+          label={tile.label}
+          onClick={() => setDensity(tile.value)}
+          testId={`${testIdPrefix}-density-${tile.value}`}
+        >
+          {densityGlyph(layout, tile, density === tile.value)}
+        </Tile>
+      ))}
+    </Box>
+  );
+}
+
 export function DisplayTab({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element {
-  const { layout, setLayout, canUseCards, canUseList, canUseBoard, density, setDensity } =
-    useDataViewsLayout();
+  const { layout, setLayout, canUseCards, canUseList, canUseBoard } = useDataViewsLayout();
   const available: DataViewsLayout[] = [
     "table",
     ...(canUseList ? (["list"] as const) : []),
@@ -336,19 +373,7 @@ export function DisplayTab({ testIdPrefix }: { testIdPrefix: string }): React.JS
           {DENSITY_HEADINGS[layout]}
         </Box>
       </Text>
-      <Box sx={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 0.75, mt: 0.5 }}>
-        {densityTiles(layout).map((tile) => (
-          <Tile
-            key={tile.value}
-            active={density === tile.value}
-            label={tile.label}
-            onClick={() => setDensity(tile.value)}
-            testId={`${testIdPrefix}-density-${tile.value}`}
-          >
-            {densityGlyph(layout, tile, density === tile.value)}
-          </Tile>
-        ))}
-      </Box>
+      <DensityTiles testIdPrefix={testIdPrefix} />
       {!canUseBoard && (
         <Text variant="caption" as="p">
           <Box component="span" sx={{ px: 0.5, pt: 1.25, display: "block", color: "text.disabled" }}>

package/src/components/data-display/DataViews/data-views-grid-bodies.tsx

@@ -6,14 +6,14 @@ import { DataGrid, type GridColumn, type GridSort } from "../DataGrid";
 import { Box } from "../../../mui/Box";
 
 import {
-  cardMinWidthForZoom,
+  cardTargetWidthFor,
   cardScaleForZoom,
   DENSITY_BOARD_SCALE,
-  DENSITY_CARD_COLUMNS,
   DENSITY_ROW_PADDING,
   useDataViewsLayout,
   type DataViewsDensity,
 } from "./data-views-layout-context";
+import { cardGridTracks } from "./data-views-grid-helpers";
 import { DataViewsBoard, type BoardConfig } from "./DataViewsBoard";
 import { SelectAllStrip } from "./data-views-select-all-strip";
 import { ListCardGroup, type ListGroupConfig } from "./list-card-rails";
@@ -90,9 +90,8 @@ interface CardBodyProps<T extends Record<string, unknown>> {
   getRowId: (row: T) => string | number;
   selectedIds: Set<string | number>;
   onToggleId: (id: string | number) => void;
-  minCardWidth: number;
-  /** Cap on cards per row, from the density preference. */
-  maxColumns: number;
+  /** The width each card asks for; `auto-fill` turns it into a column count. */
+  targetCardWidth: number;
   /** Content scale (padding + type) handed to each card, from the zoom slider. */
   cardScale: number;
   dataTestId?: string;
@@ -112,8 +111,7 @@ function CardBody<T extends Record<string, unknown>>({
   getRowId,
   selectedIds,
   onToggleId,
-  minCardWidth,
-  maxColumns,
+  targetCardWidth,
   cardScale,
   dataTestId,
   emptyState,
@@ -129,12 +127,7 @@ function CardBody<T extends Record<string, unknown>>({
         // Fixed inter-card gap — deliberately NOT scaled by the zoom slider, so
         // only the cards grow while the space between them stays constant.
         gap: 1.5,
-        // `auto-fill` still decides how many FIT; density caps how many are
-        // ALLOWED, so "Poucos" reads as bigger cards rather than more of them.
-        gridTemplateColumns: {
-          xs: "1fr",
-          sm: `repeat(auto-fill, minmax(max(${minCardWidth}px, calc((100% - ${(maxColumns - 1) * 12}px) / ${maxColumns})), 1fr))`,
-        },
+        ...cardGridTracks(targetCardWidth),
       }}
       data-testid={dataTestId ? `${dataTestId}-cards` : "data-views-cards"}
     >
@@ -353,8 +346,7 @@ function headerlessBody<T extends Record<string, unknown>>(
         getRowId={getRowId}
         selectedIds={c.selectedIds}
         onToggleId={c.toggleId}
-        minCardWidth={cardMinWidthForZoom(zoom)}
-        maxColumns={DENSITY_CARD_COLUMNS[density]}
+        targetCardWidth={cardTargetWidthFor(zoom, density)}
         cardScale={cardScaleForZoom(zoom)}
         dataTestId={dataTestId}
         emptyState={emptyState}

package/src/components/data-display/DataViews/data-views-grid-helpers.tsx

@@ -246,3 +246,24 @@ export function togglePillValues(current: string[] | undefined, value: string, c
   const list = current ?? [];
   return checked ? [...list, value] : list.filter((v) => v !== value);
 }
+
+/**
+ * The card grid's `grid-template-columns`, as an sx fragment.
+ *
+ * One rule at every width: each card asks for `targetWidth` and `auto-fill`
+ * decides how many fit. Density moves the target, so it changes the count at
+ * every size — which the previous column-count cap could not do, because its
+ * track floor bottomed out at a constant shared by all three densities.
+ *
+ * Below `sm` this is a single column, and no target changes that. That is why
+ * the density control hides itself there rather than offering three settings
+ * that all draw the same thing.
+ */
+export function cardGridTracks(targetWidth: number) {
+  return {
+    gridTemplateColumns: {
+      xs: "1fr",
+      sm: `repeat(auto-fill, minmax(${targetWidth}px, 1fr))`,
+    },
+  };
+}

package/src/components/data-display/DataViews/data-views-layout-context.tsx

@@ -81,13 +81,32 @@ export const DENSITY_ROW_PADDING: Record<DataViewsDensity, number> = {
   comfortable: 1.5,
 };
 
-/** Card grid columns per density — how many cards land on one row. */
-export const DENSITY_CARD_COLUMNS: Record<DataViewsDensity, number> = {
-  compact: 5,
-  cozy: 4,
-  comfortable: 3,
+/**
+ * The card WIDTH each density aims for, as a multiple of the base card width.
+ *
+ * Density used to cap the column COUNT, with a track floor of
+ * `max(baseWidth, 100% / count)`. That base is a constant, so wherever it won
+ * the arithmetic every density produced an identical track — "Muitos" and
+ * "Medio" both drew 3 cards of 279px at md — and where the percentage won
+ * instead, on a wide screen, the count was pinned and each card grew to a share
+ * of the viewport: ~430px of card holding one chip and two lines of text.
+ *
+ * One width per density fixes both, because the number `auto-fill` divides by
+ * now differs per density at every size. The spread is chosen so the three land
+ * on DIFFERENT column counts across the range rather than by eye — 4/3/2 at md,
+ * 6/4/3 at lg, 7/5/4 at xl, 13/9/8 at 2560.
+ */
+export const DENSITY_CARD_SCALE: Record<DataViewsDensity, number> = {
+  compact: 0.84,
+  cozy: 1.15,
+  comfortable: 1.4,
 };
 
+/** The width a card aims for: the base width, scaled by zoom, then by density. */
+export function cardTargetWidthFor(zoom: number, density: DataViewsDensity): number {
+  return Math.round(cardMinWidthForZoom(zoom) * DENSITY_CARD_SCALE[density]);
+}
+
 /**
  * The BOARD's column-width multiplier per density.
  *

package/src/components/form/DateRangePicker/DateRangePicker.tsx

@@ -22,7 +22,7 @@
  * finished window, so a half-picked or impossible range has somewhere to live
  * while it is being fixed. Every `onChange` carries the verdict with it.
  */
-import { Box, Paper } from '@mui/material';
+import { Box, Paper, useMediaQuery } from '@mui/material';
 import type { SxProps, Theme } from '@mui/material';
 import React from 'react';
 
@@ -31,12 +31,15 @@ import { Calendar } from '../Calendar';
 import { toLocalDay } from './DateRangePicker.dates';
 import { useDateRangePicker } from './DateRangePicker.hooks';
 import { DEFAULT_QUICK_RANGES } from './DateRangePicker.quick';
-import type { DateRangePickerProps } from './DateRangePicker.types';
+import type { DateRangeDraft, DateRangePickerProps, WeekStart } from './DateRangePicker.types';
 import { DateRangeFields } from './DateRangePickerFields';
 import { DateRangeQuickList } from './DateRangePickerQuickList';
 
 const CALENDAR_CLASS = 'date-range-picker__calendar';
 
+/** Below this the picker is a phone layout. MUI's own `md`, written out. */
+const NARROW_QUERY = '(max-width:899.95px)';
+
 const ROOT_SX: SxProps<Theme> = {
   display: 'inline-flex',
   flexDirection: 'column',
@@ -56,17 +59,140 @@ const ROOT_SX: SxProps<Theme> = {
 
 const BODY_SX: SxProps<Theme> = {
   display: 'flex',
-  // The quick column sits BESIDE the calendar and drops UNDER it when there is
-  // no room for both. At 390px a side column would squeeze the day grid to
-  // roughly half its width and make the numbers unreadable; stacking keeps the
-  // grid whole and costs a scroll. Checked at 390px.
-  flexDirection: { xs: 'column', md: 'row' },
-  alignItems: 'flex-start',
+  // The quick column sits BESIDE the calendar on a wide screen. Narrow, it
+  // moves ABOVE it — `column-reverse`, so the DOM order stays calendar-then-
+  // list (the calendar is the primary control and should be reached first by a
+  // screen reader and by Tab) while the eye meets the quick ranges first, which
+  // is the order the phone mock asks for and the order a thumb wants: nine
+  // one-tap answers before a grid of thirty.
+  //
+  // A side column at 390px would squeeze the day grid to roughly half its width
+  // and make the numbers unreadable. Checked at 390px.
+  flexDirection: { xs: 'column-reverse', md: 'row' },
+  alignItems: { xs: 'stretch', md: 'flex-start' },
   gap: 2,
   maxWidth: '100%',
-  overflowX: 'auto',
 };
 
+/**
+ * The rule between the calendar and the quick ranges.
+ *
+ * Two lists of dates side by side with only whitespace between them read as one
+ * ragged thing; the rule says which numbers belong to which control. It turns
+ * with the layout — a vertical rule when the list is a column beside the
+ * calendar, a horizontal one when it has moved above it — because a divider
+ * that keeps its axis while the flex direction flips ends up separating nothing.
+ */
+const QUICK_DIVIDER_SX: SxProps<Theme> = {
+  borderColor: 'divider',
+  borderStyle: 'solid',
+  borderWidth: 0,
+  borderLeftWidth: { xs: 0, md: '1px' },
+  borderBottomWidth: { xs: '1px', md: 0 },
+  pl: { xs: 0, md: 2 },
+  pb: { xs: 2, md: 0 },
+  alignSelf: 'stretch',
+};
+
+/** And the rule above the typed pair, which is a third way in, not a caption. */
+const FIELDS_DIVIDER_SX: SxProps<Theme> = {
+  borderTop: '1px solid',
+  borderColor: 'divider',
+  pt: 2,
+};
+
+type Picker = ReturnType<typeof useDateRangePicker>;
+
+/**
+ * How many months to draw.
+ *
+ * A month grid has a floor: seven columns that must stay legible, which is
+ * about 280px. Two of them need 580, so on a phone the consumer's
+ * `numberOfMonths` is not a preference that can be honoured — it is a request
+ * for a layout that does not fit. Capped here rather than left to the consumer,
+ * because the consumer chooses for its own reason (the reports dialog wants two
+ * because a period often crosses a month boundary) and has no way to know the
+ * picker is currently 390px wide.
+ *
+ * A media query rather than an `sx` breakpoint: this decides what to RENDER,
+ * and CSS cannot un-render a second month.
+ *
+ * The query is a LITERAL, not `theme.breakpoints.down('md')`. The callback form
+ * reads the theme from context and throws on a null one, so a consumer that
+ * mounts this outside a `ThemeProvider` would crash — which the unit tests here
+ * do, and which is a fair thing for a consumer to do.
+ */
+function useMonthCount(requested: number | undefined): number | undefined {
+  const narrow = useMediaQuery(NARROW_QUERY);
+  return narrow ? 1 : requested;
+}
+
+/** The grid, in range mode — `Calendar`, never a second implementation of one. */
+function RangeCalendar({
+  picker,
+  value,
+  locale,
+  weekStartsOn,
+  months,
+  maxRangeDays,
+}: {
+  picker: Picker;
+  value: DateRangeDraft;
+  locale: string;
+  weekStartsOn: WeekStart;
+  months: number | undefined;
+  maxRangeDays: number | undefined;
+}): React.JSX.Element {
+  return (
+    <Calendar
+      key={picker.viewNonce}
+      className={CALENDAR_CLASS}
+      selectionMode="range"
+      locale={locale}
+      // One prop drives the grid's first column AND the day "this week" starts
+      // on, so a highlighted week can never begin mid-row.
+      firstDayOfWeek={weekStartsOn}
+      numberOfMonths={months}
+      range={{ start: toLocalDay(value.from), end: toLocalDay(value.to) }}
+      // BOTH callbacks, and the intermediate one does the work: the other fires
+      // only on the click that CLOSES a range, so a picker wired to it alone
+      // would not repaint after the first click.
+      onIntermediateRangeChange={picker.pickOnCalendar}
+      onRangeChange={picker.pickOnCalendar}
+      // The same ceiling the quick list is judged against, so the calendar
+      // cannot hand back a window the control has just called too long.
+      maxRangeLength={maxRangeDays}
+    />
+  );
+}
+
+/** The quick ranges, inside the rule that separates them from the grid. */
+function QuickColumn({
+  picker,
+  maxRangeDays,
+  dataTestId,
+}: {
+  picker: Picker;
+  maxRangeDays: number | undefined;
+  dataTestId: string;
+}): React.JSX.Element | null {
+  if (picker.options.length === 0) return null;
+  return (
+    <Box sx={QUICK_DIVIDER_SX}>
+      <DateRangeQuickList
+        options={picker.options}
+        activeId={picker.activeId}
+        onPick={picker.pickQuick}
+        reasonFor={(option) =>
+          picker.copy.overMax({ maxRangeDays: maxRangeDays ?? option.days, days: option.days })
+        }
+        label={picker.copy.quickRanges}
+        dataTestId={dataTestId}
+      />
+    </Box>
+  );
+}
+
 export function DateRangePicker({
   value,
   onChange,
@@ -91,54 +217,32 @@ export function DateRangePicker({
     quickRanges,
     messages,
   });
+  const months = useMonthCount(numberOfMonths);
 
   return (
     <Paper className={className} data-testid={dataTestId} sx={ROOT_SX}>
       <Box sx={BODY_SX}>
-        <Calendar
-          key={picker.viewNonce}
-          className={CALENDAR_CLASS}
-          selectionMode="range"
+        <RangeCalendar
+          picker={picker}
+          value={value}
           locale={locale}
-          // One prop drives the grid's first column AND the day "this week"
-          // starts on, so a highlighted week can never begin mid-row.
-          firstDayOfWeek={weekStartsOn}
-          numberOfMonths={numberOfMonths}
-          range={{ start: toLocalDay(value.from), end: toLocalDay(value.to) }}
-          // BOTH callbacks, and the intermediate one does the work: the other
-          // fires only on the click that CLOSES a range, so a picker wired to
-          // it alone would not repaint after the first click.
-          onIntermediateRangeChange={picker.pickOnCalendar}
-          onRangeChange={picker.pickOnCalendar}
-          // The same ceiling the quick list is judged against, so the calendar
-          // cannot hand back a window the control has just called too long.
-          maxRangeLength={maxRangeDays}
+          weekStartsOn={weekStartsOn}
+          months={months}
+          maxRangeDays={maxRangeDays}
+        />
+        <QuickColumn picker={picker} maxRangeDays={maxRangeDays} dataTestId={dataTestId} />
+      </Box>
+      <Box sx={FIELDS_DIVIDER_SX}>
+        <DateRangeFields
+          value={value}
+          status={picker.status}
+          messages={picker.copy}
+          maxRangeDays={maxRangeDays}
+          onEdit={picker.editBound}
+          statusId={picker.statusId}
+          dataTestId={dataTestId}
         />
-        {picker.options.length > 0 && (
-          <DateRangeQuickList
-            options={picker.options}
-            activeId={picker.activeId}
-            onPick={picker.pickQuick}
-            reasonFor={(option) =>
-              picker.copy.overMax({
-                maxRangeDays: maxRangeDays ?? option.days,
-                days: option.days,
-              })
-            }
-            label={picker.copy.quickRanges}
-            dataTestId={dataTestId}
-          />
-        )}
       </Box>
-      <DateRangeFields
-        value={value}
-        status={picker.status}
-        messages={picker.copy}
-        maxRangeDays={maxRangeDays}
-        onEdit={picker.editBound}
-        statusId={picker.statusId}
-        dataTestId={dataTestId}
-      />
     </Paper>
   );
 }

package/src/components/form/DateRangePicker/DateRangePickerQuickList.tsx

@@ -20,10 +20,12 @@ import type { ResolvedQuickRange } from './DateRangePicker.types';
 
 const optionSx = (active: boolean, overMax: boolean): SxProps<Theme> => ({
   display: 'block',
-  // Full-width rows in the side column; chips that flow onto as many lines as
-  // they need once the column has become a row under the calendar. A fixed
-  // full width in both would make the narrow layout nine stacked lines.
+  // Full-width rows in the side column; pills in the narrow row. A fixed full
+  // width in both would make the narrow layout nine stacked lines.
   width: { xs: 'auto', md: '100%' },
+  // A pill must not be squeezed by its neighbours — the row SCROLLS rather
+  // than compressing "Este trimestre" into two characters and an ellipsis.
+  flex: { xs: '0 0 auto', md: '0 1 auto' },
   textAlign: 'left',
   font: 'inherit',
   fontSize: '0.875rem',
@@ -31,9 +33,14 @@ const optionSx = (active: boolean, overMax: boolean): SxProps<Theme> => ({
   lineHeight: 1.4,
   px: 1.5,
   py: 0.75,
+  whiteSpace: { xs: 'nowrap', md: 'normal' },
   border: '1px solid',
-  borderColor: active ? 'primary.main' : 'transparent',
-  borderRadius: 1,
+  // Narrow, an entry has to look tappable on its own, with no column and no
+  // rule to group it — so the pill carries a visible edge. Beside the calendar
+  // the group already reads as a list and a border on every row would be nine
+  // boxes where the selected one should be the only marked thing.
+  borderColor: active ? 'primary.main' : { xs: 'divider', md: 'transparent' },
+  borderRadius: { xs: 999, md: 1 },
   cursor: overMax ? 'not-allowed' : 'pointer',
   color: overMax ? 'text.disabled' : active ? 'primary.main' : 'text.primary',
   backgroundColor: active ? 'action.selected' : 'transparent',
@@ -78,11 +85,25 @@ export function DateRangeQuickList({
       data-testid={`${dataTestId}-quick-list`}
       sx={{
         display: 'flex',
-        // A column beside the calendar; a wrapping row above it once there is
-        // no width for both. Checked at 390px: the calendar keeps its full
-        // 280px grid and the entries flow onto as many lines as they need.
+        // A column beside the calendar; ONE scrolling row of pills above it
+        // once there is no width for both.
+        //
+        // Scrolling rather than wrapping: nine wrapped pills take three or four
+        // lines at 390px, which pushes the calendar most of a screen down and
+        // makes the quick ranges — the fastest way to answer — the thing you
+        // have to scroll past. One line keeps the calendar in view and costs a
+        // horizontal swipe, which is the gesture a chip row already invites.
         flexDirection: { xs: 'row', md: 'column' },
-        flexWrap: 'wrap',
+        flexWrap: { xs: 'nowrap', md: 'wrap' },
+        overflowX: { xs: 'auto', md: 'visible' },
+        // Room for the focus ring, which an `overflow` container would clip.
+        px: { xs: 0.25, md: 0 },
+        py: { xs: 0.25, md: 0 },
+        // The scrollbar is chrome on a phone and noise on a trackpad; the pills
+        // themselves are the affordance, and the last one sits half-cut at the
+        // edge to say the row continues.
+        scrollbarWidth: 'none',
+        '&::-webkit-scrollbar': { display: 'none' },
         alignContent: 'flex-start',
         gap: 0.5,
         minWidth: { md: 168 },

package/src/components/navigation/Breadcrumbs/BreadcrumbEntry.tsx

@@ -191,11 +191,12 @@ const EllipsisCrumb: React.FC<{ label: string; dataTestId?: string }> = ({
           </Tooltip>
 );
 
-// The same conditional test id was written at each crumb variant.
+// The same conditional test id was written at each crumb variant. An item that
+// names its OWN id wins: see `BreadcrumbItem.dataTestId`.
 const makeTestId =
   (dataTestId?: string) =>
-  (suffix: string): string =>
-    dataTestId ? `${dataTestId}-${suffix}` : `breadcrumbs-${suffix}`;
+  (suffix: string, own?: string): string =>
+    own ?? (dataTestId ? `${dataTestId}-${suffix}` : `breadcrumbs-${suffix}`);
 
 const ClickableCrumb: React.FC<{
   item: BreadcrumbItem;
@@ -204,7 +205,7 @@ const ClickableCrumb: React.FC<{
   size: string;
   variant: string;
   isActive: boolean;
-  testId: (suffix: string) => string;
+  testId: (suffix: string, own?: string) => string;
 }> = ({ item, index, icon, size, variant, isActive, testId }) => (
   <Tooltip title={item.tooltip || item.label} arrow disableHoverListener={!item.tooltip}>
     <BreadcrumbLink
@@ -215,7 +216,7 @@ const ClickableCrumb: React.FC<{
       active={isActive}
       underline="none"
       aria-label={item.ariaLabel || item.label}
-      data-testid={testId(`link-${index}`)}
+      data-testid={testId(`link-${index}`, item.dataTestId)}
     >
       {icon}
       <span>{item.label}</span>
@@ -283,7 +284,7 @@ export const BreadcrumbEntry: React.FC<{
         size={size}
         visualStyle={variant}
         aria-current="page"
-        data-testid={testId(`item-${index}`)}
+        data-testid={testId(`item-${index}`, item.dataTestId)}
       >
         {icon}
         <span>{item.label}</span>

package/src/components/navigation/Breadcrumbs/Breadcrumbs.types.ts

@@ -37,7 +37,18 @@ export interface BreadcrumbItem {
    * Custom aria-label for accessibility
    */
   ariaLabel?: string;
-  
+
+  /**
+   * Test id for THIS crumb, replacing the trail's positional
+   * `<dataTestId>-link-<index>` / `<dataTestId>-item-<index>`.
+   *
+   * A trail that takes over from an older affordance has to keep that
+   * affordance's id, and the positional one cannot: a crumb's index moves the
+   * moment the trail grows a step — which is exactly what happens when a
+   * screen gains an "editing" level.
+   */
+  dataTestId?: string;
+
   /**
    * Internal flag for ellipsis items (used in collapsed behavior)
    * @internal