@juwel-development/design-system 3.9.1 → 3.11.0

package/src/Arrangement/FieldRow/FieldRow.tsx

@@ -0,0 +1,313 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import {
+  createContext,
+  type FunctionComponent,
+  type ReactNode,
+  useContext,
+  useLayoutEffect,
+  useRef,
+} from 'react';
+import { alignControlEdges } from './alignControlEdges';
+import { FieldRowCompositionError } from './FieldRowCompositionError';
+import { FieldRowConfigurationError } from './FieldRowConfigurationError';
+import type { IControlEdge } from './IControlEdge';
+
+// Root's one recipe: a wrapping flex row whose items sit on their line's top edge, so the padding
+// the alignment pass writes on an item is the only thing that moves its control. The row gap is
+// Cluster's (docs/adr/0008): along a line the two attested roles, between wrapped lines `stack`.
+const fieldRowRoot = cva(
+  'flex flex-wrap items-start gap-y-[var(--space-stack)]',
+  {
+    variants: {
+      gap: {
+        stack: 'gap-x-[var(--space-stack)]',
+        region: 'gap-x-[var(--space-region)]',
+      },
+    },
+    defaultVariants: { gap: 'stack' },
+  },
+);
+
+// Field's one recipe: a share of its row from nothing, so growth is proportional to weight alone.
+// The weight and the token-named minimum are the two values ADR 0008 lets a caller choose, and
+// they are written on the item's style because a recipe cannot hold a caller's number or name.
+const fieldRowField = cva('shrink basis-0');
+
+// Actions' one recipe, keyed by part: the item takes its content width and never a share of the
+// row, capped at the row so the group inside it wraps its buttons only once it cannot fit alone.
+const fieldRowActions = cva('', {
+  variants: {
+    part: {
+      item: 'min-w-0 max-w-full flex-none',
+      group: 'flex flex-wrap items-end gap-[var(--space-stack)]',
+    },
+  },
+  defaultVariants: { part: 'item' },
+});
+
+const TOKEN_NAME = /^--[A-Za-z0-9_-]+$/;
+
+const ROOT_ITEMS = ':scope > [data-field-row-item]';
+
+type FieldRowContract = {
+  align: () => void;
+};
+
+const FieldRowContext = createContext<FieldRowContract | undefined>(undefined);
+
+const useFieldRowContract = (member: string): FieldRowContract => {
+  const contract = useContext(FieldRowContext);
+  if (contract === undefined) {
+    throw new FieldRowCompositionError(member);
+  }
+  return contract;
+};
+
+const assertWeight = (weight: number): void => {
+  if (!(Number.isFinite(weight) && weight > 0)) {
+    throw new FieldRowConfigurationError(
+      `weight must be a positive finite number, got ${weight}`,
+    );
+  }
+};
+
+const assertTokenName = (minWidth: string): void => {
+  if (!TOKEN_NAME.test(minWidth)) {
+    throw new FieldRowConfigurationError(
+      `minWidth must name a CSS custom property such as --search-field-min-width, got ${JSON.stringify(minWidth)}`,
+    );
+  }
+};
+
+// The control is whatever the field's own label labels - the association every field guarantees -
+// so the alignment boundary is the field's public contract and never its box structure. A control
+// positioned absolutely is drawn as the box it is positioned in: MultiSelect's trigger spans its
+// field inside the border, and the border is the edge a viewer aligns.
+const labelledControl = (content: Element): Element | undefined => {
+  const id = content.querySelector('label[for]')?.getAttribute('for');
+  if (!id) {
+    return undefined;
+  }
+  const control = content.ownerDocument.getElementById(id);
+  return control !== null && content.contains(control) ? control : undefined;
+};
+
+const isPositioned = (element: Element): boolean =>
+  getComputedStyle(element).position !== 'static';
+
+const controlBox = (control: Element, content: Element): Element => {
+  if (getComputedStyle(control).position !== 'absolute') {
+    return control;
+  }
+  let box = control.parentElement;
+  while (box !== null && box !== content && !isPositioned(box)) {
+    box = box.parentElement;
+  }
+  return box ?? control;
+};
+
+const measure = (item: Element): IControlEdge => {
+  const top = item.getBoundingClientRect().top;
+  const content = item.firstElementChild;
+  if (content === null) {
+    return { top, controlEdge: 0 };
+  }
+  const contentBounds = content.getBoundingClientRect();
+  const control = labelledControl(content);
+  const edge =
+    control === undefined
+      ? contentBounds.bottom
+      : controlBox(control, content).getBoundingClientRect().bottom;
+  return { top, controlEdge: edge - contentBounds.top };
+};
+
+// Reads every item's line and control edge in one pass, then writes only the paddings that
+// changed: a converged row is read-only, so the observer that called this sees no further resize.
+const alignItems = (root: HTMLElement): void => {
+  const items = Array.from(root.querySelectorAll<HTMLElement>(ROOT_ITEMS));
+  const paddings = alignControlEdges(items.map(measure));
+  items.forEach((item, index) => {
+    const padding = paddings[index] ?? 0;
+    const current = Number.parseFloat(item.style.paddingTop) || 0;
+    if (Math.abs(current - padding) > 0.01) {
+      item.style.paddingTop = padding === 0 ? '' : `${padding}px`;
+    }
+  });
+};
+
+export interface IFieldRowRootProps extends VariantProps<typeof fieldRowRoot> {
+  /** `FieldRow.Field` and `FieldRow.Actions` members, in reading order. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+const FieldRowRoot: FunctionComponent<IFieldRowRootProps> = ({
+  gap,
+  children,
+  testId,
+}) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const observerRef = useRef<ResizeObserver | undefined>(undefined);
+  const observedRef = useRef<WeakSet<Element>>(new WeakSet());
+
+  const align = (): void => {
+    if (rootRef.current) {
+      alignItems(rootRef.current);
+    }
+  };
+
+  const observe = (element: Element | undefined): void => {
+    if (element && observerRef.current && !observedRef.current.has(element)) {
+      observedRef.current.add(element);
+      observerRef.current.observe(element);
+    }
+  };
+
+  // Every render re-measures before paint, and every item's content and label are observed from
+  // then on: a label wrapping under a narrower holder or a message appearing changes their size,
+  // never the padded item's, so the observer never sees its own write and the loop settles. The
+  // label is watched on its own because it can grow exactly as a message below the control goes.
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    if (root === null) {
+      return;
+    }
+    alignItems(root);
+    if (typeof ResizeObserver === 'undefined') {
+      return;
+    }
+    observerRef.current ??= new ResizeObserver(() => alignItems(root));
+    for (const item of root.querySelectorAll(ROOT_ITEMS)) {
+      const content = item.firstElementChild ?? undefined;
+      observe(content);
+      observe(content?.querySelector('label[for]') ?? undefined);
+    }
+  });
+
+  useLayoutEffect(() => () => observerRef.current?.disconnect(), []);
+
+  return (
+    <div ref={rootRef} className={fieldRowRoot({ gap })} data-testid={testId}>
+      <FieldRowContext value={{ align }}>{children}</FieldRowContext>
+    </div>
+  );
+};
+
+export interface IFieldRowFieldProps {
+  /** One existing labelled field - `Input`, `NumberInput`, `Select`, `MultiSelect` or `TextArea`. */
+  children?: ReactNode;
+  /** The field's share of its row relative to the other fields on it. Positive and finite; `1`
+   *  when omitted, so fields share a row equally unless one says otherwise. */
+  weight?: number;
+  /** The name of the consumer's theme token holding this field's minimum readable width, such as
+   *  `--search-field-min-width`. A name, never a length, an expression or a `var()`. */
+  minWidth: `--${string}`;
+  testId?: string;
+}
+
+const FieldRowField: FunctionComponent<IFieldRowFieldProps> = ({
+  children,
+  weight = 1,
+  minWidth,
+  testId,
+}) => {
+  const { align } = useFieldRowContract('Field');
+  assertWeight(weight);
+  assertTokenName(minWidth);
+  // A member re-rendered on its own - from a consumer's state - re-measures as Root's render does.
+  useLayoutEffect(() => align());
+  return (
+    <div
+      data-field-row-item
+      className={fieldRowField()}
+      data-testid={testId}
+      style={{
+        flexGrow: weight,
+        minWidth: `min(var(${minWidth}), 100%)`,
+      }}
+    >
+      <div>{children}</div>
+    </div>
+  );
+};
+
+export interface IFieldRowActionsProps {
+  /** The consumer's action buttons, in reading order. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+const FieldRowActions: FunctionComponent<IFieldRowActionsProps> = ({
+  children,
+  testId,
+}) => {
+  const { align } = useFieldRowContract('Actions');
+  useLayoutEffect(() => align());
+  return (
+    <div data-field-row-item className={fieldRowActions()} data-testid={testId}>
+      <div className={fieldRowActions({ part: 'group' })}>{children}</div>
+    </div>
+  );
+};
+
+/**
+ * A wrapping row of labelled fields and the shared actions that trail them, aligned on the bottom
+ * edges of the controls themselves rather than on the fields' boxes - so a label that wraps, an
+ * optional marker, a hint or an error on one field never pushes its neighbours' controls out of
+ * line. It owns that one arrangement and nothing else: no form, no landmark, no filter meaning,
+ * no wording, and no outer space. Composed from `Root`, a `Field` around each existing labelled
+ * field, and `Actions` around the consumer's buttons (docs/adr/0008, Amendments).
+ *
+ * @Guarantees — enforced on every render
+ * - `Root` renders a `div` with no role and no margin; the members render unmodified inside their
+ *   items in content order, so reading and keyboard order are the content's.
+ * - On each row, every control's bottom edge and the actions' bottom edge meet the deepest one.
+ *   The control is the element a field's own label labels - the association every field already
+ *   guarantees - so a taller control, a `TextArea` or a group of wrapped buttons keeps its height
+ *   and the others come down to it. Labels, markers, hints and errors are never the anchor.
+ * - Items wrap progressively at the available width of the holder, not the viewport: a row holds
+ *   what fits every field's minimum, and each row aligns its controls independently. A field alone
+ *   on a row narrower than its minimum fits that row rather than overflowing it.
+ * - Each row's width is shared among its fields in proportion to their `weight`s - equal by
+ *   default - after the gaps and the actions' content width are reserved. Minimums come from the
+ *   consumer's theme tokens named by `minWidth`, resolved live, so a theme change re-wraps. A
+ *   field whose share would fall below its minimum keeps the minimum, and the others share the
+ *   rest by weight.
+ * - The actions stay one trailing group: they move to the next row together, and their buttons
+ *   wrap inside the group only once the group cannot fit on a row by itself, still in order.
+ * - `gap` selects which space role separates items along a row: `stack` (the default), the
+ *   sibling gap of controls that belong together, or `region`. Wrapped rows and the buttons
+ *   inside the actions are always `--space-stack`, as `Cluster` fixes its wrapped lines.
+ * - Reflow - a resize, a message appearing, a label changing, a field omitted or taken in - keeps
+ *   every retained control mounted, with its value, selection and focus; nothing is re-keyed.
+ *   Alignment is measured before paint on every render and again whenever an item's content
+ *   resizes, so no frame paints a misaligned row. An omitted field reserves no space.
+ * - No literal length and no numbered spacing rung appears in the recipes; a `weight` that is
+ *   not a positive finite number, or a `minWidth` that is not a custom property name, throws a
+ *   `FieldRowConfigurationError`, and a member outside `Root` throws a
+ *   `FieldRowCompositionError`.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Every `minWidth` token is declared in the applicable theme with a nonnegative CSS length, on
+ *   the row or an ancestor, in any unit including font-relative ones. An undeclared token is not a
+ *   responsive configuration: the field then falls back to its content's minimum width.
+ * - `Field` and `Actions` are the direct children of `Root` - through arrays, fragments and
+ *   consumer components that render them, but never wrapped in an element of the consumer's own.
+ * - A `Field` holds exactly one labelled field; the field keeps its label, hint, optional marker
+ *   and error, and FieldRow reads none of their wording.
+ * - The form, its submission and any filter meaning belong to the consumer; the actions are the
+ *   consumer's `Button`s, in the consumer's words, and a filter is never a landmark by itself.
+ *
+ * @UXGuidelines
+ * - `gap="stack"` is a filter: fields and actions that act together. `gap="region"` separates
+ *   fields that are not one set.
+ * - Weight a search field higher than a threshold or a select; give every field a minimum its
+ *   label and placeholder can be read at, and expect the row to wrap at that width.
+ * - Keep action wording short: a long label widens the group and wraps the row sooner.
+ */
+export const FieldRow = {
+  Root: FieldRowRoot,
+  Field: FieldRowField,
+  Actions: FieldRowActions,
+} as const;

package/src/Arrangement/FieldRow/FieldRowCompositionError.ts

@@ -0,0 +1,6 @@
+export class FieldRowCompositionError extends Error {
+  constructor(member: string) {
+    super(`FieldRow.${member} must be composed inside FieldRow.Root`);
+    this.name = 'FieldRowCompositionError';
+  }
+}

package/src/Arrangement/FieldRow/FieldRowConfigurationError.ts

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

package/src/Arrangement/FieldRow/IControlEdge.ts

@@ -0,0 +1,6 @@
+export interface IControlEdge {
+  /** Where the item's box starts; items sharing a top sit on one row. */
+  top: number;
+  /** How far below the item's content top its control's bottom edge sits, before any padding. */
+  controlEdge: number;
+}

package/src/Arrangement/FieldRow/alignControlEdges.ts

@@ -0,0 +1,35 @@
+import type { IControlEdge } from './IControlEdge';
+
+// Half a pixel: items on one flex line share a top exactly, and the tolerance only has to absorb
+// the fractional positions a zoomed or sub-pixel layout reports for the same line.
+const ROW_TOLERANCE = 0.5;
+
+const isOnRow = (row: number, top: number): boolean =>
+  Math.abs(row - top) <= ROW_TOLERANCE;
+
+/**
+ * The top padding each item needs so that, on every row, every control's bottom edge meets the
+ * deepest one. Rows are found from the tops alone, so the caller hands in the measurements of a
+ * finished line layout and gets back one padding per item, in the same order.
+ */
+export const alignControlEdges = (
+  items: readonly IControlEdge[],
+): readonly number[] => {
+  const rows: number[] = [];
+  for (const { top } of items) {
+    if (!rows.some((row) => isOnRow(row, top))) {
+      rows.push(top);
+    }
+  }
+  const deepest = rows.map((row) =>
+    Math.max(
+      ...items
+        .filter((item) => isOnRow(row, item.top))
+        .map((item) => item.controlEdge),
+    ),
+  );
+  return items.map(({ top, controlEdge }) => {
+    const rowIndex = rows.findIndex((row) => isOnRow(row, top));
+    return (deepest[rowIndex] ?? controlEdge) - controlEdge;
+  });
+};

package/src/Display/Box/Box.tsx

@@ -0,0 +1,77 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// No variants: a Box has nothing to choose. `min-w-0` lets a flex or grid holder shrink it below its
+// content's min-content width, and `overflow-wrap: anywhere` (MultiSelect's idiom) breaks an unbroken
+// name inside it; no overflow is hidden, so content with its own sizing contract is never clipped as
+// a stand-in for wrapping. Square corners and no shadow are the absence of a utility, not a reset.
+const box = cva(
+  [
+    'min-w-0 border border-solid border-border bg-surface text-foreground',
+    'p-[var(--space-box-inset)] [overflow-wrap:anywhere]',
+  ].join(' '),
+);
+
+export interface IBoxProps {
+  /** The enclosed matter - a Stack, a heading, facts. Rendered unmodified: Box imposes no anatomy. */
+  children?: ReactNode;
+  /** Exposes the enclosure as an accessible group with this name. Omit it, or pass an empty string,
+   *  for an ordinary enclosure: an unnamed Box has no role and is inert to assistive technology. The
+   *  name is never rendered - the consumer supplies any visible heading. */
+  name?: string;
+  testId?: string;
+}
+
+/**
+ * A bounded content group with a semantic surface, border and inner padding. The consumer owns its
+ * content, headings and internal arrangement; Stack arranges, Box encloses.
+ *
+ * @Guarantees — enforced on every render
+ * - It paints `surface`, `foreground` and a one-pixel `border` hairline, with square corners and no
+ *   shadow: it borrows neither the control radius nor the floating-layer elevation.
+ * - Its inset is the one `--space-box-inset` role on all four sides. There is no padding or size
+ *   prop: the theme chooses the value, and re-pointing the role moves the actual inset.
+ * - It fills the width its holder allocates, border and padding included, grows with its content
+ *   and shrinks inside a narrow holder: no fixed width, height, minimum viewport or aspect. Long
+ *   prose and unbroken text wrap inside it rather than truncate, and nothing is clipped.
+ * - With a non-empty `name` it is an accessible group carrying that name; without one, a plain
+ *   `div` with no role, no label and no landmark. In neither case does it add a focus stop or
+ *   listen for a key, so controls inside keep their ordinary keyboard behaviour.
+ * - An empty Box is an empty enclosure - surface, border and padding - with no invented wording.
+ * - `children` render unmodified, in order, and it needs no JavaScript.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Where `name` is given it matches the visible heading the consumer places inside, since the
+ *   component labels the group with that string and cannot reference the heading's id.
+ * - Content with its own intrinsic sizing or overflow contract - a table, a figure, a code block -
+ *   handles its own overflow; the Box wraps text and never scrolls or clips on its behalf.
+ * - Whether an empty group should render at all is the consumer's decision: omit the Box rather
+ *   than expecting empty-state text from it.
+ *
+ * @UXGuidelines
+ * - A Box groups related facts that read as one unit. Enclosing every group on a page turns the
+ *   boundary into noise; the consumer decides which group earns one.
+ */
+export const Box: FunctionComponent<IBoxProps> = ({
+  children,
+  name,
+  testId,
+}) =>
+  // Two renders rather than a conditional aria-label: a label on a role-less div is invalid ARIA,
+  // and the lint rule that says so cannot see that the role arrives with the name. An empty name
+  // is no name (Brandmark's idiom): a group with nothing to announce is worse than no group.
+  name === undefined || name === '' ? (
+    <div className={box()} data-testid={testId}>
+      {children}
+    </div>
+  ) : (
+    // biome-ignore lint/a11y/useSemanticElements: a fieldset brings the UA's min-inline-size, which stops the box shrinking inside a narrow holder, plus legend naming and a form-disabling model a content group must not carry (MultiSelect's precedent); a div with role=group named by `name` is the whole contract
+    <div
+      className={box()}
+      role={'group'}
+      aria-label={name}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );

package/src/Display/Checklist/Checklist.tsx

@@ -34,7 +34,7 @@ const checklistRoot = cva('m-0 list-none p-0');
 // `--space-stack`, split above and below the hairline so it sits centred in the gap.
 const checklistItem = cva(
   [
-    'flex items-start gap-3 font-primary text-body leading-body text-foreground',
+    'flex items-start gap-3 font-body text-body leading-body text-foreground',
     "before:mt-[0.35em] before:size-[calc(var(--tick-length)*0.7)] before:shrink-0 before:rotate-45 before:[border-top:var(--tick-thickness)_solid_var(--color-rule)] before:[border-right:var(--tick-thickness)_solid_var(--color-rule)] before:content-['']",
     '[&:not(:first-child)]:mt-[var(--space-stack)] [&:not(:first-child)]:border-border [&:not(:first-child)]:border-t [&:not(:first-child)]:border-solid [&:not(:first-child)]:pt-[var(--space-stack)]',
   ].join(' '),