@formatjs/editor 1.1.47 → 1.3.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 FormatJS
+Copyright (c) 2023 FormatJS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,3 +1,189 @@
-# @formatjs/editor [WIP]
+# Headless message editor
 
-We've migrated the docs to https://formatjs.io/docs/tooling/editor.
+Install `@formatjs/editor` alongside React 19. The published package exports
+headless APIs and TypeScript declarations; demo UI remains repository-only.
+
+The React 19 editor exposes behavior without DOM, styles, a design system, an
+IntlProvider, or network requests. Consumers own catalogs, persistence, loading
+states, labels, layout, and providers. The StyleX view in `demo/demo.tsx` is an
+example consumer, not part of the headless entry point.
+
+The optional `demo/design-system/` layer provides tokens and native button, input,
+textarea, badge, and panel components. Customize `tokens.stylex.ts` or supply a
+StyleX theme. The demo adds responsive layout, keyboard focus, validation states,
+and logical spacing for RTL. Its Vite setup uses `@stylexjs/unplugin`; consumers
+using another design system need neither StyleX nor these components.
+
+```tsx
+import {useMessageEditor} from '@formatjs/editor'
+
+function TranslationEditor({messages, onMessageChange}) {
+  const editor = useMessageEditor({messages, onMessageChange})
+  return (
+    <YourTextArea
+      label="Translation"
+      value={editor.selectedMessage?.translatedMessage ?? ''}
+      onValueChange={editor.setTranslation}
+      invalid={!!editor.translation?.error}
+    />
+  )
+}
+```
+
+Use your design system's controls and localize their labels in the consumer.
+`Editor` also accepts a render function as `children` with the same state.
+Neither API adds elements or requires a provider.
+
+- `messages` is controlled; `onMessageChange` receives the edited message.
+  Apply it to the parent catalog by ID. Invalid ICU text is preserved for editing.
+- `selectMessage`, `selectedMessage`, `query`, and `setQuery` control navigation.
+  Search covers IDs, source text, translations, and descriptions. Filtering does
+  not discard selection or edits. A missing selection falls back to the first
+  catalog message; an empty catalog has no selection.
+- `setTranslation`, `copySource`, and `clearTranslation` edit the selected message.
+  Copy means copying source text into the translation, not the system clipboard.
+- `source` and `translation` expose `{ast, error}` parse results. The AST retains
+  all plural/select branches, rich-text tags, and skeletons. `Message` passes the
+  same result to its render function; `parseMessage` is available without React.
+
+Message IDs must be unique within a catalog. Remount the editor when switching
+catalogs if selection and search should reset. Persistence and validation policy
+(such as forbidding saves with ICU errors) belong to the consumer.
+
+This replaces the WIP Material UI app entry point. Import `Editor` or
+`useMessageEditor`; mount `EditorDemo` explicitly for the example view. Standalone
+entry points use React's `createRoot`. No Material UI dependency remains.
+
+Run `bazel test //packages/editor:unit_test` for state and renderer coverage.
+See [visual tests](vrt/README.md) for browser coverage and baseline updates.
+
+## Translation workflow
+
+`useTranslationEditor` layers draft storage and persistence on `useMessageEditor`.
+The existing `Editor`, `Message`, and `useMessageEditor` APIs stay unchanged.
+It adds no DOM, styling, provider, or network dependency.
+
+```tsx
+const workflow = useTranslationEditor({
+  messages, // {id, defaultMessage, description?, catalogs?, locations?, translations}
+  locales: ['fr', 'ru'],
+  defaultLocale: 'fr',
+  pageSize: 100,
+  onSave: async update => {
+    await persist(update) // {id, locale, translation}
+    setMessages(current =>
+      current.map(message =>
+        message.id === update.id
+          ? {
+              ...message,
+              translations: {
+                ...message.translations,
+                [update.locale]: update.translation,
+              },
+            }
+          : message
+      )
+    )
+  },
+})
+```
+
+Use `workflow.editor` for editing/search/selection, `pageMessages` for the current
+page, and `setLocale`, `setCatalog`, `setStatus`, and `setPage` for navigation.
+`selectedMessage` exposes catalog and source-location context. Status filters
+reflect saved translations, so typing does not move a message out of the list.
+Locales may load asynchronously; an absent selection falls back to the first
+available locale. Pagination clamps when messages or page size change.
+
+Drafts, reset baselines, errors, and pending saves are scoped by message ID and
+locale. Switching messages, filters, or locales retains drafts. `save()` validates
+the selected draft, ignores duplicate submissions for that key, and reports
+failure through `saveError`. A completed save updates only its submitted key;
+newer edits remain dirty. Update controlled messages after persistence succeeds.
+Clean drafts adopt external changes; dirty drafts retain their text. `reset()`
+restores the latest saved baseline. Remount when switching unrelated catalogs
+that reuse message IDs, or when intentionally discarding all drafts.
+
+### Multiple locale views
+
+Mount one workflow above your locale views. `getTranslation(id, locale)` exposes
+the value, baseline, validation, save feedback, and actions for that pair, sharing
+the same draft store as the selected-message API:
+
+```tsx
+const draft = workflow.getTranslation(messageId, locale)
+if (!draft) return null
+return (
+  <YourTextArea
+    value={draft.value}
+    onValueChange={draft.setTranslation}
+    invalid={!!draft.validationError}
+  />
+)
+```
+
+Each view can call `draft.reset()` and `draft.save()` independently. Hiding or
+unmounting a view preserves its draft while the owning workflow remains mounted.
+Keep available locales in the workflow's `locales` option; choose which views
+to display in your UI. The getter returns `undefined` for IDs or locales absent
+from the current options. Drafts survive their temporary removal, including saves
+that complete while a message is outside a loaded page.
+
+### Save results and context
+
+`save(context?)` resolves to a discriminated result. Successful persistence returns
+`{status: 'saved', value}` with the value returned by `onSave`. Failures return
+`{status: 'failed', error}` and also populate `saveError`. Validation failures return
+`{status: 'invalid', validationError}`. Saves that do not call persistence return
+`{status: 'skipped', reason}`, where the reason is `unavailable`, `unchanged`, or
+`pending`. The pending guard is scoped to a message/locale pair, so different pairs
+can save concurrently.
+
+The optional caller context and persistence result are generic types:
+
+```tsx
+type SaveContext = {intent: 'save' | 'review'}
+type Receipt = {revision: string}
+
+const workflow = useTranslationEditor<SaveContext, Receipt>({
+  messages,
+  locales,
+  onSave: async (update, snapshot) => {
+    return persist(update, {
+      intent: snapshot.context?.intent ?? 'save',
+      previousTranslation: snapshot.baselineTranslation,
+      source: snapshot.source,
+    })
+  },
+})
+
+const result = await workflow.save({intent: 'review'})
+if (result.status === 'saved') showReceipt(result.value.revision)
+```
+
+`onSave` receives the submitted translation and a frozen metadata object containing
+the source, baseline translation, and context. Draft state and its `save` action
+are render snapshots: retaining an action for a confirmation dialog retains that
+translation, source, and baseline even if selection or edits subsequently change.
+Context is passed by reference, not cloned; pass immutable context values.
+Persistence policy, confirmation UI, and receipt presentation remain with the
+consumer.
+
+Existing one-argument `onSave` callbacks and callers that await or ignore `save()`
+continue to work. Callers that explicitly annotate `save()` as `Promise<void>`
+must change that annotation to `Promise<TranslationSaveResult>` (with their result
+type parameter, if needed).
+
+`validateTranslation(source, translation)` returns `null` or a localizable error
+code: `empty`, `invalid-source`, `invalid-translation`, or `structure`. It checks
+arguments, tag nesting, formatting styles, select branches, plural type/offset,
+and exact selectors. Locale-specific plural categories are allowed; new
+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,
+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.

package/index.d.ts

@@ -1,4 +1,144 @@
-/// <reference types="react" />
-export declare function CoreApp(): JSX.Element;
-export default function App(): JSX.Element;
+import { ReactNode } from "react";
+import { MessageFormatElement } from "@formatjs/icu-messageformat-parser";
+//#region packages/editor/message.d.ts
+type ParsedMessage = {
+  ast: MessageFormatElement[];
+  error: null;
+} | {
+  ast: null;
+  error: Error;
+};
+/** Retains every ICU branch and skeleton; incomplete edits are valid input. */
+export declare function parseMessage(message: string): ParsedMessage;
+interface MessageProps {
+  message: string;
+  children: (parsed: ParsedMessage) => ReactNode;
+}
+export declare function Message({ message, children }: MessageProps): ReactNode;
+//#endregion
+//#region packages/editor/types.d.ts
+interface TranslatedMessage {
+  id: string;
+  defaultMessage: string;
+  translatedMessage: string;
+  description?: string;
+}
+//#endregion
+//#region packages/editor/core.d.ts
+interface EditorOptions {
+  messages: readonly TranslatedMessage[];
+  /** Apply the edit to consumer state; persistence stays with the consumer. */
+  onMessageChange: (message: TranslatedMessage) => void;
+  defaultSelectedId?: string;
+}
+interface EditorState {
+  messages: readonly TranslatedMessage[];
+  selectedMessage: TranslatedMessage | undefined;
+  selectMessage: (id: string) => void;
+  query: string;
+  setQuery: (query: string) => void;
+  source: ParsedMessage | undefined;
+  translation: ParsedMessage | undefined;
+  setTranslation: (value: string) => void;
+  copySource: () => void;
+  clearTranslation: () => void;
+}
+/** Controlled message data with no DOM, styling, providers, or network access. */
+export declare function useMessageEditor({ messages, onMessageChange, defaultSelectedId }: EditorOptions): EditorState;
+interface EditorProps extends EditorOptions {
+  children: (editor: EditorState) => ReactNode;
+}
+export declare function Editor({ children, ...options }: EditorProps): ReactNode;
+//#endregion
+//#region packages/editor/validation.d.ts
+type TranslationValidationError = "empty" | "invalid-source" | "invalid-translation" | "structure";
+/** Returns a stable error code; consumers own localized error copy. */
+export declare function validateTranslation(source: string, translation: string): TranslationValidationError | null;
+//#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>>;
+}
+interface TranslationUpdate {
+  id: string;
+  locale: string;
+  translation: string;
+}
+type MessageStatus = "all" | "translated" | "missing";
+/** Render-snapshot metadata plus consumer-owned context supplied to save. */
+interface TranslationSaveSnapshot<TContext = void> {
+  readonly source: string;
+  readonly baselineTranslation: string;
+  readonly context: TContext | undefined;
+}
+type TranslationSaveResult<TResult = void> = {
+  status: "saved";
+  value: TResult;
+} | {
+  status: "failed";
+  error: Error;
+} | {
+  status: "invalid";
+  validationError: TranslationValidationError;
+} | {
+  status: "skipped";
+  reason: "unavailable" | "unchanged" | "pending";
+};
+interface TranslationEditorOptions<TContext = void, TResult = void> {
+  messages: readonly EditorMessage[];
+  locales: readonly string[];
+  onSave: (update: TranslationUpdate, snapshot: TranslationSaveSnapshot<TContext>) => TResult | Promise<TResult>;
+  defaultLocale?: string;
+  pageSize?: number;
+}
+/** 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>>;
+}
+interface TranslationEditorState<TContext = void, TResult = void> {
+  editor: EditorState;
+  selectedMessage: EditorMessage | undefined;
+  locale: string | undefined;
+  setLocale: (locale: string) => void;
+  catalogs: readonly string[];
+  catalog: string;
+  setCatalog: (catalog: string) => void;
+  status: MessageStatus;
+  setStatus: (status: MessageStatus) => void;
+  page: number;
+  pageCount: number;
+  setPage: (page: number) => void;
+  pageMessages: EditorState["messages"];
+  validationError: TranslationValidationError | null;
+  changed: boolean;
+  isSaving: boolean;
+  saveError: Error | null;
+  saved: boolean;
+  save: (context?: TContext) => Promise<TranslationSaveResult<TResult>>;
+  reset: () => void;
+  getTranslation: (id: string, locale: string) => TranslationDraftState<TContext, TResult> | undefined;
+}
+/** Per-message, per-locale drafts layered on the existing headless editor. */
+export declare function useTranslationEditor<TContext = void, TResult = void>({ messages, locales, onSave, defaultLocale, pageSize }: TranslationEditorOptions<TContext, TResult>): TranslationEditorState<TContext, TResult>;
+//#endregion
+export type { EditorMessage, EditorOptions, EditorProps, EditorState, MessageProps, MessageStatus, ParsedMessage, SourceLocation, TranslatedMessage, TranslationDraftState, TranslationEditorOptions, TranslationEditorState, TranslationSaveResult, TranslationSaveSnapshot, TranslationUpdate, TranslationValidationError };
 //# sourceMappingURL=index.d.ts.map