@medway-ui/notes-core 0.1.0

package/src/editor/slashCommands.ts

@@ -0,0 +1,120 @@
+/**
+ * Catalog behind the `/` menu. The editor filters ids by `keywords` as the
+ * student types; the host renders the labels and icons — natively on mobile, in
+ * the DOM on the web. Keeping one list is what stops the ends from disagreeing
+ * about which commands exist.
+ *
+ * Dependency-free on purpose: both the editor and every host read this list.
+ */
+
+import type { SlashCommandId } from './vocabulary.js';
+
+export type SlashCommandDefinition = {
+  id: SlashCommandId;
+  label: string;
+  description: string;
+  /** Lowercase, unaccented terms matched against the typed query. */
+  keywords: string[];
+};
+
+export const SLASH_COMMANDS: readonly SlashCommandDefinition[] = [
+  {
+    id: 'paragraph',
+    label: 'Texto',
+    description: 'Parágrafo simples',
+    keywords: ['texto', 'paragrafo', 'text', 'p'],
+  },
+  {
+    id: 'heading1',
+    label: 'Título 1',
+    description: 'Título de seção grande',
+    keywords: ['titulo1', 'titulo', 'h1', 'heading'],
+  },
+  {
+    id: 'heading2',
+    label: 'Título 2',
+    description: 'Título de seção médio',
+    keywords: ['titulo2', 'titulo', 'h2', 'heading'],
+  },
+  {
+    id: 'heading3',
+    label: 'Título 3',
+    description: 'Título de seção pequeno',
+    keywords: ['titulo3', 'titulo', 'h3', 'heading'],
+  },
+  {
+    id: 'bulletList',
+    label: 'Lista',
+    description: 'Lista com marcadores',
+    keywords: ['lista', 'bullet', 'marcador', 'ul'],
+  },
+  {
+    id: 'orderedList',
+    label: 'Lista numerada',
+    description: 'Lista ordenada',
+    keywords: ['lista', 'numerada', 'ordenada', 'ol', 'numero'],
+  },
+  {
+    id: 'taskList',
+    label: 'Checklist',
+    description: 'Lista de tarefas',
+    keywords: ['checklist', 'tarefa', 'todo', 'check', 'caixa'],
+  },
+  {
+    id: 'blockquote',
+    label: 'Citação',
+    description: 'Bloco de citação',
+    keywords: ['citacao', 'quote', 'aspas'],
+  },
+  {
+    id: 'codeBlock',
+    label: 'Código',
+    description: 'Bloco de código',
+    keywords: ['codigo', 'code', 'bloco'],
+  },
+  {
+    id: 'horizontalRule',
+    label: 'Divisor',
+    description: 'Linha divisória',
+    keywords: ['divisor', 'linha', 'separador', 'hr'],
+  },
+  {
+    id: 'image',
+    label: 'Imagem',
+    description: 'Insere uma imagem',
+    keywords: ['imagem', 'foto', 'image', 'picture', 'upload'],
+  },
+];
+
+const ACCENTS = 'áàâãäéèêëíìîïóòôõöúùûüçñ';
+const PLAIN = 'aaaaaeeeeiiiiooooouuuucn';
+
+/** Lowercases and strips accents so "citacao" matches "citação". */
+const normalizeTerm = (term: string) =>
+  term
+    .toLowerCase()
+    .trim()
+    .split('')
+    .map((char) => {
+      const accentIndex = ACCENTS.indexOf(char);
+      return accentIndex === -1 ? char : PLAIN[accentIndex];
+    })
+    .join('');
+
+/** Filters the catalog by the text typed after `/`. Empty query lists all. */
+export const filterSlashCommands = (query: string): SlashCommandId[] => {
+  const term = normalizeTerm(query);
+
+  if (!term) {
+    return SLASH_COMMANDS.map((command) => command.id);
+  }
+
+  return SLASH_COMMANDS.filter((command) =>
+    command.keywords.some((keyword) => normalizeTerm(keyword).startsWith(term))
+  ).map((command) => command.id);
+};
+
+export const getSlashCommand = (
+  id: SlashCommandId
+): SlashCommandDefinition | undefined =>
+  SLASH_COMMANDS.find((command) => command.id === id);

package/src/editor/vocabulary.ts

@@ -0,0 +1,126 @@
+/**
+ * The vocabulary a note editor speaks, independent of how it is hosted: what
+ * can be asked of an editor and what it reports back is identical on mobile
+ * (WebView + bridge) and web (in-process), so a toolbar written against these
+ * types works either way.
+ *
+ * The transport (envelopes, protocol version, injected global) must not land
+ * here: it only exists on React Native.
+ */
+
+export type EditorMarkFlag =
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strike'
+  | 'code'
+  | 'link';
+
+export type EditorBlockFlag =
+  | 'paragraph'
+  | 'heading1'
+  | 'heading2'
+  | 'heading3'
+  | 'bulletList'
+  | 'orderedList'
+  | 'taskList'
+  | 'blockquote'
+  | 'codeBlock';
+
+export type EditorActiveFlags = Record<
+  EditorMarkFlag | EditorBlockFlag,
+  boolean
+>;
+
+/** Small payload published on every selection change to drive the toolbar. */
+export type EditorSelectionState = {
+  isFocused: boolean;
+  isEmpty: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  canIndent: boolean;
+  canOutdent: boolean;
+  active: EditorActiveFlags;
+  /** `href` of the link under the cursor, when there is one. */
+  linkHref: string | null;
+};
+
+export type SlashCommandId =
+  | 'paragraph'
+  | 'heading1'
+  | 'heading2'
+  | 'heading3'
+  | 'bulletList'
+  | 'orderedList'
+  | 'taskList'
+  | 'blockquote'
+  | 'codeBlock'
+  | 'horizontalRule'
+  | 'image';
+
+/**
+ * Caret rectangle in CSS pixels, relative to the editor's own viewport. The
+ * host places its menu from this — natively on mobile, in the DOM on the web.
+ */
+export type EditorCaretRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type SlashMenuState = {
+  active: boolean;
+  query: string;
+  /** Ids matching `query`, in display order. Empty means "no match". */
+  commandIds: SlashCommandId[];
+  caret: EditorCaretRect | null;
+};
+
+/**
+ * Resolved design-system values handed to the editor surface. The editor never
+ * picks its own colors — the host resolves them (Restyle on mobile, CSS custom
+ * properties on web) so the document follows light/dark mode and the student's
+ * font-size preference.
+ */
+export type EditorTheme = {
+  colorScheme: 'light' | 'dark';
+  background: string;
+  text: string;
+  heading: string;
+  muted: string;
+  placeholder: string;
+  border: string;
+  accent: string;
+  caret: string;
+  selection: string;
+  codeBackground: string;
+  codeText: string;
+  fontSize: number;
+  lineHeight: number;
+  paddingHorizontal: number;
+  paddingTop: number;
+  paddingBottom: number;
+};
+
+/** Everything a host may ask the editor to do. */
+export type EditorCommand =
+  | { name: 'toggleBold' }
+  | { name: 'toggleItalic' }
+  | { name: 'toggleUnderline' }
+  | { name: 'toggleStrike' }
+  | { name: 'toggleCode' }
+  | { name: 'setParagraph' }
+  | { name: 'toggleHeading'; level: 1 | 2 | 3 }
+  | { name: 'toggleBulletList' }
+  | { name: 'toggleOrderedList' }
+  | { name: 'toggleTaskList' }
+  | { name: 'toggleBlockquote' }
+  | { name: 'toggleCodeBlock' }
+  | { name: 'setHorizontalRule' }
+  | { name: 'setLink'; href: string }
+  | { name: 'unsetLink' }
+  | { name: 'indent' }
+  | { name: 'outdent' }
+  | { name: 'undo' }
+  | { name: 'redo' };

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * `@medway-ui/notes-core` — the note editor's domain layer: the document model,
+ * its whitelist, and the vocabulary hosts drive an editor with.
+ *
+ * Hard constraint: this entry point is free of Tiptap, React, React Native and
+ * the DOM. Anything touching Tiptap lives behind the `/schema` subpath.
+ */
+
+export type {
+  EditorAttributes,
+  EditorDocument,
+  EditorImageNode,
+  EditorLinkMark,
+  EditorMark,
+  EditorMarkType,
+  EditorNode,
+  EditorNodeType,
+} from './document/types.js';
+
+export {
+  EMPTY_DOCUMENT,
+  documentToPlainText,
+  documentsAreEqual,
+  isEditorDocument,
+  isEmptyDocument,
+  normalizeDocument,
+  sanitizeImageSrc,
+  sanitizeLinkHref,
+  toEditorContent,
+} from './document/normalize.js';
+
+export type {
+  EditorActiveFlags,
+  EditorBlockFlag,
+  EditorCaretRect,
+  EditorCommand,
+  EditorMarkFlag,
+  EditorSelectionState,
+  EditorTheme,
+  SlashCommandId,
+  SlashMenuState,
+} from './editor/vocabulary.js';
+
+export type { NoteEditorHandle } from './editor/handle.js';
+export { EMPTY_SLASH_STATE, INITIAL_EDITOR_STATE } from './editor/handle.js';
+
+export type { SlashCommandDefinition } from './editor/slashCommands.js';
+export {
+  SLASH_COMMANDS,
+  filterSlashCommands,
+  getSlashCommand,
+} from './editor/slashCommands.js';

package/src/schema/contract.ts

@@ -0,0 +1,76 @@
+import type { JSONContent } from '@tiptap/core';
+import type { Schema } from '@tiptap/pm/model';
+
+import type {
+  EditorDocument,
+  EditorMarkType,
+  EditorNodeType,
+} from '../document/types.js';
+
+/**
+ * Keeps the hand-written document types in `../document/types` honest: the
+ * type-level check below fails `tsc` if the mirror stops being assignable to
+ * Tiptap's `JSONContent`, and `assertSchemaContract` fails at runtime if a
+ * declared node or mark is missing from the built schema.
+ */
+type AssignableToTiptap = EditorDocument extends JSONContent ? true : never;
+const assignableToTiptap: AssignableToTiptap = true;
+
+// `Record<Union, true>` instead of an array: adding a member without listing it
+// here stops compiling.
+const NODE_TYPE_MAP: Record<EditorNodeType, true> = {
+  doc: true,
+  paragraph: true,
+  text: true,
+  hardBreak: true,
+  heading: true,
+  bulletList: true,
+  orderedList: true,
+  listItem: true,
+  taskList: true,
+  taskItem: true,
+  blockquote: true,
+  codeBlock: true,
+  horizontalRule: true,
+  image: true,
+};
+
+const MARK_TYPE_MAP: Record<EditorMarkType, true> = {
+  bold: true,
+  italic: true,
+  underline: true,
+  strike: true,
+  code: true,
+  link: true,
+};
+
+export const NODE_TYPES = Object.keys(NODE_TYPE_MAP) as EditorNodeType[];
+
+export const MARK_TYPES = Object.keys(MARK_TYPE_MAP) as EditorMarkType[];
+
+/**
+ * Returns every disagreement between the model and the built schema, in both
+ * directions: declared but missing (`node:`/`mark:`), and present in the schema
+ * but not the model (`extra-node:`/`extra-mark:`, which is how `extra` in
+ * `buildExtensions` can smuggle a type past this file). Either direction means
+ * one client can write JSON another client's `normalizeDocument` silently
+ * drops — treat any result as fatal in dev, not just log it.
+ */
+export const assertSchemaContract = (schema: Schema): string[] => {
+  void assignableToTiptap;
+
+  return [
+    ...NODE_TYPES.filter((name) => !(name in schema.nodes)).map(
+      (name) => `node:${name}`
+    ),
+    ...MARK_TYPES.filter((name) => !(name in schema.marks)).map(
+      (name) => `mark:${name}`
+    ),
+    ...Object.keys(schema.nodes)
+      .filter((name) => !(name in NODE_TYPE_MAP))
+      .map((name) => `extra-node:${name}`),
+    ...Object.keys(schema.marks)
+      .filter((name) => !(name in MARK_TYPE_MAP))
+      .map((name) => `extra-mark:${name}`),
+  ];
+};

package/src/schema/extensions.ts

@@ -0,0 +1,120 @@
+import type { AnyExtension } from '@tiptap/core';
+import Blockquote from '@tiptap/extension-blockquote';
+import Bold from '@tiptap/extension-bold';
+import Code from '@tiptap/extension-code';
+import CodeBlock from '@tiptap/extension-code-block';
+import Document from '@tiptap/extension-document';
+import HardBreak from '@tiptap/extension-hard-break';
+import Heading from '@tiptap/extension-heading';
+import HorizontalRule from '@tiptap/extension-horizontal-rule';
+import Italic from '@tiptap/extension-italic';
+import Link from '@tiptap/extension-link';
+import Paragraph from '@tiptap/extension-paragraph';
+import Strike from '@tiptap/extension-strike';
+import Text from '@tiptap/extension-text';
+import Underline from '@tiptap/extension-underline';
+import {
+  BulletList,
+  ListItem,
+  ListKeymap,
+  OrderedList,
+  TaskItem,
+  TaskList,
+} from '@tiptap/extension-list';
+import {
+  Dropcursor,
+  Gapcursor,
+  Placeholder,
+  Selection,
+  TrailingNode,
+  UndoRedo,
+} from '@tiptap/extensions';
+
+import { Image } from './image.js';
+
+const DEFAULT_PLACEHOLDER =
+  'Comece a escrever ou digite "/" para comandos';
+const DEFAULT_CARET_HINT = 'Digite "/" para comandos';
+
+export type BuildExtensionsOptions = {
+  /** Shown while the whole note is blank. */
+  placeholder?: string;
+  /** Shown on whichever empty paragraph currently holds the caret. */
+  caretHint?: string;
+  /**
+   * Appended after the schema — the slash-command extension from
+   * `createSlashCommand`, and anything else a host adds. Nothing here may
+   * introduce a node or a mark: the schema is what this file declares, and
+   * `assertSchemaContract` checks that claim.
+   */
+  extra?: AnyExtension[];
+};
+
+/**
+ * The document schema, and the single place where it is declared: a second
+ * declaration would let two clients write documents the other reads wrong.
+ *
+ * Node and mark names end up in the persisted JSON and must stay in sync with
+ * `EditorNodeType` / `EditorMarkType` in `../document/types`.
+ */
+export const buildExtensions = ({
+  placeholder = DEFAULT_PLACEHOLDER,
+  caretHint = DEFAULT_CARET_HINT,
+  extra = [],
+}: BuildExtensionsOptions = {}): AnyExtension[] => [
+  Document,
+  Paragraph,
+  Text,
+  HardBreak,
+  Heading.configure({ levels: [1, 2, 3] }),
+  BulletList,
+  OrderedList,
+  ListItem,
+  TaskList,
+  TaskItem.configure({ nested: true }),
+  Blockquote,
+  CodeBlock,
+  HorizontalRule,
+  Image,
+
+  Bold,
+  Italic,
+  Underline,
+  Strike,
+  Code,
+  Link.configure({
+    // Clicks are reported to the host, which decides what to open. The editor
+    // surface must never navigate away from the document it is editing.
+    openOnClick: false,
+    autolink: true,
+    linkOnPaste: true,
+    protocols: ['http', 'https', 'mailto'],
+    HTMLAttributes: { rel: 'noopener noreferrer nofollow', target: '_blank' },
+  }),
+
+  UndoRedo,
+  ListKeymap,
+  Dropcursor,
+  Gapcursor,
+  // Keeps the selection visible while the toolbar holds focus instead of the
+  // editor — the normal case on mobile.
+  Selection,
+  // Always an empty paragraph to tap at the end of the note.
+  TrailingNode,
+  Placeholder.configure({
+    placeholder: ({ editor, node, pos, hasAnchor }) => {
+      if (node.type.name !== 'paragraph') return '';
+
+      // `pos === 0` is required: a blank note stays `isEmpty` after Enter adds
+      // a second paragraph, so without it both paragraphs show the note-level
+      // hint at once and it reads as duplicated/stuck placeholder text.
+      if (editor.isEmpty && pos === 0) return placeholder;
+
+      return hasAnchor ? caretHint : '';
+    },
+    showOnlyCurrent: false,
+    includeChildren: false,
+  }),
+
+  ...extra,
+];

package/src/schema/image.ts

@@ -0,0 +1,44 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+// Reimplements the minimum of `@tiptap/extension-image` (not a dependency of
+// this package); getting a `src` is host UI.
+export const Image = Node.create({
+  name: 'image',
+  group: 'block',
+  atom: true,
+  selectable: true,
+  draggable: true,
+
+  addAttributes() {
+    return {
+      src: { default: null },
+      alt: { default: null },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'img[src]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['img', mergeAttributes(HTMLAttributes)];
+  },
+
+  addCommands() {
+    return {
+      setImage:
+        (attrs: { src: string; alt?: string | null }) =>
+        ({ commands }) =>
+          commands.insertContent({ type: this.name, attrs }),
+    };
+  },
+});
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    image: {
+      /** Inserts an image node at the current selection. */
+      setImage: (attrs: { src: string; alt?: string | null }) => ReturnType;
+    };
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@medway-ui/notes-core/schema` — the Tiptap half, behind its own subpath so
+ * that importing the document model never pulls Tiptap in.
+ *
+ * `Editor`, `generateHTML` and `generateJSON` are re-exported to guarantee a
+ * single ProseMirror copy, and must always be passed the exact array
+ * `buildExtensions()` returns.
+ */
+
+export { Editor, generateHTML, generateJSON } from '@tiptap/core';
+export type { AnyExtension, JSONContent } from '@tiptap/core';
+
+export type { BuildExtensionsOptions } from './extensions.js';
+export { buildExtensions } from './extensions.js';
+
+// Re-exported so hosts can build custom extension lists, and — less obviously
+// — so `./image`'s `declare module '@tiptap/core'` augmentation (the
+// `setImage` command) ships: `buildExtensions`'s signature never mentions
+// `Image`, so declaration emission would otherwise drop the import.
+export { Image } from './image.js';
+
+export type { SlashCommandController } from './slashCommand.js';
+export { createSlashCommand } from './slashCommand.js';
+
+export {
+  MARK_TYPES,
+  NODE_TYPES,
+  assertSchemaContract,
+} from './contract.js';