@juwel-development/design-system 3.9.1 → 3.10.0

package/src/Display/DefinitionList/DefinitionList.tsx

@@ -1,50 +1,161 @@
+import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
-import type { FunctionComponent, ReactNode } from 'react';
+import type { CSSProperties, FunctionComponent, ReactNode } from 'react';
+import { DefinitionListConfigurationError } from './DefinitionListConfigurationError';
 
-// Rules are the layout. Each Item owns its two-track grid and its hairlines. The term track is a fixed
-// width, so per-item grids line up without a subgrid. At `lg` (64rem) a second `dt` is pinned to the
-// term column so it cannot auto-place into the description column and break the row silently. Colours
-// are semantic tokens re-pointed by `.dark`, so no class carries a `dark:` prefix.
+// The dl is the inline-size container its items measure, and the one place density lands: it pads
+// its items from the role of its treatment, so Item, Term and Description carry no density of
+// their own and nothing is passed down (docs/agents/standards/design-system-components.md,
+// "Compound components": a Root styles the descendants it owns through its one recipe).
+const definitionList = cva('@container', {
+  variants: {
+    density: {
+      comfortable: '[&>div]:py-[var(--space-definition-item)]',
+      compact: '[&>div]:py-[var(--space-definition-item-compact)]',
+    },
+  },
+  defaultVariants: { density: 'comfortable' },
+});
+
+// Each item shares the list's tracks. Below the fit threshold the term track is full width.
+// The registered shortfall resolves on the item and inherits as a length into its description.
+// tan(atan2(length, 1px)) converts the 0px/1px switch to a number for grid-column-start (2/1).
+// Dense placement fills column two beside the first term, or the next full row when stacked;
+// it preserves DOM reading order and supports several terms without counting them in JavaScript.
 const item = cva(
   [
-    'grid gap-[var(--space-stack)] py-6',
-    'border-b border-solid border-border first:border-t',
-    'lg:grid-cols-[16rem_minmax(0,1fr)] lg:items-baseline lg:gap-x-12',
-    'lg:[&>dt]:col-start-1 lg:[&>dd]:col-start-2 lg:[&>dd]:row-start-1',
+    'grid grid-flow-row-dense gap-[var(--space-stack)] border-b border-solid border-border first:border-t',
+    '[--definition-stack:clamp(0px,(var(--definition-threshold)-100%)*1000000,100%)]',
+    '[--definition-shortfall:clamp(0px,(var(--definition-threshold)-100cqi)*1000000,1px)]',
+    'grid-cols-[max(calc((100%-var(--space-definition-column))*var(--definition-term-share)),var(--definition-stack))_minmax(0,1fr)]',
+    'gap-x-[max(0px,var(--space-definition-column)-var(--definition-stack))]',
+    '[&>dt]:col-start-1 [&>dt]:self-baseline [&>dd]:col-span-full [&>dd]:self-baseline',
+    '[&>dd]:col-start-[calc(2-tan(atan2(var(--definition-shortfall),1px)))]',
   ].join(' '),
 );
 
 // The term at the subtitle role - a step below title (docs/adr/0005 fixes the role, no size prop), so
-// terms never tie with the heading introducing the list. Foreground, and no measure cap.
-const term = cva('font-primary text-subtitle leading-subtitle text-foreground');
+// terms never tie with the heading introducing the list. Foreground, and no measure cap. The term
+// is sized like a heading and is not one: with its description it is the reading matter, so both
+// take the body face, never the heading face (docs/adr/0004, #120).
+const term = cva(
+  'font-body text-subtitle leading-subtitle text-foreground wrap-break-word',
+);
 
 // The description at the body role, muted, capped at the reading measure in both layout modes.
 const description = cva(
-  'font-primary text-body leading-body text-muted max-w-[var(--measure)]',
+  'font-body text-body leading-body text-muted max-w-[var(--measure)] wrap-break-word',
 );
 
-interface IDefinitionListRootProps {
+/** The name of a CSS custom property, as written in a stylesheet: `--summary-term-min-width`. */
+type MinWidthToken = `--${string}`;
+
+/** One column's allocation: its share of the row relative to the other's, and the theme token that
+ *  holds its minimum readable width. Named only through `Root`'s props. */
+type ColumnAllocation = { weight: number; minWidth: MinWidthToken };
+
+const TERM_COLUMN: ColumnAllocation = {
+  weight: 1,
+  minWidth: '--definition-term-min-width',
+};
+const DESCRIPTION_COLUMN: ColumnAllocation = {
+  weight: 2,
+  minWidth: '--definition-description-min-width',
+};
+
+// 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 validateColumn = (
+  name: 'termColumn' | 'descriptionColumn',
+  column: ColumnAllocation,
+): ColumnAllocation => {
+  if (!Number.isFinite(column.weight) || column.weight <= 0) {
+    throw new DefinitionListConfigurationError(
+      `${name} needs a positive finite weight (got ${column.weight})`,
+    );
+  }
+  if (!TOKEN_NAME.test(column.minWidth)) {
+    throw new DefinitionListConfigurationError(
+      `${name} needs a custom-property name such as --summary-term-min-width for minWidth (got ${JSON.stringify(column.minWidth)})`,
+    );
+  }
+  return column;
+};
+
+// The documented threshold, `g + max(m_i * S / w_i)` with the column gap as g, 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 = (
+  termColumn: ColumnAllocation,
+  descriptionColumn: ColumnAllocation,
+): string => {
+  const total = termColumn.weight + descriptionColumn.weight;
+  return `calc(var(--space-definition-column) + max(var(${termColumn.minWidth}) * ${total / termColumn.weight}, var(${descriptionColumn.minWidth}) * ${total / descriptionColumn.weight}))`;
+};
+
+// React's CSSProperties is closed over known properties; the two custom properties the item
+// recipe reads are declared here so the style object stays typed without an assertion.
+type DefinitionListRootStyle = CSSProperties & {
+  '--definition-threshold': string;
+  '--definition-term-share': string;
+};
+
+export interface IDefinitionListRootProps
+  extends VariantProps<typeof definitionList> {
+  /** The term column's share of the row and its minimum readable width, shared by every item.
+   *  Defaults to weight `1` and the library's `--definition-term-min-width`; a consumer's own
+   *  token is declared in the theme with a nonnegative CSS length, as ColumnLayout's are. */
+  termColumn?: ColumnAllocation;
+  /** The description column's share and minimum, likewise. Defaults to weight `2` and
+   *  `--definition-description-min-width`. */
+  descriptionColumn?: ColumnAllocation;
   children?: ReactNode;
   testId?: string;
 }
 
-interface IDefinitionListItemProps {
+export interface IDefinitionListItemProps {
   children?: ReactNode;
   testId?: string;
 }
 
-interface IDefinitionListTermProps {
+export interface IDefinitionListTermProps {
   children?: ReactNode;
 }
 
-interface IDefinitionListDescriptionProps {
+export interface IDefinitionListDescriptionProps {
   children?: ReactNode;
 }
 
 const DefinitionListRoot: FunctionComponent<IDefinitionListRootProps> = ({
+  density,
+  termColumn = TERM_COLUMN,
+  descriptionColumn = DESCRIPTION_COLUMN,
   children,
   testId,
-}) => <dl data-testid={testId}>{children}</dl>;
+}) => {
+  const termAllocation = validateColumn('termColumn', termColumn);
+  const descriptionAllocation = validateColumn(
+    'descriptionColumn',
+    descriptionColumn,
+  );
+  const style: DefinitionListRootStyle = {
+    '--definition-threshold': thresholdOf(
+      termAllocation,
+      descriptionAllocation,
+    ),
+    '--definition-term-share': `calc(${termAllocation.weight} / ${termAllocation.weight + descriptionAllocation.weight})`,
+  };
+  return (
+    <dl
+      className={definitionList({ density })}
+      style={style}
+      data-testid={testId}
+    >
+      {children}
+    </dl>
+  );
+};
 
 const DefinitionListItem: FunctionComponent<IDefinitionListItemProps> = ({
   children,
@@ -70,17 +181,48 @@ const DefinitionListDescription: FunctionComponent<
  * `Description` a `<dd>`.
  *
  * @Guarantees — enforced on every render
- * - Renders semantic `dl`/`div`/`dt`/`dd`, and works with JavaScript off.
+ * - Renders semantic `dl`/`div`/`dt`/`dd` at either density, and works with JavaScript off: the
+ *   arrangement is a stylesheet rule, so nothing is measured, reordered or remounted, and resizing
+ *   keeps every descendant's state, focus and keyboard order.
  * - The term is fixed to the subtitle type role and exposes no size prop or variant (docs/adr/0005).
- * - The description is body, muted, and capped at `--measure`; the term carries no measure cap.
+ *   The description is body, muted, and capped at `--measure`; the term carries no measure cap.
+ *   Density changes neither: `compact` pads each item from `--space-definition-item-compact` where
+ *   `comfortable` (the default) pads from `--space-definition-item`, and nothing else moves.
  * - A hairline sits above the first item and below every item, in `border`, and the block closes at
  *   the foot. No card, box, fill, icon or bullet - it reads from the rules alone.
- * - Single column below 64rem with the term above its description; two columns at and above it with a
- *   fixed term track and baseline-aligned rows. The switch is a media query, not a prop.
+ * - Every item shares one allocation: the term column and the description column each take a share
+ *   of the width left after the column gap in proportion to their weights, `1` and `2` unless the
+ *   caller says otherwise. The row holds while both shares are at least their minimum readable
+ *   width; the moment one falls short, every item in the list puts its terms above its description
+ *   at the full width, separated by the stack role. There is no in-between, and the minimum decides
+ *   the switch rather than flooring a width. For column gap g, total weight S and minimums m_i the
+ *   row fits at and above `g + max(m_i * S / w_i)`.
+ * - The width measured is the list's own, never the viewport, so a narrow list on a wide screen
+ *   stacks while a wide one beside it keeps its columns, and a theme that re-points a minimum -
+ *   at any scope - moves the threshold with it.
+ * - A long phrase or an unbroken value wraps inside its column; no content is truncated, nothing
+ *   overlaps, and the list never widens past its holder.
+ * - A non-positive or non-finite `weight`, or a `minWidth` that is not a custom-property name,
+ *   throws {@link DefinitionListConfigurationError}: a programmer error, raised loud and early.
  *
- * @UXGuidelines
+ * @CallerMustEnsure — the component cannot see these and does not check them
  * - Several `Term`s may share one `Description`; keep them inside one `Item` so the term column
  *   stays intact.
+ * - A `minWidth` token the caller names is declared, on the list or an ancestor of it, as a valid
+ *   nonnegative CSS length. The library's own two defaults are declared in every token stylesheet.
+ *   A missing or invalid token is not a responsive configuration: the threshold has nothing to
+ *   compare and the list stays stacked at every width.
+ * - The holder gives the list a definite width, as any block, grid track or Dialog content region
+ *   does. Inside a shrink-to-fit frame an inline-size container contributes no width of its own.
+ *
+ * @UXGuidelines
+ * - Choose `compact` for a fact list - short values beside their labels in a panel or a content
+ *   Dialog - and `comfortable` for a glossary. The choice is what the list holds, never how much
+ *   air a page wants.
+ * - A minimum is the width below which a column's content stops being readable - the narrowest
+ *   the labels keep their lines - not the width the designer would like; the stack is the readable
+ *   fallback. Weights are structural: `1` and `3` say the value is the subject and the term its
+ *   label, and a ratio chosen to hit a pixel width is a measurement, which the theme owns.
  */
 export const DefinitionList = {
   Root: DefinitionListRoot,

package/src/Display/DefinitionList/DefinitionListConfigurationError.ts

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

package/src/Display/Icon/Icon.tsx

@@ -0,0 +1,63 @@
+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
+// text it sits in and needs no colour or 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.
+const icon = cva('inline-block shrink-0 align-[-0.125em]');
+
+// Each name selects a drawing and nothing else: the three sort indicators are told apart by their
+// arrows, not by colour or size, so they survive forced-colors mode and a monochrome print.
+const drawings = {
+  sort: [
+    'M5.5 13V3',
+    'M3 5.5l2.5-2.5L8 5.5',
+    'M10.5 3v10',
+    'M8 10.5l2.5 2.5 2.5-2.5',
+  ],
+  'sort-ascending': ['M8 13V3', 'M4 7l4-4 4 4'],
+  'sort-descending': ['M8 3v10', 'M4 9l4 4 4-4'],
+} as const;
+
+export interface IIconProps {
+  /** Which drawing. A name selects a shape, never a state or a behaviour. */
+  name: keyof typeof drawings;
+  testId?: string;
+}
+
+/**
+ * A reusable visual glyph: the three sort indicators a consumer composes inside a header cell's
+ * plain Button, or beside any text that names what the icon reinforces.
+ *
+ * @Guarantees — enforced on every render
+ * - Hidden from assistive technology and out of the tab order: it adds no stop and no spoken name.
+ * - Scales with the surrounding font-size and takes the surrounding text colour.
+ * - The three drawings differ in shape, so the ordering is never carried by colour alone.
+ *
+ * @CallerMustEnsure
+ * - The control or text beside it carries the meaning: a `Button` label, a header cell's `ariaSort`.
+ *   An icon standing alone says nothing to a screen reader.
+ */
+export const Icon: FunctionComponent<IIconProps> = ({ name, testId }) => (
+  <svg
+    aria-hidden={true}
+    focusable={false}
+    viewBox={'0 0 16 16'}
+    width={'1em'}
+    height={'1em'}
+    className={icon()}
+    data-testid={testId}
+  >
+    {drawings[name].map((segment) => (
+      <path
+        key={segment}
+        d={segment}
+        fill={'none'}
+        stroke={'currentColor'}
+        strokeWidth={1.5}
+        strokeLinecap={'round'}
+        strokeLinejoin={'round'}
+      />
+    ))}
+  </svg>
+);