@medway-ui/native 1.2.0 → 1.3.0

package/src/editor/index.ts

@@ -0,0 +1,13 @@
+export { default as NoteEditor } from "./NoteEditor";
+export type { NoteEditorHandle } from "./NoteEditor";
+export type { WebViewMessageEvent } from "react-native-webview";
+
+export {
+  EDITOR_PROTOCOL_VERSION,
+  EDITOR_RECEIVE_HANDLER,
+  isEditorMessage,
+} from "./protocol";
+export type {
+  EditorToNativeMessage,
+  NativeToEditorMessage,
+} from "./protocol";

package/src/editor/protocol.ts

@@ -0,0 +1,184 @@
+/**
+ * Transport between React Native and the Tiptap editor inside the WebView. Both
+ * sides compile against this file — the bundle imports it through the `@/`
+ * alias in `editor-bundle/vite.config.ts`.
+ *
+ * Invariants:
+ * - The document never crosses the bridge on keystrokes: the editor emits
+ *   `change` with a revision counter, and the native side asks with
+ *   `getDocument`.
+ * - Every message is validated on arrival (`isEditorMessage`: envelope plus the
+ *   required fields of its variant) — the WebView renders student content, so
+ *   its output is untrusted input. Documents get a second pass through
+ *   `normalizeDocument` before reaching the host.
+ */
+
+import type {
+  EditorCommand,
+  EditorDocument,
+  EditorSelectionState,
+  EditorTheme,
+  SlashCommandId,
+  SlashMenuState,
+} from '@medway-ui/notes-core';
+
+/**
+ * Bumped whenever the message shapes below change. The native side refuses to
+ * talk to a bundle that reports a different version, which turns a stale
+ * `editorHtml.generated.ts` into a clear error instead of silent breakage.
+ */
+export const EDITOR_PROTOCOL_VERSION = 3;
+
+/** Name of the global the WebView bundle installs to receive native messages. */
+export const EDITOR_RECEIVE_HANDLER = '__medwayNoteEditorReceive';
+
+export type NativeToEditorMessage =
+  /**
+   * `reset` rebuilds the editor instance instead of replacing the running one's
+   * content — required when opening a *different* note, since replacing content
+   * carries the previous note's undo stack over.
+   *
+   * `doc` accepts HTML as well as JSON; parse (`generateJSON`) and whitelist
+   * (`normalizeDocument`) happen bundle-side, the only side with a DOM.
+   *
+   * `focusPosition` defaults to `"end"`. `imageDeleteGraceMs` seeds the bundle's
+   * image-removal bookkeeping; read once, not reactive.
+   */
+  | {
+      type: 'setContent';
+      doc: EditorDocument | string;
+      focus: boolean;
+      focusPosition?: 'start' | 'end';
+      reset?: boolean;
+      imageDeleteGraceMs?: number;
+      /**
+       * Read only on the `reset` path. Set here instead of creating editable
+       * and following up with `setEditable`, which would let a read-only note
+       * flash as editable for one frame. Defaults to `true`.
+       */
+      editable?: boolean;
+    }
+  | { type: 'setEditable'; editable: boolean }
+  | { type: 'setTheme'; theme: EditorTheme }
+  /**
+   * `embedded` means the editor is inside a native scroll container: it stops
+   * filling the viewport and starts reporting `resize`, so React Native can
+   * size the WebView to the document instead of nesting two scrollers.
+   */
+  | { type: 'setLayout'; embedded: boolean }
+  | { type: 'scrollCaretIntoView' }
+  | { type: 'command'; command: EditorCommand }
+  | { type: 'getDocument'; requestId: string }
+  | { type: 'runSlashCommand'; commandId: SlashCommandId }
+  | { type: 'dismissSlash' }
+  | { type: 'focus'; position: 'start' | 'end' }
+  | { type: 'blur' }
+  /**
+   * Inserts an image node at the current selection, once the host's
+   * `onImageUpload` resolved with a `src`. The bundle also starts tracking that
+   * `src` as "uploaded this session" — see `imageRemoved` below.
+   */
+  | { type: 'insertImage'; src: string; alt?: string | null };
+
+export type EditorToNativeMessage =
+  | { type: 'ready'; protocol: number }
+  | { type: 'state'; state: EditorSelectionState }
+  /** Content changed. `revision` increases monotonically, never resets. */
+  | { type: 'change'; revision: number }
+  | {
+      type: 'document';
+      requestId: string;
+      revision: number;
+      doc: EditorDocument;
+    }
+  | { type: 'slash'; slash: SlashMenuState }
+  /**
+   * Height of the rendered document, in CSS pixels. Only meaningful when
+   * embedded: the WebView does not scroll there, so React Native has to size it
+   * to its content.
+   */
+  | { type: 'resize'; height: number }
+  /** A link inside the note was tapped; the native side decides what to open. */
+  | { type: 'linkPress'; href: string }
+  /**
+   * Backspace with the selection collapsed at the first cursor position of the
+   * document. `NoteEditor` uses this to hand focus back to its title field —
+   * the inverse of the title's own Enter handler.
+   */
+  | { type: 'backspaceAtDocStart' }
+  /**
+   * A `src` that `insertImage` added this session left the document and stayed
+   * out past the grace period (`imageDeleteGraceMs`).
+   */
+  | { type: 'imageRemoved'; src: string }
+  | { type: 'error'; message: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+/** Rejects `NaN` and the infinities, which `JSON.parse` can still produce. */
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+/*
+ * `Record<Union, …>` rather than an array so it is exhaustive: adding a variant
+ * to `EditorToNativeMessage` without listing it here stops compiling, instead
+ * of letting `isEditorMessage` reject the new type at runtime — which would
+ * look like the message never arrived, not like a build error.
+ *
+ * Each entry checks the fields its own variant declares, so narrowing to the
+ * union is backed by the payload and not by `type` alone: a `document` without
+ * `doc`/`requestId`, or a `ready` without `protocol`, is rejected here instead
+ * of blowing up at the use site.
+ *
+ * `state`, `slash` and `doc` are checked as objects rather than field by field:
+ * their shapes belong to `@medway-ui/notes-core` and are validated there — for
+ * `doc`, by the `normalizeDocument` pass the native side runs before handing a
+ * document to the host.
+ */
+const EDITOR_MESSAGE_VALIDATORS: Record<
+  EditorToNativeMessage['type'],
+  (message: Record<string, unknown>) => boolean
+> = {
+  ready: (message) => isFiniteNumber(message.protocol),
+  state: (message) => isRecord(message.state),
+  change: (message) => isFiniteNumber(message.revision),
+  document: (message) =>
+    isString(message.requestId) &&
+    isFiniteNumber(message.revision) &&
+    isRecord(message.doc),
+  slash: (message) => isRecord(message.slash),
+  resize: (message) => isFiniteNumber(message.height),
+  linkPress: (message) => isString(message.href),
+  backspaceAtDocStart: () => true,
+  imageRemoved: (message) => isString(message.src),
+  error: (message) => isString(message.message),
+};
+
+/**
+ * Guard for anything arriving from the WebView: checks the envelope *and* the
+ * required fields of the variant its `type` names. Establishes the shape, not
+ * the contents — a `document` payload's `doc` still goes through
+ * `normalizeDocument` before the native side hands it to the host.
+ */
+export const isEditorMessage = (
+  value: unknown
+): value is EditorToNativeMessage => {
+  if (!isRecord(value)) return false;
+
+  const { type } = value;
+  if (typeof type !== 'string') return false;
+
+  // `hasOwnProperty`, not `in`: `in` walks the prototype chain, so a `type` of
+  // `"toString"` or `"constructor"` matches any plain object literal.
+  // `Object.hasOwn` would read better but is ES2022 and `lib` here is ES2020.
+  if (!Object.prototype.hasOwnProperty.call(EDITOR_MESSAGE_VALIDATORS, type)) {
+    return false;
+  }
+
+  return EDITOR_MESSAGE_VALIDATORS[type as EditorToNativeMessage['type']](
+    value
+  );
+};

package/src/index.ts

@@ -392,3 +392,9 @@ export type { ThemeColorToken } from "@/hooks/useThemeColor";
 // Theme-aware icon helper
 export { ThemedIcon } from "@/components/ThemedIcon";
 export type { ThemedIconProps } from "@/components/ThemedIcon";
+
+// NoteEditor is deliberately absent from this barrel: it pulls in
+// `react-native-webview` (an optional peer) and the 428 KB inlined editor HTML,
+// which Metro does not reliably tree-shake — every consumer of this package
+// would carry both. It ships as the `@medway-ui/native/note-editor` subpath
+// instead. Message types alone live at `@medway-ui/native/editor/protocol`.