@juwel-development/design-system 3.9.1 → 3.10.0

package/dist/types/Layout/ScrollContainer/ScrollContainer.d.ts

@@ -0,0 +1,37 @@
+import type { VariantProps } from 'class-variance-authority';
+import { type FunctionComponent, type ReactNode } from 'react';
+declare const scrollContainer: (props?: ({
+    axis?: "both" | "horizontal" | "vertical" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface IScrollContainerProps extends VariantProps<typeof scrollContainer> {
+    /** The group's accessible name while it can be scrolled. Required: a tab stop with no name is a
+     *  mystery to a screen reader. The consuming app words it, usually after the heading above. */
+    ariaLabel: string;
+    children?: ReactNode;
+    testId?: string;
+}
+/**
+ * Makes overflowing content reachable along the chosen axes, within the space its parent allocates.
+ * It owns the scrolling; the consumer owns the content and the allocation of space.
+ *
+ * @Guarantees — enforced on every render
+ * - Scrolls only an enabled axis and only once content overflows it; overflow on a disabled axis is
+ *   clipped. Content wraps as it would anywhere else.
+ * - Keyboard-reachable - a named `group` with a tab stop - exactly while an enabled axis overflows,
+ *   static content included; no stop and no group while everything fits. Scrollability is re-read on
+ *   resize and on content change without moving focus.
+ * - Native scrolling: scrollbars, wheel, touch and the browser's own arrow/page keys on the focused
+ *   container. No key of a control inside it is intercepted and focus is never trapped.
+ * - Invents no bound: no height, width or viewport unit of its own. The only space it adds is the
+ *   focus ring's room around its content, so a focusable child flush with its edge - a Table's
+ *   scroll region, a button - keeps a visible ring instead of having it clipped at the edge.
+ *
+ * @CallerMustEnsure
+ * - The parent allocates finite space on every axis the container should scroll - a sized box, or a
+ *   flex/grid item allowed to shrink (`flex: 1 1 0; min-height: 0` in a column). Under an unbounded
+ *   parent it simply grows with its content, as any block would.
+ * - Content fits a disabled axis. Clipping is not a way to hide essential content or controls.
+ * - `ariaLabel` is wording the viewer would recognise, typically the heading above the content.
+ */
+export declare const ScrollContainer: FunctionComponent<IScrollContainerProps>;
+export {};

package/dist/types/Layout/Section/Section.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const section: (props?: ({
-    bleed?: "full" | "inset" | null | undefined;
+    bleed?: "inset" | "full" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ISectionProps extends VariantProps<typeof section> {
     /** Names the section as a region a screen-reader user can jump to. Omit for an ordinary section: an

package/dist/types/Layout/Sidebar/Sidebar.d.ts

@@ -41,6 +41,10 @@ export interface ISidebarContentProps {
  * - Activating the active entry or an inert one emits nothing; no render emits anything. Entries are
  *   non-submitting `type="button"` buttons with native Tab/Enter/Space behaviour - no tabs/menu model.
  * - An inert entry stays visible but muted and disabled, so Tab skips it and activation is inert too.
+ * - A label is rendered in full inside its entry, in either arrangement: a phrase wraps at its spaces
+ *   and a word wider than the track breaks within itself. Nothing is truncated, renamed or hidden
+ *   behind a tooltip, no horizontal scrolling is introduced, and a translated label neither widens
+ *   the 12rem track nor displaces the content.
  * - At and above 64rem the nav is a fixed 12rem track, sticky at the top of the scrolling area with no
  *   assumed top-bar offset, capped to the screen/scrolling-area height with independent entry scrolling.
  *   Content sits beside it in `minmax(0,1fr)`, so wide content cannot displace the track.

package/dist/types/Theme/Palette.d.ts

@@ -9,7 +9,8 @@
  *
  * Light and dark are two complete sets of the same roles rather than a set of `dark:` overrides
  * scattered through the components. A component therefore carries no dark-mode classes at all:
- * swapping the `.dark` class re-points the variables underneath it.
+ * swapping the `.dark` class re-points the variables underneath it. Complete means `Required`: the
+ * two roles the type marks optional are optional for a consumer's palette object, never here.
  *
  * The values below are still depot-tracker's brand (primary is its violet). They are carried over
  * so nothing changed visually during the extraction - a starting point to replace, not a decision.
@@ -113,8 +114,28 @@ export type PaletteTokens = {
      *  constraint stated on `success`. */
     warning: string;
     /** The error status tone. Carries the general status-tone contract and 4.5:1-against-`surface`
-     *  constraint stated on `success`, plus the depletion-path constraint stated on `meterFill`. */
+     *  constraint stated on `success`, plus the depletion-path constraint stated on `meterFill`. It is
+     *  also Button's destructive fill (#119), identified like `primary` by the fill alone: at least 3:1
+     *  against `surface` in the same theme, `errorHover` included - which the 4.5:1 text floor already
+     *  clears - and constrained from the other side by the ink it carries, stated on `errorForeground`.
+     *  See docs/adr/0011-status-tones-are-general-roles.md, Amendments. */
     error: string;
+    /** The destructive fill's hover step. Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against
+     *  `surface` in the same theme, and at least 4.5:1 against `errorForeground`, since a hovered
+     *  control has to stay identifiable and readable too. Not a status tone: it carries no text of its
+     *  own and the status-tone text floor does not apply to it. Optional in the type so a palette
+     *  object written before #119 keeps compiling: the shipped stylesheet declares `--color-error-hover`,
+     *  and a theme that omits the role inherits that default - which pairs with the shipped `error`,
+     *  so a theme that re-points `error` re-points this too. */
+    errorHover?: string;
+    /** Text and icons drawn on top of `error` and `errorHover`. Constraint (WCAG 2.2 SC 1.4.3): at
+     *  least 4.5:1 against both in the same theme, hover included. Optional in the type for the same
+     *  reason as `errorHover`, with the same obligation: the shipped default is the ink for the
+     *  shipped `error`. The ink inverts with the theme as `primaryForeground` does, and in light it is
+     *  pure white rather than slate-50 because the shipped `error` sits exactly on the 4.5:1 floor
+     *  against white (4.501:1) and slate-50 measures 4.30:1 - under it. Not required against
+     *  `disabled`, which SC 1.4.3 exempts. */
+    errorForeground?: string;
     /** The informational status tone. Carries the general status-tone contract and
      *  4.5:1-against-`surface` constraint stated on `success`. */
     info: string;
@@ -138,7 +159,7 @@ export type PaletteTokens = {
  *   against `#0f172a`, the dark set's own `surface`, sky-600 lands at 4.36 and fails. It also buys
  *   a light theme with white text on one button and black on the one beside it.
  */
-export declare const light: PaletteTokens;
+export declare const light: Required<PaletteTokens>;
 /**
  * Dark reverses the direction the fills step: it sits higher up the ramp than light does and hovers
  * *up* into lighter still, where light sits lower and hovers down. That is what the components' old
@@ -150,8 +171,11 @@ export declare const light: PaletteTokens;
  * under its darker ones. The pair is the two ends of the one neutral ramp the rest of the palette is
  * already built from - `#f8fafc` is slate-50, `surface` slate-900, `muted` slate-500 - rather than a
  * new colour arriving for a single job. `#020617` is also the lightest slate step that still admits
- * violet-500 and sky-600, which is what leaves this set's `secondary` pair unmoved: slate-900 draws
- * 4.22 and 4.36 against them and fails. Why the ink follows the theme at all, and the two routes
- * rejected in getting here: see the light set.
+ * violet-500: slate-900 draws 4.22 against it and fails. The `secondary` pair sits one ramp step
+ * above where it first shipped - sky-500 at rest, sky-400 on hover, where it was sky-600 and sky-500 -
+ * because #119 made `secondary` an ink as well as a fill: the outlined Button draws its text and edge
+ * in it, and sky-600 measures 4.36:1 against this surface, under the 4.5:1 text floor (now 6.44:1
+ * and 8.33:1, both still clearing `secondaryForeground` at 7.28:1 and 9.42:1). Why the ink follows
+ * the theme at all, and the two routes rejected in getting here: see the light set.
  */
-export declare const dark: PaletteTokens;
+export declare const dark: Required<PaletteTokens>;

package/dist/types/index.d.ts

@@ -1,13 +1,18 @@
 import './styles.css';
 export { Cluster } from 'Arrangement/Cluster/Cluster';
+export { ColumnLayout } from 'Arrangement/ColumnLayout/ColumnLayout';
+export { FieldRow } from 'Arrangement/FieldRow/FieldRow';
 export { Stack } from 'Arrangement/Stack/Stack';
+export { Box } from 'Display/Box/Box';
 export { Brandmark } from 'Display/Brandmark/Brandmark';
 export { Checklist } from 'Display/Checklist/Checklist';
 export { Collection } from 'Display/Collection/Collection';
 export { DefinitionList } from 'Display/DefinitionList/DefinitionList';
 export { Figure } from 'Display/Figure/Figure';
+export { Icon } from 'Display/Icon/Icon';
 export { Meter } from 'Display/Meter/Meter';
 export { Rail } from 'Display/Rail/Rail';
+export type { TableColumnAllocation } from 'Display/Table/Table';
 export { Table } from 'Display/Table/Table';
 export { Eyebrow } from 'Display/Typography/Eyebrow/Eyebrow';
 export { H1 } from 'Display/Typography/H1/H1';
@@ -37,6 +42,7 @@ export { Form } from 'Layout/Form/Form';
 export { Header } from 'Layout/Header/Header';
 export { Hero } from 'Layout/Hero/Hero';
 export { PageHead } from 'Layout/PageHead/PageHead';
+export { ScrollContainer } from 'Layout/ScrollContainer/ScrollContainer';
 export { Section } from 'Layout/Section/Section';
 export { Sidebar } from 'Layout/Sidebar/Sidebar';
 export type { PaletteTokens } from 'Theme/Palette';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juwel-development/design-system",
-	"version": "3.9.1",
+	"version": "3.10.0",
 	"type": "module",
 	"description": "Shared design system: tokens and components.",
 	"license": "MIT",

package/src/Arrangement/ColumnLayout/ColumnLayout.tsx

@@ -0,0 +1,249 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import {
+  Children,
+  type CSSProperties,
+  createContext,
+  Fragment,
+  type FunctionComponent,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  useContext,
+} from 'react';
+import { ColumnLayoutCompositionError } from './ColumnLayoutCompositionError';
+import { ColumnLayoutConfigurationError } from './ColumnLayoutConfigurationError';
+
+// A wrapping flex row that aligns its tracks to the top. The gap variant also publishes the chosen
+// role as `--column-layout-gap`, which the threshold below reads, so the switch and the paint take
+// the role from one declaration. Nothing here measures: the arrangement needs no JavaScript.
+const columnLayout = cva('flex flex-wrap items-start', {
+  variants: {
+    gap: {
+      stack:
+        'gap-[var(--space-stack)] [--column-layout-gap:var(--space-stack)]',
+      region:
+        'gap-[var(--space-region)] [--column-layout-gap:var(--space-region)]',
+    },
+  },
+  defaultVariants: { gap: 'region' },
+});
+
+// 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%)]',
+);
+
+// React's CSSProperties is closed over known properties; the two custom properties the recipes
+// read are declared here so the style objects stay typed without an assertion.
+type ColumnLayoutRootStyle = CSSProperties & {
+  '--column-layout-threshold': string;
+};
+type ColumnLayoutColumnStyle = CSSProperties & {
+  '--column-layout-weight': number;
+};
+
+/** The name of a CSS custom property, as written in a stylesheet: `--main-column-min-width`. */
+type MinWidthToken = `--${string}`;
+
+type Track = { weight: number; minWidth: MinWidthToken };
+
+// 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.
+const ColumnLayoutMembership = createContext<boolean>(false);
+
+// The ident grammar CSS gives a custom property name, restricted to ASCII so a `var()`, a length,
+// a space or a brace can never ride in on the name.
+const TOKEN_NAME = /^--[A-Za-z0-9_-]+$/;
+
+const toTrack = (
+  element: ReactElement<IColumnLayoutColumnProps>,
+  index: number,
+): Track => {
+  const { weight, minWidth } = element.props;
+  if (!Number.isFinite(weight) || weight <= 0) {
+    throw new ColumnLayoutConfigurationError(
+      `column ${index + 1} needs a positive finite weight (got ${weight})`,
+    );
+  }
+  if (!TOKEN_NAME.test(minWidth)) {
+    throw new ColumnLayoutConfigurationError(
+      `column ${index + 1} needs a custom-property name such as --main-column-min-width for minWidth (got ${JSON.stringify(minWidth)})`,
+    );
+  }
+  return { weight, minWidth };
+};
+
+// The documented threshold, `(n - 1) * g + max(m_i * S / w_i)`, left to the browser to resolve
+// so a theme re-pointing a minimum - or the gap - moves it with no script in between.
+const thresholdOf = (tracks: readonly Track[]): string => {
+  const total = tracks.reduce((sum, track) => sum + track.weight, 0);
+  const shares = tracks.map(
+    (track) => `var(${track.minWidth}) * ${total / track.weight}`,
+  );
+  return `calc(${tracks.length - 1} * var(--column-layout-gap) + max(${shares.join(', ')}))`;
+};
+
+const isFragment = (
+  node: ReactNode,
+): node is ReactElement<{ children?: ReactNode }> =>
+  isValidElement(node) && node.type === Fragment;
+
+export interface IColumnLayoutRootProps
+  extends VariantProps<typeof columnLayout> {
+  /** The columns, as `ColumnLayout.Column` elements: direct children, or arrays and fragments of
+   *  them. A conditional that renders nothing reserves nothing. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+export interface IColumnLayoutColumnProps {
+  /** This column's share of the width left after the gaps, relative to its siblings' weights: a
+   *  positive finite number. `2` beside `1` is a two-thirds/one-third arrangement. */
+  weight: number;
+  /** 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;
+  /** The column's content. Rendered unmodified: the column imposes no anatomy. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+const isColumn = (
+  node: ReactNode,
+): node is ReactElement<IColumnLayoutColumnProps> =>
+  isValidElement(node) && node.type === ColumnLayoutColumn;
+
+const collectColumns = (
+  children: ReactNode,
+): ReactElement<IColumnLayoutColumnProps>[] =>
+  Children.toArray(children).flatMap((child) => {
+    if (isFragment(child)) {
+      return collectColumns(child.props.children);
+    }
+    return isColumn(child) ? [child] : [];
+  });
+
+// Marks every counted Column and nothing else, keeping React's own keys for each position so a
+// conditional column appearing later neither remounts its siblings nor moves their focus.
+const markColumns = (children: ReactNode): ReactNode =>
+  Children.map(children, (child) => {
+    if (isFragment(child)) {
+      return <Fragment>{markColumns(child.props.children)}</Fragment>;
+    }
+    if (isColumn(child)) {
+      return (
+        <ColumnLayoutMembership.Provider value={true}>
+          {child}
+        </ColumnLayoutMembership.Provider>
+      );
+    }
+    return child;
+  });
+
+const ColumnLayoutRoot: FunctionComponent<IColumnLayoutRootProps> = ({
+  gap,
+  children,
+  testId,
+}) => {
+  const tracks = collectColumns(children).map(toTrack);
+  const style: ColumnLayoutRootStyle | undefined =
+    tracks.length === 0
+      ? undefined
+      : { '--column-layout-threshold': thresholdOf(tracks) };
+  return (
+    <div className={columnLayout({ gap })} style={style} data-testid={testId}>
+      {markColumns(children)}
+    </div>
+  );
+};
+
+const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
+  weight,
+  children,
+  testId,
+}) => {
+  const isCounted = useContext(ColumnLayoutMembership);
+  if (!isCounted) {
+    throw new ColumnLayoutCompositionError();
+  }
+  const style: ColumnLayoutColumnStyle = { '--column-layout-weight': weight };
+  return (
+    <div className={columnLayoutColumn()} style={style} data-testid={testId}>
+      <ColumnLayoutMembership.Provider value={false}>
+        {children}
+      </ColumnLayoutMembership.Provider>
+    </div>
+  );
+};
+
+/**
+ * An arrangement of weighted columns that becomes one column when the space it is given cannot
+ * satisfy every column's minimum at the requested proportions. It owns the arrangement and nothing
+ * else - no landmark, no band, no join, no gutter, no fill - and takes no outer space, so whatever
+ * holds it owns the rhythm around it. `Stack`'s `split` keeps its own viewport-keyed contract; this
+ * 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
+ *   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.
+ * - 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)`.
+ * - 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.
+ * - `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.
+ *   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,
+ *   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.
+ * - 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
+ *   contract, as `Table.Root` has; the column will not widen to hold it.
+ * - `Root`'s children are `Column`s. Anything else placed beside them is rendered as given but is
+ *   not a column: it takes no weight, counts for no gap or threshold, and sits in the row as
+ *   content of its own width, which breaks the proportions. Content belongs inside a `Column`.
+ *
+ * @UXGuidelines
+ * - A minimum is the width below which the column's content stops being readable or operable -
+ *   the narrowest a comparison table can be scanned, the narrowest a summary's labels keep their
+ *   lines - not the width the designer would like. The stack is the readable fallback.
+ * - Weights are structural relationships: `2` and `1` say the table is the subject and the summary
+ *   its support. A ratio chosen to hit a pixel width is a measurement, and the theme owns those.
+ */
+export const ColumnLayout = {
+  Root: ColumnLayoutRoot,
+  Column: ColumnLayoutColumn,
+} as const;

package/src/Arrangement/ColumnLayout/ColumnLayoutCompositionError.ts

@@ -0,0 +1,8 @@
+export class ColumnLayoutCompositionError extends Error {
+  constructor() {
+    super(
+      'ColumnLayout.Column must be a direct child of ColumnLayout.Root (arrays and fragments are fine; a wrapping component or a nested Column is not)',
+    );
+    this.name = 'ColumnLayoutCompositionError';
+  }
+}

package/src/Arrangement/ColumnLayout/ColumnLayoutConfigurationError.ts

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