@crossworks/content-core 0.232.350 → 0.232.354

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/content-core",
-  "version": "0.232.350",
+  "version": "0.232.354",
   "description": "Browser-safe content logic — markdown, blocks, pages, tables, formulas — shared by the server and any client. Zero server deps by design: nothing here may reach @mantle/db, node-only APIs, or the network (the jackdaw-repo-split P0 boundary).",
   "exports": {
     "./app-nav": "./src/app-nav.ts",
@@ -27,10 +27,11 @@
     "./table-formula": "./src/table-formula.ts",
     "./table-formula-mathjs": "./src/table-formula-mathjs.ts",
     "./table-model": "./src/table-model.ts",
-    "./thinking-tiers": "./src/thinking-tiers.ts"
+    "./thinking-tiers": "./src/thinking-tiers.ts",
+    "./tree": "./src/tree.ts"
   },
   "dependencies": {
-    "@mantle/client-types": "npm:@crossworks/client-types@0.232.350",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.232.354",
     "marked": "^18.0.11",
     "mathjs": "15.2.0"
   },

package/src/tree.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { TREE_KIND_SPECS, TREE_KINDS, TREE_MAX_DEPTH } from '@mantle/client-types/tree';
+import {
+  clampTreePath,
+  effectiveLevel,
+  isTreeFolderPathAllowed,
+  treeDepth,
+  treeFolderChain,
+  treeKindOfPath,
+  treeMoveDepth,
+  treeParentPath,
+} from './tree';
+
+describe('tree path math', () => {
+  it('finds the kind from the root label', () => {
+    expect(treeKindOfPath('files.clients.acme')).toBe('files');
+    expect(treeKindOfPath('draw')).toBe('draw');
+    expect(treeKindOfPath('documentation.x')).toBeNull();
+    expect(treeKindOfPath('')).toBeNull();
+  });
+
+  it('measures depth below the root', () => {
+    expect(treeDepth('files')).toBe(0);
+    expect(treeDepth('files.a')).toBe(1);
+    expect(treeDepth('files.a.b.c')).toBe(3);
+  });
+
+  it('walks parents and the folder chain', () => {
+    expect(treeParentPath('files.a.b')).toBe('files.a');
+    expect(treeParentPath('files')).toBe('files');
+    expect(treeFolderChain('files.a.b')).toEqual(['files.a', 'files.a.b']);
+    expect(treeFolderChain('files')).toEqual([]);
+  });
+
+  it('allows folders at depth 1..3 only', () => {
+    expect(isTreeFolderPathAllowed('files')).toBe(false);
+    expect(isTreeFolderPathAllowed('files.a')).toBe(true);
+    expect(isTreeFolderPathAllowed('files.a.b.c')).toBe(true);
+    expect(isTreeFolderPathAllowed('files.a.b.c.d')).toBe(false);
+  });
+
+  it('clamps a deep path into the third level', () => {
+    expect(clampTreePath('files.a.b.c.d.e')).toBe('files.a.b.c');
+    expect(clampTreePath('files.a')).toBe('files.a');
+  });
+
+  it('measures a moved subtree', () => {
+    expect(treeMoveDepth('files.a', 2)).toBe(3);
+    expect(treeMoveDepth('files.a.b', 2)).toBeGreaterThan(TREE_MAX_DEPTH);
+  });
+
+  it('has one spec per kind with distinct roots', () => {
+    const roots = TREE_KINDS.map((k) => TREE_KIND_SPECS[k].root);
+    expect(new Set(roots).size).toBe(TREE_KINDS.length);
+    for (const k of TREE_KINDS) {
+      expect(TREE_KIND_SPECS[k].kind).toBe(k);
+      expect(TREE_KIND_SPECS[k].sorts.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('the effective level', () => {
+  it('is the more open of an item’s own level and its folder’s share', () => {
+    expect(effectiveLevel('admin', null)).toBe('admin');
+    expect(effectiveLevel('admin', 'team')).toBe('team');
+    expect(effectiveLevel('admin', 'client')).toBe('client');
+    expect(effectiveLevel('team', 'client')).toBe('client');
+    expect(effectiveLevel('client', 'team')).toBe('client');
+    // A public item stays public in a client folder: folding its text for the
+    // public reader is safe for the client reader too.
+    expect(effectiveLevel('public', 'client')).toBe('public');
+  });
+});

package/src/tree.ts

@@ -0,0 +1,88 @@
+/**
+ * Path math for the item tree (@mantle/client-types/tree). A folder's or an
+ * item's place is an ltree path under its kind's root: `files` is the root,
+ * `files.clients` a top-level folder, `files.clients.acme.contracts` the
+ * deepest a folder may sit. Pure, so the brain and every client agree on
+ * depth, parents and crumbs without a round trip.
+ */
+import {
+  TREE_KIND_SPECS,
+  TREE_KINDS,
+  TREE_MAX_DEPTH,
+  type TreeKind,
+  type TreeShareLevel,
+} from '@mantle/client-types/tree';
+import type { AccessLevel } from '@mantle/client-types';
+
+const LEVEL_RANK: Record<AccessLevel, number> = { public: 0, client: 1, team: 2, admin: 3 };
+
+/**
+ * The level an item is read at: the more open of its own level and the share
+ * it inherits from a folder (public < client < team < admin). This is the
+ * level its pill shows, its embeds follow and its indexed page text is
+ * folded for. Folding for the more open reader is safe for every reader of
+ * the row: what a public or client reader may see, every reader above may
+ * too. (Which ROLES read the row is the database's union of the two:
+ * nodes_viewer_read, migration 0204.)
+ */
+export function effectiveLevel(
+  own: AccessLevel,
+  inherited: TreeShareLevel | null | undefined,
+): AccessLevel {
+  if (!inherited) return own;
+  return LEVEL_RANK[inherited] < LEVEL_RANK[own] ? inherited : own;
+}
+
+function labels(path: string): string[] {
+  return path ? path.split('.') : [];
+}
+
+/** The kind whose root the path sits under, or null outside every root. */
+export function treeKindOfPath(path: string): TreeKind | null {
+  const root = labels(path)[0];
+  return TREE_KINDS.find((k) => TREE_KIND_SPECS[k].root === root) ?? null;
+}
+
+/** How deep below its root a path is: 0 for the root itself, 1 for a
+ *  top-level folder. */
+export function treeDepth(path: string): number {
+  return Math.max(0, labels(path).length - 1);
+}
+
+/** The parent path; the root is its own parent. */
+export function treeParentPath(path: string): string {
+  const parts = labels(path);
+  return parts.length <= 1 ? path : parts.slice(0, -1).join('.');
+}
+
+/** The folder paths from the top level down to `path` itself, root excluded:
+ *  `files.a.b` gives `['files.a', 'files.a.b']`. */
+export function treeFolderChain(path: string): string[] {
+  const parts = labels(path);
+  const out: string[] = [];
+  for (let i = 2; i <= parts.length; i++) out.push(parts.slice(0, i).join('.'));
+  return out;
+}
+
+/** Whether a folder may live at `path` (its depth is within the limit). */
+export function isTreeFolderPathAllowed(path: string): boolean {
+  const depth = treeDepth(path);
+  return depth >= 1 && depth <= TREE_MAX_DEPTH;
+}
+
+/**
+ * Cut a folder path that would sit too deep back to the deepest allowed
+ * level: the extra levels are lifted into the third. Inbound paths use it (an
+ * agent's `mkdir -p`, the crawler, Accept), so a deep chain lands in the
+ * deepest folder instead of failing.
+ */
+export function clampTreePath(path: string): string {
+  const parts = labels(path);
+  return parts.slice(0, TREE_MAX_DEPTH + 1).join('.');
+}
+
+/** A moved folder subtree's deepest depth: `subtreeDepth` levels (1 for a
+ *  folder with no subfolders) placed under `targetPath`. */
+export function treeMoveDepth(targetPath: string, subtreeDepth: number): number {
+  return treeDepth(targetPath) + subtreeDepth;
+}