@medway-ui/notes-core 0.1.0

package/src/document/normalize.ts

@@ -0,0 +1,456 @@
+/**
+ * Validation and normalization of the note document. The walk is a whitelist:
+ * unknown nodes, marks and attributes are dropped, not passed through, which is
+ * also what keeps `javascript:` hrefs out.
+ *
+ * Dependency-free on purpose: runs in React Native, the WebView bundle and the
+ * web, so it may not import from any of them.
+ */
+
+import type {
+  EditorAttributes,
+  EditorDocument,
+  EditorMark,
+  EditorMarkType,
+  EditorNode,
+  EditorNodeType,
+} from './types.js';
+
+/**
+ * Minimum valid document, and the value sent as `content` when creating a note.
+ * Note that this is *not* what the editor is fed: ProseMirror's `doc` requires
+ * at least one block, so `toEditorContent` expands it to an empty paragraph.
+ */
+export const EMPTY_DOCUMENT: EditorDocument = { type: 'doc', content: [] };
+
+const MAX_HEADING_LEVEL = 3;
+/**
+ * Far beyond any real document: caps `normalizeNode`'s recursion so a corrupt
+ * payload collapses into a dropped node instead of overflowing the call stack,
+ * which would violate `normalizeDocument`'s "never throws" contract.
+ */
+const MAX_NODE_DEPTH = 64;
+const SAFE_LINK_PROTOCOLS = ['http:', 'https:', 'mailto:'];
+const SAFE_IMAGE_PROTOCOLS = ['http:', 'https:', 'data:'];
+
+/*
+ * `Record<Union, true>` rather than an array, so the list is exhaustive by
+ * compilation: adding a member to `EditorMarkType` without listing it here
+ * stops `tsc`, instead of being silently dropped by `normalizeDocument` at
+ * runtime. Same pattern as `MARK_TYPE_MAP` in `../schema/contract.ts` and
+ * `EDITOR_MESSAGE_VALIDATORS` in `@medway-ui/native`.
+ */
+const MARK_TYPES: Record<EditorMarkType, true> = {
+  bold: true,
+  italic: true,
+  underline: true,
+  strike: true,
+  code: true,
+  link: true,
+};
+
+/** What each node accepts as children, mirroring the Tiptap schema. */
+type ContentKind =
+  | 'block'
+  | 'inline'
+  | 'listItem'
+  | 'taskItem'
+  | 'text'
+  | 'none';
+
+/**
+ * Node types that may sit directly under `doc` or under a block container.
+ * Declared as an `Exclude` so a new member of `EditorNodeType` has to be
+ * classified here, in one direction or the other, before this file compiles.
+ */
+type EditorBlockNodeType = Exclude<
+  EditorNodeType,
+  'doc' | 'text' | 'hardBreak' | 'listItem' | 'taskItem'
+>;
+
+const BLOCK_TYPES: Record<EditorBlockNodeType, true> = {
+  paragraph: true,
+  heading: true,
+  bulletList: true,
+  orderedList: true,
+  taskList: true,
+  blockquote: true,
+  codeBlock: true,
+  horizontalRule: true,
+  image: true,
+};
+
+const isBlockType = (type: EditorNodeType): boolean =>
+  Object.prototype.hasOwnProperty.call(BLOCK_TYPES, type);
+
+const CONTENT_KIND: Record<EditorNodeType, ContentKind> = {
+  doc: 'block',
+  paragraph: 'inline',
+  text: 'none',
+  hardBreak: 'none',
+  heading: 'inline',
+  bulletList: 'listItem',
+  orderedList: 'listItem',
+  listItem: 'block',
+  taskList: 'taskItem',
+  taskItem: 'block',
+  blockquote: 'block',
+  codeBlock: 'text',
+  horizontalRule: 'none',
+  image: 'none',
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const toArray = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value : [];
+
+const clampHeadingLevel = (value: unknown): 1 | 2 | 3 => {
+  const level = Math.trunc(Number(value));
+
+  if (!Number.isFinite(level) || level < 1) return 1;
+
+  return (level > MAX_HEADING_LEVEL ? MAX_HEADING_LEVEL : level) as 1 | 2 | 3;
+};
+
+/**
+ * Accepts only absolute `http(s)` and `mailto` links. Relative URLs are
+ * rejected too: a note is not served from a page, so there is no base to
+ * resolve them against.
+ */
+export const sanitizeLinkHref = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+
+  const href = value.trim();
+  if (!href) return null;
+
+  try {
+    const { protocol } = new URL(href);
+    return SAFE_LINK_PROTOCOLS.includes(protocol) ? href : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Same idea as `sanitizeLinkHref`, with `data:` additionally allowed. */
+export const sanitizeImageSrc = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+
+  const src = value.trim();
+  if (!src) return null;
+
+  try {
+    const { protocol } = new URL(src);
+    return SAFE_IMAGE_PROTOCOLS.includes(protocol) ? src : null;
+  } catch {
+    return null;
+  }
+};
+
+const normalizeMark = (value: unknown): EditorMark | null => {
+  if (!isPlainObject(value)) return null;
+
+  const { type } = value;
+  if (typeof type !== 'string') return null;
+  // `hasOwnProperty`, not `in`: `type` is raw JSON, and `in` walks the
+  // prototype chain, so `"toString"` would pass as a mark type.
+  if (!Object.prototype.hasOwnProperty.call(MARK_TYPES, type)) return null;
+
+  if (type !== 'link') {
+    return { type: type as EditorMarkType };
+  }
+
+  const attrs = isPlainObject(value.attrs) ? value.attrs : {};
+  const href = sanitizeLinkHref(attrs.href);
+  if (!href) return null;
+
+  return {
+    type: 'link',
+    attrs: { href, target: '_blank', rel: 'noopener noreferrer nofollow' },
+  };
+};
+
+const normalizeMarks = (value: unknown): EditorMark[] | undefined => {
+  const marks = toArray(value)
+    .map(normalizeMark)
+    .filter((mark): mark is EditorMark => mark !== null);
+
+  return marks.length ? marks : undefined;
+};
+
+const normalizeAttrs = (
+  type: EditorNodeType,
+  value: unknown
+): EditorAttributes | undefined => {
+  const attrs = isPlainObject(value) ? value : {};
+
+  switch (type) {
+    case 'heading':
+      return { level: clampHeadingLevel(attrs.level) };
+    case 'orderedList': {
+      const start = Math.trunc(Number(attrs.start));
+      return { start: Number.isFinite(start) && start > 0 ? start : 1 };
+    }
+    case 'taskItem':
+      return { checked: attrs.checked === true };
+    case 'codeBlock':
+      return {
+        language: typeof attrs.language === 'string' ? attrs.language : null,
+      };
+    default:
+      return undefined;
+  }
+};
+
+const acceptsChild = (
+  kind: ContentKind,
+  childType: EditorNodeType
+): boolean => {
+  switch (kind) {
+    case 'block':
+      return isBlockType(childType);
+    case 'inline':
+      return childType === 'text' || childType === 'hardBreak';
+    case 'listItem':
+      return childType === 'listItem';
+    case 'taskItem':
+      return childType === 'taskItem';
+    case 'text':
+      return childType === 'text';
+    case 'none':
+    default:
+      return false;
+  }
+};
+
+const stripMarks = (node: EditorNode): EditorNode => {
+  if (!node.marks) return node;
+
+  const stripped = { ...node };
+  delete stripped.marks;
+
+  return stripped;
+};
+
+const normalizeNode = (value: unknown, depth = 0): EditorNode | null => {
+  // Deliberately dropped rather than throwing or truncating in place, same as
+  // every other "unusable input" case in this function.
+  if (depth > MAX_NODE_DEPTH) return null;
+  if (!isPlainObject(value)) return null;
+
+  const { type } = value;
+  if (typeof type !== 'string') return null;
+  // Same reason as in `normalizeMark`: `in` would let a prototype key such as
+  // `"toString"` through as a node type.
+  if (!Object.prototype.hasOwnProperty.call(CONTENT_KIND, type)) return null;
+  if (type === 'doc') return null;
+
+  const nodeType = type as EditorNodeType;
+
+  if (nodeType === 'text') {
+    // A text node with no text is not representable in ProseMirror.
+    if (typeof value.text !== 'string' || value.text === '') return null;
+
+    const marks = normalizeMarks(value.marks);
+    return marks
+      ? { type: 'text', text: value.text, marks }
+      : {
+          type: 'text',
+          text: value.text,
+        };
+  }
+
+  if (nodeType === 'image') {
+    // Dropped outright: unlike a block, there is no sane placeholder for "a
+    // photo that isn't there".
+    const attrs = isPlainObject(value.attrs) ? value.attrs : {};
+    const src = sanitizeImageSrc(attrs.src);
+    if (!src) return null;
+
+    const alt = typeof attrs.alt === 'string' ? attrs.alt : undefined;
+    return alt
+      ? { type: 'image', attrs: { src, alt } }
+      : { type: 'image', attrs: { src } };
+  }
+
+  const kind = CONTENT_KIND[nodeType];
+  const attrs = normalizeAttrs(nodeType, value.attrs);
+  const node: EditorNode = attrs
+    ? { type: nodeType, attrs }
+    : { type: nodeType };
+
+  if (kind === 'none') return node;
+
+  // Arrow, not `.map(normalizeNode)`: `map` passes `index` as the second
+  // argument, which would land in `depth` — the `.map(parseInt)` footgun.
+  const children = toArray(value.content)
+    .map((child) => normalizeNode(child, depth + 1))
+    .filter((child): child is EditorNode => child !== null)
+    .filter((child) => acceptsChild(kind, child.type));
+
+  // Code blocks hold plain text; marks inside them are meaningless.
+  const content =
+    nodeType === 'codeBlock' ? children.map(stripMarks) : children;
+
+  // Containers that cannot legally be empty get an empty paragraph instead of
+  // being dropped, so a malformed list keeps its structure and stays editable.
+  if (
+    !content.length &&
+    (kind === 'block' || kind === 'listItem' || kind === 'taskItem')
+  ) {
+    if (
+      nodeType === 'listItem' ||
+      nodeType === 'taskItem' ||
+      nodeType === 'blockquote'
+    ) {
+      return { ...node, content: [{ type: 'paragraph' }] };
+    }
+    if (nodeType === 'bulletList' || nodeType === 'orderedList') {
+      return {
+        ...node,
+        content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }],
+      };
+    }
+    if (nodeType === 'taskList') {
+      return {
+        ...node,
+        content: [
+          {
+            type: 'taskItem',
+            attrs: { checked: false },
+            content: [{ type: 'paragraph' }],
+          },
+        ],
+      };
+    }
+  }
+
+  return content.length ? { ...node, content } : node;
+};
+
+/**
+ * Turns anything into a document that fits the schema. Never throws and never
+ * returns `null` — unusable input collapses to `EMPTY_DOCUMENT`, which is what
+ * keeps a corrupt payload from blanking the screen or reaching the API.
+ */
+export const normalizeDocument = (value: unknown): EditorDocument => {
+  if (!isPlainObject(value) || value.type !== 'doc') return EMPTY_DOCUMENT;
+
+  const content = toArray(value.content)
+    .map((node) => normalizeNode(node))
+    .filter((node): node is EditorNode => node !== null)
+    .filter((node) => isBlockType(node.type));
+
+  return { type: 'doc', content };
+};
+
+/** Type guard for callers that need to know whether normalization changed anything. */
+export const isEditorDocument = (value: unknown): value is EditorDocument =>
+  isPlainObject(value) && value.type === 'doc' && Array.isArray(value.content);
+
+/**
+ * ProseMirror's `doc` node requires `block+`, so the empty document has to grow
+ * a paragraph before it can be loaded into the editor. The API keeps storing
+ * the empty form.
+ */
+export const toEditorContent = (doc: EditorDocument): EditorDocument =>
+  doc.content.length ? doc : { type: 'doc', content: [{ type: 'paragraph' }] };
+
+const nodeHasText = (node: EditorNode): boolean => {
+  if (node.type === 'text') return Boolean(node.text?.trim());
+  if (node.type === 'horizontalRule' || node.type === 'image') return true;
+
+  return (node.content ?? []).some(nodeHasText);
+};
+
+/**
+ * True for a document a student would consider blank. An image or a horizontal
+ * rule counts as content, so a note holding only a photo is not empty — which
+ * is why `documentToPlainText` can return `""` for a document this call
+ * reports as non-empty. See the note there.
+ */
+export const isEmptyDocument = (doc: EditorDocument): boolean =>
+  !doc.content.some(nodeHasText);
+
+const jsonEquals = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+
+    return a.every((item, index) => jsonEquals(item, b[index]));
+  }
+
+  if (typeof a !== 'object') return false;
+
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+
+  if (keys.length !== Object.keys(right).length) return false;
+
+  return keys.every((key) => key in right && jsonEquals(left[key], right[key]));
+};
+
+/**
+ * Deep equality for documents, used by the autosave to skip no-op writes.
+ * Key order is irrelevant, so a document that only travelled through
+ * serialization does not read as changed.
+ */
+export const documentsAreEqual = (
+  a: EditorDocument,
+  b: EditorDocument
+): boolean => jsonEquals(a, b);
+
+/**
+ * Plain-text projection, used for previews and as a fallback note title.
+ *
+ * Returns `""` for documents that are *not* empty: an uncaptioned image, or a
+ * horizontal rule, is content for `isEmptyDocument` but has no text to project.
+ * Hosts deriving a title from this must keep their own fallback — do not read
+ * `documentToPlainText(doc) === ""` as "the note is blank", use
+ * `isEmptyDocument` for that.
+ */
+export const documentToPlainText = (doc: EditorDocument): string => {
+  const lines: string[] = [];
+
+  const walk = (nodes: EditorNode[], into: string[]) => {
+    nodes.forEach((node) => {
+      if (node.type === 'text') {
+        into.push(node.text ?? '');
+        return;
+      }
+      if (node.type === 'hardBreak') {
+        into.push(' ');
+        return;
+      }
+      if (node.type === 'image') {
+        // The only text an image carries. Emitted so a note whose first block is
+        // a captioned image still projects something — see the contract note on
+        // `documentToPlainText` for the uncaptioned case.
+        const alt =
+          typeof node.attrs?.alt === 'string' ? node.attrs.alt.trim() : '';
+        if (alt) lines.push(alt);
+        return;
+      }
+
+      const isBlock = isBlockType(node.type);
+      const target = isBlock ? [] : into;
+      walk(node.content ?? [], target);
+
+      if (isBlock && target !== into) {
+        const line = target.join('').trim();
+        if (line) lines.push(line);
+      }
+    });
+  };
+
+  walk(doc.content, []);
+
+  return lines.join('\n');
+};

package/src/document/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Document model of the notes editor. Mirrors Tiptap's `JSONContent` but
+ * declared by hand, so importing the document model never drags Tiptap in.
+ *
+ * This is the *whole* supported schema: adding a block means adding it here, in
+ * `./normalize.ts` and in `../schema/extensions.ts` — in that order.
+ */
+
+export type EditorMarkType =
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strike'
+  | 'code'
+  | 'link';
+
+export type EditorNodeType =
+  | 'doc'
+  | 'paragraph'
+  | 'text'
+  | 'hardBreak'
+  | 'heading'
+  | 'bulletList'
+  | 'orderedList'
+  | 'listItem'
+  | 'taskList'
+  | 'taskItem'
+  | 'blockquote'
+  | 'codeBlock'
+  | 'horizontalRule'
+  | 'image';
+
+export type EditorAttributes = Record<string, unknown>;
+
+export interface EditorMark {
+  type: EditorMarkType;
+  attrs?: EditorAttributes;
+}
+
+export interface EditorLinkMark extends EditorMark {
+  type: 'link';
+  attrs: {
+    href: string;
+    target: string | null;
+    rel: string | null;
+  };
+}
+
+/**
+ * `src` is whatever the host's upload callback returned (bucket URL in prod,
+ * `data:` only in a backend-less demo). Uploading and deleting the underlying
+ * file is the host's job; this package only carries the reference.
+ */
+export interface EditorImageNode extends EditorNode {
+  type: 'image';
+  attrs: {
+    src: string;
+    alt?: string | null;
+  };
+}
+
+export interface EditorNode {
+  type: EditorNodeType;
+  attrs?: EditorAttributes;
+  content?: EditorNode[];
+  marks?: EditorMark[];
+  text?: string;
+}
+
+/** Root of a note. This is the shape persisted in `Note.content`. */
+export interface EditorDocument {
+  type: 'doc';
+  content: EditorNode[];
+}

package/src/editor/handle.ts

@@ -0,0 +1,65 @@
+import type { EditorDocument } from '../document/types.js';
+import type {
+  EditorCommand,
+  EditorSelectionState,
+  SlashCommandId,
+  SlashMenuState,
+} from './vocabulary.js';
+
+/**
+ * What every host exposes once it has an editor running — a WebView plus
+ * message bridge on React Native, an in-process Tiptap `Editor` on web.
+ * Neither the WebView nor the `Editor` may leak past this interface.
+ */
+export type NoteEditorHandle = {
+  /** `false` until the editor is mounted and ready to accept commands. */
+  isReady: boolean;
+  state: EditorSelectionState;
+  slash: SlashMenuState;
+  /**
+   * Pulls the current document. Asynchronous because on React Native it is a
+   * round trip across the bridge — the document is serialized on demand, never
+   * pushed on every keystroke.
+   */
+  requestDocument: () => Promise<EditorDocument>;
+  runCommand: (command: EditorCommand) => void;
+  runSlashCommand: (commandId: SlashCommandId) => void;
+  dismissSlash: () => void;
+  focus: (position?: 'start' | 'end') => void;
+  blur: () => void;
+};
+
+/** The state a host starts from, before the editor has reported anything. */
+export const INITIAL_EDITOR_STATE: EditorSelectionState = {
+  isFocused: false,
+  isEmpty: true,
+  canUndo: false,
+  canRedo: false,
+  canIndent: false,
+  canOutdent: false,
+  active: {
+    bold: false,
+    italic: false,
+    underline: false,
+    strike: false,
+    code: false,
+    link: false,
+    paragraph: true,
+    heading1: false,
+    heading2: false,
+    heading3: false,
+    bulletList: false,
+    orderedList: false,
+    taskList: false,
+    blockquote: false,
+    codeBlock: false,
+  },
+  linkHref: null,
+};
+
+export const EMPTY_SLASH_STATE: SlashMenuState = {
+  active: false,
+  query: '',
+  commandIds: [],
+  caret: null,
+};