@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/_internal/choiceTile.scss

@@ -0,0 +1,74 @@
+// Shared look for DateStrip / SlotGrid tiles: a <label> wrapping a visually
+// hidden native radio. Unchecked = Button secondary, checked = Button primary.
+// Consumers of the mixin pass their component tokens so each stays themable.
+@use '../../styles/mixins' as *;
+
+@mixin choice-tile(
+  $input,
+  $bg,
+  $bg-hover,
+  $fg,
+  $border,
+  $bg-checked,
+  $bg-checked-hover,
+  $fg-checked,
+  $radius,
+  $ring,
+  $opacity-disabled
+) {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  border: var(--border-width) solid $border;
+  border-radius: $radius;
+  background: $bg;
+  color: $fg;
+  font: inherit;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background var(--transition-fast),
+    border-color var(--transition-fast),
+    color var(--transition-fast);
+
+  #{$input} {
+    @include visually-hidden;
+  }
+
+  &:hover:not(:has(#{$input}:disabled)) {
+    background: $bg-hover;
+  }
+
+  &:has(#{$input}:checked) {
+    border-color: transparent;
+    background: $bg-checked;
+    color: $fg-checked;
+  }
+
+  &:has(#{$input}:checked):hover {
+    background: $bg-checked-hover;
+  }
+
+  &:has(#{$input}:focus-visible) {
+    @include focus-ring($ring);
+  }
+
+  &:has(#{$input}:disabled) {
+    opacity: $opacity-disabled;
+    cursor: not-allowed;
+  }
+
+  // Forced colors (Windows High Contrast) drops backgrounds, which is all
+  // that marks the checked tile — add an outline outside its border (text
+  // color, forced to a system color) so checked still reads as different.
+  // Not while focus-visible: this rule would come after the focus ring and
+  // replace it (arrows select as they move, so the focused tile is usually
+  // the checked one) — the ring is the stronger signal there.
+  @media (forced-colors: active) {
+    &:has(#{$input}:checked:not(:focus-visible)) {
+      outline: var(--border-width) solid currentcolor;
+    }
+  }
+}

package/src/components/_internal/collapse.scss

@@ -0,0 +1,10 @@
+// Container-width collapse thresholds shared by Grid's `collapseBelow` and
+// Sortable's grid-arrangement `collapseBelow`. SCSS constants (not CSS custom
+// properties): container-query conditions can't read custom properties.
+// Keep in sync with the CollapseBreakpoint JSDoc AND the COLLAPSE_BREAKPOINT_PX
+// record in collapse.ts — Rail evaluates the same scale in JS via matchMedia
+// (against the VIEWPORT, since a container query on the rail's own width would
+// be circular), so the two copies of these numbers must not drift.
+$collapse-sm: 480px;
+$collapse-md: 640px;
+$collapse-lg: 768px;

package/src/components/_internal/collapse.ts

@@ -0,0 +1,58 @@
+import { createContext } from 'react';
+
+/**
+ * Shared `collapseBelow` threshold scale: `sm` 480px / `md` 640px / `lg` 768px.
+ *
+ * The scale is shared; **the measurement basis is per-component**:
+ *
+ * - **Container** (`@container (max-width: …)`) for Grid / Sortable (grid
+ *   arrangement) / Split / DashboardCanvas / DataTable. Collapsing re-templates
+ *   content *inside* a box whose width the collapse doesn't change, so querying
+ *   the box's own width is stable and needs no JS.
+ * - **Viewport** (`matchMedia`, via the `useBelowBreakpoint` hook in
+ *   `src/hooks/`) for Rail and AppLayout's overlay sidebar. A container query
+ *   there would be circular — the thing being measured IS what the collapse
+ *   changes (Rail's own width 240px → 56px; the sidebar's presence in
+ *   AppLayout's row). Rail's collapsed state also drives React behavior (Item
+ *   tooltips, Group flyouts, section titles), which CSS can't express, so the
+ *   threshold has to exist in JS regardless.
+ */
+export type CollapseBreakpoint = 'sm' | 'md' | 'lg';
+
+/**
+ * Pixel value of each breakpoint, for components that evaluate the threshold in
+ * JS (`matchMedia`) rather than in CSS.
+ *
+ * **Keep in sync with `collapse.scss`** (`$collapse-sm` / `-md` / `-lg`) — the
+ * SCSS constants are the CSS-side copy of these same numbers. Both are
+ * inclusive upper bounds: `max-width: 480px` matches AT 480px.
+ */
+export const COLLAPSE_BREAKPOINT_PX: Record<CollapseBreakpoint, number> = {
+  sm: 480,
+  md: 640,
+  lg: 768,
+};
+
+/**
+ * Graduated collapse: breakpoint → column count. Below each breakpoint the
+ * grid re-templates to that many equal columns and every item's span is
+ * clamped to fit. E.g. `{ md: 6, sm: 1 }` = 12-col grid above 640px, 6-col
+ * between 480–640px, single column below 480px. When several breakpoints
+ * match, the smallest wins.
+ */
+export type CollapseColumnsMap = Partial<Record<CollapseBreakpoint, number>>;
+
+/** Largest → smallest; step CSS is declared in this order so the smallest matching breakpoint wins by source order. */
+export const COLLAPSE_BREAKPOINTS: readonly CollapseBreakpoint[] = ['lg', 'md', 'sm'];
+
+/**
+ * The container's graduated-collapse map, provided by Grid / Sortable (grid
+ * arrangement) to their Items so each can stamp per-breakpoint clamped span
+ * custom properties. `null` when the container has no map-form collapse.
+ */
+export const CollapseColumnsContext = createContext<CollapseColumnsMap | null>(null);
+
+/** Track template for a collapse step — mirrors Grid's fixed-column template. */
+export function collapseTrackTemplate(columns: number): string {
+  return `repeat(${columns}, minmax(0, 1fr))`;
+}

package/src/components/_internal/currency.ts

@@ -0,0 +1,257 @@
+/** Shared currency parse/format helpers for MoneyInput / CurrencySelect. Amounts stay strings (never JS numbers). */
+
+export type CurrencyDisplay = 'code' | 'symbol' | 'both';
+
+/** Parsed, in-progress amount. `frac === null` → no decimal point typed; `''` → trailing point. */
+export interface AmountDraft {
+  negative: boolean;
+  int: string;
+  frac: string | null;
+}
+
+// Callers must guard codes with isValidCurrency; the Intl helpers below assume a valid code.
+export function currencyPrecision(code: string): number {
+  return new Intl.NumberFormat('en', { style: 'currency', currency: code }).resolvedOptions()
+    .maximumFractionDigits!;
+}
+
+export function currencySymbol(code: string, locale: string): string {
+  const parts = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: code,
+    currencyDisplay: 'symbol',
+  }).formatToParts(0);
+  return parts.find((p) => p.type === 'currency')?.value ?? code;
+}
+
+export function currencyName(code: string, locale: string): string {
+  try {
+    return new Intl.DisplayNames(locale, { type: 'currency' }).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}
+
+export function currencyDisplayText(
+  code: string,
+  display: CurrencyDisplay,
+  locale: string,
+): string {
+  if (display === 'code') return code;
+  const symbol = currencySymbol(code, locale);
+  return display === 'symbol' ? symbol : `${code} ${symbol}`;
+}
+
+export function isValidCurrency(code: string): boolean {
+  try {
+    new Intl.NumberFormat('en', { style: 'currency', currency: code });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function localeSeparators(locale: string): { group: string; decimal: string } {
+  const parts = new Intl.NumberFormat(locale).formatToParts(1234.5);
+  return {
+    group: parts.find((p) => p.type === 'group')?.value ?? ',',
+    decimal: parts.find((p) => p.type === 'decimal')?.value ?? '.',
+  };
+}
+
+/** Space-like grouping chars allowed inside a pasted number (one kind per number). */
+const SPACE_GROUP = /[   '’]/g;
+// One affix token: currency symbols and/or one letter word ('US$', 'руб.', prefix label 'Total:').
+const PREFIX_TOKEN = /^(?:\p{Sc}*\p{L}+[.:]?\p{Sc}*|\p{Sc}+)$/u;
+const SUFFIX_TOKEN = /^(?:\p{Sc}*\p{L}+\.?\p{Sc}*|\p{Sc}+)$/u;
+const SUFFIX_WORDS = new Set(['руб', 'р']);
+let isoCodes: Set<string> | undefined;
+/** A real ISO 4217 code (not merely well-formed), so magnitude words ('K', 'bn', 'млн') never pass. */
+// Without Intl.supportedValuesOf no suffix word counts as a currency (reject, never throw).
+const isIsoCode = (w: string) =>
+  (isoCodes ??= new Set(
+    typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('currency') : [],
+  )).has(w.toUpperCase());
+
+/**
+ * Splits one affix side into sign marks; null when anything but symbols / ONE word / sign remains.
+ * A prefix word is a free label ('Total', 'Итого:'); a suffix word must be a currency
+ * (ISO code or 'руб'/'р') — anything else may be a magnitude ('5 тыс.', '$2 million').
+ */
+function readAffix(side: string, open: string, signs: string, suffix: boolean) {
+  const marks = { open: 0, minus: 0, plus: 0 };
+  for (const c of side) {
+    if (c === open) marks.open++;
+    else if (c === '-' && signs.includes('-')) marks.minus++;
+    else if (c === '+' && signs.includes('+')) marks.plus++;
+  }
+  const rest = side.replace(new RegExp(`[\\${open}${signs.replace('-', '\\-')}]`, 'g'), ' ');
+  const tokens = rest.split(/[   ]+/).filter(Boolean);
+  if (!tokens.every((tk) => (suffix ? SUFFIX_TOKEN : PREFIX_TOKEN).test(tk))) return null;
+  const words = tokens.map((tk) => tk.replace(/[^\p{L}]/gu, '')).filter(Boolean);
+  if (words.length > 1) return null;
+  if (suffix && words.length && !SUFFIX_WORDS.has(words[0].toLowerCase()) && !isIsoCode(words[0]))
+    return null;
+  return marks;
+}
+
+/**
+ * Lenient parse of a PASTED segment: exactly one number, with optional currency symbols / one word
+ * per side, a sign ('-', '−', '+', trailing '-') or accounting parentheses. Grouping must be
+ * unambiguous (first group 1–3 digits, then exactly 3, one group char kind); the cross-locale rules
+ * pick the decimal. Anything doubtful → `'invalid'`; no digits at all → `null`.
+ */
+export function parseAmount(
+  text: string,
+  opts: { locale: string; precision: number; allowNegative: boolean },
+): AmountDraft | null | 'invalid' {
+  const t = text.replace(/−/g, '-').trim().replace(/\.$/, ''); // trailing sentence period
+  const first = t.search(/\d/);
+  if (first < 0) return null;
+  let last = t.length - 1;
+  while (!/\d/.test(t[last])) last--;
+  // '.5' — but a separator glued to a word belongs to it ('Rs.100', 'руб.10').
+  const leadingSep = /[.,]/.test(t[first - 1] ?? '') && !/\p{L}/u.test(t[first - 2] ?? '');
+  const from = leadingSep ? first - 1 : first;
+  // Letters glued to the number ('5K', '3bn', 'USD5') are magnitudes or noise.
+  if (/\p{L}/u.test(t[from - 1] ?? '') || /\p{L}/u.test(t[last + 1] ?? '')) return 'invalid';
+  const core = t.slice(from, last + 1);
+
+  const pre = readAffix(t.slice(0, from), '(', '-+', false);
+  const post = readAffix(t.slice(last + 1), ')', '-', true);
+  if (!pre || !post) return 'invalid';
+  const parens = pre.open + post.open;
+  const signs = pre.minus + pre.plus + post.minus;
+  if (pre.open > 1 || post.open > 1 || parens === 1 || signs > 1 || (parens && signs)) {
+    return 'invalid';
+  }
+  const negative = opts.allowNegative && (parens === 2 || pre.minus + post.minus === 1);
+
+  if (!/^[\d.,]+$/.test(core.replace(SPACE_GROUP, ''))) return 'invalid'; // tab, newline, '-', letters
+  const { group: lg, decimal: ld } = localeSeparators(opts.locale);
+  const count = (c: string) => core.split(c).length - 1;
+  const dots = count('.');
+  const commas = count(',');
+  let dec: string | null = null;
+  let grp: string | null = null;
+  if (dots && commas) {
+    dec = core.lastIndexOf('.') > core.lastIndexOf(',') ? '.' : ',';
+    grp = dec === '.' ? ',' : '.';
+    if (count(dec) > 1) return 'invalid';
+  } else if (dots > 1 || commas > 1) {
+    grp = dots ? '.' : ',';
+  } else if (dots || commas) {
+    const c = dots ? '.' : ',';
+    const fracLen = core.length - core.indexOf(c) - 1;
+    if (c === ld) dec = c;
+    // Numpad-dot rule: in a comma-decimal locale, a lone '.' + 1..precision digits is a decimal.
+    else if (
+      c === '.' &&
+      ld === ',' &&
+      opts.precision <= 2 &&
+      fracLen >= 1 &&
+      fracLen <= opts.precision
+    )
+      dec = c;
+    // Neither the locale's group nor its decimal + exactly 3 digits (ru '1.234'): don't guess.
+    else if (c !== lg && fracLen === 3) return 'invalid';
+    else if (c === lg || c === '.') grp = c;
+    else dec = c;
+    // '1,234' / '1.234' as a decimal below precision 3 could equally be grouping: don't guess.
+    if (dec && fracLen === 3 && opts.precision < 3) return 'invalid';
+  }
+  const spaces = new Set(core.match(SPACE_GROUP) ?? []);
+  if (spaces.size) {
+    if (grp || spaces.size > 1) return 'invalid'; // one group char kind
+    grp = [...spaces][0];
+  }
+
+  const at = dec ? core.indexOf(dec) : -1;
+  const intPart = at < 0 ? core : core.slice(0, at);
+  const fracPart = at < 0 ? null : core.slice(at + 1);
+  if (fracPart !== null && !/^\d*$/.test(fracPart)) return 'invalid';
+  if (grp) {
+    const groups = intPart.split(grp);
+    if (!/^\d{1,3}$/.test(groups[0]) || !groups.slice(1).every((g) => /^\d{3}$/.test(g))) {
+      return 'invalid';
+    }
+  } else if (!/^\d*$/.test(intPart)) return 'invalid';
+
+  const int = grp ? intPart.split(grp).join('') : intPart;
+  // Full fraction: the caller truncates (whole-value paste) or rejects the overflow (partial paste).
+  const frac = fracPart;
+  return { negative, int, frac };
+}
+
+/**
+ * Strict parse of the field's OWN text: only the locale group char is stripped and only the
+ * locale decimal is a decimal. No cross-locale or numpad guessing.
+ */
+export function parseLocalAmount(
+  text: string,
+  opts: { locale: string; precision: number; allowNegative: boolean },
+): AmountDraft | null {
+  const { group, decimal } = localeSeparators(opts.locale);
+  const s = [...text.split(group).join('')]
+    .filter((c) => (c >= '0' && c <= '9') || c === decimal || c === '-')
+    .join('');
+  if (!s) return null;
+  const negative = opts.allowNegative && s.startsWith('-');
+  return toDraft(s.replace(/-/g, ''), decimal, opts.precision, negative);
+}
+
+function toDraft(s: string, decimal: string, precision: number, negative: boolean) {
+  const at = s.indexOf(decimal);
+  const digits = (v: string) => v.replace(/\D/g, '');
+  const int = digits(at < 0 ? s : s.slice(0, at));
+  const frac = at < 0 ? null : digits(s.slice(at + 1)).slice(0, precision);
+  if (!int && frac === null && !negative) return null;
+  return { negative, int, frac };
+}
+
+/** Prefix '-' only for a negative with a non-zero digit (never '-0' / '-0.00'). */
+const signed = (negative: boolean, body: string) =>
+  (negative && /[1-9]/.test(body) ? '-' : '') + body;
+
+export function draftToCanonical(d: AmountDraft): string | null {
+  // A lone decimal separator ('.', ',') is a partial draft, not zero (#663).
+  if (!d.int && !d.frac) return null;
+  const int = d.int.replace(/^0+(?=\d)/, '') || '0';
+  const body = `${int}${d.frac ? `.${d.frac}` : ''}`;
+  return signed(d.negative, body);
+}
+
+export function canonicalToDraft(s: string | null): AmountDraft | null {
+  if (s === null || s === '') return null;
+  const negative = s.startsWith('-');
+  const [int, frac] = (negative ? s.slice(1) : s).split('.');
+  // Strip leading zeros so an external '0012.5' displays like typed input would (#663).
+  return { negative, int: int.replace(/^0+(?=\d)/, ''), frac: frac ?? null };
+}
+
+export function formatDraft(
+  d: AmountDraft,
+  opts: { locale: string; precision: number; pad: boolean },
+): string {
+  const { group, decimal } = localeSeparators(opts.locale);
+  const sign = d.negative ? '-' : '';
+  // A lone separator shows as itself, not '0.': a synthesized 0 would parse back as an amount (#663).
+  if (!d.int && !d.frac) return d.frac === null || opts.precision === 0 ? sign : sign + decimal;
+  const int = (d.int || '0').replace(/\B(?=(\d{3})+$)/g, group);
+  if (opts.precision === 0) return sign + int;
+  let frac = d.frac === null ? null : d.frac.slice(0, opts.precision);
+  if (opts.pad) frac = (frac ?? '').padEnd(opts.precision, '0');
+  return sign + int + (frac === null ? '' : decimal + frac);
+}
+
+/** String half-up (away from zero) rounding; never pads. */
+export function roundAmount(canonical: string, precision: number): string {
+  const negative = canonical.startsWith('-');
+  const [int, frac = ''] = (negative ? canonical.slice(1) : canonical).split('.');
+  if (frac.length <= precision) return signed(negative, canonical.slice(negative ? 1 : 0));
+  let n = BigInt(int + frac.slice(0, precision));
+  if (frac[precision] >= '5') n += 1n;
+  const s = n.toString().padStart(precision + 1, '0');
+  const cut = s.length - precision;
+  return signed(negative, precision ? `${s.slice(0, cut)}.${s.slice(cut)}` : s);
+}

package/src/components/_internal/dragAnnouncements.ts

@@ -0,0 +1,200 @@
+// dragAnnouncements.ts — localized screen-reader copy for dnd-kit drags.
+//
+// dnd-kit's built-in announcements are hard-coded English AND interpolate raw
+// ids ("Draggable item deal-7 was moved over droppable area col-3"), which is
+// both a Hard rule 9 violation and useless to a listener. Every `<DndContext>`
+// in the library passes `accessibility={useDragAccessibility(...)}` instead.
+//
+// Internal — not exported from `src/index.ts`.
+import { useMemo, useRef, type RefObject } from 'react';
+import type { Active, Announcements, ScreenReaderInstructions } from '@dnd-kit/core';
+import { useTranslation } from '../../i18n';
+
+/** Collapse whitespace and cap the length so an announcement stays listenable. */
+export function tidy(text: string): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > 80 ? `${flat.slice(0, 79)}…` : flat;
+}
+
+/**
+ * What a draggable publishes on its dnd-kit `data` so the announcements can
+ * name it. Read with `dragLabelOf`.
+ */
+export interface DragLabelData {
+  /** Consumer's explicit `aria-label`. Wins outright when set. */
+  dragLabel?: string;
+  /** The rendered node to read text from when there is no explicit label. */
+  dragNode?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * The name to announce for a draggable: the consumer's `aria-label` if there is
+ * one, else the node's rendered text.
+ *
+ * Reading the DOM rather than walking the React children is deliberate. A card
+ * with a `<DropdownMenu>` / `<Tooltip>` / `<ConfirmationPopover>` in it has the
+ * closed panel's contents in its children tree but NOT in the document, so a
+ * children walk announces "Draft Q3 OKRs View Archive" while the DOM announces
+ * "Draft Q3 OKRs". Collapsed and portalled subtrees drop out by construction.
+ */
+export function dragLabelOf(data: Record<string, unknown> | undefined): string | undefined {
+  const { dragLabel, dragNode } = (data ?? {}) as DragLabelData;
+  if (typeof dragLabel === 'string' && dragLabel.trim()) return tidy(dragLabel);
+  const node = dragNode?.current;
+  if (!node) return undefined;
+  const text = tidy(domText(node));
+  return text || undefined;
+}
+
+/**
+ * `textContent` for announcements: separates element boundaries with a space
+ * (raw `textContent` glues siblings — "Acme Corp$50,000") and skips
+ * `aria-hidden` subtrees, which are decoration a screen reader is already told
+ * to ignore.
+ */
+function domText(el: Element): string {
+  let out = '';
+  for (const child of el.childNodes) {
+    if (child.nodeType === 3) out += child.nodeValue ?? '';
+    else if (child.nodeType === 1 && (child as Element).getAttribute('aria-hidden') !== 'true')
+      out += ` ${domText(child as Element)}`;
+  }
+  return out;
+}
+
+/**
+ * The accessible name a consumer gave a container (a Kanban column, a
+ * SortableGroup list) — `aria-label`, or the text of whatever `aria-labelledby`
+ * points at, since naming a column by its visible `<Title>` is the natural
+ * choice. Returns undefined when neither is set; the caller falls back to a
+ * positional stand-in.
+ */
+export function containerName(props: {
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+}): string | undefined {
+  const label = props['aria-label'];
+  if (typeof label === 'string' && label.trim()) return tidy(label);
+  const ids = props['aria-labelledby'];
+  if (!ids || typeof document === 'undefined') return undefined;
+  const text = ids
+    .split(/\s+/)
+    .map((id) => document.getElementById(id)?.textContent ?? '')
+    .join(' ');
+  return text.trim() ? tidy(text) : undefined;
+}
+
+/** The `active` / `over` shape dnd-kit hands to an announcement callback. */
+export type DragEntry = Pick<Active, 'id' | 'data'>;
+
+/** What a component knows about the slot an id occupies (or would land in). */
+export interface DragTarget {
+  /** Human name. Empty / omitted → the message says "the item" instead. */
+  label?: string;
+  /** 1-based slot within `container`. */
+  index: number;
+  /** Number of slots in `container`, counting the incoming item. */
+  total: number;
+  /** Human name of the list the slot belongs to. Omit in single-list components. */
+  container?: string;
+}
+
+/**
+ * Default `describe`: the name from `dragLabelOf`, plus the index / items
+ * `useSortable` already publishes under `data.sortable`. Returns `null` for
+ * anything that is not a sortable item (including a missing entry).
+ */
+export function sortableTarget(entry: DragEntry | null): DragTarget | null {
+  const data = entry?.data.current;
+  const sortable = data?.sortable as { index: number; items: unknown[] } | undefined;
+  if (!sortable || sortable.index < 0) return null;
+  return {
+    label: dragLabelOf(data),
+    index: sortable.index + 1,
+    total: sortable.items.length,
+  };
+}
+
+/**
+ * Describes the slot an `active` / `over` entry names. `activeId` is passed so
+ * a container droppable can answer "where would THIS card land in me" — the
+ * multi-list components need it to position a drop onto an empty column.
+ *
+ * `entry` is null when dnd-kit resolved no `over` at all. Most components
+ * return null straight back; a component whose drop has its OWN fallback for
+ * that case (DataTable's last-resolved band slot, #383) must answer with that
+ * slot here too, or it announces "nothing moved" about a real reorder.
+ */
+export type DescribeDragTarget = (
+  entry: DragEntry | null,
+  activeId: Active['id'],
+) => DragTarget | null;
+
+/**
+ * Build the `accessibility` prop for a `<DndContext>`: localized announcements
+ * for the whole drag lifecycle plus localized keyboard instructions.
+ *
+ * @param describe   Resolves an entry (or `null` when there is no `over`) to a
+ *                   human slot. Return `null` when nothing would land anywhere
+ *                   — that announces "not over a drop target" / "nothing
+ *                   moved".
+ * @param isRejectedDrop Optional. Consulted on drag end BEFORE `over`: return
+ *                   `true` when the component refuses to commit the release, so
+ *                   it announces a cancel rather than a drop that never
+ *                   happened (Kanban's outside-the-board release, #390).
+ */
+export function useDragAccessibility(
+  describe: DescribeDragTarget,
+  isRejectedDrop?: () => boolean,
+): { announcements: Announcements; screenReaderInstructions: ScreenReaderInstructions } {
+  const t = useTranslation();
+
+  // Latched during render so the returned object can stay stable across the
+  // re-renders a live drag causes (dnd-kit re-subscribes its monitor listener
+  // whenever `announcements` changes identity). Both writes are idempotent —
+  // a StrictMode double render stores the same functions.
+  const describeRef = useRef(describe);
+  describeRef.current = describe;
+  const rejectedRef = useRef(isRejectedDrop);
+  rejectedRef.current = isRejectedDrop;
+
+  return useMemo(() => {
+    const nameOf = (entry: DragEntry, activeId: Active['id']) =>
+      describeRef.current(entry, activeId)?.label || t('drag.unnamed');
+
+    const at = (
+      key: 'movedOver' | 'dropped',
+      item: string,
+      target: DragTarget,
+    ): string | undefined => {
+      const { index, total, container } = target;
+      return container == null
+        ? t(`drag.${key}`, { item, index, total })
+        : t(key === 'movedOver' ? 'drag.movedOverIn' : 'drag.droppedIn', {
+            item,
+            index,
+            total,
+            container,
+          });
+    };
+
+    return {
+      announcements: {
+        onDragStart: ({ active }) => t('drag.pickedUp', { item: nameOf(active, active.id) }),
+        onDragOver: ({ active, over }) => {
+          const item = nameOf(active, active.id);
+          const target = describeRef.current(over, active.id);
+          return target ? at('movedOver', item, target) : t('drag.movedOutside', { item });
+        },
+        onDragEnd: ({ active, over }) => {
+          const item = nameOf(active, active.id);
+          if (rejectedRef.current?.()) return t('drag.cancelled', { item });
+          const target = describeRef.current(over, active.id);
+          return target ? at('dropped', item, target) : t('drag.droppedNowhere', { item });
+        },
+        onDragCancel: ({ active }) => t('drag.cancelled', { item: nameOf(active, active.id) }),
+      } satisfies Announcements,
+      screenReaderInstructions: { draggable: t('drag.instructions') },
+    };
+  }, [t]);
+}