@juwel-development/design-system 3.2.0 → 3.4.0

package/src/Arrangement/Stack/Stack.tsx

@@ -4,8 +4,8 @@ import type { FunctionComponent, ReactNode } from 'react';
 
 // One recipe on a plain <div>. Six components hand-write this same utility set and their specs pin
 // it as a set, not an order (architecture standard, the import test). `band` is vertical padding,
-// never a gap; the bound holds exactly the two container roles docs/adr/0008's Amendments attest
-// (#97), which argue the `w-full` pairing. `split` turns at `lg`, the Rail/DefinitionList threshold.
+// never a gap; `split` turns at `lg`, the Rail/DefinitionList threshold. The bound holds the two
+// container roles docs/adr/0008's Amendments attest (#97), sized as the guarantees below argue (#99).
 const stack = cva('flex', {
   variants: {
     gap: {
@@ -15,7 +15,11 @@ const stack = cva('flex', {
     measure: {
       true: 'max-w-[var(--measure)]',
       false: '',
-      action: 'w-full max-w-[var(--measure-action)]',
+      action: 'w-[var(--measure-action)] max-w-full mx-auto',
+    },
+    align: {
+      start: 'text-start',
+      center: 'text-center',
     },
     direction: {
       column: 'flex-col',
@@ -33,12 +37,14 @@ export interface IStackProps extends VariantProps<typeof stack> {
 
 /**
  * A vertical arrangement: children in a column, separated by one named space role and optionally
- * bounded by the reading measure or the action column. It owns one axis and one gap and nothing
- * else - no landmark, no heading, no band, no join, no gutter, no fill - and takes no outer space,
- * so whatever holds it owns the rhythm around it.
+ * bounded by the reading measure or the action column, with optional inherited text alignment.
+ * It owns no landmark, heading, band, join, gutter or fill and takes no outer space, so whatever
+ * holds it owns the rhythm around it.
  *
  * @Guarantees — enforced on every render
- * - It renders a `div` with no landmark role, no heading and no margin of its own.
+ * - It renders a `div` with no landmark role, no heading and no margin of its own - the one
+ *   exception the action column's auto inline margins, which name no space role and take no space:
+ *   they only centre the bound column inside a holder wider than the bound.
  * - `gap` selects which space role separates the children: `stack` (the default), the gap between
  *   siblings within one block, or `region`, the gap between groups of blocks. Nothing else — a
  *   spacing neither role expresses is a request for a measurement (docs/adr/0003, docs/adr/0004).
@@ -46,14 +52,24 @@ export interface IStackProps extends VariantProps<typeof stack> {
  *   unbounded, which is right wherever the children are not running text. It sets no font-size, so
  *   a `ch`-counted measure keeps resolving against inherited body type.
  * - `measure="action"` bounds the element to `--measure-action`, the action column - the width a
- *   stack of full-width controls fills, so they read as one unit and their labels align - and fills
- *   its slot up to that bound, so a centering frame cannot shrink it to its widest label. The two
+ *   stack of full-width controls fills, so they read as one unit and their labels align. The column
+ *   asks for that bound as its own definite width, capped at its holder's, so it reaches the bound
+ *   even inside a shrink-to-fit frame that sizes from its content - `Cover`'s slot - independently
+ *   of what its siblings measure, and its auto inline margins keep it centred in a holder that
+ *   stays wider. (#99, correcting #97's reasoning: `w-full` fills a containing slot but cannot
+ *   raise a shrink-to-fit ancestor's intrinsic width, so it never guaranteed the bound.) The two
  *   options answer different questions about what the column holds - text or controls - never how
  *   wide it should be (docs/adr/0008, Amendments).
  * - `direction="column"` (the default) never changes axis. `direction="split"` is the same column
  *   turning into a row at and above 64rem, its children aligned to their start edge rather than
  *   stretched. It is the only viewport-dependent behaviour here, and it is named for the job: the
  *   breakpoint is an implementation detail and is not part of the vocabulary.
+ * - `align="center"` centres inline text within each receiving text block; `align="start"`
+ *   resets it to the logical start edge in LTR or RTL. Omission sets no alignment, so nested
+ *   Stacks inherit. Descendants that declare their own alignment retain it.
+ * - Alignment never moves or resizes child boxes or changes gap, measure, direction, wrapping or
+ *   overflow. A narrower text block centres within itself, not on its holder's axis; an unbroken
+ *   word wider than its block is outside the centring guarantee, including in split arrangements.
  * - No literal length and no numbered spacing rung appears in the recipe: every value it emits is a
  *   role the token layer already names, so a second brand re-points all of them.
  * - `children` render unmodified, and it needs no JavaScript.
@@ -72,10 +88,14 @@ export const Stack: FunctionComponent<IStackProps> = ({
   gap,
   measure,
   direction,
+  align,
   children,
   testId,
 }) => (
-  <div className={stack({ gap, measure, direction })} data-testid={testId}>
+  <div
+    className={stack({ gap, measure, direction, align })}
+    data-testid={testId}
+  >
     {children}
   </div>
 );

package/src/Display/Collection/Collection.tsx

@@ -0,0 +1,58 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+const collectionRoot = cva('m-0 list-none p-0');
+const collectionItem = cva(
+  'py-[var(--space-collection-item)] [&+li]:border-t [&+li]:border-solid [&+li]:border-border',
+);
+
+export interface ICollectionRootProps {
+  /** Collection.Item children, including mapped items and conditional omissions. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+export interface ICollectionItemProps {
+  /** Freely composed content; its typography, arrangement and interaction remain its own. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+const CollectionRoot: FunctionComponent<ICollectionRootProps> = ({
+  children,
+  testId,
+}) => (
+  // biome-ignore lint/a11y/noRedundantRoles: list-style:none removes list semantics in Safari/VoiceOver; Checklist establishes this explicit-role precedent.
+  <ul className={collectionRoot()} role={'list'} data-testid={testId}>
+    {children}
+  </ul>
+);
+
+const CollectionItem: FunctionComponent<ICollectionItemProps> = ({
+  children,
+  testId,
+}) => (
+  <li className={collectionItem()} data-testid={testId}>
+    {children}
+  </li>
+);
+
+/**
+ * A vertical group of freely composed items with internal hairlines and open outer edges.
+ * The library owns spacing and separation; the consumer owns content, arrangement and interaction.
+ *
+ * @Guarantees
+ * - Root is a semantic list and Item a list item, with no visual markers or horizontal indent.
+ * - Each item takes vertical padding from --space-collection-item; adjacent items share one
+ *   hairline in the border colour role. Empty and single-item roots have no rules or placeholder.
+ * - Children render in supplied order, retaining their own typography and arrangement.
+ * - Neither member adds focus stops, interaction, or responsive content rearrangement.
+ *
+ * @CallerMustEnsure
+ * - Supply Collection.Item as Root's rendered children, directly or through fragments and maps.
+ * - Compose each item's content with typography, arrangements and controls for the jobs it contains.
+ */
+export const Collection = {
+  Root: CollectionRoot,
+  Item: CollectionItem,
+} as const;

package/src/Display/Meter/Meter.tsx

@@ -0,0 +1,136 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { CSSProperties, FunctionComponent } from 'react';
+import { MeterConfigurationError } from './MeterConfigurationError';
+
+// The track is the whole capacity: square corners, no radius token - Meter is not a control
+// (docs/adr/0003). The one-pixel `rule` line identifies the capacity against the surface;
+// `meterTrack` behind it makes the scale visible without boxing (docs/adr/0010). Deliberately no
+// transition class: the library's one motion belongs to state changes on controls, not a display.
+const meterTrack = cva(
+  'w-full h-[var(--meter-track-thickness)] bg-meter-track border border-solid border-rule',
+);
+
+// The fill is a block box sized by --meter-level, the normalized share the component computes;
+// block layout places it at inline-start in both LTR and RTL, no physical offset. Depleting reads
+// the same share into color-mix: `meterFill` at max, `error` at min, linearly through OKLab - a
+// perceptual space, so no threshold (docs/adr/0010). Both endpoints stay tokens a brand re-points.
+const meterFill = cva('h-full w-[calc(var(--meter-level)*100%)]', {
+  variants: {
+    treatment: {
+      neutral: 'bg-meter-fill',
+      depleting:
+        'bg-[color-mix(in_oklab,var(--color-meter-fill)_calc(var(--meter-level)*100%),var(--color-error))]',
+    },
+  },
+  defaultVariants: {
+    treatment: 'neutral',
+  },
+});
+
+// React's CSSProperties is closed over known properties; the one custom property the recipes read
+// is declared here so the style object stays typed without an assertion.
+type MeterLevelStyle = CSSProperties & { '--meter-level': number };
+
+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. */
+  value: number;
+  /** The bottom of the scale. Defaults to `0`. */
+  min?: number;
+  /** The top of the scale. Must exceed `min`. */
+  max: number;
+  /** The meter's accessible name - what the level measures. Required, and never rendered visibly:
+   *  the component shows a filled track and nothing else. Its wording is the consumer's. */
+  label: string;
+  /** Optional `aria-valuetext`, so a screen reader hears the consumer's wording ("strained")
+   *  instead of a bare number. Omitted, the numeric value is announced. */
+  valueText?: string;
+  testId?: string;
+}
+
+/**
+ * A read-only display of one numeric level within a bounded scale, shown as a filled share of a
+ * whole: a short track, a fill from inline-start, no text. It states an amount - not an operation's
+ * completion, and unlike a Slider it cannot be operated.
+ *
+ * @Guarantees — enforced on every render
+ * - 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.
+ * - 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).
+ * - A value change lands instantly: no width or colour animation.
+ * - The track fills its container, reads `--meter-track-thickness`, keeps square corners (no
+ *   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.
+ * - No visible wording of its own, no numeric readout, no caption slot, no `className`/`style`
+ *   passthrough.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - `label` carries meaningful wording; the component renders it to assistive technology only and
+ *   does not inspect it.
+ * - When `depleting` is selected, surrounding visible content explains why nearing the minimum
+ *   matters - the colour walk reinforces a stated consequence and must not be its only carrier.
+ *
+ * @UXGuidelines
+ * - Place any visible caption or readout yourself with typography; the Meter deliberately carries
+ *   none, so what the level measures stays the consumer's wording.
+ * - Reach for `depleting` only where a low value is genuinely more erroneous - some quantities
+ *   become safer toward their minimum, which is why the treatment is opt-in.
+ */
+export const Meter: FunctionComponent<IMeterProps> = ({
+  value,
+  min = 0,
+  max,
+  treatment,
+  label,
+  valueText,
+  testId,
+}) => {
+  if (
+    !Number.isFinite(value) ||
+    !Number.isFinite(min) ||
+    !Number.isFinite(max)
+  ) {
+    throw new MeterConfigurationError(
+      `value, min and max must be finite numbers (got value=${value}, min=${min}, max=${max})`,
+    );
+  }
+  if (min >= max) {
+    throw new MeterConfigurationError(
+      `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),
+  };
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: the native <meter> paints its own optimum/low/high bands the token contract cannot reach, and its fill is unstylable cross-browser; the ARIA meter pattern on a div carries the same semantics with the library's paint (#105).
+    <div
+      role={'meter'}
+      aria-valuenow={value}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-label={label}
+      aria-valuetext={valueText}
+      data-testid={testId}
+      className={meterTrack()}
+      style={style}
+    >
+      <div aria-hidden={'true'} className={meterFill({ treatment })} />
+    </div>
+  );
+};

package/src/Display/Meter/MeterConfigurationError.ts

@@ -0,0 +1,6 @@
+export class MeterConfigurationError extends Error {
+  constructor(reason: string) {
+    super(`Meter configuration is invalid: ${reason}`);
+    this.name = 'MeterConfigurationError';
+  }
+}

package/src/Interaction/Slider/Slider.tsx

@@ -0,0 +1,125 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent } from 'react';
+import type { Subject } from 'rxjs';
+import { SliderConfigurationError } from './SliderConfigurationError';
+
+// The track and thumb are vendor pseudo-elements, so every dimension on them needs a token name -
+// no consumer selector reaches them (ADR 0004's test; the tick precedent). The track takes
+// `controlBorder`: the one thing separating an unfilled control from the surface, >=3:1 against it.
+// The thumb takes `foreground`, a solid mark drawn on the surface like the tab marker; disabled
+// paints both in the disabled role, the non-operable statement every control makes. WebKit does
+// not centre the thumb on the track, hence the computed negative margin; Firefox does, but draws a
+// default thumb border WebKit does not, hence border-none on its thumb alone.
+const slider = cva(
+  [
+    'block h-[var(--slider-thumb-size)] w-full cursor-pointer appearance-none bg-transparent',
+    'disabled:cursor-not-allowed',
+    'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+    '[&::-webkit-slider-runnable-track]:h-[var(--slider-track-thickness)] [&::-webkit-slider-runnable-track]:rounded-[var(--radius-control)] [&::-webkit-slider-runnable-track]:bg-control-border',
+    '[&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:size-[var(--slider-thumb-size)] [&::-webkit-slider-thumb]:rounded-[var(--radius-control)] [&::-webkit-slider-thumb]:bg-foreground',
+    '[&::-webkit-slider-thumb]:mt-[calc((var(--slider-track-thickness)-var(--slider-thumb-size))/2)]',
+    '[&:disabled::-webkit-slider-runnable-track]:bg-disabled [&:disabled::-webkit-slider-thumb]:bg-disabled',
+    '[&::-moz-range-track]:h-[var(--slider-track-thickness)] [&::-moz-range-track]:rounded-[var(--radius-control)] [&::-moz-range-track]:bg-control-border',
+    '[&::-moz-range-thumb]:size-[var(--slider-thumb-size)] [&::-moz-range-thumb]:rounded-[var(--radius-control)] [&::-moz-range-thumb]:border-none [&::-moz-range-thumb]:bg-foreground',
+    '[&:disabled::-moz-range-track]:bg-disabled [&:disabled::-moz-range-thumb]:bg-disabled',
+  ].join(' '),
+);
+
+export interface ISliderProps {
+  /** The operating range's lower bound - interaction geometry, not a content rule (ADR 0009). */
+  min: number;
+  /** The operating range's upper bound. */
+  max: number;
+  /**
+   * The increment a movement produces. Defaults to 1: whole-step movement. Keeping `value` and
+   * `max` on the step grid is the caller's obligation - Slider neither rejects nor repairs an
+   * off-grid value, and the native control's own conduct stays observable: inside a surrounding
+   * form, misalignment counts as a `stepMismatch` against that form's validity.
+   */
+  step?: number;
+  /** The current value. Controlled - the consumer holds it and passes it back in. */
+  value: number;
+  /**
+   * Emits the new value on every native input event. Required, not optional: the control is
+   * controlled and takes no part in form submission, so a consumer that did not listen here
+   * could never read a value at all.
+   */
+  onInput$: Subject<number>;
+  /** The control's accessible name. */
+  label: string;
+  /**
+   * How the value is announced, in the consumer's wording ("$60 a week"). Left out, assistive
+   * technology reads the bare number: the library ships no wording of its own.
+   */
+  valueText?: string;
+  /** The explicit non-operable state: native disabled conduct, no emissions, disabled paint. */
+  disabled?: boolean;
+  testId?: string;
+}
+
+// Structural misconfiguration is a programmer error, so it fails fast - no clamping, no
+// normalization, no substitute emission. Step-grid alignment is deliberately not checked: that is
+// the caller's obligation, documented on `step`, and native constraint behaviour stays observable.
+const assertOperatingRange = (
+  range: Pick<Required<ISliderProps>, 'min' | 'max' | 'step' | 'value'>,
+): void => {
+  for (const [name, given] of Object.entries(range)) {
+    if (!Number.isFinite(given)) {
+      throw new SliderConfigurationError(
+        `\`${name}\` must be a finite number, got ${given}`,
+      );
+    }
+  }
+  if (range.min >= range.max) {
+    throw new SliderConfigurationError(
+      `\`min\` (${range.min}) must be below \`max\` (${range.max})`,
+    );
+  }
+  if (range.step <= 0) {
+    throw new SliderConfigurationError(
+      `\`step\` (${range.step}) must be positive`,
+    );
+  }
+  if (range.value < range.min || range.value > range.max) {
+    throw new SliderConfigurationError(
+      `\`value\` (${range.value}) must lie within [${range.min}, ${range.max}]`,
+    );
+  }
+};
+
+/**
+ * A control that sets one numeric value by moving one thumb along a fixed, visible operating
+ * range. Controlled: the consumer holds the value and passes it back in, and a value it does not
+ * pass back is never adopted. It renders the value nowhere - the consumer sets any figures beside
+ * it with typography - and it fills its container's width the way `Input` does. `disabled` is the
+ * explicit non-operable state.
+ */
+export const Slider: FunctionComponent<ISliderProps> = ({
+  min,
+  max,
+  step = 1,
+  value,
+  onInput$,
+  label,
+  valueText,
+  disabled,
+  testId,
+}) => {
+  assertOperatingRange({ min, max, step, value });
+  return (
+    <input
+      type={'range'}
+      className={slider()}
+      min={min}
+      max={max}
+      step={step}
+      value={value}
+      disabled={disabled}
+      aria-label={label}
+      aria-valuetext={valueText}
+      data-testid={testId}
+      // React's onChange rides the native input event, so every movement emits through here.
+      onChange={(event) => onInput$.next(event.currentTarget.valueAsNumber)}
+    />
+  );
+};

package/src/Interaction/Slider/SliderConfigurationError.ts

@@ -0,0 +1,6 @@
+export class SliderConfigurationError extends Error {
+  constructor(violation: string) {
+    super(`Slider configuration: ${violation}`);
+    this.name = 'SliderConfigurationError';
+  }
+}