@juwel-development/design-system 3.11.0 → 4.0.0

package/src/Arrangement/ColumnLayout/ColumnLayout.tsx

@@ -19,6 +19,10 @@ import { ColumnLayoutConfigurationError } from './ColumnLayoutConfigurationError
 // the role from one declaration. Nothing here measures: the arrangement needs no JavaScript.
 const columnLayout = cva('flex flex-wrap items-start', {
   variants: {
+    fill: {
+      false: '',
+      true: 'h-full min-h-0 content-start [--column-layout-shortfall:clamp(0px,(var(--column-layout-threshold)-100cqi)*1000000,1px)] [&>div]:[@container_style(--column-layout-shortfall:0px)]:h-full [&>div]:[@container_style(--column-layout-shortfall:0px)]:min-h-0',
+    },
     gap: {
       stack:
         'gap-[var(--space-stack)] [--column-layout-gap:var(--space-stack)]',
@@ -26,30 +30,38 @@ const columnLayout = cva('flex flex-wrap items-start', {
         'gap-[var(--space-region)] [--column-layout-gap:var(--space-region)]',
     },
   },
-  defaultVariants: { gap: 'region' },
+  defaultVariants: { gap: 'region', fill: false },
 });
 
+// A fill frame supplies the query width without imposing block-size containment. The row's
+// registered shortfall resolves against it, so style queries release the columns when stacked.
+const columnLayoutFrame = cva(
+  'h-full min-h-0 min-w-0 [container-type:inline-size]',
+);
+
 // The all-or-one switch, after Heydon Pickering's "Holy Albatross": `100%` is the Root's width W
 // and the threshold T sits on the Root, so W >= T clamps the basis to 0 (one line, grown by weight)
 // and W < T amplifies the shortfall past 100% (a line each). The factor turns a 1/64px shortfall,
 // Chrome's layout grain, into a full switch; `0px` and `100%` are the two states, not measurements.
 const columnLayoutColumn = cva(
-  'min-w-0 grow-[var(--column-layout-weight)] basis-[clamp(0px,(var(--column-layout-threshold)-100%)*1000000,100%)]',
+  'min-w-0 grow-[calc(var(--column-layout-weight)/var(--column-layout-growth-unit))] basis-[clamp(0px,(var(--column-layout-threshold)-100%)*1000000,100%)] max-w-[var(--column-layout-maximum)]',
 );
 
-// React's CSSProperties is closed over known properties; the two custom properties the recipes
+// React's CSSProperties is closed over known properties; the custom properties the recipes
 // read are declared here so the style objects stay typed without an assertion.
 type ColumnLayoutRootStyle = CSSProperties & {
   '--column-layout-threshold': string;
+  '--column-layout-growth-unit': number;
 };
 type ColumnLayoutColumnStyle = CSSProperties & {
   '--column-layout-weight': number;
+  '--column-layout-maximum': string;
 };
 
 /** The name of a CSS custom property, as written in a stylesheet: `--main-column-min-width`. */
-type MinWidthToken = `--${string}`;
+type WidthToken = `--${string}`;
 
-type Track = { weight: number; minWidth: MinWidthToken };
+type Track = { weight: number; minWidth: WidthToken; maxWidth?: WidthToken };
 
 // Granted only to a Column the Root counted: the Root wraps each direct Column child in it, and a
 // Column revokes it for its own descendants. Anything else is outside the composition.
@@ -63,7 +75,7 @@ const toTrack = (
   element: ReactElement<IColumnLayoutColumnProps>,
   index: number,
 ): Track => {
-  const { weight, minWidth } = element.props;
+  const { weight, minWidth, maxWidth } = element.props;
   if (!Number.isFinite(weight) || weight <= 0) {
     throw new ColumnLayoutConfigurationError(
       `column ${index + 1} needs a positive finite weight (got ${weight})`,
@@ -74,7 +86,12 @@ const toTrack = (
       `column ${index + 1} needs a custom-property name such as --main-column-min-width for minWidth (got ${JSON.stringify(minWidth)})`,
     );
   }
-  return { weight, minWidth };
+  if (maxWidth !== undefined && !TOKEN_NAME.test(maxWidth)) {
+    throw new ColumnLayoutConfigurationError(
+      `column ${index + 1} needs a custom-property name such as --support-column-max-width for maxWidth (got ${JSON.stringify(maxWidth)})`,
+    );
+  }
+  return { weight, minWidth, maxWidth };
 };
 
 // The documented threshold, `(n - 1) * g + max(m_i * S / w_i)`, left to the browser to resolve
@@ -87,6 +104,12 @@ const thresholdOf = (tracks: readonly Track[]): string => {
   return `calc(${tracks.length - 1} * var(--column-layout-gap) + max(${shares.join(', ')}))`;
 };
 
+// Flex factors below one leave surplus unallocated, even after other columns freeze at caps.
+const growthUnitOf = (tracks: readonly Track[]): number =>
+  tracks.some((track) => track.maxWidth !== undefined)
+    ? Math.min(1, ...tracks.map((track) => track.weight))
+    : 1;
+
 const isFragment = (
   node: ReactNode,
 ): node is ReactElement<{ children?: ReactNode }> =>
@@ -94,6 +117,9 @@ const isFragment = (
 
 export interface IColumnLayoutRootProps
   extends VariantProps<typeof columnLayout> {
+  /** Accept the parent's allocated height and pass it to horizontal columns. Unsized parents
+   *  and stacked columns retain content height; the holder owns stacked overflow. */
+  fill?: VariantProps<typeof columnLayout>['fill'];
   /** The columns, as `ColumnLayout.Column` elements: direct children, or arrays and fragments of
    *  them. A conditional that renders nothing reserves nothing. */
   children?: ReactNode;
@@ -107,7 +133,11 @@ export interface IColumnLayoutColumnProps {
   /** The name of the consumer's custom property holding this column's minimum readable width,
    *  such as `--main-column-min-width`. A token name, never a length or a `var()`: the consumer
    *  declares it in the theme with a nonnegative CSS length. */
-  minWidth: MinWidthToken;
+  minWidth: WidthToken;
+  /** Optional horizontal cap, named by a theme custom property. Stacked columns ignore it.
+   * The theme must supply a nonnegative CSS length at least as large as minWidth; resolved
+   * lengths are not read or validated by the component. */
+  maxWidth?: WidthToken;
   /** The column's content. Rendered unmodified: the column imposes no anatomy. */
   children?: ReactNode;
   testId?: string;
@@ -147,6 +177,7 @@ const markColumns = (children: ReactNode): ReactNode =>
 
 const ColumnLayoutRoot: FunctionComponent<IColumnLayoutRootProps> = ({
   gap,
+  fill,
   children,
   testId,
 }) => {
@@ -154,16 +185,25 @@ const ColumnLayoutRoot: FunctionComponent<IColumnLayoutRootProps> = ({
   const style: ColumnLayoutRootStyle | undefined =
     tracks.length === 0
       ? undefined
-      : { '--column-layout-threshold': thresholdOf(tracks) };
-  return (
-    <div className={columnLayout({ gap })} style={style} data-testid={testId}>
+      : {
+          '--column-layout-threshold': thresholdOf(tracks),
+          '--column-layout-growth-unit': growthUnitOf(tracks),
+        };
+  const row = (
+    <div
+      className={columnLayout({ gap, fill })}
+      style={style}
+      data-testid={testId}
+    >
       {markColumns(children)}
     </div>
   );
+  return fill ? <div className={columnLayoutFrame()}>{row}</div> : row;
 };
 
 const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
   weight,
+  maxWidth,
   children,
   testId,
 }) => {
@@ -171,7 +211,13 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
   if (!isCounted) {
     throw new ColumnLayoutCompositionError();
   }
-  const style: ColumnLayoutColumnStyle = { '--column-layout-weight': weight };
+  const style: ColumnLayoutColumnStyle = {
+    '--column-layout-weight': weight,
+    '--column-layout-maximum':
+      maxWidth === undefined
+        ? 'none'
+        : `max(var(${maxWidth}), clamp(0px, (var(--column-layout-threshold) - 100%) * 1000000, 100%))`,
+  };
   return (
     <div className={columnLayoutColumn()} style={style} data-testid={testId}>
       <ColumnLayoutMembership.Provider value={false}>
@@ -189,45 +235,57 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
  * one answers to the width of its holder (docs/adr/0008, Amendments).
  *
  * @Guarantees — enforced on every render
- * - `Root` renders a `div` with no landmark role, no heading and no margin. Each `Column` is a
- *   `div` directly inside it, in the order written, so DOM, reading and keyboard order are the
+ * - `Root` renders plain containers with no landmark role, no heading and no margin. Each
+ *   `Column` is a `div` directly inside the row, so DOM, reading and keyboard order are the
  *   order of the children in both arrangements, and no column is ever remounted merely because
  *   the arrangement changed: resizing keeps every column's state and focus.
  * - In the horizontal arrangement the gaps are taken off the Root's content width and the rest is
  *   divided in proportion to the weights: `2`, `1`, `1` is one half and two quarters of it. The
- *   columns align at the top and keep their own heights.
+ *   columns align at the top and keep their own heights by default (`fill={false}`). Optional
+ *   maximums cap each allocation and redistribute surplus by weight among columns still able
+ *   to grow. If all are capped, unused width stays at the trailing edge with unchanged gaps.
+ * - With `fill`, Root accepts its parent's allocated height and every horizontal column takes
+ *   that height, bounding a filling Pane, Table or ScrollContainer. An internal inline-size
+ *   frame supplies the width query; columns remain direct children of the row.
+ * - In an unsized parent, `fill` invents no bound: columns retain content height. When stacked,
+ *   columns return to content height and the holder owns scrolling. No column scrolls itself.
  * - The row holds only while every proportional share is at least its own minimum. The moment one
  *   falls short, every column takes a line of its own and fills the Root's width - a column
  *   narrower than its minimum included: the minimum decides the switch and never floors a width.
- *   There is no in-between: no column wraps alone, no share is clamped, nothing is redistributed to
- *   postpone the switch. For n columns, gap g, total weight S and minimums m_i the row fits at and
- *   above `(n - 1) * g + max(m_i * S / w_i)`.
+ *   There is no in-between: no column wraps alone. Caps and redistribution never postpone
+ *   the switch; stacked columns ignore their maximums. For n columns, gap g, total weight S and
+ *   minimums m_i the row fits at and above `(n - 1) * g + max(m_i * S / w_i)`.
  * - The space measured is the Root's own width, never the viewport, so two instances on one page
  *   switch independently, and a narrow holder on a wide screen stacks.
- * - Every minimum is read from the theme as a CSS length each time layout runs, so re-pointing a
- *   token - in a theme class, a media query, or a scope around the Root - moves the threshold
- *   with it, and a font-relative length moves it as the type does.
+ * - Every bound is read from the theme as a CSS length each time layout runs, so re-pointing a
+ *   token - in a theme class, a media query, or a scope around the Root - updates allocation.
+ *   Minimums move the threshold; maximums change caps. Font-relative bounds follow the type.
  * - `gap` selects which space role separates the columns, across the row and between the stacked
  *   lines alike: `region` (the default), the gap between groups of blocks, or `stack`, the gap
  *   between siblings within one block. Nothing else.
  * - Only rendered columns count: a conditional that renders nothing reserves neither width nor
- *   gap, a single column fills the width, and an empty Root holds no tracks and no gaps.
+ *   gap, a single uncapped column fills the width, and an empty Root holds no tracks and no gaps.
  *   Allocations follow every change of columns, weights, gap, holder width or theme.
  * - A column adds no scrolling, truncation or overflow treatment of its own and does not widen its
  *   track for its content: the content keeps whatever wrapping or scrolling contract it has.
  * - Every value it emits is a role the token layer or the consumer's theme already names; the
  *   only literals are the switch's two states.
- * - A non-positive or non-finite `weight`, or a `minWidth` that is not a custom-property name,
+ * - A non-positive or non-finite `weight`, or a bound that is not a custom-property name,
  *   throws {@link ColumnLayoutConfigurationError}; a `Column` that is not a direct child of a
  *   `Root` - loose, nested in another column, or reached through a wrapping component - throws
  *   {@link ColumnLayoutCompositionError}. Both are programmer errors, raised loud and early.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
- * - Every `minWidth` token is declared, on the Root or an ancestor of it, as a valid nonnegative
- *   CSS length: `24rem`, `20em`, `40ch`, `320px`. A `rem` resolves against the document root, an
- *   `em` or `ch` against the Root's inherited type. A missing or invalid token is not a
- *   responsive configuration: the switch has nothing to compare and the columns size from their
- *   content instead.
+ * - Every `minWidth` and supplied `maxWidth` token is declared, on the Root or an ancestor of it,
+ *   as a valid nonnegative CSS length: `24rem`, `20em`, `40ch`, `320px`. A `rem` resolves against
+ *   the document root, an `em` or `ch` against the Root's inherited type. Missing or invalid
+ *   bounds are outside this contract and can invalidate the switch or cap.
+ * - Maximums must be at least their column's minimum in every scope and responsive state.
+ *   Percentages are outside the contract. Resolved lengths are not read by the component;
+ *   maximum below minimum has no guaranteed runtime exception. A valid maximum below the
+ *   original share at the threshold applies immediately, with its surplus redistributed.
+ * - With `fill`, the holder supplies a definite height to bound content and owns overflow for
+ *   the stacked fallback. Filling children own their overflow; fixed content must fit the bound.
  * - The holder gives the Root a definite width, as any block does. Inside a shrink-to-fit frame
  *   there is no width to measure the shares against.
  * - Content that cannot wrap - an unbroken string, a fixed-width control - needs its own overflow

package/src/Display/Callout/Callout.tsx

@@ -0,0 +1,64 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+const callout = cva(
+  'min-w-0 border-s-[length:var(--callout-mark-width)] border-solid ps-[var(--space-callout-inset)] text-foreground [overflow-wrap:anywhere] forced-colors:border-s-[CanvasText]',
+  {
+    variants: {
+      tone: {
+        warning: 'border-warning',
+        info: 'border-info',
+        success: 'border-success',
+        error: 'border-error',
+      },
+    },
+    defaultVariants: { tone: 'warning' },
+  },
+);
+
+export interface ICalloutProps extends VariantProps<typeof callout> {
+  /** Content and its arrangement belong to the consumer. */
+  children?: ReactNode;
+  /** Optional accessible group name, never rendered as visible text. Empty means unnamed. */
+  name?: string;
+  testId?: string;
+}
+
+/**
+ * A status-toned leading-edge mark beside consumer-owned content, without a surrounding box.
+ * @Guarantees
+ * - Supports warning (default), info, success and error through the theme's status tones.
+ * - The logical leading border follows writing direction; forced colours use CanvasText.
+ * - Only the leading edge is inset; no fill, outer space, layout, clipping or fixed size is added.
+ * - Named content is a group; unnamed content has no role. Neither adds focus or announcements.
+ * - Children keep their order, arrangement and native keyboard behaviour.
+ * @CallerMustEnsure
+ * - State the status and its consequence in visible text or a named Icon; colour is supplementary.
+ * - Keep the optional name consistent with any visible heading. Own any live announcements.
+ * - Keep tones at least 3:1 against the surrounding surface; the shared 4.5:1 text floor clears it.
+ * - Theme --callout-mark-width is a positive CSS length; --space-callout-inset is nonnegative.
+ * - Content with intrinsic sizing owns its overflow; Callout wraps prose but never clips it.
+ * @UXGuidelines
+ * - Mark a block needing attention; the consumer owns its text, controls and status meaning.
+ */
+export const Callout: FunctionComponent<ICalloutProps> = ({
+  children,
+  tone,
+  name,
+  testId,
+}) =>
+  name === undefined || name === '' ? (
+    <div className={callout({ tone })} data-testid={testId}>
+      {children}
+    </div>
+  ) : (
+    // biome-ignore lint/a11y/useSemanticElements: a content group must not acquire fieldset form semantics or intrinsic minimum sizing
+    <div
+      className={callout({ tone })}
+      role="group"
+      aria-label={name}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );

package/src/Display/Icon/Icon.tsx

@@ -2,7 +2,7 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent } from 'react';
 
-// The glyph is sized in `em` and stroked in `currentColor`, so it takes the size and colour of the
+// The glyph is sized in `em` and drawn in `currentColor`, so it takes the size and colour of the
 // text it sits in and needs no size prop. Baseline at -0.125em is what seats a 1em square beside
 // lowercase letters; the inline-box exists so an icon reads as a word in its line. `color` has no
 // default on purpose (docs/adr/0011, the #126 amendment): absent, no class competes with the text.
@@ -27,9 +27,13 @@ const icon = cva(
 const bubble =
   'M3.5 2h9a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H7.25L4 13.75V11h-.5a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1z';
 
-// Each name selects a drawing and nothing else: drawings are told apart by their strokes, not by
+// Each name selects a drawing and nothing else: drawings are told apart by their shapes, not by
 // colour or size, so they survive forced-colors mode and a monochrome print.
 const drawings = {
+  plus: ['M3 8h10', 'M8 3v10'],
+  right: ['M3 8h10', 'M9 4l4 4-4 4'],
+  remove: ['M3 8h10'],
+  dot: ['M8 5a3 3 0 1 0 0 6a3 3 0 1 0 0-6z'],
   sort: [
     'M5.5 13V3',
     'M3 5.5l2.5-2.5L8 5.5',
@@ -49,9 +53,7 @@ const drawings = {
   'bubble-tick': [bubble, 'M5.75 6.75l1.5 1.5 3-3.5'],
 } as const;
 
-export interface IIconProps extends VariantProps<typeof icon> {
-  /** Which drawing. A name selects a shape, never a state or a behaviour. */
-  name: keyof typeof drawings;
+export interface IIconPartProps extends VariantProps<typeof icon> {
   /**
    * The accessible name that makes the icon a status mark (CONTEXT.md). Give it only where the icon
    * stands alone for a state; absent or empty, the icon stays hidden from assistive technology.
@@ -60,10 +62,19 @@ export interface IIconProps extends VariantProps<typeof icon> {
   testId?: string;
 }
 
+export interface IIconProps extends IIconPartProps {
+  /** Legacy selector, retained alongside the compound drawing components. */
+  name: Exclude<keyof typeof drawings, 'plus' | 'right' | 'remove'>;
+}
+
+interface IIconDrawingProps extends IIconPartProps {
+  name: keyof typeof drawings;
+}
+
 /**
- * A reusable visual glyph in six drawings: three sort indicators, a bin, and a speech bubble holding
- * an exclamation mark or a tick. Decorative beside the control or text that names it, or - given a
- * `label` - a status mark that stands alone for an item's state.
+ * Seven drawings: a filled dot, three sort indicators, a bin, and a bubble holding an exclamation
+ * mark or a tick. Decorative beside the control or text that names it, or - given a `label` - a
+ * status mark that stands alone for an item's state.
  *
  * @Guarantees — enforced on every render
  * - Out of the tab order in both forms: it adds no stop.
@@ -72,15 +83,18 @@ export interface IIconProps extends VariantProps<typeof icon> {
  *   without a name is never rendered.
  * - Scales with the surrounding font-size and takes the surrounding text colour unless `color`
  *   selects `muted` or a status tone. The tone changes colour only: no role, name or announcement.
- * - Every drawing differs in shape, so no meaning is carried by colour alone.
+ * - Every drawing differs in shape; the dot is filled, the other drawings are outlined.
+ * - Inline glyphs align with the first line of the text beside them.
  *
  * @CallerMustEnsure
  * - An unlabelled icon sits beside what carries the meaning: a `Button` label or `ariaLabel`, a
  *   header cell's `ariaSort`. Inside a named control it stays unlabelled, or the name is said twice.
  * - A status mark's `label` states the status in the reader's language; the library words nothing.
- * - The two forms of one state use two drawings, never one drawing in two colours.
+ * - The two forms of one state use two drawings, never one drawing in two colours. When absence
+ *   is the other form of a dot, the dot must not be the only carrier: give the state a name or
+ *   a second cue, such as stronger text weight. A standalone dot still requires a label.
  */
-export const Icon: FunctionComponent<IIconProps> = ({
+const IconDrawing: FunctionComponent<IIconDrawingProps> = ({
   name,
   label,
   color,
@@ -102,8 +116,8 @@ export const Icon: FunctionComponent<IIconProps> = ({
       <path
         key={segment}
         d={segment}
-        fill={'none'}
-        stroke={'currentColor'}
+        fill={name === 'dot' ? 'currentColor' : 'none'}
+        stroke={name === 'dot' ? 'none' : 'currentColor'}
         strokeWidth={1.5}
         strokeLinecap={'round'}
         strokeLinejoin={'round'}
@@ -111,3 +125,29 @@ export const Icon: FunctionComponent<IIconProps> = ({
     ))}
   </svg>
 );
+
+// All parts share the same SVG renderer and recipe; only their drawing is fixed.
+const partOf =
+  (name: keyof typeof drawings): FunctionComponent<IIconPartProps> =>
+  ({ label, color, testId }) => (
+    <IconDrawing name={name} label={label} color={color} testId={testId} />
+  );
+
+const LegacyIcon: FunctionComponent<IIconProps> = ({
+  name,
+  label,
+  color,
+  testId,
+}) => <IconDrawing name={name} label={label} color={color} testId={testId} />;
+
+/** Legacy named drawings and five compound action drawings, all sharing em sizing, currentColor,
+ * optional status tones, label and testId. Parts take no name. Leave parts decorative inside
+ * Buttons and supply the action-specific ariaLabel on the Button itself. Remove is a minus, not bin.
+ */
+export const Icon = Object.assign(LegacyIcon, {
+  Plus: partOf('plus'),
+  Up: partOf('sort-ascending'),
+  Down: partOf('sort-descending'),
+  Right: partOf('right'),
+  Remove: partOf('remove'),
+});

package/src/Display/Meter/Meter.tsx

@@ -31,10 +31,15 @@ const meterFill = cva('h-full w-[calc(var(--meter-level)*100%)]', {
 // is declared here so the style object stays typed without an assertion.
 type MeterLevelStyle = CSSProperties & { '--meter-level': number };
 
+const filledShare = (value: number, min: number, max: number): number => {
+  if (value <= min) return 0;
+  if (value >= max) return 1;
+  return (value - min) / (max - min);
+};
+
 export interface IMeterProps extends VariantProps<typeof meterFill> {
-  /** The current level. Must lie inside `[min, max]`; an outside value throws
-   *  {@link MeterConfigurationError} rather than clamping - a wrong number must not render as a
-   *  plausible level. */
+  /** The current level. Off-range values clamp the visual fill to the nearest bound;
+   *  `aria-valuenow` retains the raw value. */
   value: number;
   /** The bottom of the scale. Defaults to `0`. */
   min?: number;
@@ -58,8 +63,8 @@ export interface IMeterProps extends VariantProps<typeof meterFill> {
  * - The root carries `role="meter"`, `aria-valuenow`/`aria-valuemin`/`aria-valuemax`, the `label`
  *   as its accessible name, and `aria-valuetext` exactly when `valueText` is supplied. It is not
  *   focusable, and the visual fill is hidden from the accessibility tree.
- * - The filled share is `(value - min) / (max - min)` of the container and begins at logical
- *   inline-start under both LTR and RTL direction.
+ * - The filled share is `(value - min) / (max - min)`, clamped to `[0, 1]`, and begins at logical
+ *   inline-start under both LTR and RTL direction. `aria-valuenow` retains the raw value.
  * - Neutral paints the fill with `meterFill`; `depleting` maps the normalized level linearly
  *   through OKLab from `meterFill` at the maximum to `error` at the minimum - no threshold, no
  *   wording, no icon (docs/adr/0010-meter-depletion-is-a-treatment.md).
@@ -68,7 +73,7 @@ export interface IMeterProps extends VariantProps<typeof meterFill> {
  *   radius token - Meter is not a control), and draws a persistent one-pixel `rule` line that
  *   identifies the whole capacity against the surface.
  * - Invalid numeric configuration throws {@link MeterConfigurationError}: non-finite `value`,
- *   `min` or `max`, `min >= max`, or a value outside the inclusive range. Nothing is clamped.
+ *   `min` or `max`, or `min >= max`.
  * - No visible wording of its own, no numeric readout, no caption slot, no `className`/`style`
  *   passthrough.
  *
@@ -107,14 +112,8 @@ export const Meter: FunctionComponent<IMeterProps> = ({
       `min must be less than max (got min=${min}, max=${max})`,
     );
   }
-  if (value < min || value > max) {
-    throw new MeterConfigurationError(
-      `value must lie within [min, max] (got value=${value}, min=${min}, max=${max})`,
-    );
-  }
-
   const style: MeterLevelStyle = {
-    '--meter-level': (value - min) / (max - min),
+    '--meter-level': filledShare(value, min, max),
   };
 
   return (

package/src/Display/Rule/Rule.tsx

@@ -0,0 +1,31 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent } from 'react';
+
+const rule = cva(
+  'w-full shrink-0 border-t border-solid border-border forced-colors:border-[CanvasText]',
+);
+
+export interface IRuleProps {
+  testId?: string;
+}
+
+/**
+ * A decorative horizontal hairline between two blocks of one arrangement.
+ *
+ * @Guarantees
+ * - One CSS pixel in the theme's border role, spanning its holder's width.
+ * - Forced colours use CanvasText so the hairline survives the user's palette.
+ * - Always hidden from assistive technology, with no role, content or focus stop.
+ * - No margin or padding: the surrounding arrangement owns space on both sides.
+ *
+ * @CallerMustEnsure
+ * - Place it between blocks in a column Stack; Stack's gap supplies the space role.
+ * - Rule is never a semantic separator. A thematic break that must be conveyed to
+ *   assistive technology requires semantic markup instead of this component.
+ *
+ * @UXGuidelines
+ * - Use Collection for a semantic list with rules between items; Rule creates no list.
+ */
+export const Rule: FunctionComponent<IRuleProps> = ({ testId }) => (
+  <div aria-hidden={'true'} className={rule()} data-testid={testId} />
+);