@tarhnama/core 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ npm install @tarhnama/core
 
 Part of **طرح‌نما**, a Persian-first outline editor. Everything is optional — features,
 styling, and copy — so it can be embedded without bringing opinions you did not ask for.
-See the [consumer guide](https://github.com/mahdi/tarhnama/blob/main/docs/CONSUMING.md) for the styling levels,
+See the [consumer guide](https://github.com/smhosseini72/tarhnama-editor/blob/main/docs/CONSUMING.md) for the styling levels,
 the feature switches and the i18n contract.
 
 Licensed MIT.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@tarhnama/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic outline document model: flat blocks with outline levels, plus a derived tree index. No DOM, no editor dependency.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mahdi/tarhnama.git",
+    "url": "git+https://github.com/smhosseini72/tarhnama-editor.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/mahdi/tarhnama#readme",
-  "bugs": "https://github.com/mahdi/tarhnama/issues",
+  "homepage": "https://github.com/smhosseini72/tarhnama-editor#readme",
+  "bugs": "https://github.com/smhosseini72/tarhnama-editor/issues",
   "keywords": [
     "outline",
     "editor",

package/src/context-menu.ts

@@ -50,8 +50,42 @@ export interface ContextTarget {
   readonly canMoveDown: boolean;
 }
 
+/**
+ * A host's own command, spelled `host:<id>` so it can never collide with a built-in one and a
+ * renderer can tell the two apart with a prefix check (`hostCommandId`).
+ */
+export type HostCommand = `host:${string}`;
+
+/**
+ * A command the HOST adds to the right-click menu — «send to my app», «open in the CRM».
+ *
+ * Data, like everything else here: the host decides per right-click which items exist (it is
+ * handed the same `ContextTarget`), and runs the one chosen by its id. No closure goes in, so
+ * the descriptor stays serializable and a host can build it anywhere.
+ */
+export interface HostMenuItem {
+  /** Unique among the host's items. Comes back as `host:<id>` on the chosen item. */
+  readonly id: string;
+  /** Already translated: the host owns its own words. */
+  readonly label: string;
+  /** Defaults to true. Dimmed, not removed, when false — the menu keeps its shape. */
+  readonly enabled?: boolean;
+  /**
+   * Order among the HOST's items: higher first, ties keep the given order. Never moves one
+   * above the editor's own items — those stay where a writer learned them.
+   */
+  readonly priority?: number;
+  /** A rule before this item, to group the host's own commands. */
+  readonly separator?: boolean;
+}
+
+/** The host id inside a `host:` command, or null for one of the editor's own. */
+export function hostCommandId(command: string): string | null {
+  return command.startsWith('host:') ? command.slice('host:'.length) : null;
+}
+
 export interface ContextMenuItem {
-  readonly command: ContextCommand;
+  readonly command: ContextCommand | HostCommand;
   /** English; a host translates through their own label pack. */
   readonly label: string;
   readonly enabled: boolean;
@@ -76,6 +110,7 @@ export interface ContextMenuItem {
 export function contextMenuFor(
   target: ContextTarget,
   features: OutlineFeatures,
+  hostItems: readonly HostMenuItem[] = [],
 ): readonly ContextMenuItem[] {
   // A lock stops EDITING, never reading — so copy survives it and the mutating pair does not.
   const editable = !target.locked;
@@ -135,5 +170,30 @@ export function contextMenuFor(
     },
   ];
 
-  return all.filter((item) => item.feature === undefined || features[item.feature]);
+  const builtIn = all.filter((item) => item.feature === undefined || features[item.feature]);
+  return hostItems.length === 0 ? builtIn : [...builtIn, ...hostEntries(hostItems)];
+}
+
+/*
+ * The host's items go BELOW the editor's own, behind one rule, ordered by priority. Below,
+ * because the built-in geometry is what a writer learns ("cut is first, lock is last") and a
+ * host item above it would move every one of them; ordered, because a host with several
+ * commands knows which matters most and the order it happened to build the array in does not.
+ */
+function hostEntries(items: readonly HostMenuItem[]): ContextMenuItem[] {
+  const seen = new Set<string>();
+  for (const item of items) {
+    // A host item that cannot be told apart from another runs the wrong command, silently.
+    if (item.id === '') throw new Error('contextMenuFor: a host menu item has an empty id');
+    if (seen.has(item.id)) throw new Error(`contextMenuFor: duplicate host menu item id "${item.id}"`);
+    seen.add(item.id);
+  }
+  // `sort` is stable, so equal priorities keep the order the host gave.
+  const ordered = [...items].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  return ordered.map((item, i) => ({
+    command: `host:${item.id}` as const,
+    label: item.label,
+    enabled: item.enabled ?? true,
+    ...(i === 0 || item.separator === true ? { separator: true } : {}),
+  }));
 }

package/src/index.ts

@@ -1,3 +1,4 @@
+/** The public surface of @tarhnama/core: the flat block model, tree derivation, pure structural ops, features, shortcuts, context menu and the nested-tree adapter. */
 export * from './types.js';
 export * from './tree.js';
 export * from './ops.js';
@@ -48,8 +49,8 @@ export type {
 } from './shortcuts.js';
 
 export { skippedLevelAt } from './ops.js';
-export { contextMenuFor } from './context-menu.js';
-export type { ContextCommand, ContextMenuItem, ContextTarget } from './context-menu.js';
+export { contextMenuFor, hostCommandId } from './context-menu.js';
+export type { ContextCommand, ContextMenuItem, ContextTarget, HostCommand, HostMenuItem } from './context-menu.js';
 
 export { blocksToNested, nestedToBlocks } from './nested.js';
 export type { NestedNode, NestedOptions, NestedToBlocksResult } from './nested.js';

package/src/ops.ts

@@ -167,7 +167,13 @@ export function canMoveSubtree(blocks: Blocks, from: number, to: number): boolea
     const [, end] = subtreeRange(index, before);
     if (to < end) return false;
   }
-  if (to < blocks.length && isLocked(blocks, index, to)) return false;
+  /*
+   * Landing AT a locked block's index puts the subtree just before it. That is inside the lock
+   * only when the block is locked through an ancestor (a locked chapter's own content); before
+   * a locked chapter's own heading the move changes nothing read-only, and refusing it dimmed
+   * «پایین بردن گره» for any heading whose next sibling preceded a locked one.
+   */
+  if (to < blocks.length && isLocked(blocks, index, to) && blocks[to]?.locked !== true) return false;
   return true;
 }