@appinternalleads/ui 0.2.0 → 0.3.0

package/src/components/checklist/contract.ts

@@ -1,4 +1,4 @@
-import { FILTER_OPS, VALUELESS_FILTER_OPS, type FilterAuthor, type FilterOp } from '../../runtime/query';
+import { FILTER_OPS, VALUELESS_FILTER_OPS, type FilterAuthor, type FilterOp } from '../../runtime/query/filters';
 
 /**
  * **Checklist — the contract.** A piece of shared, durable work: a named set of tasks that people
@@ -117,17 +117,188 @@ export type ChecklistConfig = {
   /** `channels` holds host-declared channel **ids**. The component ships zero concrete channels. */
   notifications: { enabled: boolean; channels: string[] };
 
-  /** The nouns. Separate strings because they are different facts. */
-  copy: {
-    /** No tasks at all. */
-    emptyLabel: string;
-    /** Every required task done. */
-    allDoneLabel: string;
-    addTaskLabel: string;
-    addSectionLabel: string;
-  };
+  /**
+   * Every word the checklist shows that is not the document's own. The four nouns are always
+   * present (separate strings because they are different facts); every other key is optional and
+   * falls back to `CHECKLIST_COPY`. See `ChecklistCopy`.
+   */
+  copy: Pick<ChecklistCopy, 'emptyLabel' | 'allDoneLabel' | 'addTaskLabel' | 'addSectionLabel'> & Partial<ChecklistCopy>;
+};
+
+/**
+ * **Every word a Checklist shows that is not the document's.** Task, section and checklist titles,
+ * people's names and a rule's own `label` are content; everything else is here. Placeholders are
+ * filled at render: `{title}` (the task or section it acts on), `{name}` (a person), `{count}`,
+ * `{done}`, `{total}`, `{label}`, `{section}`, `{tasks}`, `{names}`. A blank value falls back.
+ */
+export type ChecklistCopy = {
+  /** No tasks at all. */
+  emptyLabel: string;
+  /** Every required task done. */
+  allDoneLabel: string;
+  addTaskLabel: string;
+  addSectionLabel: string;
+  /** The progress count: "{done} of {total} done". */
+  progress: string;
+  /** The header when the checklist has no title. */
+  untitled: string;
+  /** An assignee the people boundary does not know. */
+  unknownPerson: string;
+  /** A task with `required: false`. */
+  optional: string;
+  /** A skipped task. */
+  skipped: string;
+  save: string;
+  cancel: string;
+  add: string;
+  tryAgain: string;
+  dismiss: string;
+  /** The Add task button inside a named section (accessible name): "{label} in {section}". */
+  addTaskIn: string;
+  /** Editing a task: the title field's accessible name. */
+  taskTitle: string;
+  /** Editing a task: the description field's accessible name. */
+  taskDescription: string;
+  /** The placeholder of every description field. */
+  description: string;
+  /** Editing the checklist: the title field (accessible name and placeholder). */
+  checklistTitle: string;
+  /** Editing the checklist: the description field's accessible name. */
+  checklistDescription: string;
+  /** The header's edit button (accessible name). */
+  editChecklist: string;
+  /** A task's buttons (accessible names). `{title}` is the task's. */
+  moveUp: string;
+  moveDown: string;
+  assign: string;
+  skip: string;
+  unskip: string;
+  edit: string;
+  delete: string;
+  /** A person in the assign picker (accessible name): "Assign to {name}". */
+  assignTo: string;
+  unassign: string;
+  /** A change that failed. */
+  notSaved: string;
+  notSavedBody: string;
+  /** A section's collapse button when the section has no title (accessible name). */
+  section: string;
+  /** Editing a section: the title field's accessible name. */
+  sectionTitle: string;
+  /** A section's buttons (accessible names). `{title}` is the section's. */
+  editSection: string;
+  moveSectionUp: string;
+  deleteSection: string;
+  /** The Share button, before and after sharing. */
+  share: string;
+  shared: string;
+  /** The share panel's heading. */
+  shareWith: string;
+  /** A person in the share picker (accessible name): "Share with {name}". */
+  shareWithPerson: string;
+  /** The send button: "Share with {count}". */
+  shareWithCount: string;
+  /** The send button while sharing. */
+  sharing: string;
+  /** The label before the two scope choices. */
+  shareScope: string;
+  scopeChecklist: string;
+  scopeOwn: string;
+  /** Who gets what, per person: "{name} · {tasks}". */
+  shareOwnTasks: string;
+  /** Who gets what, a person with none: "{name} · no tasks assigned". */
+  shareOwnNone: string;
+  /** After sharing: "Shared with {names}". */
+  sharedWithNames: string;
+  notShared: string;
+  notSharedBody: string;
+  notNotified: string;
+  notNotifiedBody: string;
+  /** A blocked task, when another task must be done first: "Finish “{title}” first". */
+  finishFirst: string;
+  /** A blocked task, any other gate with no `label`. */
+  blocked: string;
+  /** The title of the callout listing configuration errors. */
+  configTitle: string;
+};
+
+/** The English default for every key of `ChecklistCopy`. */
+export const CHECKLIST_COPY: ChecklistCopy = {
+  emptyLabel: 'Nothing on this checklist yet',
+  allDoneLabel: 'All done',
+  addTaskLabel: 'Add task',
+  addSectionLabel: 'Add section',
+  progress: '{done} of {total} done',
+  untitled: 'Untitled checklist',
+  unknownPerson: 'Unknown person',
+  optional: 'Optional',
+  skipped: 'Skipped',
+  save: 'Save',
+  cancel: 'Cancel',
+  add: 'Add',
+  tryAgain: 'Try again',
+  dismiss: 'Dismiss',
+  addTaskIn: '{label} in {section}',
+  taskTitle: 'Task title',
+  taskDescription: 'Task description',
+  description: 'Description',
+  checklistTitle: 'Checklist title',
+  checklistDescription: 'Checklist description',
+  editChecklist: 'Edit checklist title and description',
+  moveUp: 'Move “{title}” up',
+  moveDown: 'Move “{title}” down',
+  assign: 'Assign “{title}”',
+  skip: 'Skip “{title}”',
+  unskip: 'Un-skip “{title}”',
+  edit: 'Edit “{title}”',
+  delete: 'Delete “{title}”',
+  assignTo: 'Assign to {name}',
+  unassign: 'Unassign',
+  notSaved: 'Not saved',
+  notSavedBody: 'We could not save that.',
+  section: 'Section',
+  sectionTitle: 'Section title',
+  editSection: 'Edit section “{title}”',
+  moveSectionUp: 'Move section “{title}” up',
+  deleteSection: 'Delete section “{title}”',
+  share: 'Share',
+  shared: 'Shared',
+  shareWith: 'Share with',
+  shareWithPerson: 'Share with {name}',
+  shareWithCount: 'Share with {count}',
+  sharing: 'Sharing…',
+  shareScope: 'Share',
+  scopeChecklist: 'The whole checklist',
+  scopeOwn: 'Each person’s own tasks',
+  shareOwnTasks: '{name} · {tasks}',
+  shareOwnNone: '{name} · no tasks assigned',
+  sharedWithNames: 'Shared with {names}',
+  notShared: 'Not shared',
+  notSharedBody: 'We could not share this.',
+  notNotified: 'Not notified',
+  notNotifiedBody: 'We could not let everyone know.',
+  finishFirst: 'Finish “{title}” first',
+  blocked: 'Something else has to happen first',
+  configTitle: 'Configuration',
 };
 
+/** `CHECKLIST_COPY` ← a configuration's copy. Only non-blank strings override. Pure. */
+export function checklistCopy(copy: Partial<ChecklistCopy> | undefined): ChecklistCopy {
+  const out = { ...CHECKLIST_COPY };
+  if (copy && typeof copy === 'object') {
+    for (const k of Object.keys(out) as (keyof ChecklistCopy)[]) {
+      const v = copy[k];
+      if (typeof v === 'string' && v.trim()) out[k] = v;
+    }
+  }
+  return out;
+}
+
+/** Fill `{name}` placeholders. An unknown placeholder is left as written. */
+export function fillChecklistCopy(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (m, k: string) => (k in vars ? String(vars[k]) : m));
+}
+
 /**
  * A constant, not a derivation — and not dressed up as more. Directory's `defaultConfigFor(schema)`
  * derives a starting point from what was *discovered*; a Checklist has nothing to discover, so its
@@ -566,6 +737,11 @@ export function validateChecklistConfig(
 ): string[] {
   const errors: string[] = [];
 
+  const copy = config.copy as unknown;
+  if (copy !== undefined && (!copy || typeof copy !== 'object' || Array.isArray(copy))) errors.push('Copy: must be an object of text');
+  else if (copy) {
+    for (const [k, v] of Object.entries(copy)) if (typeof v !== 'string') errors.push(`Copy: "${k}" must be text`);
+  }
   if (config.can.assign && config.assignees === 'hidden') {
     errors.push('Assign: tasks can be assigned but assignees are hidden');
   }

package/src/components/checklist/derive.ts

@@ -1,7 +1,7 @@
 import { applyFilter } from '../../runtime/query';
 import {
-  findSection, findTask,
-  type Checklist, type ChecklistCondition, type ChecklistRule, type ChecklistSection, type ChecklistTask,
+  CHECKLIST_COPY, fillChecklistCopy, findSection, findTask,
+  type Checklist, type ChecklistCondition, type ChecklistCopy, type ChecklistRule, type ChecklistSection, type ChecklistTask,
 } from './contract';
 
 /**
@@ -118,18 +118,19 @@ export function unsatisfiedGates(
 export function gateMessage(
   entry: { rule: ChecklistRule; unmet: ChecklistCondition[] },
   checklist: Checklist,
+  copy: Pick<ChecklistCopy, 'finishFirst' | 'blocked'> = CHECKLIST_COPY,
 ): string {
   if (entry.rule.label) return entry.rule.label;
   const first = entry.unmet[0];
   if (first?.subject === 'task' && first.field === 'done' && first.op === 'eq' && first.value === 'true') {
     const other = findTask(checklist, first.ref);
-    if (other) return `Finish “${other.task.title}” first`;
+    if (other) return fillChecklistCopy(copy.finishFirst, { title: other.task.title });
   }
   if (first?.subject === 'section' && first.field === 'complete' && first.op === 'eq' && first.value === 'true') {
     const section = findSection(checklist, first.ref);
-    if (section?.title) return `Finish “${section.title}” first`;
+    if (section?.title) return fillChecklistCopy(copy.finishFirst, { title: section.title });
   }
-  return 'Something else has to happen first';
+  return copy.blocked;
 }
 
 /**

package/src/components/checklist/index.ts

@@ -19,13 +19,13 @@
 export { ChecklistView, type ChecklistViewProps } from './ChecklistView';
 
 export {
-  defaultChecklistConfig, validateChecklistConfig,
+  defaultChecklistConfig, validateChecklistConfig, CHECKLIST_COPY, checklistCopy,
   validateChecklistRule, validateChecklistRules, hasGateCycle,
   findTask, findSection, allTasks,
   CHECKLIST_EVENTS, CHECKLIST_CHANGE_KINDS, CAPABILITY_FOR_CHANGE, OPERATORS_BY_FIELD,
   TASK_FIELDS, SECTION_FIELDS,
   type Checklist, type ChecklistSection, type ChecklistTask, type ChecklistDocument,
-  type ChecklistConfig, type ChecklistProgressMode, type ChecklistSectionMode, type ChecklistAssigneeMode,
+  type ChecklistConfig, type ChecklistCopy, type ChecklistProgressMode, type ChecklistSectionMode, type ChecklistAssigneeMode,
   type ChecklistRule, type ChecklistGateRule, type ChecklistNotifyRule, type ChecklistCondition,
   type ChecklistEvent, type ChecklistTaskField, type ChecklistSectionField,
   type ChecklistChange, type ChecklistChangeBody, type ChecklistChangeKind, type ChecklistEffect,

package/src/components/directory/DirectoryView.tsx

@@ -10,8 +10,8 @@ import {
   type DataAdapter, type QueryFilter, type QueryRecord,
 } from '../../runtime/query';
 import {
-  canFilter, rulesToFilters, validateDirectoryConfig,
-  type DirectoryColumn, type DirectoryConfig, type DirectoryRule, type DirectorySchema,
+  canFilter, directoryCopy, fillDirectoryCopy as fill, rulesToFilters, validateDirectoryConfig,
+  type DirectoryColumn, type DirectoryConfig, type DirectoryCopy, type DirectoryRule, type DirectorySchema,
 } from './contract';
 
 /**
@@ -150,13 +150,13 @@ function Row({
 }
 
 function Detail({
-  record, config, columns, onBack,
-}: { record: QueryRecord; config: DirectoryConfig; columns: Map<string, DirectoryColumn>; onBack: () => void }) {
+  record, config, copy, columns, onBack,
+}: { record: QueryRecord; config: DirectoryConfig; copy: DirectoryCopy; columns: Map<string, DirectoryColumn>; onBack: () => void }) {
   const { colors } = useDs();
   const d = record.data ?? {};
   return (
     <Box style={{ gap: 10 }}>
-      <Button variant="secondary" size="xsmall" leadingGlyph="chev-l" onPress={onBack} aria-label="Back to results">Back to results</Button>
+      <Button variant="secondary" size="xsmall" leadingGlyph="chev-l" onPress={onBack} aria-label={copy.back}>{copy.back}</Button>
       <Text role="heading" aria-level={3} style={{ fontSize: 16, lineHeight: 21, fontWeight: '600', letterSpacing: -0.24 }}>{d[config.primaryColumn] ?? ''}</Text>
       <Box role="list" style={{ gap: 0 }}>
         {config.detailColumns.map((key, i) => {
@@ -167,7 +167,7 @@ function Detail({
               <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 15 }}>{columns.get(key)?.label ?? key}</Text>
               {/* An empty cell is said, not skipped — "not recorded" and "blank" are different facts. */}
               <Text style={{ fontSize: 13, lineHeight: 19, color: value ? colors.textPrimary : colors.textSecondary }}>
-                {value || 'Not recorded'}
+                {value || copy.notRecorded}
               </Text>
             </Box>
           );
@@ -200,6 +200,7 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
   const { surface, onLayout } = useMeasuredSurface();
   const columns = useMemo(() => new Map(schema.columns.map(c => [c.key, c])), [schema]);
   const configErrors = useMemo(() => validateDirectoryConfig(config, schema), [config, schema]);
+  const copy = useMemo(() => directoryCopy(config.copy), [config.copy]);
 
   /* In-memory execution over rows the host already read, through the SAME runtime adapter the
      `list` fixtures use — so every operator here is one `applyFilter` really implements. */
@@ -297,11 +298,11 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
 
   /* Before any records arrive the footer says what is happening — and a failed first read is not
      "Loading": the alert above it says what went wrong, the count says nothing was read. */
-  const counter = !state.data ? (state.status === 'error' ? 'Nothing read' : 'Loading')
-    : rows.length === 0 ? (isPristine(state.query) ? config.copy.emptyLabel : config.copy.noResultsLabel)
-    : total === undefined ? `Showing ${rows.length}`
-    : rows.length === total && pageOffset === 0 ? `${total} records`
-    : `${pageOffset + 1}–${pageOffset + rows.length} of ${total}`;
+  const counter = !state.data ? (state.status === 'error' ? copy.nothingRead : copy.loadingLabel)
+    : rows.length === 0 ? (isPristine(state.query) ? copy.emptyLabel : copy.noResultsLabel)
+    : total === undefined ? fill(copy.showing, { count: rows.length })
+    : rows.length === total && pageOffset === 0 ? fill(total === 1 ? copy.totalOne : copy.totalOther, { count: total })
+    : fill(copy.range, { from: pageOffset + 1, to: pageOffset + rows.length, total });
 
   const canPrev = pageOffset > 0;
   const canNext = total !== undefined ? pageOffset + config.pageSize < total : rows.length >= config.pageSize;
@@ -312,7 +313,7 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
        screen: it is shown as an apricot Callout, rather than rendering something misleading. */
     return (
       <BlockCard testID={testID} title={config.title} subtitle={config.description}>
-        <Callout title="Configuration">{configErrors.join('\n')}</Callout>
+        <Callout title={copy.configTitle}>{configErrors.join('\n')}</Callout>
       </BlockCard>
     );
   }
@@ -320,7 +321,7 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
   const busy = typing || (state.status === 'loading' && !!state.data);
   const sortLabel = state.query.sort
     ? `${columns.get(state.query.sort.column)?.label ?? state.query.sort.column} ${state.query.sort.dir === 'asc' ? '↑' : '↓'}`
-    : 'None';
+    : copy.sortNone;
 
   /* The current card shell (S1): header (title, description, a spinner while it searches) · body
      (search, facets, sort, the records) · footer (the count on the left, paging on the right). The
@@ -332,25 +333,25 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
           testID={testID}
           title={config.title}
           subtitle={config.description}
-          meta={busy ? <Spinner label="Searching" /> : undefined}
+          meta={busy ? <Spinner label={copy.searching} /> : undefined}
           hint={selected ? undefined : <Text accessibilityLiveRegion="polite" color="textSecondary" numeric style={{ fontSize: 12 }}>{counter}</Text>}
           actions={selected ? undefined : (
             <>
-              <Button variant="secondary" size="small" disabled={!canPrev} aria-label="Previous"
-                onPress={() => machine.setPage(Math.max(0, pageOffset - config.pageSize))}>Previous</Button>
-              <Button variant="secondary" size="small" disabled={!canNext} aria-label="Next"
-                onPress={() => machine.setPage(pageOffset + config.pageSize)}>Next</Button>
+              <Button variant="secondary" size="small" disabled={!canPrev} aria-label={copy.previous}
+                onPress={() => machine.setPage(Math.max(0, pageOffset - config.pageSize))}>{copy.previous}</Button>
+              <Button variant="secondary" size="small" disabled={!canNext} aria-label={copy.next}
+                onPress={() => machine.setPage(pageOffset + config.pageSize)}>{copy.next}</Button>
             </>
           )}>
           {selected ? (
-            <Detail record={selected} config={config} columns={columns} onBack={() => setSelectedId(null)} />
+            <Detail record={selected} config={config} copy={copy} columns={columns} onBack={() => setSelectedId(null)} />
           ) : (
             <>
               {config.searchColumns.length ? (
                 <Input
                   value={text} onChangeText={onText}
-                  placeholder={`Search ${config.searchColumns.map(k => columns.get(k)?.label ?? k).join(', ')}`}
-                  aria-label="Search"
+                  placeholder={fill(copy.searchPlaceholder, { columns: config.searchColumns.map(k => columns.get(k)?.label ?? k).join(', ') })}
+                  aria-label={copy.searchLabel}
                 />
               ) : null}
 
@@ -373,10 +374,14 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
 
               {config.sortColumns.length ? (
                 <Box row wrap align="center" style={{ gap: 8 }}>
-                  <Text color="textPrimary" style={{ fontSize: 12, lineHeight: 16, fontWeight: '600' }}>Sort</Text>
+                  <Text color="textPrimary" style={{ fontSize: 12, lineHeight: 16, fontWeight: '600' }}>{copy.sort}</Text>
                   <Button
                     variant="secondary" size="xsmall"
-                    aria-label={`Sort: ${state.query.sort ? `${columns.get(state.query.sort.column)?.label ?? state.query.sort.column} ${state.query.sort.dir}` : 'none'}. Press to change`}
+                    aria-label={fill(copy.sortAria, {
+                      sort: state.query.sort
+                        ? `${columns.get(state.query.sort.column)?.label ?? state.query.sort.column} ${state.query.sort.dir === 'asc' ? copy.sortAsc : copy.sortDesc}`
+                        : copy.sortNoneAria,
+                    })}
                     onPress={() => {
                       const next = config.sortColumns[(sortIndex + 1) % config.sortColumns.length]!;
                       const dir = state.query.sort?.column === next && state.query.sort.dir === 'asc' ? 'desc' : 'asc';
@@ -388,9 +393,9 @@ function DirectoryBody({ schema, config, rules = [], adapter, records = [], onSe
               ) : null}
 
               {state.status === 'error' ? (
-                <Box role="group" aria-label="Error">
-                  <Callout alert title="Couldn’t read the records" action={<Button variant="secondary" size="xsmall" onPress={machine.retry} aria-label="Retry">Retry</Button>}>
-                    {state.data ? 'We could not refresh these records. Showing earlier results.' : 'We could not read these records.'}
+                <Box role="group" aria-label={copy.errorLabel}>
+                  <Callout alert title={copy.errorTitle} action={<Button variant="secondary" size="xsmall" onPress={machine.retry} aria-label={copy.retryLabel}>{copy.retryLabel}</Button>}>
+                    {state.data ? copy.errorStale : copy.errorBody}
                   </Callout>
                 </Box>
               ) : null}

package/src/components/directory/contract.ts

@@ -1,7 +1,7 @@
 import {
   FILTER_OPS, RANGE_SEPARATOR, VALUELESS_FILTER_OPS,
   type FilterAuthor, type FilterOp, type QueryFilter,
-} from '../../runtime/query';
+} from '../../runtime/query/filters';
 
 /**
  * **Directory — the contract.** A data-backed record discovery component: connect a relation,
@@ -91,9 +91,120 @@ export type DirectoryConfig = {
   pageSize: number;
   selection: 'none' | 'single';
   sort?: { column: string; dir: DirectorySortDirection };
-  copy: { emptyLabel: string; noResultsLabel: string };
+  /**
+   * Every word the Directory shows that is not the source's own (records, column headers, facet
+   * values). `emptyLabel` and `noResultsLabel` are always present — they carry the noun; every
+   * other key is optional and falls back to `DIRECTORY_COPY`. See `DirectoryCopy`.
+   */
+  copy: Pick<DirectoryCopy, 'emptyLabel' | 'noResultsLabel'> & Partial<DirectoryCopy>;
 };
 
+/**
+ * **Every word a Directory shows that is not data.** Placeholders are filled at render: `{count}`,
+ * `{from}`, `{to}`, `{total}`, `{columns}` (the searched columns' labels), `{sort}` (the sorted
+ * column and its direction word). A blank value falls back to the default.
+ */
+export type DirectoryCopy = {
+  /** The source has no records at all. */
+  emptyLabel: string;
+  /** Records exist, but none survive the rules, search and chips. */
+  noResultsLabel: string;
+  /** The footer before the first read returns. */
+  loadingLabel: string;
+  /** The footer when the first read failed. */
+  nothingRead: string;
+  /** The footer when the source gives no total: "Showing {count}". */
+  showing: string;
+  /** Every record on one page, one record: "{count} record". */
+  totalOne: string;
+  /** Every record on one page: "{count} records". */
+  totalOther: string;
+  /** A page of a larger set: "{from}–{to} of {total}". */
+  range: string;
+  /** The spinner's accessible name while a search runs. */
+  searching: string;
+  previous: string;
+  next: string;
+  /** The search box's accessible name. */
+  searchLabel: string;
+  /** The search box's placeholder: "Search {columns}". */
+  searchPlaceholder: string;
+  /** The sort control's label. */
+  sort: string;
+  /** The sort button when nothing is sorted. */
+  sortNone: string;
+  /** The sort button's accessible name: "Sort: {sort}. Press to change". */
+  sortAria: string;
+  /** `{sort}` when nothing is sorted. */
+  sortNoneAria: string;
+  /** The direction word in `{sort}`, ascending. */
+  sortAsc: string;
+  /** The direction word in `{sort}`, descending. */
+  sortDesc: string;
+  /** The failure block's accessible name. */
+  errorLabel: string;
+  errorTitle: string;
+  /** The first read failed. */
+  errorBody: string;
+  /** A later read failed; the earlier records stay. */
+  errorStale: string;
+  retryLabel: string;
+  /** The open record's way back. */
+  back: string;
+  /** An empty cell in the open record — said, not skipped. */
+  notRecorded: string;
+  /** The title of the callout listing configuration errors. */
+  configTitle: string;
+};
+
+/** The English default for every key of `DirectoryCopy`. */
+export const DIRECTORY_COPY: DirectoryCopy = {
+  emptyLabel: 'No records yet',
+  noResultsLabel: 'No records match these rules',
+  loadingLabel: 'Loading',
+  nothingRead: 'Nothing read',
+  showing: 'Showing {count}',
+  totalOne: '{count} record',
+  totalOther: '{count} records',
+  range: '{from}–{to} of {total}',
+  searching: 'Searching',
+  previous: 'Previous',
+  next: 'Next',
+  searchLabel: 'Search',
+  searchPlaceholder: 'Search {columns}',
+  sort: 'Sort',
+  sortNone: 'None',
+  sortAria: 'Sort: {sort}. Press to change',
+  sortNoneAria: 'none',
+  sortAsc: 'asc',
+  sortDesc: 'desc',
+  errorLabel: 'Error',
+  errorTitle: 'Couldn’t read the records',
+  errorBody: 'We could not read these records.',
+  errorStale: 'We could not refresh these records. Showing earlier results.',
+  retryLabel: 'Retry',
+  back: 'Back to results',
+  notRecorded: 'Not recorded',
+  configTitle: 'Configuration',
+};
+
+/** `DIRECTORY_COPY` ← the configuration's copy. Only non-blank strings override. Pure. */
+export function directoryCopy(copy: Partial<DirectoryCopy> | undefined): DirectoryCopy {
+  const out = { ...DIRECTORY_COPY };
+  if (copy && typeof copy === 'object') {
+    for (const k of Object.keys(out) as (keyof DirectoryCopy)[]) {
+      const v = copy[k];
+      if (typeof v === 'string' && v.trim()) out[k] = v;
+    }
+  }
+  return out;
+}
+
+/** Fill `{name}` placeholders. An unknown placeholder is left as written. */
+export function fillDirectoryCopy(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (m, k: string) => (k in vars ? String(vars[k]) : m));
+}
+
 /* ── C · The rule set ────────────────────────────────────────────────────── */
 
 /**
@@ -355,6 +466,11 @@ export function validateDirectoryConfig(config: DirectoryConfig, schema: Directo
   check(config.detailColumns, 'Detail');
   if (config.sort) check([config.sort.column], 'Sort', canSort);
   if (config.pageSize < 1) errors.push('Page size must be at least 1');
+  const copy = config.copy as unknown;
+  if (copy !== undefined && (!copy || typeof copy !== 'object' || Array.isArray(copy))) errors.push('Copy must be an object of text');
+  else if (copy) {
+    for (const [k, v] of Object.entries(copy)) if (typeof v !== 'string') errors.push(`Copy: "${k}" must be text`);
+  }
   return errors;
 }
 
@@ -468,6 +584,9 @@ export function normalizeDirectoryConfig(config: Partial<DirectoryConfig>, schem
       ? { sort: { column: sortColumn, dir: config.sort?.dir === 'asc' ? 'asc' as const : 'desc' as const } }
       : fallback.sort ? { sort: fallback.sort } : {}),
     copy: {
+      /* Every other word the configuration renamed survives, as long as it is text. */
+      ...Object.fromEntries(Object.entries(config.copy && typeof config.copy === 'object' ? config.copy : {})
+        .filter(([k, v]) => k in DIRECTORY_COPY && typeof v === 'string')),
       emptyLabel: config.copy?.emptyLabel || fallback.copy.emptyLabel,
       noResultsLabel: config.copy?.noResultsLabel || fallback.copy.noResultsLabel,
     },

package/src/components/directory/index.ts

@@ -8,11 +8,13 @@ export {
   directoryDocument, loadDirectoryDocument, DIRECTORY_DOCUMENT_VERSION,
   /* Rules */
   rulesToFilters, blankRule, newRuleId, isRuleOn, RULE_ACTIONS, FUTURE_RULE_ACTIONS,
+  /* Every word it shows */
+  DIRECTORY_COPY, directoryCopy,
   /* What a column can do */
   operatorsFor, canSearch, canFilter, canSort,
   OPERATORS_BY_TYPE, OPERATOR_LABELS, INFERENCE, RANGE_SEPARATOR,
   type DirectorySource, type DirectorySourceKind, type DirectoryColumn, type DirectoryColumnType,
-  type DirectorySchema, type DirectoryConfig, type DirectoryDocument,
+  type DirectorySchema, type DirectoryConfig, type DirectoryCopy, type DirectoryDocument,
   type DirectoryRule, type LegacyDirectoryRule, type DirectoryCondition,
   type DirectoryAction, type DirectoryActionKind,
   type DirectorySortDirection, type RuleCheck, type RuleRejection,

package/src/components/onboarding/ab-tests/presets.json

@@ -1,6 +1,8 @@
 {
   "component": "ab-tests",
   "baseCopy": {
+    "loadingLabel": "Loading {title}",
+    "attentionLabel": "Needs attention",
     "loadErrorTitle": "Couldn’t load this step",
     "loadErrorBody": "Nothing was lost. Retry to load it again.",
     "retryLabel": "Retry",
@@ -322,4 +324,4 @@
       "scenario": "Results load, then reveal. The hero headline test is a tie, so both bars are full and there’s no winner."
     }
   }
-}
+}

package/src/components/onboarding/achievement/AchievementView.tsx

@@ -112,7 +112,7 @@ function Valid({
             <CrossFadeText value={v.rewardText} style={figure} />
           </Box>
         </Box>
-        {state.claim === 'failed' ? <Callout alert strong title="Couldn’t claim your reward">Nothing was lost. Retry in a moment.</Callout> : null}
+        {state.claim === 'failed' ? <Callout alert strong title={config.claimFailedTitle}>{config.claimFailedBody}</Callout> : null}
       </Box>
     </OnboardingCard>
   );

package/src/components/onboarding/achievement/contract.ts

@@ -33,6 +33,29 @@ export type AchievementSettings = HeaderConfig & LoadCopy & {
   state: AchievementStateName;
   primaryLabel: string;
   claimedHint: string;
+  /** Progress read out on the bar; `{current}`, `{target}`, `{unit}` (with its leading space). */
+  progressWordsTemplate: string;
+  /** Label for the progress row; `{tier}` is the tier being worked toward. */
+  progressToTemplate: string;
+  rewardLabel: string;
+  /** The reward row's label while the milestone is still locked. */
+  lockedRewardLabel: string;
+  /** The status line while the milestone is still locked. */
+  lockedLine: string;
+  unlockedChipLabel: string;
+  inProgressChipLabel: string;
+  /** The chip and the button while the claim runs. */
+  claimingLabel: string;
+  claimedLabel: string;
+  /** Footer hint once unlocked; `{amount}`, `{unit}` and `{tier}` (the next tier). */
+  toNextTierTemplate: string;
+  /** Footer hint while locked; `{amount}` and `{unit}`. */
+  moreToUnlockTemplate: string;
+  shareLabel: string;
+  /** The Share button's flash after the link is copied. */
+  sharedLabel: string;
+  claimFailedTitle: string;
+  claimFailedBody: string;
   /** Demo-only: the scene this case ships in (B2-9). */
   ship?: AchievementScene;
 };