@12-apps/ui 6.66.2 → 6.68.0

package/src/components/data-display/DataViews/data-views-quick-chip.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+/**
+ * A QUICK CHIP — the toolbar's one-click filter (see `QuickFilterConfig`).
+ *
+ * Its own module because it is drawn in two places: on the bar, as a
+ * pill-shaped toggle with its count, and inside "Mais" when the ladder had no
+ * room for it, as a toggle row with the same label and count. Both write the
+ * same state through `onToggleQuick`, so where the chip sits never changes what
+ * it does.
+ *
+ * Hand-drawn rather than `Toggle` (MUI ToggleButton), as the range preset chips
+ * beside it are: a ToggleButton is a squared group member with its own
+ * selected tint, and this is a standalone pill whose pressed state INVERTS —
+ * the approved Estoque prototype's chip, pill radius included.
+ */
+import Checkbox from "@mui/material/Checkbox/index.js";
+import type { Theme } from "@mui/material/styles/index.js";
+
+import { Box } from "../../../mui/Box";
+import { fieldHeight } from "../../../tokens/field-height";
+import { fieldEdge } from "../../../tokens/field-edge";
+import { sxRem } from "../../../tokens/relative";
+
+import type { QuickFilterConfig } from "./data-views-types";
+
+/** The count's colour: the attention the rows need, or neutral. */
+function toneColor(theme: Theme, tone: QuickFilterConfig["tone"]): string {
+  return tone ? theme.palette[tone].main : theme.palette.text.secondary;
+}
+
+/** The chip on the toolbar: pressed reads as a filled, inverted pill. */
+export function QuickChip({
+  quick,
+  active,
+  onToggle,
+  testIdPrefix,
+}: {
+  quick: QuickFilterConfig;
+  active: boolean;
+  onToggle: () => void;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onToggle}
+      aria-pressed={active}
+      data-testid={`${testIdPrefix}-quick-${quick.id}`}
+      sx={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 0.75,
+        minHeight: fieldHeight,
+        px: 1.5,
+        border: 1,
+        borderStyle: "solid",
+        borderColor: (theme: Theme) => (active ? theme.palette.text.primary : fieldEdge(theme)),
+        borderRadius: 999,
+        bgcolor: active ? "text.primary" : "background.paper",
+        color: active ? "background.paper" : "text.primary",
+        cursor: "pointer",
+        font: "inherit",
+        fontSize: sxRem(13),
+        fontWeight: 500,
+        whiteSpace: "nowrap",
+        "&:hover": { borderColor: "text.primary" },
+        "&:focus-visible": {
+          outlineWidth: sxRem(2),
+          outlineStyle: "solid",
+          outlineColor: "primary.main",
+          // Inset, as the scope tabs draw theirs: the chip is the bar's full
+          // field height, and an outset ring is clipped above and below.
+          outlineOffset: sxRem(-2),
+        },
+      }}
+    >
+      {quick.label}
+      {quick.count !== undefined && (
+        <Box
+          component="span"
+          sx={{
+            fontWeight: 400,
+            fontVariantNumeric: "tabular-nums",
+            color: (theme: Theme) => (active ? "inherit" : toneColor(theme, quick.tone)),
+            opacity: active ? 0.75 : 1,
+          }}
+        >
+          {quick.count}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/** The same chip inside "Mais": a toggle row, label and count. */
+export function QuickRow({
+  quick,
+  active,
+  onToggle,
+  testIdPrefix,
+}: {
+  quick: QuickFilterConfig;
+  active: boolean;
+  onToggle: () => void;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="label"
+      data-testid={`${testIdPrefix}-more-quick-${quick.id}`}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 0.25,
+        pr: 1,
+        minHeight: fieldHeight,
+        cursor: "pointer",
+        fontSize: sxRem(13),
+        color: active ? "primary.main" : "text.primary",
+      }}
+    >
+      <Checkbox
+        size="small"
+        checked={active}
+        onChange={onToggle}
+        inputProps={{ "aria-label": quick.label }}
+      />
+      <Box component="span" sx={{ flex: 1 }}>
+        {quick.label}
+      </Box>
+      {quick.count !== undefined && (
+        <Box
+          component="span"
+          sx={{ fontVariantNumeric: "tabular-nums", color: (theme: Theme) => toneColor(theme, quick.tone) }}
+        >
+          {quick.count}
+        </Box>
+      )}
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-quick-types.ts

@@ -0,0 +1,33 @@
+/**
+ * The quick-chip model, split from `data-views-types` at the file-size gate.
+ */
+
+/**
+ * A ONE-CLICK FILTER: a toggle chip on the toolbar that applies one value of a
+ * declared pill field.
+ *
+ * A pill is two clicks — open it, tick a value — which is right for a facet
+ * with many values and wrong for the one question a page exists to answer
+ * ("what is empty on the shelf?"). The chip writes the SAME state a pill would
+ * (`pills[fieldId] = [value]`), so the URL, saved views, the active count and
+ * "Limpar" treat it as the filter it is; the field it targets is not drawn as a
+ * pill anywhere, the chips stand in for it. Chips sharing a `fieldId` are
+ * mutually exclusive, and pressing the pressed chip clears it.
+ *
+ * Chips are on the overflow ladder like every control: they keep the bar ahead
+ * of idle pills, and on a row too narrow for them they move into "Mais" as a
+ * toggle rather than scrolling the bar sideways.
+ */
+export interface QuickFilterConfig {
+  /** Stable id, for the test id and the React key. */
+  id: string;
+  label: string;
+  /** The pill field this chip writes to. Declare it in `fields` too. */
+  fieldId: string;
+  /** The single value the chip applies. */
+  value: string;
+  /** How many rows the chip would show, when the host knows. */
+  count?: number;
+  /** Colours the count: what kind of attention the rows need. */
+  tone?: "error" | "warning" | "info" | "success";
+}

package/src/components/data-display/DataViews/data-views-range-types.ts

@@ -60,6 +60,8 @@ interface RangeFieldBase {
    * field to suppress the defaults.
    */
   presets?: RangePreset[];
+  /** Never on the bar — always behind "Mais". See `FilterFieldConfig.inMore`. */
+  inMore?: boolean;
 }
 
 /** "Filter by amount": price, stock, margin, order total. */

package/src/components/data-display/DataViews/data-views-shell-toolbar.tsx

@@ -12,28 +12,11 @@ import { GridToolbar } from "./data-views-toolbar";
 import type { RowAction } from "./data-views-types";
 import type { DataViewsController } from "./use-data-views-state";
 
-/**
- * The toolbar band, fed from the controller. Split out of `GridShell` for that
- * function's size budget — it is ~25 props of pure forwarding and nothing else.
- */
-export function ShellToolbar<T extends Record<string, unknown>>({
-  c,
-  rows,
-  testIdPrefix,
-  rowActions,
-  bulkActions,
-  selectionExtra,
-  allOnPageSelected,
-  toolbarRightSlot,
-  showInline,
-  compactControls,
-  counterHidden,
-  sortKinds,
-  displayView,
-  exportConfig,
-  filterControls,
-  barRef,
-}: {
+/** What the shell hands the toolbar band. */
+interface ShellToolbarProps<T extends Record<string, unknown>> {
+
+  /** Pin the band to the top of the page's scroll area. */
+  sticky?: boolean;
   c: DataViewsController<T>;
   rows: T[];
   testIdPrefix: string;
@@ -55,7 +38,31 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   compactControls?: boolean;
   /** Step 5, last resort: drop the counter so the row still fits one line. */
   counterHidden?: boolean;
-}): React.JSX.Element {
+}
+
+/**
+ * The toolbar band, fed from the controller. Split out of `GridShell` for that
+ * function's size budget — it is ~25 props of pure forwarding and nothing else.
+ */
+export function ShellToolbar<T extends Record<string, unknown>>({
+  c,
+  rows,
+  testIdPrefix,
+  rowActions,
+  bulkActions,
+  selectionExtra,
+  allOnPageSelected,
+  toolbarRightSlot,
+  showInline,
+  compactControls,
+  counterHidden,
+  sortKinds,
+  displayView,
+  exportConfig,
+  filterControls,
+  barRef,
+  sticky = false,
+}: ShellToolbarProps<T>): React.JSX.Element {
   const columnOptions: ColumnVisibilityOption[] = c.hideableColumns.map((col) => ({
     id: col.id,
     label: col.label,
@@ -69,6 +76,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
       exportConfig={exportConfig}
       filterControls={filterControls}
       barRef={barRef}
+      sticky={sticky}
       compactControls={compactControls}
       counterHidden={counterHidden}
       testIdPrefix={testIdPrefix}

package/src/components/data-display/DataViews/data-views-sticky-head.ts

@@ -0,0 +1,132 @@
+"use client";
+
+/**
+ * THE TABLE HEADER THAT FOLLOWS THE PAGE — for `stickyToolbar`.
+ *
+ * `position: sticky` cannot do this job. A sticky cell sticks inside its
+ * nearest scroll container, and the table's is its own wrapper: it scrolls
+ * SIDEWAYS (`overflow-x: auto`, so a wide table is never squeezed), which
+ * makes it a scroll container on both axes, and it never scrolls vertically —
+ * the page does. So the header would stick to a box that never moves. Taking
+ * the sideways scroll away to let it stick would trade one defect for another:
+ * columns clipped or crushed on every narrow screen.
+ *
+ * Instead the header cells are TRANSLATED down by however far the page has
+ * scrolled the table's top past the sticky toolbar's bottom edge, clamped so
+ * the header never leaves its own table. The translation stays inside the
+ * table's box, so the wrapper's overflow clips nothing.
+ *
+ * Driven by the page's scroll (any scroller: a capturing listener on `window`
+ * hears every element's scroll event) and by resizes, one frame at a time.
+ */
+import { useEffect, type RefObject } from "react";
+
+/** The attribute the shell root carries, so the head can find its own toolbar. */
+export const SHELL_ATTR = "data-dv-shell";
+/** The attribute the sticky toolbar carries. */
+export const STICKY_BAR_ATTR = "data-dv-sticky-bar";
+/** Spread on the shell root. */
+export const SHELL_PROPS = { [SHELL_ATTR]: "" };
+
+/** How far the header must move down to sit under `edge` (px), inside its table. */
+export function headShift(tableTop: number, tableHeight: number, headHeight: number, edge: number): number {
+  return Math.max(0, Math.min(edge - tableTop, tableHeight - headHeight));
+}
+
+/** The top edge the header slides under: the sticky toolbar's bottom, else the viewport's top. */
+function stickyEdge(wrapper: HTMLElement): number {
+  const bar = wrapper.closest(`[${SHELL_ATTR}]`)?.querySelector<HTMLElement>(`[${STICKY_BAR_ATTR}]`);
+  return bar ? bar.getBoundingClientRect().bottom : 0;
+}
+
+/** The element whose scrolling moves the page under the bar: the nearest scrolling ancestor. */
+function scrollParent(element: HTMLElement): HTMLElement | null {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    const { overflowY } = getComputedStyle(node);
+    if (overflowY === "auto" || overflowY === "scroll") return node;
+  }
+  return null;
+}
+
+/**
+ * Stick the toolbar to the VISIBLE top of its scroll area.
+ *
+ * `top: 0` sticks to the scroll container's content edge, which sits inside
+ * its padding: a main pane padded 24px held the bar 24px below the app bar,
+ * with rows showing through the gap above it. The bar's `top` is therefore
+ * the negative of that padding, read from the live layout (the shell does not
+ * know which pane it is in, nor what padding the host gave it).
+ */
+export function useStickyBarTop(ref: RefObject<HTMLElement | null>, enabled: boolean): void {
+  useEffect(() => {
+    const shell = ref.current;
+    const bar = shell?.querySelector<HTMLElement>(`[${STICKY_BAR_ATTR}]`);
+    if (!enabled || !shell || !bar) return undefined;
+    const apply = (): void => {
+      const parent = scrollParent(bar);
+      // The host's own computed length, passed through — never one of ours.
+      bar.style.top = parent ? `calc(-1 * ${getComputedStyle(parent).paddingTop})` : "";
+    };
+    apply();
+    window.addEventListener("resize", apply);
+    return () => {
+      window.removeEventListener("resize", apply);
+      bar.style.top = "";
+    };
+  }, [ref, enabled]);
+}
+
+/** Move every header cell down by `shift` px (0 puts them back), above the rows they cover. */
+export function paint(head: HTMLElement, shift: number): void {
+  // A measured offset, so a matrix rather than a design length. No DOMMatrix
+  // (jsdom), no translation: the header simply stays in the table.
+  const transform =
+    shift > 0 && typeof DOMMatrixReadOnly !== "undefined"
+      ? new DOMMatrixReadOnly().translate(0, shift).toString()
+      : "";
+  head.querySelectorAll<HTMLElement>("th").forEach((cell) => {
+    cell.style.transform = transform;
+    // Above the rows it now covers, below the toolbar (z-index 3).
+    cell.style.zIndex = transform ? "2" : "";
+  });
+}
+
+/** Translate the header cells of the table inside `ref` so they follow the page. */
+export function useStickyTableHead(ref: RefObject<HTMLElement | null>, enabled: boolean): void {
+  useEffect(() => {
+    const wrapper = ref.current;
+    if (!enabled || !wrapper) return undefined;
+    let frame = 0;
+    const apply = (): void => {
+      frame = 0;
+      const table = wrapper.querySelector("table");
+      const head = table?.querySelector("thead");
+      if (!table || !head) return;
+      const box = table.getBoundingClientRect();
+      const shift = headShift(box.top, box.height, head.getBoundingClientRect().height, stickyEdge(wrapper));
+      paint(head, shift);
+    };
+    const schedule = (): void => {
+      if (frame === 0) frame = requestAnimationFrame(apply);
+    };
+    window.addEventListener("scroll", schedule, { capture: true, passive: true });
+    window.addEventListener("resize", schedule);
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    observer?.observe(wrapper);
+    // A header cell added while scrolled (a column shown from "Exibir") must
+    // follow too, not wait for the next scroll.
+    const mutations = typeof MutationObserver === "undefined" ? null : new MutationObserver(schedule);
+    mutations?.observe(wrapper, { childList: true, subtree: true });
+    schedule();
+    return () => {
+      window.removeEventListener("scroll", schedule, { capture: true });
+      window.removeEventListener("resize", schedule);
+      observer?.disconnect();
+      mutations?.disconnect();
+      if (frame !== 0) cancelAnimationFrame(frame);
+      // Turned off mid-scroll: the header goes back where it belongs.
+      const head = wrapper.querySelector("thead");
+      if (head) paint(head, 0);
+    };
+  }, [ref, enabled]);
+}

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

@@ -18,6 +18,7 @@ import { renderBulkActions } from "./data-views-grid-helpers";
 import type { RowAction } from "./data-views-types";
 import type { DataViewsController } from "./use-data-views-state";
 import { sxRem } from "../../../tokens/relative";
+import { STICKY_BAR_ATTR } from "./data-views-sticky-head";
 
 export interface GridToolbarProps<T extends Record<string, unknown>> {
   testIdPrefix: string;
@@ -72,6 +73,12 @@ export interface GridToolbarProps<T extends Record<string, unknown>> {
    * line instead of spilling outside the toolbar.
    */
   counterHidden?: boolean;
+  /**
+   * Pin the band to the top of the page's scroll area (`stickyToolbar`). It
+   * takes the page background so rows scrolling under it do not show through,
+   * and sits above the table header that follows it (`useStickyTableHead`).
+   */
+  sticky?: boolean;
 }
 
 /** The right-aligned toolbar controls: Sort By, the counter, zoom/layout/columns, filters. */
@@ -147,7 +154,9 @@ export function GridToolbar<T extends Record<string, unknown>>(props: GridToolba
   return (
     <Box
       ref={props.barRef}
+      {...(props.sticky ? { [STICKY_BAR_ATTR]: "" } : {})}
       sx={{
+        ...(props.sticky && { position: "sticky", top: 0, zIndex: 3, bgcolor: "background.default" }),
         borderTop: 1,
         borderBottom: 1,
         borderColor: "divider",

package/src/components/data-display/DataViews/data-views-types.ts

@@ -137,21 +137,17 @@ export interface FilterFieldConfig<T extends Record<string, unknown>> {
    * its values is selected. Defaults to `String(row[id])`.
    */
   accessor?: (row: T) => string | string[];
+  /** Never on the bar, always behind "Mais" (beside quick chips); still counted, saved, cleared. */
+  inMore?: boolean;
 }
 
 /**
- * The range types live in `data-views-range-types` (this file outgrew the
- * size gate); they are re-exported here so `data-views-types` stays the one
- * name every consumer imports the model from.
+ * The range and quick-chip types live in their own modules (this file outgrew
+ * the size gate); re-exported so `data-views-types` stays the one import.
  */
-export type {
-  DayRangeFieldConfig,
-  NumberRangeFieldConfig,
-  RangeFieldConfig,
-  RangeFieldKind,
-  RangePreset,
-  RangeValue,
-} from "./data-views-range-types";
+export type { QuickFilterConfig } from "./data-views-quick-types";
+export type { DayRangeFieldConfig, NumberRangeFieldConfig, RangeFieldConfig } from "./data-views-range-types";
+export type { RangeFieldKind, RangePreset, RangeValue } from "./data-views-range-types";
 
 /** A grid column that can join the search scan and the column-visibility menu. */
 export interface DataViewColumn<T extends Record<string, unknown>> extends GridColumn<T> {

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

@@ -62,6 +62,7 @@ export type {
   DataViewsLayout,
   DataViewColumn,
   FilterFieldConfig,
+  QuickFilterConfig,
   RangeFieldConfig,
   RangeFieldKind,
   RangeValue,

package/src/components/feedback/StackedModal/StackedModal.md

@@ -138,6 +138,7 @@ new component that portals should too.
 | `fullScreen` | `boolean` | `false` | Full screen mode |
 | `maxWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| false` | `'md'` | Maximum modal width |
 | `size` | `'default' \| 'wide'` | `'default'` | Viewport share of the top panel: default is 80vw (`sm`–`lg`), 60vw (`lg`+), 40vw (≥2200px); `wide` is 90vw up to `xl`, 75vw above, 60vw ≥2200px — for a dense two-column editor |
+| `panelWidth` | `{ share: string; maxPx: number; fullBelowPx?: number }` | - | An exact width for the top panel: `min(share, maxPx)` of the viewport, the whole screen under `fullBelowPx`. Replaces `size` and `maxWidth`. Viewport only — nothing inside the panel feeds back into it |
 | `disableBackdrop` | `boolean` | `false` | Hide backdrop |
 | `disableFocusTrap` | `boolean` | `false` | Disable focus trapping |
 | `keepMounted` | `boolean` | `false` | Keep modal mounted when closed |

package/src/components/feedback/StackedModal/StackedModal.styles.ts

@@ -3,7 +3,7 @@ import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 import { scrim } from '../../../tokens/ink';
 import { rem } from '../../../tokens/relative';
 import { dynamicViewportHeight } from '../../../utils/viewport';
-import type { ModalPanelRole, PanelMaxWidth, PanelSize } from './StackedModal.types';
+import type { ModalPanelRole, PanelMaxWidth, PanelSize, PanelWidth } from './StackedModal.types';
 
 /** Props that drive the panel's look but must not reach the DOM. */
 export interface PanelStyleProps {
@@ -13,10 +13,11 @@ export interface PanelStyleProps {
   rtl?: boolean;
   customMaxWidth?: PanelMaxWidth;
   panelSize?: PanelSize;
+  panelWidth?: PanelWidth;
 }
 
 /** Style-only props, filtered out before they can land on a DOM node. */
-export const STYLE_ONLY_PROPS = ['modalRole', 'isAnimating', 'glass', 'rtl', 'customMaxWidth', 'panelSize'];
+export const STYLE_ONLY_PROPS = ['modalRole', 'isAnimating', 'glass', 'rtl', 'customMaxWidth', 'panelSize', 'panelWidth'];
 
 /** MUI breakpoint names mapped to the pixel width they cap the panel at. */
 const MAX_WIDTH_PX: Record<Exclude<PanelMaxWidth, false>, number> = {
@@ -38,6 +39,15 @@ const ANIMATION_BY_ROLE: Partial<Record<ModalPanelRole, string>> = {
   primary: 'contractModal 300ms ease-in-out forwards',
 };
 
+/** The custom property an exact-width panel's width and keyframes share. */
+const EXACT_WIDTH_VAR = '--stacked-modal-width';
+
+/** An exact-width panel settles at its own width, so its keyframes read it too. */
+const EXACT_ANIMATION_BY_ROLE: Partial<Record<ModalPanelRole, string>> = {
+  secondary: 'expandModalExact 300ms ease-in-out forwards',
+  primary: 'contractModalExact 300ms ease-in-out forwards',
+};
+
 /** A wide panel settles at 90vw, so its keyframes must end there too, or it snaps. */
 const WIDE_ANIMATION_BY_ROLE: Partial<Record<ModalPanelRole, string>> = {
   secondary: 'expandModalWide 300ms ease-in-out forwards',
@@ -63,6 +73,15 @@ const KEYFRAMES: CSSObject = {
     from: { width: '100vw', transform: 'translateX(0)' },
     to: { width: '90vw', transform: 'translateX(0)' },
   },
+  // An exact-width panel settles at its own width, carried by the custom property.
+  '@keyframes expandModalExact': {
+    from: { width: `var(${EXACT_WIDTH_VAR})`, transform: 'translateX(0)' },
+    to: { width: '100vw', transform: 'translateX(0)' },
+  },
+  '@keyframes contractModalExact': {
+    from: { width: '100vw', transform: 'translateX(0)' },
+    to: { width: `var(${EXACT_WIDTH_VAR})`, transform: 'translateX(0)' },
+  },
 };
 
 const cap = (customMaxWidth?: PanelMaxWidth): number | null =>
@@ -106,6 +125,22 @@ const widePrimaryPanelStyles = (theme: Theme, capPx: number | null): CSSObject =
   [theme.breakpoints.up(2200)]: panelWidth(theme, '60vw', capPx),
 });
 
+/**
+ * `panelWidth`: `min(share, maxPx)` from `sm` up, the whole screen under `sm`
+ * and under `fullBelowPx`. Viewport media queries only — never the panel's size.
+ */
+const exactPrimaryPanelStyles = (theme: Theme, exact: PanelWidth): CSSObject => {
+  const width = `min(${exact.share}, ${rem(theme, exact.maxPx)})`;
+  const full = { [EXACT_WIDTH_VAR]: '100%', width: '100%', maxWidth: '100%' };
+  return {
+    [EXACT_WIDTH_VAR]: width,
+    width: `var(${EXACT_WIDTH_VAR})`,
+    maxWidth: `var(${EXACT_WIDTH_VAR})`,
+    [theme.breakpoints.down('sm')]: full,
+    ...(exact.fullBelowPx ? { [theme.breakpoints.down(exact.fullBelowPx)]: full } : {}),
+  };
+};
+
 /** Panels below the top one expand to full width, producing the GTM stacking effect. */
 const secondaryPanelStyles = (): CSSObject => ({
   width: '100vw !important',
@@ -123,8 +158,10 @@ const rolePanelStyles = (
   role: ModalPanelRole | undefined,
   capPx: number | null,
   size?: PanelSize,
+  exact?: PanelWidth,
 ): CSSObject => {
   if (role === 'primary') {
+    if (exact) return exactPrimaryPanelStyles(theme, exact);
     return size === 'wide' ? widePrimaryPanelStyles(theme, capPx) : primaryPanelStyles(theme, capPx);
   }
   if (role === 'secondary') return secondaryPanelStyles();
@@ -143,8 +180,18 @@ const glassStyles = (theme: Theme, glass?: boolean, role?: ModalPanelRole): CSSO
       }
     : {};
 
-const animationStyles = (isAnimating?: boolean, role?: ModalPanelRole, size?: PanelSize): CSSObject => {
-  const byRole = size === 'wide' ? WIDE_ANIMATION_BY_ROLE : ANIMATION_BY_ROLE;
+const animationByRole = (size?: PanelSize, exact?: PanelWidth): Partial<Record<ModalPanelRole, string>> => {
+  if (exact) return EXACT_ANIMATION_BY_ROLE;
+  return size === 'wide' ? WIDE_ANIMATION_BY_ROLE : ANIMATION_BY_ROLE;
+};
+
+const animationStyles = (
+  isAnimating?: boolean,
+  role?: ModalPanelRole,
+  size?: PanelSize,
+  exact?: PanelWidth,
+): CSSObject => {
+  const byRole = animationByRole(size, exact);
   return isAnimating ? { animation: (role && byRole[role]) ?? 'none' } : {};
 };
 
@@ -169,9 +216,9 @@ const panelStyles = (theme: Theme, props: PanelStyleProps): CSSObject => {
   const capPx = cap(props.customMaxWidth);
   return {
     ...panelBaseStyles(theme),
-    ...rolePanelStyles(theme, props.modalRole, capPx, props.panelSize),
+    ...rolePanelStyles(theme, props.modalRole, capPx, props.panelSize, props.panelWidth),
     ...glassStyles(theme, props.glass, props.modalRole),
-    ...animationStyles(props.isAnimating, props.modalRole, props.panelSize),
+    ...animationStyles(props.isAnimating, props.modalRole, props.panelSize, props.panelWidth),
   };
 };
 

package/src/components/feedback/StackedModal/StackedModal.tsx

@@ -79,7 +79,7 @@ const useUnnamedDialogWarning = (unnamed: boolean): void => {
 const StackedModalPanel: FC<ResolvedProps> = (props) => {
   const {
     open, onClose, glass, navigationTitle, backLabel, hideClose, hideHeader, children, actions, modalId,
-    closeOnClickOutside, closeOnEsc, loading, loadingText, fullScreen, maxWidth, size, disableBackdrop,
+    closeOnClickOutside, closeOnEsc, loading, loadingText, fullScreen, maxWidth, size, panelWidth, disableBackdrop,
     disableFocusTrap, keepMounted, rtl, dataTestId,
     'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, ...otherProps
   } = props;
@@ -114,6 +114,7 @@ const StackedModalPanel: FC<ResolvedProps> = (props) => {
       rtl={rtl}
       customMaxWidth={maxWidth}
       panelSize={size}
+      panelWidth={panelWidth}
       TransitionComponent={SlideTransition}
       maxWidth={maxWidth}
       disableEscapeKeyDown={!closeOnEsc}

package/src/components/feedback/StackedModal/StackedModal.types.ts

@@ -12,6 +12,21 @@ export type PanelMaxWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
  * 60vw starves on a laptop.
  */
 export type PanelSize = 'default' | 'wide';
+/**
+ * An exact width for the top panel, for a screen whose owner set one: the
+ * panel takes `min(share, maxPx)` of the viewport, and the whole screen when
+ * the viewport is narrower than `fullBelowPx`. It replaces `size` and
+ * `maxWidth`. Everything here reads the VIEWPORT, never the panel, so nothing
+ * inside the panel can feed back into the width that laid it out.
+ */
+export interface PanelWidth {
+  /** The viewport share, as a CSS length (`'72vw'`). */
+  share: string;
+  /** The cap, in px; converted to rem like every other size here. */
+  maxPx: number;
+  /** Under this viewport width (px) the panel takes the whole screen. */
+  fullBelowPx?: number;
+}
 
 export interface StackedModalProps {
   /** The back arrow's accessible name — it carries a glyph only. REQUIRED. */
@@ -64,6 +79,8 @@ export interface StackedModalProps {
   maxWidth?: PanelMaxWidth;
   /** Viewport share of the top panel — `wide` gives a dense editor more room */
   size?: PanelSize;
+  /** An exact width for the top panel; replaces `size` and `maxWidth` (see `PanelWidth`). */
+  panelWidth?: PanelWidth;
   /** Disable the backdrop click behavior */
   disableBackdrop?: boolean;
   /** Disable focus trap functionality */

package/src/components/feedback/StackedModal/index.ts

@@ -8,4 +8,4 @@ export {
   useModalStack as useStackedModal,
 } from './StackedModal';
 
-export type { PanelSize, StackedModalProps } from './StackedModal.types';
+export type { PanelSize, PanelWidth, StackedModalProps } from './StackedModal.types';

package/src/components/navigation/Tabs/Tabs.md

@@ -50,6 +50,7 @@ The Tabs component provides an intuitive way to organize related content into se
 | `content`  | `ReactNode` | Yes      | Content to display in panel         |
 | `icon`     | `ReactNode` | No       | Icon to display before label        |
 | `badge`    | `string \| number` | No | Badge content (notification count)  |
+| `count`    | `{ value: string \| number; tone?: 'neutral' \| 'warning' \| 'danger' }` | No | A count said inside the tab, after its label, as a small pill (lines, events, charges); `tone` marks one asking for action |
 | `disabled` | `boolean`   | No       | Whether tab is disabled             |
 | `closable` | `boolean`   | No       | Whether tab can be closed           |
 | `className`| `string`    | No       | Custom CSS class for the tab        |