@juwel-development/design-system 3.10.0 → 4.0.0

package/src/Display/Table/Table.tsx

@@ -2,6 +2,7 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import {
   type CSSProperties,
+  type FocusEvent,
   type FunctionComponent,
   type KeyboardEvent,
   type MouseEvent,
@@ -14,35 +15,45 @@ import type { Observable, Subject } from 'rxjs';
 import { TableConfigurationError } from './TableConfigurationError';
 
 // Rules are the layout. One recipe styles the whole table from its wrapper, so the block reads as a
-// table from two rule weights and nothing else: no cell borders, no fill, no zebra, no hover. Colours
+// table from two rule weights and nothing else: no cell borders, no default fill, no zebra, no hover. Colours
 // are semantic tokens re-pointed by `.dark`, so no selector carries a `dark:` class. The responsive
 // behaviour is keyed on the wrapper's `data-notes`, so a server renders the right markup with no
 // hydration and the mode is one attribute a stylesheet and a test can both read.
 const DEFAULT_DENSITY = 'comfortable';
+const DEFAULT_SELECTION_TREATMENT = 'marker';
 
 const table = cva(
   [
     // Residual horizontal overflow scrolls in every mode (#114); the scroll sits on the wrapper so
     // the table keeps its table formatting context and the figures stay column-aligned. No vertical
-    // bound: a long table is bounded by the ScrollContainer a consumer puts around it.
+    // bound unless bounded is requested; then this same wrapper owns both axes.
     'overflow-x-auto',
+    // Content-sized actions need room at both scroll edges, including static rows. The outer
+    // inset also protects rings above/below compact cells without changing the row height.
+    '[&[data-icon-actions]]:p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    '[&[data-icon-actions]]:m-[calc(-1*(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+    '[&[data-icon-actions]]:scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    // Overflowing grid tracks extend beyond the table border box; wrapper padding alone does not
+    // survive at that trailing scroll edge. Keep ring room inside the outer cells as well.
+    '[&[data-icon-actions]>table>*>tr>*:first-child]:pl-[max(var(--table-cell-padding-inline),calc(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+    '[&[data-icon-actions]>table>*>tr>*:last-child]:pr-[max(var(--table-cell-padding-inline),calc(var(--focus-ring-width)+var(--focus-ring-offset)))]',
     // The wrapper takes the one focus ring when it is keyboard-reachable - docs/adr/0002.
     'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
     // The table: full width, collapsed borders so adjacent row rules meet as one line, text flush left.
     '[&>table]:w-full [&>table]:border-collapse [&>table]:text-left',
     // The required caption, rendered first, as the table's label in the tracked grotesk device.
-    '[&_caption]:pb-3 [&_caption]:text-left [&_caption]:font-secondary [&_caption]:text-label [&_caption]:tracking-label [&_caption]:text-muted',
+    '[&_caption]:text-left [&_caption]:font-secondary [&_caption]:text-label [&_caption]:tracking-label [&_caption]:text-muted',
     // Every row carries a hairline top (Row); the first row - the first row group after the caption -
     // is promoted to the heavier `rule` colour, and that heavier line is what reads as a table not a list.
     '[&>table>*:nth-child(2)>tr:first-child]:border-rule',
     // notes="supplementary": the note column leaves the page for everyone, sighted or not, below 48rem.
     // Every narrow-viewport rule is off once an allocation is declared (#115): a declared comparison
     // keeps all of its columns and tabular rows, and the residual overflow scrolls instead.
-    '[&[data-notes=supplementary]:not([data-columns])_[data-variant=note]]:max-md:hidden',
+    '[&[data-notes=supplementary]:not([data-columns]):not([data-bounded])_[data-variant=note]]:max-md:hidden',
     // notes="content": the note is the content, so each row stacks into a single column below 48rem.
-    '[&[data-notes=content]:not([data-columns])>table]:max-md:block',
-    '[&[data-notes=content]:not([data-columns])_thead]:max-md:block [&[data-notes=content]:not([data-columns])_tbody]:max-md:block [&[data-notes=content]:not([data-columns])_tfoot]:max-md:block',
-    '[&[data-notes=content]:not([data-columns])_tr]:max-md:block [&[data-notes=content]:not([data-columns])_td]:max-md:block [&[data-notes=content]:not([data-columns])_th]:max-md:block',
+    '[&[data-notes=content]:not([data-columns]):not([data-bounded])>table]:max-md:block',
+    '[&[data-notes=content]:not([data-columns]):not([data-bounded])_thead]:max-md:block [&[data-notes=content]:not([data-columns]):not([data-bounded])_tbody]:max-md:block [&[data-notes=content]:not([data-columns]):not([data-bounded])_tfoot]:max-md:block',
+    '[&[data-notes=content]:not([data-columns]):not([data-bounded])_tr]:max-md:block [&[data-notes=content]:not([data-columns]):not([data-bounded])_td]:max-md:block [&[data-notes=content]:not([data-columns]):not([data-bounded])_th]:max-md:block',
     // A declared allocation (#115) lays the table out as a grid whose tracks are the allocation, each
     // row group and row a column subgrid of it, so every cell sits on boundaries no row's content can
     // move and the browser's track algorithm does the floors and the redistribution. Rows stay boxes,
@@ -64,11 +75,24 @@ const table = cva(
     // margin hands the room back to the page, so the ring sits outside the row and never covers the
     // marker at its leading edge. Written from the two ring tokens so it cannot drift from the ring.
     '[&:has(tr[tabindex])]:p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
-    '[&:has(tr[tabindex])]:m-[calc(-1*(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+    '[&:not([data-bounded]):has(tr[tabindex])]:m-[calc(-1*(var(--focus-ring-width)+var(--focus-ring-offset)))]',
     '[&:has(tr[tabindex])]:scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
   ].join(' '),
   {
     variants: {
+      bounded: {
+        true: 'max-h-full min-h-0 min-w-0 overflow-y-auto overscroll-contain p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] [&>table>thead]:sticky [&>table>thead]:top-0 [&>table>thead]:z-10 [&>table>thead]:bg-surface [&>table>thead>tr>*]:bg-surface',
+        false: '',
+      },
+      selectionTreatment: {
+        marker: '',
+        highlight:
+          '[&>table>*>tr[aria-selected=true]]:bg-selected-surface [&>table>*>tr[aria-selected=true]]:[--color-error:var(--color-selected-error)]',
+      },
+      captionVisibility: {
+        visible: '[&>table>caption]:pb-3',
+        hidden: '[&>table>caption]:sr-only',
+      },
       // Density publishes the two cell insets the cells read, so head and body move together and the
       // theme's comfortable or compact pair is the only source (docs/adr/0008, Amendments, #115).
       density: {
@@ -78,7 +102,11 @@ const table = cva(
           '[--table-cell-padding-inline:var(--table-cell-inset-inline-compact)] [--table-cell-padding-block:var(--table-cell-inset-block-compact)]',
       },
     },
-    defaultVariants: { density: DEFAULT_DENSITY },
+    defaultVariants: {
+      density: DEFAULT_DENSITY,
+      captionVisibility: 'visible',
+      selectionTreatment: DEFAULT_SELECTION_TREATMENT,
+    },
   },
 );
 
@@ -185,6 +213,12 @@ type TableColumnWidthRole = 'name' | 'fact' | 'figure' | 'action';
  * optional named minimum as its floor. Declared once on `Table.Root`, in cell order.
  */
 export type TableColumnAllocation =
+  | {
+      /** Fits the widest rendered action group, without sharing surplus width. */
+      readonly width: 'icon-action';
+      readonly weight?: never;
+      readonly minWidth?: never;
+    }
   | {
       /** The role whose width this column takes exactly, at any available width. */
       readonly width: TableColumnWidthRole;
@@ -212,6 +246,7 @@ const widthOf = (role: TableColumnWidthRole): string =>
 // One grid track per definition: a fixed role, floored by max() when it has a minimum so it holds at
 // any width; a share as minmax(floor, weight fr), which is the browser's own floor-and-redistribute.
 const trackOf = (column: TableColumnAllocation, index: number): string => {
+  if (column.width === 'icon-action') return 'max-content';
   const minimum =
     column.minWidth === undefined ? undefined : widthOf(column.minWidth);
   if (column.width !== undefined) {
@@ -234,13 +269,15 @@ const trackListOf = (
     : columns.map(trackOf).join(' ');
 
 export interface ITableRootProps extends VariantProps<typeof table> {
+  /** Opt into parent-bounded scrolling on both axes with a pinned header; short tables keep natural height. */
+  bounded?: boolean;
   /** The table's accessible name. Rendered as the first child; always present. */
   caption: string;
   /** What the note column is. Governs narrow-viewport behaviour; omit when there is none. */
   notes?: 'supplementary' | 'content';
   /** The columns' allocations, in the order the cells of every row are written. Omit it and widths
    *  follow content as before; declare it and every row shares one allocation the rows' content
-   *  cannot move, and the narrow-viewport `notes` behaviour is replaced by residual scrolling. */
+   *  cannot move (except content-sized `icon-action` tracks), and the narrow-viewport `notes` behaviour is replaced by residual scrolling. */
   columns?: readonly TableColumnAllocation[];
   children?: ReactNode;
   testId?: string;
@@ -283,42 +320,104 @@ export interface ITableHeaderCellProps
 // (WCAG 2.1.1): reachable until measured, so server markup is operable before hydration, and while
 // it holds focus, since dropping tabindex from the focused element relocates it. The table and the
 // caption are observed too: under an allocation the caption, spanning every track, is what grows.
-const useHorizontalOverflow = (
+const useOverflow = (
   wrapper: { current: HTMLElement | null },
   table: { current: HTMLElement | null },
   caption: { current: HTMLElement | null },
+  bounded: boolean,
 ): boolean => {
   const [isOverflowing, setIsOverflowing] = useState(true);
   useLayoutEffect(() => {
     const element = wrapper.current;
     if (element === null) return;
-    const measure = () =>
+    const measure = () => {
+      // WebKit may perform native focus scrolling after focus handlers; scroll padding keeps
+      // that second movement below even a wrapped header, rather than undoing focus reveal.
+      if (bounded) {
+        const headerHeight =
+          table.current?.querySelector('thead')?.getBoundingClientRect()
+            .height ?? 0;
+        const ringRoom =
+          Number.parseFloat(getComputedStyle(element).paddingTop) || 0;
+        element.style.scrollPaddingTop = `${headerHeight + 2 * ringRoom}px`;
+      }
       setIsOverflowing(
         element.scrollWidth > element.clientWidth ||
+          (bounded && element.scrollHeight > element.clientHeight) ||
           element === document.activeElement,
       );
+    };
     measure();
     const observer =
       typeof ResizeObserver === 'undefined'
         ? undefined
         : new ResizeObserver(measure);
     observer?.observe(element);
-    for (const observed of [table.current, caption.current]) {
+    for (const observed of [
+      table.current,
+      caption.current,
+      table.current?.querySelector('thead') ?? null,
+    ]) {
       if (observed !== null) observer?.observe(observed);
     }
+    const mutations = new MutationObserver(measure);
+    mutations.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
     window.addEventListener('resize', measure);
     element.addEventListener('blur', measure);
     return () => {
       observer?.disconnect();
+      mutations.disconnect();
+      if (bounded) element.style.removeProperty('scroll-padding-top');
       window.removeEventListener('resize', measure);
       element.removeEventListener('blur', measure);
     };
-  }, [wrapper, table, caption]);
+  }, [wrapper, table, caption, bounded]);
   return isOverflowing;
 };
 
+const revealFocus = (event: FocusEvent<HTMLDivElement>): void => {
+  const wrapper = event.currentTarget;
+  const target = event.target;
+  if (target === wrapper) return;
+  const bounds = wrapper.getBoundingClientRect();
+  const header = wrapper.querySelector(':scope > table > thead');
+  const targetBounds = target.getBoundingClientRect();
+  const ringRoom = Number.parseFloat(getComputedStyle(wrapper).paddingTop) || 0;
+  const top =
+    bounds.top +
+    wrapper.clientTop +
+    (header?.getBoundingClientRect().height ?? 0) +
+    2 * ringRoom;
+  const bottom =
+    bounds.top + wrapper.clientTop + wrapper.clientHeight - ringRoom;
+  if (!header?.contains(target)) {
+    if (targetBounds.top < top) wrapper.scrollTop += targetBounds.top - top;
+    else if (targetBounds.bottom > bottom)
+      wrapper.scrollTop += targetBounds.bottom - bottom;
+  }
+  if (targetBounds.left < bounds.left + ringRoom)
+    wrapper.scrollLeft += targetBounds.left - bounds.left - ringRoom;
+  else if (
+    targetBounds.right >
+    bounds.left + wrapper.clientLeft + wrapper.clientWidth - ringRoom
+  )
+    wrapper.scrollLeft +=
+      targetBounds.right -
+      bounds.left -
+      wrapper.clientLeft -
+      wrapper.clientWidth +
+      ringRoom;
+};
+
 const TableRoot: FunctionComponent<ITableRootProps> = ({
   caption,
+  captionVisibility,
+  bounded,
+  selectionTreatment,
   notes,
   columns,
   density,
@@ -329,10 +428,11 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
   const tableElement = useRef<HTMLTableElement>(null);
   const captionElement = useRef<HTMLTableCaptionElement>(null);
   const trackList = trackListOf(columns);
-  const isOverflowing = useHorizontalOverflow(
+  const isOverflowing = useOverflow(
     wrapper,
     tableElement,
     captionElement,
+    bounded === true,
   );
   const style: TableRootStyle | undefined =
     trackList === undefined ? undefined : { '--table-columns': trackList };
@@ -347,13 +447,24 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
   // scrolled table is keyboard-operable - WCAG 2.1.1 needs the scroll container itself focusable,
   // there being no focusable cell content to carry it. With a note column the wrapper is a plain
   // grouping element that becomes a named, reachable group only while the table overflows it.
-  if (notes === undefined) {
+  if (notes === undefined && !bounded) {
     return (
       <section
-        className={table({ density })}
+        className={table({
+          density,
+          captionVisibility,
+          selectionTreatment,
+          bounded,
+        })}
         style={style}
         data-columns={columnCount}
+        data-icon-actions={
+          columns?.some((column) => column.width === 'icon-action') || undefined
+        }
         data-density={density ?? DEFAULT_DENSITY}
+        data-selection-treatment={
+          selectionTreatment ?? DEFAULT_SELECTION_TREATMENT
+        }
         data-testid={testId}
         aria-label={caption}
         // biome-ignore lint/a11y/noNoninteractiveTabindex: a scroll container must be keyboard-operable (WCAG 2.1.1)
@@ -365,13 +476,27 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
   }
   return (
     // biome-ignore lint/a11y/useAriaPropsSupportedByRole: the name and the `group` role are set together; biome cannot see the pair
+    // biome-ignore lint/a11y/noStaticElementInteractions: focus bubbles from descendants; this reveals their focus without adding an interaction
     <div
       ref={wrapper}
-      className={table({ density })}
+      onFocus={bounded ? revealFocus : undefined}
+      className={table({
+        density,
+        captionVisibility,
+        selectionTreatment,
+        bounded,
+      })}
       style={style}
+      data-bounded={bounded || undefined}
       data-notes={notes}
       data-columns={columnCount}
+      data-icon-actions={
+        columns?.some((column) => column.width === 'icon-action') || undefined
+      }
       data-density={density ?? DEFAULT_DENSITY}
+      data-selection-treatment={
+        selectionTreatment ?? DEFAULT_SELECTION_TREATMENT
+      }
       data-testid={testId}
       role={isOverflowing ? 'group' : undefined}
       aria-label={isOverflowing ? caption : undefined}
@@ -494,26 +619,43 @@ const TableCell: FunctionComponent<ITableCellProps> = ({
  * @Guarantees — enforced on every render
  * - Renders semantic `table`/`thead`/`tbody`/`tfoot`/`tr`/`th`/`td`, and works with JavaScript off.
  * - `Root` renders its required `caption` as the table's first child, so every table is named.
+ *   `captionVisibility` defaults to `visible`; `hidden` visually clips the caption out of flow,
+ *   including its spacing, while preserving its native accessible name and the scroll wrapper's name.
+ *   Hide it only when visible text directly above the table already names what it lists; the
+ *   enclosing arrangement owns the gap above the table. The consumer still supplies the caption.
  * - The block reads as a table from two rule weights alone: the heavier `rule` above the first row,
- *   `border` hairlines between rows, and no bottom rule on the last. No cell borders, fill, zebra or hover.
+ *   `border` hairlines between rows, and no bottom rule on the last. No cell borders, default fill, zebra or hover.
  * - `Cell variant="value"` sets tabular figures; `variant="note"` does not. Both at the 15px small role.
  * - `HeaderCell` emits the `scope` it is given; none is inferred. It emits `ariaSort` the same way:
  *   the attribute states the displayed order and the component never orders, cycles or requests one.
  * - Residual horizontal overflow scrolls in every `notes` mode, with no opt-in. The wrapper is
  *   keyboard-reachable while there is something to scroll - always, as a named region, with no note
- *   column; as a named group only once the table overflows, with one. No vertical bound is ever set:
- *   a long table sits inside a `ScrollContainer` with `axis="vertical"`, which owns that axis.
+ *   column; as a named group only once the table overflows, with one. Bounded tables instead expose
+ *   a named group and keyboard stop only while either axis overflows, retained while focused.
+ * - `bounded` makes this same wrapper own both scroll axes within the parent's allocated height.
+ *   Short tables retain natural height; unsized parents allow natural growth. Only the header pins,
+ *   on the themed surface; captions scroll normally and keep naming the table. All columns and rows
+ *   remain tabular at every width, including both notes modes. Unbounded behavior is unchanged.
+ * - Focus reveals rows and controls below the pinned header inside the wrapper. Selection updates
+ *   alone never scroll. The wrapper reserves the shared focus ring's room.
  * - `Root columns` declares every column's allocation once, in cell order, and every row shares it:
  *   a fixed column takes its named width role at any available width; proportional columns share
  *   the width the fixed ones leave by their weights, each floored at its named minimum, and while a
  *   minimum holds one column the others share what is left. A fixed width below its minimum is the
- *   minimum. Nothing a row holds moves a boundary: filtering, sorting, paging, long or short content,
+ *   minimum. Except for `icon-action`, nothing a row holds moves a boundary: filtering, sorting, paging, long or short content,
  *   an empty body and its repopulation all leave the allocation as it was. Only the definitions, the
  *   theme's `--table-column-*` values and the available width can. All-fixed columns do not stretch.
+ * - `{ width: 'icon-action' }` fits the widest rendered cell (including its header and insets),
+ *   takes no surplus width, and may shrink after filtering. Compose multiple plain icon buttons
+ *   in `Cluster gap="stack"`; max-content track sizing keeps the group on one line.
  * - With `columns` declared, no narrow-viewport rule applies whatever `notes` says: the note column
  *   stays, rows stay tabular, and what does not fit scrolls in the wrapper as above. Text wraps inside
- *   its allocation, an unbroken run included; the table never truncates, hides or resizes content.
+ *   its allocation, an unbroken run included; the table does not itself truncate, hide or resize content.
  *   Without `columns`, widths follow content and both `notes` behaviours are exactly as before.
+ * - Exception: a consumer may mark individual `P` or `Note` content with `truncate`. Only that
+ *   text stays on one line and ellipsizes at its allocated inline end, in either column layout;
+ *   its full DOM text remains accessible and does not force the table wider. Unmarked siblings
+ *   retain their wrapping/overflow behavior; fixed column widths and minimums still hold.
  * - `Root density` insets every header and body cell from one theme pair: `comfortable` (the
  *   default, the former spacing exactly) or `compact`, per table. It moves no type size and no
  *   control's own dimensions. A non-positive or non-finite `weight` throws
@@ -528,6 +670,10 @@ const TableCell: FunctionComponent<ITableCellProps> = ({
  *   emitted reads unselected; a replaced source reads unselected until it emits; unmounting
  *   unsubscribes. The selection input is independent of `onClick$`, so a row may be selected and
  *   noninteractive, interactive and unselected, or both. Rendering and selection changes emit nothing.
+ * - `Root selectionTreatment="highlight"` adds `selectedSurface` behind selected rows only;
+ *   the default `marker` preserves the former presentation. Neither treatment changes on hover.
+ *   The marker remains a border in forced colours, where backgrounds may be suppressed; selection
+ *   stays distinct from the focus outline. A nested table chooses its own treatment.
  * - The row stays a `tr` in a `table`: no grid role, no arrow-key navigation. `aria-selected` is a
  *   WAI-ARIA 1.2 state of `row` and valid here, but Chromium exposes a row's selected state only
  *   inside a `grid`, so Chrome and Edge screen readers do not announce it on these rows (accepted
@@ -538,12 +684,31 @@ const TableCell: FunctionComponent<ITableCellProps> = ({
  *   clipped by the scroll region. A table with neither keeps its static geometry exactly.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
+ * - For bounded mode supply finite usable parent height, with room for the header and readable rows.
+ *   Compose directly inside `Pane.Body scrollOwner="child"` or `Dialog.Content scrollOwner="child"`:
+ *   those holders add no scrolling. Intermediate wrappers must preserve the height allocation.
+ *   Fixed surrounding content must fit; no component promises impossible viewport fitting.
+ * - For narrow comparisons use weighted columns without minimums when the content can wrap into
+ *   their shares. Fixed widths and declared minimums retain their meaning; controls may overflow.
+ * - A theme's `selectedSurface` differs from resting/hover surfaces and keeps foreground, muted
+ *   and link/status text at 4.5:1, and the marker, rule and focus ring at 3:1.
+ *   Highlighted rows use selectedError for their error ink/fill. Other consumer-composed inks and
+ *   controls must meet their own contrast constraints against this surface too.
  * - Every row writes exactly as many cells as there are `columns`, in the same order. A row with
  *   fewer leaves tracks empty; one with more breaks onto a second line of its own row.
  * - A cell whose content cannot wrap - a `Button`, an `Input`, an image - sits in a column whose
  *   fixed width or minimum holds it: the `action` role holds one standard control at comfortable
  *   density. The allocation never widens for content, so an under-allocated control overflows its
- *   cell rather than moving its neighbours.
+ *   cell rather than moving its neighbours. The content-sized icon-action allocation is the exception.
+ * - Every icon-only Button needs an action-specific `ariaLabel`; leave its nested Icon decorative.
+ *   Prefer labelled buttons wherever there is room. No tooltip is required. Only plain buttons
+ *   inherit cell typography without increasing a single-line row's height; ghost keeps its padding.
+ * - For icon actions, theme `--space-stack` must be at least the focus width plus offset, so a ring
+ *   cannot reach its neighbour. Twice the cell block inset must hold that same ring extent
+ *   between adjacent rows. Keep line height at least one em. The wrapper
+ *   reserves ring room at scroll boundaries without changing row height.
+ * - For truncated text, provide an operable path to the full wording (for example row activation
+ *   opening the item). Truncation must not hide essential content or interactive descendants.
  * - A cell's `align` and `variant` are the consumer's as before; an allocation sets neither.
  * - Each row's `onClick$` and `isSelected$` are tied to that row's stable identity, so a reordered or
  *   temporarily removed row keeps its association. Table holds no identity, registry or policy, and

package/src/Display/Typography/Note/Note.tsx

@@ -2,15 +2,14 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 
-// The annotation device: the secondary family at the small role, because docs/adr/0004 fixes
-// --font-secondary as the face labels are set in and an annotation labels rather than reads. It
-// defaults to `foreground` where Eyebrow defaults to `muted`: Eyebrow inverts the ordinary default
-// because its device is defined as muted, and an annotation is not - it is foreground *or* muted -
-// so Note follows `P` and keeps the ordinary default. No tracking and no weight: those two
-// are what make an Eyebrow. No measure and no margin: the annotation sits in no reading column, and
-// the page owns the rhythm around it. Colour is re-pointed by `.dark`, so no variant carries `dark:`.
+// The annotation uses the secondary family (docs/adr/0004). Its default weight is inherited;
+// strong emphasis changes weight only. The enclosing arrangement owns measure and spacing.
 const note = cva('font-secondary text-small', {
   variants: {
+    emphasis: { regular: '', strong: 'font-strong' },
+    // Inline containment removes this text's intrinsic width from automatic table sizing (#132).
+    // The block still fills its allocated width; only its own text is clipped, never its siblings.
+    truncate: { true: 'min-w-0 truncate [contain:inline-size]', false: '' },
     color: {
       foreground: 'text-foreground',
       muted: 'text-muted',
@@ -20,7 +19,11 @@ const note = cva('font-secondary text-small', {
       info: 'text-info',
     },
   },
-  defaultVariants: { color: 'foreground' },
+  defaultVariants: {
+    color: 'foreground',
+    truncate: false,
+    emphasis: 'regular',
+  },
 });
 
 export interface INoteProps extends VariantProps<typeof note> {
@@ -33,16 +36,27 @@ export interface INoteProps extends VariantProps<typeof note> {
  * A short annotation at the small type role in the secondary family — a routing line above a submit
  * button, a privacy line at the point of submission, a line beside a control. Not reading matter:
  * it takes no measure and sits in no reading column, which is what separates it from `Prose.Tail`
- * at the same size, and it carries neither the tracking nor the weight that make an `Eyebrow`.
+ * at the same size. It carries no tracking and inherits weight unless emphasis is requested.
  *
  * @Guarantees — enforced on every render
  * - Renders a `p`, reading `--font-secondary` and sized by `--text-small`.
  * - `color` selects `foreground` (default), `muted`, `success`, `warning`, `error` or `info`;
  *   nothing else paints text. A status tone changes colour only.
- * - Emits no tracking, no font-weight, no measure and no margin under any prop.
+ * - Emits no tracking, no measure and no margin under any prop.
  * - Carries no ARIA role and no live region under any prop.
+ * - `truncate` opts into one line with an ellipsis at the inline end, following inherited writing
+ *   direction. The complete text stays in the DOM and accessibility tree. Omitted or false wraps
+ *   as before. Marked text can shrink inside ordinary and allocated Table cells.
+ * - `emphasis="strong"` reads `--font-weight-strong` without changing size, family or line height.
+ *   This is visual only: no `strong` element, importance semantics or live announcement is added.
+ *   Omitted or `regular` leaves weight inherited, exactly as before.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Communicate state in words or an accessible name; weight alone must never carry a state.
+ * - Allocate a width through the enclosing layout: truncated text does not size its holder.
+ * - Make the full wording reachable to sighted readers, for example by opening the item. Never
+ *   truncate essential content without that path, or put links, controls or line breaks inside
+ *   truncated text; use text and noninteractive inline phrasing only. No tooltip is added.
  * - The device has three carriers and this primitive is only one: use it for an annotation no other
  *   component owns. A form's own message belongs to `Form`'s `note` and a table's to its note cell,
  *   each painted by the component that owns it.
@@ -58,9 +72,11 @@ export interface INoteProps extends VariantProps<typeof note> {
 export const Note: FunctionComponent<INoteProps> = ({
   children,
   color,
+  emphasis,
+  truncate,
   testId,
 }) => (
-  <p className={note({ color })} data-testid={testId}>
+  <p className={note({ color, emphasis, truncate })} data-testid={testId}>
     {children}
   </p>
 );

package/src/Display/Typography/P/P.tsx

@@ -7,6 +7,10 @@ import type { FunctionComponent, ReactNode } from 'react';
 // P owns no reading measure - that belongs to whatever owns the reading column (Prose #21).
 const p = cva('font-body text-body leading-body', {
   variants: {
+    emphasis: { regular: '', strong: 'font-strong' },
+    // Inline containment removes this text's intrinsic width from automatic table sizing (#132).
+    // The block still fills its allocated width; only its own text is clipped, never its siblings.
+    truncate: { true: 'min-w-0 truncate [contain:inline-size]', false: '' },
     color: {
       foreground: 'text-foreground',
       muted: 'text-muted',
@@ -16,10 +20,14 @@ const p = cva('font-body text-body leading-body', {
       info: 'text-info',
     },
   },
-  defaultVariants: { color: 'foreground' },
+  defaultVariants: {
+    color: 'foreground',
+    truncate: false,
+    emphasis: 'regular',
+  },
 });
 
-interface IPProps extends VariantProps<typeof p> {
+export interface IPProps extends VariantProps<typeof p> {
   children: ReactNode;
   testId?: string;
 }
@@ -33,8 +41,19 @@ interface IPProps extends VariantProps<typeof p> {
  *   theme re-points it, #120), sized by `--text-body` and led by `--leading-body`.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
+ * - `truncate` opts into one line with an ellipsis at the inline end, following inherited writing
+ *   direction. The complete text stays in the DOM and accessibility tree. Omitted or false wraps
+ *   as before. Marked text can shrink inside ordinary and allocated Table cells.
+ * - `emphasis="strong"` reads `--font-weight-strong` without changing size, family or line height.
+ *   This is visual only: no `strong` element, importance semantics or live announcement is added.
+ *   Omitted or `regular` leaves weight inherited, exactly as before.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Communicate state in words or an accessible name; weight alone must never carry a state.
+ * - Allocate a width through the enclosing layout: truncated text does not size its holder.
+ * - Make the full wording reachable to sighted readers, for example by opening the item. Never
+ *   truncate essential content without that path, or put links, controls or line breaks inside
+ *   truncated text; use text and noninteractive inline phrasing only. No tooltip is added.
  * - Where line length matters, place the paragraph inside whatever bounds the reading measure; `P`
  *   does not constrain its own width.
  * - For a paragraph inside a reading column, reach for `Prose.Body`, which is measure-bounded by its
@@ -42,8 +61,14 @@ interface IPProps extends VariantProps<typeof p> {
  * - Status-toned content communicates its status without relying on colour. If a change needs to be
  *   announced, the caller owns that behavior; selecting a tone does not create a status event.
  */
-export const P: FunctionComponent<IPProps> = ({ children, color, testId }) => (
-  <p className={p({ color })} data-testid={testId}>
+export const P: FunctionComponent<IPProps> = ({
+  children,
+  color,
+  emphasis,
+  truncate,
+  testId,
+}) => (
+  <p className={p({ color, emphasis, truncate })} data-testid={testId}>
     {children}
   </p>
 );