@formatjs/editor 1.3.0 → 1.4.0

package/README.md

@@ -1,7 +1,8 @@
 # Headless message editor
 
 Install `@formatjs/editor` alongside React 19. The published package exports
-headless APIs and TypeScript declarations; demo UI remains repository-only.
+headless APIs and TypeScript declarations at the root, plus optional reusable UI
+at `@formatjs/editor/ui`. The styled demos remain repository-only.
 
 The React 19 editor exposes behavior without DOM, styles, a design system, an
 IntlProvider, or network requests. Consumers own catalogs, persistence, loading
@@ -182,8 +183,212 @@ categories inherit the source `other` branch's argument contract. Repeated
 placeholders do not change that contract. Validation is structural, not a check
 of translation quality.
 
-The optional `TranslationEditorDemo` in `demo/workflow-demo.tsx` reuses the StyleX
-`EditorView`, tokens, and controls. It includes locale/catalog/status filters,
+The optional `TranslationEditorDemo` in `demo/workflow-demo.tsx` uses the public
+`TranslationEditorView` with a StyleX component adapter and localized labels. It includes locale/catalog/status filters,
 pagination, source locations, localized validation, reset, and save feedback.
 Supply an `IntlProvider` and the same StyleX Vite integration used by the demo.
 It is separate from the headless entry point; consumers can use any design system.
+
+## Reusable UI with your design system
+
+Import `TranslationEditorView`, `MessageList`, `SourceMessage`, and
+`TranslationField` from `@formatjs/editor/ui`. This separate entry point owns
+message-row selection wiring, field labels and error descriptions, draft status,
+and copy/reset/save controls. It ships unstyled native controls and requires only
+React. The headless root does not import the UI, StyleX, icons, or React Intl.
+
+Mount one workflow above the views and pass its existing drafts:
+
+```tsx
+import {useTranslationEditor} from '@formatjs/editor'
+import {TranslationEditorView} from '@formatjs/editor/ui'
+
+const workflow = useTranslationEditor({messages, locales, onSave: persist})
+const selected = workflow.selectedMessage
+return (
+  <TranslationEditorView
+    messages={workflow.pageMessages}
+    selectedMessage={selected}
+    onSelect={workflow.editor.selectMessage}
+    search={{
+      value: workflow.editor.query,
+      onValueChange: workflow.editor.setQuery,
+    }}
+    translations={
+      selected
+        ? visibleLocales.map(locale => {
+            const draft = workflow.getTranslation(selected.id, locale)!
+            return {
+              locale,
+              draft,
+              onSave: () => {
+                void draft.save()
+              },
+            }
+          })
+        : []
+    }
+  />
+)
+```
+
+`visibleLocales` must be a subset of the workflow's available `locales`. Hiding a
+view does not remove its draft. The view does not create a workflow or own
+selection, fetching, filtering, pagination, locale visibility, or persistence.
+For server-side search, pass the loaded page directly as `messages`, your search
+value/callback as `search`, and your externally selected detail as
+`selectedMessage`. Selection can remain outside the loaded page. `loading` marks
+navigation busy and displays a status; it does not clear the controlled list.
+
+### Component adapters
+
+`EditorDesignSystemProvider` accepts partial overrides of `EditorComponents`: `Button`,
+`TextInput`, `TextArea`, `MessageRow`, `Panel`, and `Layout`. Unspecified entries
+inherit from the nearest provider, falling back to `nativeEditorComponents`. Adapters map a design system's control API to
+semantic `onPress`, `onSelect`, and `onValueChange` callbacks. Define adapters at
+module scope so React preserves focus and control state between edits:
+
+```tsx
+import {
+  EditorDesignSystemProvider,
+  useEditorDesignSystem,
+  type EditorComponents,
+} from '@formatjs/editor/ui'
+import {Button, Textarea} from './controls'
+
+const components: Partial<EditorComponents> = {
+  Button: ({onPress, ...props}) => (
+    <Button {...props} onClick={() => onPress()} />
+  ),
+  TextArea: ({onValueChange, ...props}) => (
+    <Textarea {...props} onValueChange={onValueChange} />
+  ),
+}
+```
+
+Configure the design system once around your application or editor subtree:
+
+```tsx
+function EditorWorkspace() {
+  return (
+    <EditorDesignSystemProvider components={components}>
+      <TranslationEditorView {...viewProps} />
+      <CustomToolbar />
+    </EditorDesignSystemProvider>
+  )
+}
+
+function CustomToolbar() {
+  const {Button} = useEditorDesignSystem()
+  return (
+    <Button variant="secondary" onPress={openReview}>
+      Review
+    </Button>
+  )
+}
+```
+
+All built-in views and downstream consumers use `useEditorDesignSystem()`;
+there is no component-registry prop on individual views. The hook returns the
+resolved, read-only `EditorComponents` contract. Providers are React-tree scoped,
+so sibling editors (and separate server-rendered trees) do not share mutable
+configuration. Nested providers override only specified components and inherit
+the rest. Changing the registry updates consumers; keeping each component type
+stable preserves field focus and local state. No provider is needed for native
+controls.
+
+Each component has an exported props contract:
+
+| Component                              | Inputs                                                                                     | Output callback                      |
+| -------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------ |
+| `Button` / `EditorButtonProps`         | `children`, `variant`, optional `disabled`                                                 | `onPress(): void`                    |
+| `TextInput` / `EditorTextInputProps`   | `id`, `value`, `type` (`text` or `search`), optional disabled/error-description attributes | `onValueChange(value: string): void` |
+| `TextArea` / `EditorTextAreaProps`     | `id`, `value`, optional `rows` (default six), disabled/error-description attributes        | `onValueChange(value: string): void` |
+| `MessageRow` / `EditorMessageRowProps` | `children`, controlled `selected`                                                          | `onSelect(): void`                   |
+| `Panel` / `EditorPanelProps`           | `children`, accessible `label`, `kind` (`source` or `translation`)                         | None; layout only                    |
+| `Layout` / `EditorLayoutProps`         | `toolbar`, `navigation`, `content` nodes                                                   | None; layout only                    |
+
+`EditorInputProps` defines the shared input attributes explicitly: `id`, `value`,
+`onValueChange`, optional `disabled`, `aria-invalid`, and `aria-describedby`.
+Callbacks never receive DOM events. Inputs remain controlled; callbacks request
+a change and the caller supplies the next value. Disabled buttons must not invoke
+`onPress`. Panel and Layout do not invent interaction callbacks.
+
+The complete StyleX adapter lives in `demo/design-system/editor-components.tsx`;
+its layout, tokens, and native-control wrappers are not bundled into the package.
+
+Adapter requirements:
+
+- Inputs forward `id`, `value`, `disabled`, `aria-invalid`, and
+  `aria-describedby` to their focusable control. They report strings through
+  `onValueChange` and stay associated with the view's visible label.
+- Buttons honor `disabled`, support keyboard activation, and do not submit a
+  surrounding form. `onPress` and `onSelect` take no event argument.
+- Message rows expose selection (the native adapter uses `aria-current`) and
+  preserve keyboard activation. Icons and selection styling belong in the adapter.
+- Panels retain their accessible label and render their children. Layout receives
+  `toolbar`, `navigation`, and `content` nodes, which it can arrange responsively.
+  Preserve a meaningful reading and keyboard order.
+
+The reusable pieces retain semantic labels, headings, lists, alerts, and status
+nodes. Adapters control the interactive controls and outer presentation; use the
+standalone pieces when a different page composition is needed.
+
+### Application slots and localization
+
+`filters`, `pagination`, `context`, and `notice` accept React nodes. Supply your
+own locale picker or filter controls in `filters`; no native-select API is
+imposed on applications with multi-select or asynchronous selectors.
+`sourcePreview` and each translation's `preview` can render a custom preview.
+Each translation also accepts a readable `label` and an `actions` slot (`null`
+suppresses default actions).
+
+A translation's `onSave` is a command callback. It can open a confirmation dialog
+that retains the supplied draft's `save` action, then supply typed context and
+handle the returned result. The view never calls persistence itself or interprets
+application receipts. Without `onSave`, default actions include copy and reset
+but no save button. Validation and pending state disable the default save button;
+custom action slots own their own disabled/confirmation behavior.
+
+All built-in strings can be overridden through `labels`, including individual
+`labels.validation` entries. Supply already-localized strings from your preferred
+library. The workflow demo demonstrates a React Intl consumer without making
+`IntlProvider` a requirement for the public UI.
+
+## Browser interaction tests
+
+Write native Playwright `*.spec.ts` files in `packages/editor/vrt/`. The
+`e2eConfig` helper supplies `baseURL`, so specs can use `page.goto('/')`,
+accessible locators, clicks, and web-first assertions. VRT captures are generated from the `.visual.tsx` module. Both targets share the consumer-owned
+server, shell, declared inputs, and pinned Testcontainers browser.
+
+```sh
+bazel test //packages/editor/vrt:e2e_test --test_output=errors
+bazel test //packages/editor/vrt:e2e_test --test_arg=--grep=translation
+```
+
+E2E covers editing, search, selection, copy/clear, ICU error recovery, locale
+drafts, and saving. It requires Docker and runs manually, locally, and uncached.
+CI should explicitly select both `e2e_test` and `visual_test`. Failures retain
+JUnit, screenshots, and Playwright traces in undeclared test outputs.
+
+## Component browser tests
+
+`bazel test //packages/editor/vrt:component_test --test_output=errors` runs
+Playwright 1.63 native `mount()` specs for the real editor. The typed
+`editor.visual.tsx` uses the existing provider shell and demo; `gallery.tsx` owns
+mount/update/unmount. The tests check provider updates without losing a draft,
+clear, ICU validation, and isolation between mounts.
+
+`component_browser_test` shares the custom server, root npm dependencies, strict
+typechecks, and pinned Testcontainers browser with E2E and VRT.
+`componentBrowserConfig` discovers `*.browser.spec.ts` separately from the E2E
+`*.spec.ts` and generated VRT capture cases. CI should explicitly run all three
+manual browser targets. Screenshot baselines and updates remain in `visual_test`.
+
+The default export of `editor.visual.tsx` is a `ComponentVisualModule`: it declares
+renderable cases, browser-side capture hooks, and VRT options. The gallery registers
+that module with `installVisualGallery`. The shared runtime generates all six
+screenshot tests; no `editor.visual.spec.ts` is maintained. Interaction tests stay
+in `editor.browser.spec.tsx`, and the existing PNG names remain explicit in the
+visual declarations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formatjs/editor",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "description": "Headless ICU MessageFormat editor for React",
   "keywords": [
@@ -34,7 +34,11 @@
   "sideEffects": false,
   "types": "index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./ui": {
+      "types": "./ui.d.ts",
+      "default": "./ui.js"
+    }
   },
   "dependencies": {
     "@formatjs/icu-messageformat-parser": "3.5.17"

package/ui.d.ts

@@ -0,0 +1,177 @@
+import { ComponentType, ReactNode } from "react";
+import "@formatjs/icu-messageformat-parser";
+//#region packages/editor/validation.d.ts
+type TranslationValidationError = "empty" | "invalid-source" | "invalid-translation" | "structure";
+//#endregion
+//#region packages/editor/workflow.d.ts
+interface SourceLocation {
+  file: string;
+  start?: number;
+  end?: number;
+}
+interface EditorMessage {
+  id: string;
+  defaultMessage: string;
+  description?: string;
+  catalogs?: readonly string[];
+  locations?: readonly SourceLocation[];
+  translations: Readonly<Record<string, string | undefined>>;
+}
+type TranslationSaveResult<TResult = void> = {
+  status: "saved";
+  value: TResult;
+} | {
+  status: "failed";
+  error: Error;
+} | {
+  status: "invalid";
+  validationError: TranslationValidationError;
+} | {
+  status: "skipped";
+  reason: "unavailable" | "unchanged" | "pending";
+};
+/** A render snapshot and actions for one message/locale pair. */
+interface TranslationDraftState<TContext = void, TResult = void> {
+  readonly value: string;
+  readonly baseline: string;
+  readonly validationError: TranslationValidationError | null;
+  readonly changed: boolean;
+  readonly isSaving: boolean;
+  readonly saveError: Error | null;
+  readonly saved: boolean;
+  setTranslation: (value: string) => void;
+  reset: () => void;
+  save: (context?: TContext) => Promise<TranslationSaveResult<TResult>>;
+}
+//#endregion
+//#region packages/editor/ui.d.ts
+export interface EditorButtonProps {
+  children: ReactNode;
+  /** Called once per activation, without a DOM event; disabled controls must not call it. */
+  onPress: () => void;
+  disabled?: boolean;
+  variant: "primary" | "secondary";
+}
+export interface EditorInputProps {
+  id: string;
+  value: string;
+  /** Reports the complete next string value; never a DOM event. */
+  onValueChange: (value: string) => void;
+  disabled?: boolean;
+  "aria-invalid"?: boolean;
+  "aria-describedby"?: string;
+}
+export interface EditorTextInputProps extends EditorInputProps {
+  type: "text" | "search";
+}
+export interface EditorTextAreaProps extends EditorInputProps {
+  /** Visible rows when supported by the control; defaults to six. */
+  rows?: number;
+}
+export interface EditorMessageRowProps {
+  children: ReactNode;
+  selected: boolean;
+  /** Activates this row without changing controlled selection itself. */
+  onSelect: () => void;
+}
+export interface EditorPanelProps {
+  children: ReactNode;
+  label: string;
+  kind: "source" | "translation";
+}
+export interface EditorLayoutProps {
+  toolbar: ReactNode;
+  navigation: ReactNode;
+  content: ReactNode;
+}
+/** Define adapters outside render so controls retain focus across edits. */
+export interface EditorComponents {
+  Button: ComponentType<EditorButtonProps>;
+  TextInput: ComponentType<EditorTextInputProps>;
+  TextArea: ComponentType<EditorTextAreaProps>;
+  MessageRow: ComponentType<EditorMessageRowProps>;
+  Panel: ComponentType<EditorPanelProps>;
+  Layout: ComponentType<EditorLayoutProps>;
+}
+export interface EditorLabels {
+  search: string;
+  messages: string;
+  source: string;
+  noMessages: string;
+  noSelection: string;
+  loading: string;
+  copySource: string;
+  reset: string;
+  save: string;
+  saving: string;
+  saved: string;
+  unsaved: string;
+  unchanged: string;
+  validation: Record<TranslationValidationError, string>;
+}
+export type EditorLabelOverrides = Partial<Omit<EditorLabels, "validation">> & {
+  validation?: Partial<EditorLabels["validation"]>;
+};
+/** Unstyled native controls; no CSS, icons, or localization provider is required. */
+export declare const nativeEditorComponents: EditorComponents;
+export interface EditorDesignSystemProviderProps {
+  /** Overrides inherit unspecified components from the nearest provider. */
+  components: Partial<EditorComponents>;
+  children: ReactNode;
+}
+/** Configure a tree once; sibling providers remain independent. */
+export declare function EditorDesignSystemProvider({ components, children }: EditorDesignSystemProviderProps): ReactNode;
+/** Read the resolved controls, including native defaults outside a provider. */
+export declare function useEditorDesignSystem(): Readonly<EditorComponents>;
+interface ViewOptions {
+  labels?: EditorLabelOverrides;
+}
+export type EditorViewMessage = Pick<EditorMessage, "id" | "defaultMessage" | "description">;
+export interface EditorSearch {
+  value: string;
+  onValueChange: (value: string) => void;
+}
+export interface MessageListProps extends ViewOptions {
+  messages: readonly EditorViewMessage[];
+  selectedId?: string;
+  onSelect: (id: string) => void;
+  search?: EditorSearch;
+  loading?: boolean;
+  pagination?: ReactNode;
+}
+/** Controlled list: it never filters, paginates, fetches, or changes selection itself. */
+export declare function MessageList({ messages, selectedId, onSelect, search, loading, pagination, labels }: MessageListProps): ReactNode;
+export interface SourceMessageProps extends ViewOptions {
+  message: EditorViewMessage;
+  preview?: ReactNode;
+  context?: ReactNode;
+}
+export declare function SourceMessage({ message, preview, context, labels }: SourceMessageProps): ReactNode;
+export type TranslationFieldDraft = Pick<TranslationDraftState, "value" | "validationError" | "changed" | "isSaving" | "saveError" | "saved" | "setTranslation" | "reset">;
+export interface TranslationFieldProps extends ViewOptions {
+  locale: string;
+  /** Human-readable label; defaults to the locale identifier. */
+  label?: string;
+  source: string;
+  draft: TranslationFieldDraft;
+  /** The caller owns confirmation, context, persistence, and receipt presentation. */
+  onSave?: () => void;
+  /** Overrides the default copy/reset/save actions, including with null. */
+  actions?: ReactNode;
+  preview?: ReactNode;
+}
+export declare function TranslationField({ locale, label, source, draft, onSave, actions, preview, labels }: TranslationFieldProps): ReactNode;
+export type EditorTranslation = Omit<TranslationFieldProps, "source" | "labels">;
+export interface TranslationEditorViewProps extends Omit<MessageListProps, "selectedId"> {
+  /** May be outside the loaded list, e.g. during a server-side page change. */
+  selectedMessage?: EditorViewMessage;
+  translations: readonly EditorTranslation[];
+  filters?: ReactNode;
+  context?: ReactNode;
+  sourcePreview?: ReactNode;
+  notice?: ReactNode;
+}
+/** A stateless composition over caller-owned navigation and locale drafts. */
+export declare function TranslationEditorView({ selectedMessage, translations, filters, context, sourcePreview, notice, labels, ...list }: TranslationEditorViewProps): ReactNode;
+//#endregion
+//# sourceMappingURL=ui.d.ts.map

package/ui.js

@@ -0,0 +1,212 @@
+import { createContext, createElement, useContext, useId, useMemo } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region packages/editor/ui.tsx
+const defaultLabels = {
+	search: "Search messages",
+	messages: "Messages",
+	source: "Source message",
+	noMessages: "No matching messages",
+	noSelection: "Select a message",
+	loading: "Loading messages…",
+	copySource: "Copy source",
+	reset: "Reset",
+	save: "Save translation",
+	saving: "Saving…",
+	saved: "Translation saved.",
+	unsaved: "Unsaved changes",
+	unchanged: "No unsaved changes",
+	validation: {
+		empty: "Enter a translation before saving.",
+		"invalid-source": "The source contains invalid ICU syntax.",
+		"invalid-translation": "The translation contains invalid ICU syntax.",
+		structure: "Preserve ICU arguments, tags, formatting styles, and selector branches."
+	}
+};
+function resolveLabels(labels) {
+	return {
+		...defaultLabels,
+		...labels,
+		validation: {
+			...defaultLabels.validation,
+			...labels?.validation
+		}
+	};
+}
+/** Unstyled native controls; no CSS, icons, or localization provider is required. */
+const nativeEditorComponents = {
+	Button: ({ children, onPress, disabled }) => /* @__PURE__ */ jsx("button", {
+		type: "button",
+		disabled,
+		onClick: () => onPress(),
+		children
+	}),
+	TextInput: ({ onValueChange, ...props }) => /* @__PURE__ */ jsx("input", {
+		...props,
+		onChange: (event) => onValueChange(event.target.value)
+	}),
+	TextArea: ({ onValueChange, rows = 6, ...props }) => /* @__PURE__ */ jsx("textarea", {
+		...props,
+		rows,
+		onChange: (event) => onValueChange(event.target.value)
+	}),
+	MessageRow: ({ children, selected, onSelect }) => /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"aria-current": selected ? "true" : void 0,
+		onClick: () => onSelect(),
+		children
+	}),
+	Panel: ({ children, label }) => /* @__PURE__ */ jsx("section", {
+		"aria-label": label,
+		children
+	}),
+	Layout: ({ toolbar, navigation, content }) => /* @__PURE__ */ jsxs("div", { children: [toolbar, /* @__PURE__ */ jsxs("div", { children: [navigation, content] })] })
+};
+const EditorDesignSystemContext = createContext(nativeEditorComponents);
+/** Configure a tree once; sibling providers remain independent. */
+function EditorDesignSystemProvider({ components, children }) {
+	const parent = useEditorDesignSystem();
+	const value = useMemo(() => ({
+		...parent,
+		...components
+	}), [parent, components]);
+	return /* @__PURE__ */ jsx(EditorDesignSystemContext, {
+		value,
+		children
+	});
+}
+/** Read the resolved controls, including native defaults outside a provider. */
+function useEditorDesignSystem() {
+	return useContext(EditorDesignSystemContext);
+}
+/** Controlled list: it never filters, paginates, fetches, or changes selection itself. */
+function MessageList({ messages, selectedId, onSelect, search, loading = false, pagination, labels }) {
+	const { TextInput, MessageRow } = useEditorDesignSystem();
+	const text = resolveLabels(labels);
+	const searchId = useId();
+	return /* @__PURE__ */ jsxs("nav", {
+		"aria-label": text.messages,
+		"aria-busy": loading,
+		children: [
+			search && /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("label", {
+				htmlFor: searchId,
+				children: text.search
+			}), /* @__PURE__ */ jsx(TextInput, {
+				id: searchId,
+				type: "search",
+				value: search.value,
+				onValueChange: search.onValueChange
+			})] }),
+			loading && /* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("output", { children: text.loading }) }),
+			/* @__PURE__ */ jsx("ul", { children: messages.map((message) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(MessageRow, {
+				selected: message.id === selectedId,
+				onSelect: () => onSelect(message.id),
+				children: [
+					/* @__PURE__ */ jsx("span", { children: message.defaultMessage }),
+					" ",
+					/* @__PURE__ */ jsx("code", { children: message.id })
+				]
+			}) }, message.id)) }),
+			!loading && messages.length === 0 && /* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("output", { children: text.noMessages }) }),
+			pagination
+		]
+	});
+}
+function SourceMessage({ message, preview, context, labels }) {
+	const { Panel } = useEditorDesignSystem();
+	const text = resolveLabels(labels);
+	return /* @__PURE__ */ jsxs(Panel, {
+		kind: "source",
+		label: text.source,
+		children: [
+			/* @__PURE__ */ jsx("h2", { children: text.source }),
+			/* @__PURE__ */ jsx("code", { children: message.id }),
+			preview ?? /* @__PURE__ */ jsx("pre", { children: message.defaultMessage }),
+			message.description && /* @__PURE__ */ jsx("p", { children: message.description }),
+			context
+		]
+	});
+}
+function TranslationField({ locale, label = locale, source, draft, onSave, actions, preview, labels }) {
+	const { Panel, TextArea, Button } = useEditorDesignSystem();
+	const text = resolveLabels(labels);
+	const id = useId();
+	const errorId = `${id}-error`;
+	const statusId = `${id}-status`;
+	const validation = draft.validationError ? text.validation[draft.validationError] : null;
+	const error = validation ?? draft.saveError?.message;
+	return /* @__PURE__ */ jsxs(Panel, {
+		kind: "translation",
+		label,
+		children: [
+			/* @__PURE__ */ jsx("label", {
+				htmlFor: id,
+				children: label
+			}),
+			/* @__PURE__ */ jsx(TextArea, {
+				id,
+				value: draft.value,
+				onValueChange: draft.setTranslation,
+				"aria-invalid": !!validation,
+				"aria-describedby": error ? `${errorId} ${statusId}` : statusId
+			}),
+			error && /* @__PURE__ */ jsx("p", {
+				id: errorId,
+				role: "alert",
+				children: error
+			}),
+			/* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("output", {
+				id: statusId,
+				children: draft.isSaving ? text.saving : draft.saved ? text.saved : draft.changed ? text.unsaved : text.unchanged
+			}) }),
+			preview,
+			actions !== void 0 ? actions : /* @__PURE__ */ jsxs("div", { children: [
+				/* @__PURE__ */ jsx(Button, {
+					variant: "secondary",
+					disabled: draft.isSaving,
+					onPress: () => draft.setTranslation(source),
+					children: text.copySource
+				}),
+				/* @__PURE__ */ jsx(Button, {
+					variant: "secondary",
+					disabled: !draft.changed || draft.isSaving,
+					onPress: draft.reset,
+					children: text.reset
+				}),
+				onSave && /* @__PURE__ */ jsx(Button, {
+					variant: "primary",
+					disabled: !draft.changed || !!draft.validationError || draft.isSaving,
+					onPress: onSave,
+					children: draft.isSaving ? text.saving : text.save
+				})
+			] })
+		]
+	});
+}
+/** A stateless composition over caller-owned navigation and locale drafts. */
+function TranslationEditorView({ selectedMessage, translations, filters, context, sourcePreview, notice, labels, ...list }) {
+	const { Layout } = useEditorDesignSystem();
+	const text = resolveLabels(labels);
+	return /* @__PURE__ */ jsx(Layout, {
+		toolbar: filters,
+		navigation: /* @__PURE__ */ jsx(MessageList, {
+			...list,
+			selectedId: selectedMessage?.id,
+			labels
+		}),
+		content: /* @__PURE__ */ jsxs(Fragment, { children: [notice, selectedMessage ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(SourceMessage, {
+			message: selectedMessage,
+			preview: sourcePreview,
+			context,
+			labels
+		}), translations.map((translation) => /* @__PURE__ */ createElement(TranslationField, {
+			...translation,
+			key: `${selectedMessage.id}:${translation.locale}`,
+			source: selectedMessage.defaultMessage,
+			labels
+		}))] }) : /* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsx("output", { children: text.noSelection }) })] })
+	});
+}
+//#endregion
+export { EditorDesignSystemProvider, MessageList, SourceMessage, TranslationEditorView, TranslationField, nativeEditorComponents, useEditorDesignSystem };
+
+//# sourceMappingURL=ui.js.map

package/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","names":[],"sources":["../ui.tsx"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  useId,\n  useMemo,\n  type ComponentType,\n  type ReactNode,\n} from 'react'\nimport type {\n  EditorMessage,\n  TranslationDraftState,\n} from '#packages/editor/workflow.js'\nimport type {TranslationValidationError} from '#packages/editor/validation.js'\n\nexport interface EditorButtonProps {\n  children: ReactNode\n  /** Called once per activation, without a DOM event; disabled controls must not call it. */\n  onPress: () => void\n  disabled?: boolean\n  variant: 'primary' | 'secondary'\n}\nexport interface EditorInputProps {\n  id: string\n  value: string\n  /** Reports the complete next string value; never a DOM event. */\n  onValueChange: (value: string) => void\n  disabled?: boolean\n  'aria-invalid'?: boolean\n  'aria-describedby'?: string\n}\nexport interface EditorTextInputProps extends EditorInputProps {\n  type: 'text' | 'search'\n}\nexport interface EditorTextAreaProps extends EditorInputProps {\n  /** Visible rows when supported by the control; defaults to six. */\n  rows?: number\n}\nexport interface EditorMessageRowProps {\n  children: ReactNode\n  selected: boolean\n  /** Activates this row without changing controlled selection itself. */\n  onSelect: () => void\n}\nexport interface EditorPanelProps {\n  children: ReactNode\n  label: string\n  kind: 'source' | 'translation'\n}\nexport interface EditorLayoutProps {\n  toolbar: ReactNode\n  navigation: ReactNode\n  content: ReactNode\n}\n/** Define adapters outside render so controls retain focus across edits. */\nexport interface EditorComponents {\n  Button: ComponentType<EditorButtonProps>\n  TextInput: ComponentType<EditorTextInputProps>\n  TextArea: ComponentType<EditorTextAreaProps>\n  MessageRow: ComponentType<EditorMessageRowProps>\n  Panel: ComponentType<EditorPanelProps>\n  Layout: ComponentType<EditorLayoutProps>\n}\nexport interface EditorLabels {\n  search: string\n  messages: string\n  source: string\n  noMessages: string\n  noSelection: string\n  loading: string\n  copySource: string\n  reset: string\n  save: string\n  saving: string\n  saved: string\n  unsaved: string\n  unchanged: string\n  validation: Record<TranslationValidationError, string>\n}\nconst defaultLabels: EditorLabels = {\n  search: 'Search messages',\n  messages: 'Messages',\n  source: 'Source message',\n  noMessages: 'No matching messages',\n  noSelection: 'Select a message',\n  loading: 'Loading messages…',\n  copySource: 'Copy source',\n  reset: 'Reset',\n  save: 'Save translation',\n  saving: 'Saving…',\n  saved: 'Translation saved.',\n  unsaved: 'Unsaved changes',\n  unchanged: 'No unsaved changes',\n  validation: {\n    empty: 'Enter a translation before saving.',\n    'invalid-source': 'The source contains invalid ICU syntax.',\n    'invalid-translation': 'The translation contains invalid ICU syntax.',\n    structure:\n      'Preserve ICU arguments, tags, formatting styles, and selector branches.',\n  },\n}\nexport type EditorLabelOverrides = Partial<Omit<EditorLabels, 'validation'>> & {\n  validation?: Partial<EditorLabels['validation']>\n}\nfunction resolveLabels(labels?: EditorLabelOverrides): EditorLabels {\n  return {\n    ...defaultLabels,\n    ...labels,\n    validation: {...defaultLabels.validation, ...labels?.validation},\n  }\n}\n/** Unstyled native controls; no CSS, icons, or localization provider is required. */\nexport const nativeEditorComponents: EditorComponents = {\n  Button: ({children, onPress, disabled}) => (\n    <button type=\"button\" disabled={disabled} onClick={() => onPress()}>\n      {children}\n    </button>\n  ),\n  TextInput: ({onValueChange, ...props}) => (\n    <input {...props} onChange={event => onValueChange(event.target.value)} />\n  ),\n  TextArea: ({onValueChange, rows = 6, ...props}) => (\n    <textarea\n      {...props}\n      rows={rows}\n      onChange={event => onValueChange(event.target.value)}\n    />\n  ),\n  MessageRow: ({children, selected, onSelect}) => (\n    <button\n      type=\"button\"\n      aria-current={selected ? 'true' : undefined}\n      onClick={() => onSelect()}\n    >\n      {children}\n    </button>\n  ),\n  Panel: ({children, label}) => (\n    <section aria-label={label}>{children}</section>\n  ),\n  Layout: ({toolbar, navigation, content}) => (\n    <div>\n      {toolbar}\n      <div>\n        {navigation}\n        {content}\n      </div>\n    </div>\n  ),\n}\nconst EditorDesignSystemContext = createContext<Readonly<EditorComponents>>(\n  nativeEditorComponents\n)\n\nexport interface EditorDesignSystemProviderProps {\n  /** Overrides inherit unspecified components from the nearest provider. */\n  components: Partial<EditorComponents>\n  children: ReactNode\n}\n/** Configure a tree once; sibling providers remain independent. */\nexport function EditorDesignSystemProvider({\n  components,\n  children,\n}: EditorDesignSystemProviderProps): ReactNode {\n  const parent = useEditorDesignSystem()\n  const value = useMemo(\n    () => ({...parent, ...components}),\n    [parent, components]\n  )\n  return (\n    <EditorDesignSystemContext value={value}>\n      {children}\n    </EditorDesignSystemContext>\n  )\n}\n/** Read the resolved controls, including native defaults outside a provider. */\nexport function useEditorDesignSystem(): Readonly<EditorComponents> {\n  return useContext(EditorDesignSystemContext)\n}\ninterface ViewOptions {\n  labels?: EditorLabelOverrides\n}\nexport type EditorViewMessage = Pick<\n  EditorMessage,\n  'id' | 'defaultMessage' | 'description'\n>\nexport interface EditorSearch {\n  value: string\n  onValueChange: (value: string) => void\n}\nexport interface MessageListProps extends ViewOptions {\n  messages: readonly EditorViewMessage[]\n  selectedId?: string\n  onSelect: (id: string) => void\n  search?: EditorSearch\n  loading?: boolean\n  pagination?: ReactNode\n}\n/** Controlled list: it never filters, paginates, fetches, or changes selection itself. */\nexport function MessageList({\n  messages,\n  selectedId,\n  onSelect,\n  search,\n  loading = false,\n  pagination,\n  labels,\n}: MessageListProps): ReactNode {\n  const {TextInput, MessageRow} = useEditorDesignSystem()\n  const text = resolveLabels(labels)\n  const searchId = useId()\n  return (\n    <nav aria-label={text.messages} aria-busy={loading}>\n      {search && (\n        <div>\n          <label htmlFor={searchId}>{text.search}</label>\n          <TextInput\n            id={searchId}\n            type=\"search\"\n            value={search.value}\n            onValueChange={search.onValueChange}\n          />\n        </div>\n      )}\n      {loading && (\n        <p>\n          <output>{text.loading}</output>\n        </p>\n      )}\n      <ul>\n        {messages.map(message => (\n          <li key={message.id}>\n            <MessageRow\n              selected={message.id === selectedId}\n              onSelect={() => onSelect(message.id)}\n            >\n              <span>{message.defaultMessage}</span> <code>{message.id}</code>\n            </MessageRow>\n          </li>\n        ))}\n      </ul>\n      {!loading && messages.length === 0 && (\n        <p>\n          <output>{text.noMessages}</output>\n        </p>\n      )}\n      {pagination}\n    </nav>\n  )\n}\nexport interface SourceMessageProps extends ViewOptions {\n  message: EditorViewMessage\n  preview?: ReactNode\n  context?: ReactNode\n}\nexport function SourceMessage({\n  message,\n  preview,\n  context,\n  labels,\n}: SourceMessageProps): ReactNode {\n  const {Panel} = useEditorDesignSystem()\n  const text = resolveLabels(labels)\n  return (\n    <Panel kind=\"source\" label={text.source}>\n      <h2>{text.source}</h2>\n      <code>{message.id}</code>\n      {preview ?? <pre>{message.defaultMessage}</pre>}\n      {message.description && <p>{message.description}</p>}\n      {context}\n    </Panel>\n  )\n}\nexport type TranslationFieldDraft = Pick<\n  TranslationDraftState,\n  | 'value'\n  | 'validationError'\n  | 'changed'\n  | 'isSaving'\n  | 'saveError'\n  | 'saved'\n  | 'setTranslation'\n  | 'reset'\n>\nexport interface TranslationFieldProps extends ViewOptions {\n  locale: string\n  /** Human-readable label; defaults to the locale identifier. */\n  label?: string\n  source: string\n  draft: TranslationFieldDraft\n  /** The caller owns confirmation, context, persistence, and receipt presentation. */\n  onSave?: () => void\n  /** Overrides the default copy/reset/save actions, including with null. */\n  actions?: ReactNode\n  preview?: ReactNode\n}\nexport function TranslationField({\n  locale,\n  label = locale,\n  source,\n  draft,\n  onSave,\n  actions,\n  preview,\n  labels,\n}: TranslationFieldProps): ReactNode {\n  const {Panel, TextArea, Button} = useEditorDesignSystem()\n  const text = resolveLabels(labels)\n  const id = useId()\n  const errorId = `${id}-error`\n  const statusId = `${id}-status`\n  const validation = draft.validationError\n    ? text.validation[draft.validationError]\n    : null\n  const error = validation ?? draft.saveError?.message\n  return (\n    <Panel kind=\"translation\" label={label}>\n      <label htmlFor={id}>{label}</label>\n      <TextArea\n        id={id}\n        value={draft.value}\n        onValueChange={draft.setTranslation}\n        aria-invalid={!!validation}\n        aria-describedby={error ? `${errorId} ${statusId}` : statusId}\n      />\n      {error && (\n        <p id={errorId} role=\"alert\">\n          {error}\n        </p>\n      )}\n      <p>\n        <output id={statusId}>\n          {draft.isSaving\n            ? text.saving\n            : draft.saved\n              ? text.saved\n              : draft.changed\n                ? text.unsaved\n                : text.unchanged}\n        </output>\n      </p>\n      {preview}\n      {actions !== undefined ? (\n        actions\n      ) : (\n        <div>\n          <Button\n            variant=\"secondary\"\n            disabled={draft.isSaving}\n            onPress={() => draft.setTranslation(source)}\n          >\n            {text.copySource}\n          </Button>\n          <Button\n            variant=\"secondary\"\n            disabled={!draft.changed || draft.isSaving}\n            onPress={draft.reset}\n          >\n            {text.reset}\n          </Button>\n          {onSave && (\n            <Button\n              variant=\"primary\"\n              disabled={\n                !draft.changed || !!draft.validationError || draft.isSaving\n              }\n              onPress={onSave}\n            >\n              {draft.isSaving ? text.saving : text.save}\n            </Button>\n          )}\n        </div>\n      )}\n    </Panel>\n  )\n}\nexport type EditorTranslation = Omit<TranslationFieldProps, 'source' | 'labels'>\nexport interface TranslationEditorViewProps extends Omit<\n  MessageListProps,\n  'selectedId'\n> {\n  /** May be outside the loaded list, e.g. during a server-side page change. */\n  selectedMessage?: EditorViewMessage\n  translations: readonly EditorTranslation[]\n  filters?: ReactNode\n  context?: ReactNode\n  sourcePreview?: ReactNode\n  notice?: ReactNode\n}\n/** A stateless composition over caller-owned navigation and locale drafts. */\nexport function TranslationEditorView({\n  selectedMessage,\n  translations,\n  filters,\n  context,\n  sourcePreview,\n  notice,\n  labels,\n  ...list\n}: TranslationEditorViewProps): ReactNode {\n  const {Layout} = useEditorDesignSystem()\n  const text = resolveLabels(labels)\n  return (\n    <Layout\n      toolbar={filters}\n      navigation={\n        <MessageList\n          {...list}\n          selectedId={selectedMessage?.id}\n          labels={labels}\n        />\n      }\n      content={\n        <>\n          {notice}\n          {selectedMessage ? (\n            <>\n              <SourceMessage\n                message={selectedMessage}\n                preview={sourcePreview}\n                context={context}\n                labels={labels}\n              />\n              {translations.map(translation => (\n                <TranslationField\n                  {...translation}\n                  key={`${selectedMessage.id}:${translation.locale}`}\n                  source={selectedMessage.defaultMessage}\n                  labels={labels}\n                />\n              ))}\n            </>\n          ) : (\n            <p>\n              <output>{text.noSelection}</output>\n            </p>\n          )}\n        </>\n      }\n    />\n  )\n}\n"],"mappings":"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"}