@tarhnama/core 0.1.0

package/src/code-tokens.ts

@@ -0,0 +1,236 @@
+/**
+ * The colouring 1a draws in a code block — keywords in the accent, strings in green —
+ * as a pure function over text, so the editor's decorations and both readers colour the
+ * same characters.
+ *
+ * Deliberately small. It is not a parser and does not try to be: a full grammar per
+ * language is a dependency this package must not force on a host, and a host that wants
+ * one passes its own tokenizer with the same signature. What it does, it does exactly —
+ * whole words only, escapes honoured, comment markers inside strings left alone — because
+ * a highlighter that is right most of the time teaches the reader to distrust the colours.
+ *
+ * Numbers and identifiers are not tokens. The prototype colours neither consistently
+ * (`editor` is accent once in 1a and plain on the next line; `const` is plain in 2a-06),
+ * so there is no rule to measure — see docs/DESIGN-REQUESTS.md.
+ */
+
+export type CodeTokenKind = 'keyword' | 'string' | 'comment';
+
+export interface CodeToken {
+  /** Offset of the first character, in UTF-16 code units of the block's text. */
+  readonly from: number;
+  /** Offset after the last character. */
+  readonly to: number;
+  readonly kind: CodeTokenKind;
+}
+
+/** A host-supplied replacement for `tokenizeCode`, e.g. one backed by a real grammar. */
+export type CodeTokenizer = (code: string, lang: string | undefined) => readonly CodeToken[];
+
+interface Grammar {
+  readonly keywords: ReadonlySet<string>;
+  readonly lineComment: '//' | '#' | null;
+  readonly blockComment: boolean;
+  /** Quote characters that may run past the end of their line. */
+  readonly multilineQuotes: string;
+  readonly quotes: string;
+  /** Shell: inside `'…'` a backslash is an ordinary character. */
+  readonly rawQuotes: string;
+  readonly tripleQuotes: boolean;
+  /** Shell: `#` opens a comment only at the start of a word (`$#` is a variable). */
+  readonly hashNeedsBoundary: boolean;
+  /** JavaScript: `x.new` is a property, not the keyword. */
+  readonly memberAccessIsNotKeyword: boolean;
+}
+
+const words = (list: string) => new Set(list.split(/\s+/).filter(Boolean));
+
+const C_LIKE: Omit<Grammar, 'keywords'> = {
+  lineComment: '//',
+  blockComment: true,
+  quotes: `'"\``,
+  rawQuotes: '',
+  multilineQuotes: '`',
+  tripleQuotes: false,
+  hashNeedsBoundary: false,
+  memberAccessIsNotKeyword: true,
+};
+
+/*
+ * Contextual words that are routinely identifiers (`type`, `from`, `of`, `as`, `get`, `set`)
+ * are left out: colouring `const type = …` as a keyword is wrong far more often than
+ * leaving `import x from` plain is.
+ */
+const JS = {
+  ...C_LIKE,
+  keywords: words(`
+    abstract async await break case catch class const continue debugger declare default delete
+    do else enum export extends false finally for function if implements import in instanceof
+    interface keyof let namespace new null private protected public readonly return satisfies
+    static super switch this throw true try typeof undefined var void while with yield
+  `),
+};
+
+const JSON_GRAMMAR: Grammar = {
+  keywords: words('true false null'),
+  lineComment: null,
+  blockComment: false,
+  quotes: '"',
+  rawQuotes: '',
+  multilineQuotes: '',
+  tripleQuotes: false,
+  hashNeedsBoundary: false,
+  memberAccessIsNotKeyword: false,
+};
+
+const PYTHON: Grammar = {
+  keywords: words(`
+    False None True and as assert async await break class continue def del elif else except
+    finally for from global if import in is lambda nonlocal not or pass raise return try while
+    with yield
+  `),
+  lineComment: '#',
+  blockComment: false,
+  quotes: `'"`,
+  rawQuotes: '',
+  multilineQuotes: '',
+  tripleQuotes: true,
+  hashNeedsBoundary: false,
+  memberAccessIsNotKeyword: true,
+};
+
+const SHELL: Grammar = {
+  keywords: words('if then else elif fi case esac for while until do done in function return exit local export select'),
+  lineComment: '#',
+  blockComment: false,
+  quotes: `'"`,
+  rawQuotes: "'",
+  multilineQuotes: `'"`,
+  tripleQuotes: false,
+  hashNeedsBoundary: true,
+  memberAccessIsNotKeyword: false,
+};
+
+const GRAMMARS: Readonly<Record<string, Grammar>> = {
+  js: JS, jsx: JS, mjs: JS, cjs: JS, javascript: JS,
+  ts: JS, tsx: JS, mts: JS, cts: JS, typescript: JS,
+  json: JSON_GRAMMAR, jsonc: { ...JSON_GRAMMAR, lineComment: '//', blockComment: true },
+  py: PYTHON, python: PYTHON, python3: PYTHON,
+  sh: SHELL, bash: SHELL, zsh: SHELL, shell: SHELL, console: SHELL,
+};
+
+const WORD_START = /[\p{L}_$]/u;
+const WORD_PART = /[\p{L}\p{N}_$]/u;
+
+export function tokenizeCode(code: string, lang: string | undefined): CodeToken[] {
+  const grammar = lang ? GRAMMARS[lang.trim().toLowerCase()] : undefined;
+  if (!grammar) return [];
+
+  const tokens: CodeToken[] = [];
+  const length = code.length;
+  let i = 0;
+
+  while (i < length) {
+    const ch = code[i]!;
+
+    if (grammar.lineComment && code.startsWith(grammar.lineComment, i)) {
+      const atBoundary = i === 0 || /\s/.test(code[i - 1]!);
+      if (!grammar.hashNeedsBoundary || atBoundary) {
+        const end = lineEnd(code, i);
+        tokens.push({ from: i, to: end, kind: 'comment' });
+        i = end;
+        continue;
+      }
+    }
+
+    if (grammar.blockComment && code.startsWith('/*', i)) {
+      const close = code.indexOf('*/', i + 2);
+      const end = close === -1 ? length : close + 2;
+      tokens.push({ from: i, to: end, kind: 'comment' });
+      i = end;
+      continue;
+    }
+
+    if (grammar.quotes.includes(ch)) {
+      const end = grammar.tripleQuotes && code.startsWith(ch.repeat(3), i)
+        ? tripleQuoteEnd(code, i, ch)
+        : quoteEnd(code, i, ch, grammar.multilineQuotes.includes(ch), !grammar.rawQuotes.includes(ch));
+      tokens.push({ from: i, to: end, kind: 'string' });
+      i = end;
+      continue;
+    }
+
+    if (WORD_START.test(ch)) {
+      let end = i + 1;
+      while (end < length && WORD_PART.test(code[end]!)) end += 1;
+      const word = code.slice(i, end);
+      const member = grammar.memberAccessIsNotKeyword && i > 0 && code[i - 1] === '.';
+      if (!member && grammar.keywords.has(word)) tokens.push({ from: i, to: end, kind: 'keyword' });
+      i = end;
+      continue;
+    }
+
+    // A digit run is skipped whole, so `1e5` or `0x1f` never starts a word in its middle.
+    if (/\p{N}/u.test(ch)) {
+      let end = i + 1;
+      while (end < length && WORD_PART.test(code[end]!)) end += 1;
+      i = end;
+      continue;
+    }
+
+    i += 1;
+  }
+
+  return tokens;
+}
+
+export interface CodeSegment {
+  readonly text: string;
+  /** Absent for the text between tokens. */
+  readonly kind?: CodeTokenKind;
+}
+
+/**
+ * The text cut into runs, each token its own. Every renderer goes through this, so the
+ * editor and both readers colour the same characters — including when a HOST tokenizer
+ * returns something malformed: a token that is empty, out of range or overlaps the one
+ * before is skipped, and the text itself always comes back whole.
+ */
+export function codeSegments(code: string, tokens: readonly CodeToken[]): CodeSegment[] {
+  const segments: CodeSegment[] = [];
+  let at = 0;
+  for (const token of tokens) {
+    if (token.from < at || token.to <= token.from || token.to > code.length) continue;
+    if (token.from > at) segments.push({ text: code.slice(at, token.from) });
+    segments.push({ text: code.slice(token.from, token.to), kind: token.kind });
+    at = token.to;
+  }
+  if (at < code.length) segments.push({ text: code.slice(at) });
+  return segments;
+}
+
+function lineEnd(code: string, from: number): number {
+  const newline = code.indexOf('\n', from);
+  return newline === -1 ? code.length : newline;
+}
+
+/** After the closing quote; an unterminated single-line quote stops at the end of its line. */
+function quoteEnd(code: string, from: number, quote: string, multiline: boolean, escapes: boolean): number {
+  let i = from + 1;
+  while (i < code.length) {
+    const ch = code[i]!;
+    if (escapes && ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    if (ch === '\n' && !multiline) return i;
+    i += 1;
+  }
+  return code.length;
+}
+
+function tripleQuoteEnd(code: string, from: number, quote: string): number {
+  const close = code.indexOf(quote.repeat(3), from + 3);
+  return close === -1 ? code.length : close + 3;
+}

package/src/context-menu.ts

@@ -0,0 +1,139 @@
+import type { OutlineFeatureName, OutlineFeatures } from './features.js';
+
+/**
+ * What a right-click on the document offers.
+ *
+ * The spine's handle already has a node menu. The TEXT does not, so right-clicking a
+ * paragraph gets the browser's own menu — spell-check and "view source", nothing about the
+ * document you are writing.
+ *
+ * Computed as DATA, like the shortcut registry and for the same reasons: a host can render
+ * it in their own menu component, translate it through their own label pack, filter it, or
+ * ignore it entirely. Nothing here holds a closure or touches the DOM.
+ */
+
+export type ContextCommand =
+  | 'cut'
+  | 'copy'
+  | 'paste'
+  | 'undo'
+  | 'redo'
+  | 'indent'
+  | 'outdent'
+  | 'moveUp'
+  | 'moveDown'
+  | 'toggleCollapse'
+  | 'isolate'
+  | 'focus'
+  | 'toggleLock';
+
+/** What the host knows about the place that was right-clicked. */
+export interface ContextTarget {
+  readonly blockId: string;
+  readonly level: number;
+  readonly hasSelection: boolean;
+  readonly locked: boolean;
+  readonly collapsed: boolean;
+  /** Whether this heading governs anything — a fold with nothing under it does nothing. */
+  readonly governsSubtree: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  /**
+   * Whether a sibling exists to move past.
+   *
+   * Part of the target rather than derived here, for the same reason as the undo stack:
+   * this function is handed one block, and "is there a previous sibling" is a question only
+   * the whole document can answer. Getting it wrong is not cosmetic — "move down" was live
+   * on a heading with nowhere to go, and choosing it did nothing.
+   */
+  readonly canMoveUp: boolean;
+  readonly canMoveDown: boolean;
+}
+
+export interface ContextMenuItem {
+  readonly command: ContextCommand;
+  /** English; a host translates through their own label pack. */
+  readonly label: string;
+  readonly enabled: boolean;
+  /** A rule drawn before this item. Named here so a renderer does not invent grouping. */
+  readonly separator?: boolean;
+  readonly feature?: OutlineFeatureName;
+}
+
+/**
+ * Build the menu for one right-click.
+ *
+ * Two rules, and the difference between them is the whole design:
+ *
+ * **A command that cannot act right now is DIMMED.** The menu has the same shape every
+ * time it opens, so its geometry can be learned and the third item is always the third
+ * item. This is the rule the toolbars follow.
+ *
+ * **A command whose FEATURE is off is REMOVED.** Dimming says "not now", which is a
+ * promise. A feature the host switched off is never coming back, and leaving it there
+ * spends the reader's attention on it at every opening, forever.
+ */
+export function contextMenuFor(
+  target: ContextTarget,
+  features: OutlineFeatures,
+): readonly ContextMenuItem[] {
+  // A lock stops EDITING, never reading — so copy survives it and the mutating pair does not.
+  const editable = !target.locked;
+
+  const all: ContextMenuItem[] = [
+    {
+      command: 'cut',
+      label: 'Cut',
+      enabled: target.hasSelection && editable,
+      feature: 'clipboard',
+    },
+    { command: 'copy', label: 'Copy', enabled: target.hasSelection, feature: 'clipboard' },
+    { command: 'paste', label: 'Paste', enabled: editable, feature: 'clipboard' },
+
+    {
+      command: 'undo',
+      label: 'Undo',
+      enabled: target.canUndo,
+      separator: true,
+      feature: 'history',
+    },
+    { command: 'redo', label: 'Redo', enabled: target.canRedo, feature: 'history' },
+
+    /*
+     * Structural commands carry no feature: indent and outdent ARE the outline, not a
+     * feature of it, and an editor without them is a different product rather than this
+     * one configured down.
+     */
+    { command: 'indent', label: 'Indent', enabled: editable && target.level > 0, separator: true },
+    { command: 'outdent', label: 'Outdent', enabled: editable && target.level > 1 },
+    { command: 'moveUp', label: 'Move up', enabled: editable && target.canMoveUp },
+    { command: 'moveDown', label: 'Move down', enabled: editable && target.canMoveDown },
+
+    {
+      command: 'toggleCollapse',
+      label: target.collapsed ? 'Expand' : 'Collapse',
+      // A heading that governs nothing has nothing to fold — the spine's eighth state,
+      // in menu form.
+      enabled: target.governsSubtree,
+      separator: true,
+      feature: 'collapse',
+    },
+    {
+      command: 'isolate',
+      label: 'Keep only this subtree open',
+      enabled: target.governsSubtree,
+      feature: 'collapse',
+    },
+    { command: 'focus', label: 'Focus this subtree', enabled: target.governsSubtree },
+
+    {
+      command: 'toggleLock',
+      label: target.locked ? 'Unlock' : 'Lock',
+      enabled: true,
+      separator: true,
+      feature: 'lock',
+    },
+  ];
+
+  return all.filter((item) => item.feature === undefined || features[item.feature]);
+}

package/src/features.ts

@@ -0,0 +1,173 @@
+/**
+ * What a host turns on.
+ *
+ * This editor is embedded in projects that want very different subsets of it: a note pane
+ * that needs no cross-document links, a review surface that needs no formatting, a viewer
+ * that needs no editing at all. Every one of those is a supported configuration rather
+ * than a fork.
+ *
+ * ── The rule that shapes this whole file ───────────────────────────────────────
+ *
+ * **Features gate BEHAVIOUR, never the schema.**
+ *
+ * It is tempting to make `links: false` remove the link mark from the document schema —
+ * it would be smaller, and it would tree-shake. It is also data loss: ProseMirror strips
+ * any mark its schema does not know, so a host with links disabled that opens a document
+ * containing links **destroys them on load**, silently, and writes the damaged version
+ * back on the next save. A document must round-trip through every configuration
+ * unchanged.
+ *
+ * So the schema is always complete, and a disabled feature removes its input rules, its
+ * keymap entries, its commands, its decorations and its UI. Bundle size is addressed the
+ * honest way instead — subpath exports, so a host that never imports the link picker
+ * never ships it.
+ */
+
+/** Every switchable behaviour. Deliberately flat and small; this is a public contract. */
+export interface OutlineFeatures {
+  /**
+   * `[[` autocomplete, anchor commands, link input rules, reference previews.
+   * Existing link marks still render and still round-trip when this is off.
+   */
+  readonly links: boolean;
+  /** Bold/italic/colour/highlight commands and the formatting keymap (⌘B and friends). */
+  readonly formatting: boolean;
+  /** Collapse state, the spine, the hidden-count decorations, ⌘. and the ladder. */
+  readonly collapse: boolean;
+  /** Read-only subtrees, the lock guard, and the padlock affordance. */
+  readonly lock: boolean;
+  /** Undo/redo. Turn OFF when adopting Yjs: two undo managers fight (see CLAUDE.md §4). */
+  readonly history: boolean;
+  /** Table editing commands. Existing tables still render either way. */
+  readonly tables: boolean;
+  /** Image insertion. Existing images still render either way. */
+  readonly images: boolean;
+  /**
+   * Outline-aware copy: the host's serializer decides the `text/plain` flavour.
+   * Off leaves ProseMirror's default, which loses every level.
+   */
+  readonly clipboard: boolean;
+}
+
+export type OutlineFeatureName = keyof OutlineFeatures;
+
+/**
+ * The default: everything.
+ *
+ * A host that has not thought about features yet should get the whole editor, not an empty
+ * shell to debug. "Off unless named" reads as safer and is worse — the failure it produces
+ * is a missing feature with no error, which is the hardest kind to diagnose.
+ */
+export const ALL_FEATURES: OutlineFeatures = {
+  links: true,
+  formatting: true,
+  collapse: true,
+  lock: true,
+  history: true,
+  tables: true,
+  images: true,
+  clipboard: true,
+};
+
+/** Nothing but text. Useful as a base to switch individual features back on. */
+export const NO_FEATURES: OutlineFeatures = {
+  links: false,
+  formatting: false,
+  collapse: false,
+  lock: false,
+  history: false,
+  tables: false,
+  images: false,
+  clipboard: false,
+};
+
+const NAMES = Object.keys(ALL_FEATURES) as readonly OutlineFeatureName[];
+
+/**
+ * Normalize whatever the host passed into a complete record.
+ *
+ * Three input shapes, because hosts reach for different ones and all three are reasonable:
+ *
+ *   undefined                     → everything (the default)
+ *   { links: false }              → everything except links (a partial override)
+ *   ['collapse', 'formatting']    → ONLY those two (an allowlist)
+ *
+ * The array form flips the default deliberately: writing a list reads as "these are the
+ * features I want", and having it mean "these, plus the six I did not mention" would be a
+ * trap. The object form keeps the opposite reading, which is why both exist.
+ *
+ * An unknown name in the array throws rather than being ignored — a typo'd feature that
+ * silently does nothing is the exact failure this API exists to prevent.
+ */
+export function resolveFeatures(
+  input?: Partial<OutlineFeatures> | readonly OutlineFeatureName[] | undefined,
+): OutlineFeatures {
+  if (input === undefined) return ALL_FEATURES;
+
+  if (Array.isArray(input)) {
+    const wanted = new Set(input as readonly OutlineFeatureName[]);
+    for (const name of wanted) {
+      if (!NAMES.includes(name)) {
+        throw new Error(
+          `Unknown outline feature ${JSON.stringify(name)}. Known: ${NAMES.join(', ')}.`,
+        );
+      }
+    }
+    const out = { ...NO_FEATURES } as Record<OutlineFeatureName, boolean>;
+    for (const name of wanted) out[name] = true;
+    return out as OutlineFeatures;
+  }
+
+  return { ...ALL_FEATURES, ...(input as Partial<OutlineFeatures>) };
+}
+
+/**
+ * How the document is being used.
+ *
+ * A separate axis from features, not another flag among them: `read` is not "formatting
+ * off plus links off", it is a different contract — nothing may mutate the document, and
+ * the machinery that exists to mutate it does not need to be constructed at all.
+ */
+export type OutlineMode = 'edit' | 'read';
+
+/**
+ * The features a mode can actually support.
+ *
+ * Read mode keeps `collapse` and `links`, and that distinction is the point: **a lock stops
+ * editing, never reading.** A reader who cannot fold a section or follow a reference has
+ * been given a screenshot, not a document. Everything that mutates content is off, and no
+ * host flag can turn it back on — an editing command reachable in read mode is a bug, not
+ * a configuration.
+ */
+export function featuresForMode(features: OutlineFeatures, mode: OutlineMode): OutlineFeatures {
+  if (mode === 'edit') return features;
+  return {
+    ...features,
+    formatting: false,
+    history: false,
+    tables: false,
+    images: false,
+    lock: false,
+  };
+}
+
+/**
+ * A stable string for a resolved feature set.
+ *
+ * Exists because of how React memoization actually gets used. The natural way for a host to
+ * configure this editor is an inline literal:
+ *
+ *     <OutlineEditor features={{ links: hasLinks }} />
+ *
+ * That object has a new identity on every render. Memoizing the extension list on it
+ * rebuilds the Tiptap editor on every render — the document is torn down and recreated
+ * between keystrokes, and the symptom is not an error but an editor that never settles:
+ * the spine's handles move continuously and a click can never land.
+ *
+ * An API that is only correct when the caller remembers to `useMemo` is a bad API, so the
+ * comparison is by CONTENT here rather than by reference. The key is ordered by
+ * `ALL_FEATURES` so two equal sets always produce the same string.
+ */
+export function featureKey(features: OutlineFeatures): string {
+  return NAMES.filter((name) => features[name]).join(',');
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+export * from './types.js';
+export * from './tree.js';
+export * from './ops.js';
+
+export {
+  clearDirectFormat,
+  effectiveFormat,
+  effectiveRunStyle,
+  redefineStyle,
+  styleChain,
+  styleOutlineLevel,
+  styleUsage,
+} from './styles.js';
+export type { StyleUsage } from './styles.js';
+
+export {
+  collapseSiblings,
+  currentOpenLevel,
+  deepestParentLevel,
+  isHidden,
+  isolateSubtree,
+  openToFit,
+  openToLevel,
+  subtreeSize,
+} from './spine.js';
+
+export {
+  ALL_FEATURES,
+  NO_FEATURES,
+  featureKey,
+  featuresForMode,
+  resolveFeatures,
+} from './features.js';
+export type { OutlineFeatureName, OutlineFeatures, OutlineMode } from './features.js';
+
+export {
+  DEFAULT_SHORTCUTS,
+  formatShortcut,
+  resolveShortcuts,
+  shortcutsFor,
+} from './shortcuts.js';
+export type {
+  ShortcutBinding,
+  ShortcutCommand,
+  ShortcutGroup,
+  ShortcutOptions,
+  ShortcutPlatform,
+} from './shortcuts.js';
+
+export { skippedLevelAt } from './ops.js';
+export { contextMenuFor } from './context-menu.js';
+export type { ContextCommand, ContextMenuItem, ContextTarget } from './context-menu.js';
+
+export { blocksToNested, nestedToBlocks } from './nested.js';
+export type { NestedNode, NestedOptions, NestedToBlocksResult } from './nested.js';
+
+export { codeSegments, tokenizeCode } from './code-tokens.js';
+export type { CodeSegment, CodeToken, CodeTokenKind, CodeTokenizer } from './code-tokens.js';