@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/RelativeDateInput/RelativeDateInput.tsx

@@ -0,0 +1,474 @@
+import { forwardRef, useEffect, useId, useState, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import { Cluster } from '../Cluster';
+import { DatePicker } from '../DatePicker';
+import { Input } from '../Input';
+import { Select } from '../Select';
+import { Stack } from '../Stack';
+import { Switch } from '../Switch';
+import { Text } from '../Text';
+import { useTranslation } from '../../i18n';
+import {
+  formatRelativeDate,
+  parseRelativeDate,
+  OFFSET_MAX,
+  ROLLING_MAX,
+  ROLLING_MIN,
+  type RelativeDateValue,
+  type RelativePeriod,
+  type RelativeScope,
+  type RelativeUnit,
+} from './relativeDate';
+import styles from './RelativeDateInput.module.scss';
+
+/** A quick-pick shown above the controls: the consumer's label and the expression it emits. */
+export interface RelativeDatePreset {
+  /** Visible button text (the consumer's, already translated). */
+  label: string;
+  /** Canonical expression emitted when the preset is chosen, e.g. `'last:30d'`. */
+  value: string;
+}
+
+export interface RelativeDateInputProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /**
+   * What the expression describes.
+   * - `'point'` — one date: an anchor (today, now, start/end of a period) plus a signed offset, or an exact date.
+   * - `'range'` — a date range: last/next N units, a whole this/last/next period, or a period to date.
+   */
+  mode: 'point' | 'range';
+  /** Datetime fields: offers the Now anchor with hour/minute offsets, and a minute-granular exact date (UTC `YYYY-MM-DDTHH:mm:ssZ`). Default `false`. */
+  allowNow?: boolean;
+  /** The controlled expression (see the grammar in the docs), or `null` for none. `null` shows the defaults (`today` / `this:month`) without emitting them. A value that doesn't parse shows the defaults plus an "Unrecognised value" note. */
+  value: string | null;
+  /** Fires with the next canonical expression after a valid edit, and only when it differs from `value`. Invalid drafts (an out-of-range amount, an exact date not yet picked) never fire it. */
+  onChange: (expr: string | null) => void;
+  /** Quick-pick toggle buttons rendered above the controls. The one whose `value` equals the canonical form of `value` is pressed (`last:07d` presses `last:7d`). */
+  presets?: readonly RelativeDatePreset[];
+  /** Disables every control, presets included. Default `false`. */
+  disabled?: boolean;
+  /** Error chrome on the controls (`aria-invalid`), e.g. from `<Field error>`. Default `false`. The Exact-date Switch is never marked invalid. */
+  invalid?: boolean;
+  /**
+   * Consumed for `<Field asGroup required>` composition, so Field can show its required
+   * marker. Adds no ARIA: `role="group"` does not support `aria-required` (ARIA 1.2), and
+   * the controls always show a value. Default `false`.
+   */
+  required?: boolean;
+}
+
+type Mode = RelativeDateInputProps['mode'];
+/** Range kinds: rolling past/coming N units, a whole calendar period, or a period to date. */
+type RangeKind = 'past' | 'coming' | 'calendar' | 'toDate';
+
+/** Every edit state the controls show; one shape for both modes. */
+interface Draft {
+  exact: boolean;
+  /** Canonical exact date, or `null` until one is picked. */
+  date: string | null;
+  /** `'today'`, `'now'` or `'{start|end}:{scope}:{period}'`. */
+  anchor: string;
+  sign: 1 | -1;
+  kind: RangeKind;
+  scope: RelativeScope;
+  period: RelativePeriod;
+  /** Raw numeric text, kept as typed so an invalid draft survives re-renders. */
+  amount: string;
+  unit: RelativeUnit;
+}
+
+const PERIODS: RelativePeriod[] = ['week', 'month', 'quarter', 'year'];
+const SCOPES: RelativeScope[] = ['this', 'last', 'next'];
+const DATE_UNITS: RelativeUnit[] = ['d', 'w', 'm', 'y'];
+const KINDS: RangeKind[] = ['past', 'coming', 'calendar', 'toDate'];
+const CALENDAR = SCOPES.flatMap((scope) => PERIODS.map((period) => ({ scope, period })));
+const BOUNDARIES = (['start', 'end'] as const).flatMap((edge) =>
+  SCOPES.flatMap((scope) => PERIODS.map((period) => ({ edge, scope, period }))),
+);
+
+const defaults = (mode: Mode): Draft => ({
+  exact: false,
+  date: null,
+  anchor: 'today',
+  sign: 1,
+  kind: 'calendar',
+  scope: 'this',
+  period: 'month',
+  amount: mode === 'point' ? '0' : '7',
+  unit: 'd',
+});
+
+/** Hours and minutes exist only on Now; leaving Now resets the offset (3h is not 3d). */
+const normalize = (d: Draft, mode: Mode): Draft =>
+  mode === 'point' && d.anchor !== 'now' && (d.unit === 'h' || d.unit === 'min')
+    ? { ...d, unit: 'd', amount: '0' }
+    : d;
+
+/**
+ * The draft for an incoming value. Fields the value doesn't carry keep `prev`'s
+ * (an exact date keeps the relative fields; a whole period keeps the rolling
+ * amount/unit), so switching back restores what the user had.
+ */
+function fromValue(parsed: RelativeDateValue | null, mode: Mode, prev: Draft): Draft {
+  if (!parsed) return defaults(mode);
+  const base = { ...prev, exact: false };
+  switch (parsed.kind) {
+    case 'exact':
+      return { ...prev, exact: true, date: parsed.date };
+    case 'anchor':
+    case 'boundary': {
+      const anchor =
+        parsed.kind === 'anchor'
+          ? parsed.anchor
+          : `${parsed.edge}:${parsed.scope}:${parsed.period}`;
+      const o = parsed.offset;
+      return normalize(
+        o
+          ? { ...base, anchor, sign: o.sign, amount: String(o.n), unit: o.unit }
+          : { ...base, anchor, amount: '0' },
+        mode,
+      );
+    }
+    case 'rolling':
+      return {
+        ...base,
+        kind: parsed.dir === 'last' ? 'past' : 'coming',
+        amount: String(parsed.n),
+        unit: parsed.unit,
+      };
+    case 'period':
+      return { ...base, kind: 'calendar', scope: parsed.scope, period: parsed.period };
+    case 'toDate':
+      return { ...base, kind: 'toDate', period: parsed.period };
+  }
+}
+
+const usesAmount = (d: Draft, mode: Mode) =>
+  mode === 'point' ? !d.exact : d.kind === 'past' || d.kind === 'coming';
+
+const amountLimits = (mode: Mode) =>
+  mode === 'point' ? { min: 0, max: OFFSET_MAX } : { min: ROLLING_MIN, max: ROLLING_MAX };
+
+/** The parsed amount, or `null` when it is not a whole number within the mode's limits. */
+function amountOf(d: Draft, mode: Mode): number | null {
+  if (!/^\d+$/.test(d.amount)) return null;
+  const n = Number(d.amount);
+  const { min, max } = amountLimits(mode);
+  return n >= min && n <= max ? n : null;
+}
+
+/** The value a draft stands for, or `null` while it is incomplete or invalid. */
+function toValue(d: Draft, mode: Mode): RelativeDateValue | null {
+  if (mode === 'point' && d.exact) return d.date ? { kind: 'exact', date: d.date } : null;
+  if (mode === 'range' && d.kind === 'calendar')
+    return { kind: 'period', scope: d.scope, period: d.period };
+  if (mode === 'range' && d.kind === 'toDate') return { kind: 'toDate', period: d.period };
+  const n = amountOf(d, mode);
+  if (n === null) return null;
+  if (mode === 'range') {
+    const unit = d.unit as 'd' | 'w' | 'm' | 'y';
+    return { kind: 'rolling', dir: d.kind === 'past' ? 'last' : 'next', n, unit };
+  }
+  const offset = { sign: d.sign, n, unit: d.unit };
+  if (d.anchor === 'today' || d.anchor === 'now')
+    return { kind: 'anchor', anchor: d.anchor, offset };
+  const [edge, scope, period] = d.anchor.split(':') as [
+    'start' | 'end',
+    RelativeScope,
+    RelativePeriod,
+  ];
+  return {
+    kind: 'boundary',
+    edge,
+    scope,
+    period,
+    offset: offset as { sign: 1 | -1; n: number; unit: 'd' | 'w' | 'm' | 'y' },
+  };
+}
+
+/** Exact date → Date for the picker: a local calendar day, or an instant for a UTC datetime. */
+function toPickerDate(date: string | null): Date | null {
+  if (!date) return null;
+  if (date.includes('T')) return new Date(date);
+  const [y, m, d] = date.split('-').map(Number);
+  return new Date(y, m - 1, d);
+}
+
+/** Picker Date → exact date: the local calendar day, or (with `allowNow`) UTC to the minute. */
+function fromPickerDate(date: Date, allowNow: boolean): string {
+  if (allowNow) return `${date.toISOString().slice(0, 16)}:00Z`;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/**
+ * Compact editor for one relative date or date-range expression (`today+7d`, `last:30d`, `this:quarter:to_date`).
+ * @see docs/components/RelativeDateInput.md
+ */
+export const RelativeDateInput = forwardRef<HTMLDivElement, RelativeDateInputProps>(
+  function RelativeDateInput(
+    {
+      mode,
+      allowNow = false,
+      value,
+      onChange,
+      presets,
+      disabled = false,
+      invalid = false,
+      // Consumed, not spread: `required` is not a valid attribute on a div.
+      required: _required,
+      className,
+      'aria-describedby': ariaDescribedby,
+      ...rest
+    },
+    ref,
+  ) {
+    const t = useTranslation();
+    const uid = useId();
+    const errorId = `${uid}-error`;
+    const noteId = `${uid}-note`;
+
+    const parse = (v: string | null) =>
+      v === null ? null : parseRelativeDate(v, { mode, allowNow });
+    const [draft, setDraft] = useState(() => fromValue(parse(value), mode, defaults(mode)));
+    // Re-derive the draft whenever `value`, `mode` or `allowNow` changes (render-phase
+    // update, no effect). A new mode starts from that mode's defaults.
+    const [seen, setSeen] = useState({ value, mode, allowNow });
+    if (value !== seen.value || mode !== seen.mode || allowNow !== seen.allowNow) {
+      setSeen({ value, mode, allowNow });
+      setDraft((prev) => fromValue(parse(value), mode, mode === seen.mode ? prev : defaults(mode)));
+    }
+
+    const unrecognised = value !== null && parse(value) === null;
+    const amountError = usesAmount(draft, mode) && amountOf(draft, mode) === null;
+
+    const commit = (patch: Partial<Draft>) => {
+      const next = normalize({ ...draft, ...patch }, mode);
+      setDraft(next);
+      const v = toValue(next, mode);
+      if (!v) return;
+      const expr = formatRelativeDate(v);
+      if (expr !== value) onChange(expr);
+    };
+
+    const opt = (v: string, label: string) => ({ value: v, label });
+    const pickOne = (fn: (v: string) => void) => (v: string | string[]) => fn(v as string);
+    // The note also describes every control: unnamed (inside `<Field asGroup>`) the root
+    // is a plain div, whose aria-describedby screen readers never announce.
+    const noteRef = unrecognised ? noteId : undefined;
+    const common = { size: 'sm' as const, disabled, invalid, 'aria-describedby': noteRef };
+
+    const amountInput = (
+      <Input
+        {...common}
+        className={styles.amount}
+        inputMode="numeric"
+        aria-label={t('relativeDateInput.amount')}
+        invalid={invalid || amountError}
+        aria-describedby={clsx(amountError && errorId, noteRef) || undefined}
+        value={draft.amount}
+        onChange={(e) => commit({ amount: e.target.value })}
+      />
+    );
+    const units =
+      mode === 'point' && draft.anchor === 'now' ? [...DATE_UNITS, 'h', 'min'] : DATE_UNITS;
+    const unitSelect = (
+      <Select
+        {...common}
+        className={styles.select}
+        aria-label={t('relativeDateInput.unit')}
+        // Labels agree with the current amount ("1 day", ru «21 день»); an invalid amount reads as plural.
+        options={units.map((u) =>
+          opt(u, t('relativeDateInput.units', { unit: u, n: amountOf(draft, mode) ?? 0 })),
+        )}
+        value={draft.unit}
+        onChange={pickOne((u) => commit({ unit: u as RelativeUnit }))}
+      />
+    );
+    const periodLabel = t('relativeDateInput.period');
+    const calendarSelect = (
+      <Select
+        {...common}
+        className={styles.select}
+        aria-label={periodLabel}
+        options={CALENDAR.map((c) =>
+          opt(`${c.scope}:${c.period}`, t('relativeDateInput.calendarPeriod', c)),
+        )}
+        value={`${draft.scope}:${draft.period}`}
+        onChange={pickOne((v) => {
+          const [scope, period] = v.split(':') as [RelativeScope, RelativePeriod];
+          commit({ scope, period });
+        })}
+      />
+    );
+    const toDateSelect = (
+      <Select
+        {...common}
+        className={styles.select}
+        aria-label={periodLabel}
+        options={PERIODS.map((period) =>
+          opt(period, t('relativeDateInput.periodToDate', { period })),
+        )}
+        value={draft.period}
+        onChange={pickOne((p) => commit({ period: p as RelativePeriod }))}
+      />
+    );
+
+    let controls;
+    if (mode === 'range') {
+      controls = (
+        <>
+          <Select
+            {...common}
+            className={styles.select}
+            aria-label={t('relativeDateInput.kind')}
+            options={KINDS.map((k) => opt(k, t(`relativeDateInput.kinds.${k}`)))}
+            value={draft.kind}
+            onChange={pickOne((k) => commit({ kind: k as RangeKind }))}
+          />
+          {draft.kind === 'calendar' ? (
+            calendarSelect
+          ) : draft.kind === 'toDate' ? (
+            toDateSelect
+          ) : (
+            <>
+              {amountInput}
+              {unitSelect}
+            </>
+          )}
+        </>
+      );
+    } else {
+      controls = (
+        <>
+          {draft.exact ? (
+            <DatePicker
+              size="sm"
+              disabled={disabled}
+              invalid={invalid}
+              className={styles.select}
+              aria-label={t('relativeDateInput.date')}
+              granularity={allowNow ? 'minute' : 'day'}
+              clearable={false}
+              value={toPickerDate(draft.date)}
+              onChange={(d) => d && commit({ date: fromPickerDate(d, allowNow) })}
+            />
+          ) : (
+            <>
+              <Select
+                {...common}
+                className={styles.select}
+                aria-label={t('relativeDateInput.anchor')}
+                options={[
+                  opt('today', t('relativeDateInput.today')),
+                  ...(allowNow ? [opt('now', t('relativeDateInput.now'))] : []),
+                  ...BOUNDARIES.map((b) =>
+                    opt(`${b.edge}:${b.scope}:${b.period}`, t('relativeDateInput.boundary', b)),
+                  ),
+                ]}
+                value={draft.anchor}
+                onChange={pickOne((a) => commit({ anchor: a }))}
+              />
+              <Select
+                {...common}
+                className={styles.select}
+                aria-label={t('relativeDateInput.sign')}
+                options={[opt('+', '+'), opt('-', '−')]}
+                value={draft.sign === 1 ? '+' : '-'}
+                onChange={pickOne((s) => commit({ sign: s === '-' ? -1 : 1 }))}
+              />
+              {amountInput}
+              {unitSelect}
+            </>
+          )}
+          <Switch
+            size="sm"
+            disabled={disabled}
+            checked={draft.exact}
+            // Toggling on waits for a pick; toggling off restores the kept relative fields.
+            onChange={(on) => commit(on ? { exact: true, date: null } : { exact: false })}
+          >
+            {t('relativeDateInput.exactDate')}
+          </Switch>
+        </>
+      );
+    }
+
+    // The expression the controls currently show, only while the draft agrees with
+    // `value` (compared canonically, so `last:07d` presses a `last:7d` preset), so
+    // no preset reads as pressed over an invalid or unpicked draft.
+    const drafted = toValue(draft, mode);
+    const parsedValue = parse(value);
+    const canonical = parsedValue ? formatRelativeDate(parsedValue) : value;
+    const shown = drafted && formatRelativeDate(drafted) === canonical ? canonical : null;
+
+    // Only a named group is a group; unnamed (e.g. inside `<Field asGroup>`, which is
+    // the group) it would be an extra, nameless landmark for screen readers.
+    const named = rest['aria-label'] != null || rest['aria-labelledby'] != null;
+    const describedBy = clsx(ariaDescribedby, named && noteRef) || undefined;
+    // A preset must parse in this mode, or choosing it would emit an unrecognised value.
+    const isValidPreset = (p: RelativeDatePreset) => parse(p.value) !== null;
+    const badPresets = (presets ?? [])
+      .filter((p) => !isValidPreset(p))
+      .map((p) => p.value)
+      .join(', ');
+    // Keyed on content (a string), so equal arrays don't re-warn per render.
+    useEffect(() => {
+      if (process.env.NODE_ENV === 'production' || !badPresets) return;
+      console.warn(
+        `<RelativeDateInput>: ignoring presets that don't parse in this mode: ${badPresets}`,
+      );
+    }, [badPresets]);
+
+    return (
+      // {...rest} first so the group role and merged aria-describedby win.
+      <Stack
+        gap="sm"
+        {...rest}
+        ref={ref}
+        role={named ? 'group' : undefined}
+        aria-describedby={describedBy}
+        className={className}
+      >
+        {presets && presets.length > 0 && (
+          <Cluster gap="xs">
+            {presets.map((p) => (
+              <Button
+                key={p.value}
+                size="sm"
+                variant="secondary"
+                disabled={disabled || !isValidPreset(p)}
+                selected={p.value === shown}
+                aria-pressed={p.value === shown}
+                onClick={() =>
+                  p.value === value
+                    ? // Same value, diverged draft (e.g. Exact date on, nothing picked): restore it.
+                      setDraft(fromValue(parse(value), mode, draft))
+                    : onChange(p.value)
+                }
+              >
+                {p.label}
+              </Button>
+            ))}
+          </Cluster>
+        )}
+        <Cluster gap="xs" align="center" className={styles.row}>
+          {controls}
+        </Cluster>
+        {amountError && (
+          <Text id={errorId} size="sm" tone="danger">
+            {t('relativeDateInput.errorRange', amountLimits(mode))}
+          </Text>
+        )}
+        {unrecognised && (
+          <Text id={noteId} size="sm" tone="muted">
+            {t('relativeDateInput.unrecognised', { value })}
+          </Text>
+        )}
+      </Stack>
+    );
+  },
+);

package/src/components/RelativeDateInput/index.ts

@@ -0,0 +1,10 @@
+export { RelativeDateInput } from './RelativeDateInput';
+export type { RelativeDateInputProps, RelativeDatePreset } from './RelativeDateInput';
+export { parseRelativeDate, formatRelativeDate } from './relativeDate';
+export type {
+  RelativeDateValue,
+  RelativeDateOptions,
+  RelativePeriod,
+  RelativeScope,
+  RelativeUnit,
+} from './relativeDate';

package/src/components/RelativeDateInput/relativeDate.ts

@@ -0,0 +1,127 @@
+export type RelativePeriod = 'week' | 'month' | 'quarter' | 'year';
+export type RelativeScope = 'this' | 'last' | 'next';
+export type RelativeUnit = 'd' | 'w' | 'm' | 'y' | 'h' | 'min';
+export type RelativeDateValue =
+  | {
+      kind: 'anchor';
+      anchor: 'today' | 'now';
+      offset?: { sign: 1 | -1; n: number; unit: RelativeUnit };
+    }
+  | {
+      kind: 'boundary';
+      edge: 'start' | 'end';
+      scope: RelativeScope;
+      period: RelativePeriod;
+      offset?: { sign: 1 | -1; n: number; unit: 'd' | 'w' | 'm' | 'y' };
+    }
+  | { kind: 'exact'; date: string } // 'YYYY-MM-DD' or 'YYYY-MM-DDTHH:mm:ssZ'
+  | { kind: 'rolling'; dir: 'last' | 'next'; n: number; unit: 'd' | 'w' | 'm' | 'y' }
+  | { kind: 'period'; scope: RelativeScope; period: RelativePeriod }
+  | { kind: 'toDate'; period: RelativePeriod };
+
+export interface RelativeDateOptions {
+  mode: 'point' | 'range';
+  allowNow?: boolean;
+}
+
+export const OFFSET_MAX = 1000;
+export const ROLLING_MIN = 1;
+export const ROLLING_MAX = 1000;
+
+const ANCHOR_RE = /^(today|now)(?:([+-])(\d{1,4})(d|w|m|y|h|min))?$/;
+const BOUNDARY_RE =
+  /^(start|end):(this|last|next):(week|month|quarter|year)(?:([+-])(\d{1,4})(d|w|m|y))?$/;
+const EXACT_RE = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})Z)?$/;
+const ROLLING_RE = /^(last|next):(\d{1,4})(d|w|m|y)$/;
+const PERIOD_RE = /^(this|last|next):(week|month|quarter|year)$/;
+const TO_DATE_RE = /^this:(week|month|quarter|year):to_date$/;
+
+function parseOffset(sign: string | undefined, n: string | undefined, unit: string | undefined) {
+  if (sign === undefined) return { ok: true as const, offset: undefined };
+  const num = Number(n);
+  if (num > OFFSET_MAX) return { ok: false as const };
+  return {
+    ok: true as const,
+    offset: { sign: (sign === '-' ? -1 : 1) as 1 | -1, n: num, unit: unit as RelativeUnit },
+  };
+}
+
+function isRealDate(m: RegExpExecArray): boolean {
+  const [y, mo, d, h = 0, mi = 0, s = 0] = m.slice(1).map((x) => (x === undefined ? 0 : Number(x)));
+  if (h > 23 || mi > 59 || s > 59) return false;
+  const dt = new Date(Date.UTC(y, mo - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d;
+}
+
+export function parseRelativeDate(
+  expr: string,
+  opts: RelativeDateOptions,
+): RelativeDateValue | null {
+  const allowNow = opts.allowNow === true;
+  if (opts.mode === 'point') {
+    let m = ANCHOR_RE.exec(expr);
+    if (m) {
+      const anchor = m[1] as 'today' | 'now';
+      if (anchor === 'now' && !allowNow) return null;
+      if (anchor === 'today' && (m[4] === 'h' || m[4] === 'min')) return null;
+      const o = parseOffset(m[2], m[3], m[4]);
+      if (!o.ok) return null;
+      return o.offset ? { kind: 'anchor', anchor, offset: o.offset } : { kind: 'anchor', anchor };
+    }
+    m = BOUNDARY_RE.exec(expr);
+    if (m) {
+      const o = parseOffset(m[4], m[5], m[6]);
+      if (!o.ok) return null;
+      const base = {
+        kind: 'boundary' as const,
+        edge: m[1] as 'start' | 'end',
+        scope: m[2] as RelativeScope,
+        period: m[3] as RelativePeriod,
+      };
+      return o.offset
+        ? { ...base, offset: o.offset as { sign: 1 | -1; n: number; unit: 'd' | 'w' | 'm' | 'y' } }
+        : base;
+    }
+    m = EXACT_RE.exec(expr);
+    if (m && isRealDate(m) && (m[4] === undefined || allowNow))
+      return { kind: 'exact', date: expr };
+    return null;
+  }
+  let m = ROLLING_RE.exec(expr);
+  if (m) {
+    const n = Number(m[2]);
+    if (n < ROLLING_MIN || n > ROLLING_MAX) return null;
+    return {
+      kind: 'rolling',
+      dir: m[1] as 'last' | 'next',
+      n,
+      unit: m[3] as 'd' | 'w' | 'm' | 'y',
+    };
+  }
+  m = PERIOD_RE.exec(expr);
+  if (m) return { kind: 'period', scope: m[1] as RelativeScope, period: m[2] as RelativePeriod };
+  m = TO_DATE_RE.exec(expr);
+  if (m) return { kind: 'toDate', period: m[1] as RelativePeriod };
+  return null;
+}
+
+function formatOffset(o?: { sign: 1 | -1; n: number; unit: string }): string {
+  return o && o.n !== 0 ? `${o.sign === -1 ? '-' : '+'}${o.n}${o.unit}` : '';
+}
+
+export function formatRelativeDate(v: RelativeDateValue): string {
+  switch (v.kind) {
+    case 'anchor':
+      return v.anchor + formatOffset(v.offset);
+    case 'boundary':
+      return `${v.edge}:${v.scope}:${v.period}${formatOffset(v.offset)}`;
+    case 'exact':
+      return v.date;
+    case 'rolling':
+      return `${v.dir}:${v.n}${v.unit}`;
+    case 'period':
+      return `${v.scope}:${v.period}`;
+    case 'toDate':
+      return `this:${v.period}:to_date`;
+  }
+}

package/src/components/RichText/RichText.module.scss

@@ -0,0 +1,5 @@
+@use './prose';
+
+.root {
+  @include prose.prose;
+}

package/src/components/RichText/RichText.tsx

@@ -0,0 +1,70 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import type { RichDoc } from './engine/model';
+import { renderDoc } from './engine/renderDoc';
+import type { RenderLink } from './engine/renderLink';
+import type { RenderMention } from './engine/renderMention';
+import { imageMaxHeightStyle } from './imageMaxHeightStyle';
+import styles from './RichText.module.scss';
+
+export interface RichTextProps extends HTMLAttributes<HTMLDivElement> {
+  /** The document to render. Build one with `emptyDoc()` / `createBlock()` or the transforms. */
+  value: RichDoc;
+  /**
+   * Substitute how a link renders. Called per link with `{ href, text }` and the
+   * default `<a>` node; return your own node (e.g. a task/member chip) or the
+   * `defaultNode` to keep the standard anchor. Render-time only — the document
+   * model is unchanged, so serialization still emits a plain link.
+   *
+   * Prose link styling (accent colour + underline) applies to BARE anchors
+   * only: an `<a>` you return with any `className` — including a DS `<Link>` —
+   * keeps its own decoration and colour entirely (#570).
+   *
+   * @remarks Keep it cheap — it runs on every render. Don't block on a network
+   * call inside `renderLink`; return a component that fetches/caches the lookup
+   * itself (or falls back to `defaultNode` while loading).
+   */
+  renderLink?: RenderLink;
+  /**
+   * Substitute how an `@`-mention renders. Called per mention with `{ id, label }`
+   * and the default mention span; return your own node (e.g. an interactive member
+   * chip / popover trigger) or the `defaultNode` to keep the standard
+   * non-interactive span. Render-time only — the document model is unchanged, so
+   * serialization still emits the mention mark. Composes with `renderLink`.
+   *
+   * @remarks Keep it cheap — it runs on every render. Don't block on a network
+   * call inside `renderMention`; return a component that fetches/caches the lookup
+   * itself (or falls back to `defaultNode` while loading).
+   */
+  renderMention?: RenderMention;
+  /**
+   * Maximum DISPLAYED height of image attachments, in px. Default: the
+   * `--size-rich-text-image-max-height` token (480px). A taller image shrinks
+   * (width follows, aspect preserved) — render-time only; stored `width`/`height`
+   * are unchanged, so existing documents need no migration. There is no "off":
+   * pass a large value to effectively remove the cap.
+   */
+  imageMaxHeight?: number;
+}
+
+/**
+ * Read-only renderer for a `RichDoc` (paragraphs, headings, lists, quotes, code blocks, inline marks) on the in-house engine.
+ * @see docs/components/RichText.md
+ */
+export const RichText = forwardRef<HTMLDivElement, RichTextProps>(function RichText(
+  { value, renderLink, renderMention, imageMaxHeight, className, style, ...props },
+  ref,
+) {
+  // {...props} last so the consumer can override anything except the composed
+  // className and style (Pattern A — consumer wins).
+  return (
+    <div
+      ref={ref}
+      className={clsx(styles.root, className)}
+      style={imageMaxHeightStyle(imageMaxHeight, style)}
+      {...props}
+    >
+      {renderDoc(value, { renderLink, renderMention })}
+    </div>
+  );
+});