@murumets-ee/menus 0.37.0

package/dist/menu-item-schema-xXWZKw7t.d.mts

@@ -0,0 +1,296 @@
+import { z } from "zod";
+
+//#region src/menu-entity-types.d.ts
+/**
+ * Upper bound on how many entity types one menu's whitelist may name.
+ *
+ * A real app registers a few dozen entities, so this is a malformed-payload
+ * guard rather than a product limit — it keeps a hostile PATCH from parking an
+ * unbounded array in the column (and, through it, in every editor's RSC
+ * payload).
+ *
+ * **Not** `MAX_MENU_ENTITY_TYPES` (`./get-menu.ts`, 16). That one bounds RENDER
+ * fan-out — how many distinct types one menu render may issue batched lookups
+ * for — and applies to the types actually present in the stored tree. This one
+ * bounds the stored AUTHORING whitelist, which costs no I/O at all.
+ */
+declare const MAX_MENU_ENTITY_TYPE_WHITELIST = 64;
+/**
+ * The write-boundary schema for `menu.entityTypes`.
+ *
+ * Strict where {@link normalizeMenuEntityTypes} is tolerant: a junk entry is a
+ * 400, not a silent drop, because silently discarding half an admin's selection
+ * and reporting success is worse than refusing the write. Duplicates ARE folded
+ * (an idempotent selection is not an error), and `[]` becomes `null` so the
+ * column only ever holds one representation of "unrestricted".
+ */
+declare const MenuEntityTypesSchema: z.ZodType<string[] | null, z.ZodTypeDef, unknown>;
+/**
+ * Narrow a raw `entityTypes` column value (untrusted shape) to a usable
+ * whitelist, or `null` for "no restriction".
+ *
+ * The read-side counterpart of {@link MenuEntityTypesSchema}, and tolerant for
+ * the same reason `normalizeMenuTree` is: rows written before this column
+ * existed, hand edits and restored dumps all reach readers, and a render must
+ * degrade rather than throw. Anything unusable — a non-array, a non-string
+ * entry, a whitelist that reduces to nothing — reads as `null`.
+ */
+declare function normalizeMenuEntityTypes(value: unknown): string[] | null;
+/**
+ * Does this menu accept links to `entityType`?
+ *
+ * Takes the RAW column value so callers holding a `field.json()`-typed row can
+ * ask directly, without narrowing first. Exact string match — entity names are
+ * lowercase identifiers, and a case-insensitive or prefix match would silently
+ * widen a whitelist the admin wrote precisely.
+ *
+ * Fails OPEN (see the module header): absent, empty and malformed all mean "no
+ * restriction".
+ */
+declare function menuAcceptsEntityType(value: unknown, entityType: string): boolean;
+//#endregion
+//#region src/menu-item-schema.d.ts
+/**
+ * Absolute nesting cap for any menu, independent of a menu's own `maxDepth`
+ * (phase 07 §2.7 — "depth is capped per menu (default 3, max 6)"). Also the
+ * bound that keeps the recursive parse from being a DoS vector.
+ */
+declare const MAX_MENU_DEPTH = 6;
+/** `maxDepth`'s default — a 3-level menu (phase 08 §2). */
+declare const DEFAULT_MENU_DEPTH = 3;
+/**
+ * Upper bound on the number of nodes in one menu tree. Navigation menus are
+ * hand-curated: a few dozen items is a big one. The cap exists so a single
+ * PATCH can't hand the validator (and `extractRefs`' ref walk, and every
+ * subsequent render) an unbounded amount of work — CLAUDE.md's
+ * "no unbounded fan-out" rule applied to a single request payload.
+ */
+declare const MAX_MENU_TREE_NODES = 500;
+/**
+ * Max stored length of a `url`-kind link. Pinned to `entity`'s
+ * `MAX_EXTERNAL_URL_LENGTH` (the `external_link_usage.url_raw` column width)
+ * at COMPILE time via `satisfies` + a type-only import — so a longer URL is
+ * rejected at the boundary instead of being silently dropped from the
+ * reference graph. Same drift-proofing trick as content's
+ * `DEFAULT_LOCALE_SENTINEL`; `import type` has zero runtime cost, so the pure
+ * schema module keeps its (client-safe) dependency-free shape.
+ */
+declare const MAX_MENU_URL_LENGTH = 2048;
+/**
+ * Max length of an entity-link fragment/anchor.
+ *
+ * Exported because this module is the SINGLE OWNER of the anchor bounds: the
+ * write-side schema below, the read-side anchor walk
+ * (`admin/anchors.ts`) and the editor's manual-entry fallback
+ * (`@murumets-ee/menus-ui`'s anchor picker, via the client-safe `./schema`
+ * subpath) all validate against exactly these two constants. Two of those three
+ * used to carry their own copy; a drift between them would let the picker offer
+ * — or the editor accept — a value the write boundary then rejects.
+ */
+declare const MAX_ANCHOR_LENGTH = 128;
+/**
+ * Anchors are slugified by the block editor (phase 08 §5) and rendered into an
+ * `href` as `#<anchor>`; restricting them to slug characters keeps that
+ * interpolation inert.
+ *
+ * Exported for the same single-owner reason as {@link MAX_ANCHOR_LENGTH}.
+ */
+declare const ANCHOR_PATTERN: RegExp;
+/**
+ * A menu item's link target — the item-type union phase 07 §2.2 and phase 08 §3
+ * define: `entity` (+ optional anchor) | `url` | `email`.
+ *
+ * **A NARROWED SUBSET of `@murumets-ee/blocks`' `LinkValue`, deliberately.**
+ * Blocks additionally carries a `media` kind; menus does NOT, because no phase
+ * gives a menu a media-href seam to resolve one with (phase 11 §2 specifies
+ * `href` as "canonical path from `toolkit_paths`; external URLs verbatim;
+ * header items null" and nothing else). Accepting a `media` link would let it
+ * validate, persist, and register an `entity_refs` row — arming delete
+ * protection for that file — while the renderer had no way to emit it: the item
+ * would silently never appear. Rejecting it at the write boundary turns that
+ * dead weight into a real 400. Widening later is additive (an arm here plus a
+ * `resolveMediaHref` dep on `MenuResolveDeps`) and needs no shape change.
+ *
+ * Every `MenuLinkValue` IS a valid blocks `LinkValue` (the subset direction, and
+ * the one `resolveLinkHref` needs) — pinned at compile time by an assignment in
+ * `menu-item-schema.test.ts`, so a drift in blocks' union is a build error
+ * rather than a silent divergence.
+ *
+ * The `anchor?: string | undefined` is forced by the combination of Zod and this
+ * repo's `exactOptionalPropertyTypes`: `.optional()` always widens to
+ * `T | undefined`, which is NOT assignable to blocks' `anchor?: string` under
+ * that flag.
+ */
+type MenuLinkValue = {
+  kind: 'entity';
+  entity: string;
+  id: string;
+  anchor?: string | undefined;
+} | {
+  kind: 'url';
+  url: string;
+} | {
+  kind: 'email';
+  email: string;
+};
+/**
+ * A menu tree node (phase 08 §3 / D009).
+ *
+ * `label: null` means "use the LIVE title of the linked entity, per locale";
+ * a map is an explicit per-locale override. `enabled` is per-locale visibility
+ * in BOTH directions — absent/`true` shows the item, `false` hides it in that
+ * locale — so one tree serves every locale (no `menu_translations` table).
+ *
+ * Declared as a `type`, NOT an `interface`, on purpose: only type aliases get
+ * TypeScript's implicit index signature, and without it `MenuItem[]` is not
+ * assignable to the `Record<string, unknown>[]` arm of `AdminClient.create/
+ * update`'s json-field value type — every caller storing a typed tree would
+ * need a cast.
+ */
+type MenuItem = {
+  /** Stable id — DND identity + anchor for audit diffs. */id: string; /** `header` = a text-only dropdown parent with no link of its own. */
+  kind: 'link' | 'header';
+  /**
+   * Present iff `kind === 'link'`.
+   *
+   * The explicit `| undefined` is required by the repo's
+   * `exactOptionalPropertyTypes` — Zod's `.optional()` emits
+   * `LinkValue | undefined`, and without it the schema wouldn't typecheck
+   * against this interface.
+   */
+  link?: MenuLinkValue | undefined; /** `null` = live entity title per locale; a map = explicit override. */
+  label: Record<string, string> | null; /** Per-locale visibility. Absent/`true` = visible; `false` = hidden. */
+  enabled?: Record<string, boolean> | undefined;
+  newTab?: boolean | undefined;
+  children: MenuItem[];
+};
+/**
+ * One menu item's target, as the editor needs to render its row
+ * (`@murumets-ee/menus/admin`'s `resolveMenuItemSummaries`).
+ *
+ * Declared here — not in `admin/summaries.ts` — for the same reason
+ * {@link BlockAnchor} is: it is a pure data shape with no server dependency,
+ * so the client-safe `./schema` subpath can re-export it without pulling the
+ * server-only resolver along. `import type` is erased at compile time either
+ * way, but a single canonical home (this leaf module) is simpler to reason
+ * about than "which of two server-only files owns the type".
+ */
+interface MenuItemSummary {
+  /**
+   * The target row's live title, or `null` when the entity declares no
+   * display-able field. Unlike the public render path — which DROPS such an
+   * item rather than show a raw uuid as navigation — the admin editor still
+   * reports the target as present, just unlabelled.
+   */
+  title: string | null;
+  /** `false` = the target row is gone (deleted) → a BROKEN item. */
+  exists: boolean;
+  /** `null` when the entity isn't publishable — no draft/published distinction applies. */
+  published: boolean | null;
+}
+/**
+ * One addressable block anchor on a document (`@murumets-ee/menus/admin`'s
+ * `collectBlockAnchors` / the anchors endpoint). See {@link MenuItemSummary}'s
+ * doc for why this pure shape lives here rather than in `admin/anchors.ts`.
+ */
+interface BlockAnchor {
+  /** The stable id rendered as the block element's `id` attribute. */
+  anchor: string;
+  /** Display text — `anchorLabel` when usable, else the anchor value itself. */
+  label: string;
+}
+/** Options for {@link buildMenuItemSchema} / {@link buildMenuTreeSchema}. */
+interface MenuSchemaOptions {
+  /**
+   * Locale codes accepted as keys in `label` / `enabled` maps. Anything else
+   * is a validation error — a typo'd locale would produce a label no renderer
+   * ever reads (the same failure mode content's `validateLocale` guards).
+   */
+  allowedLocales: readonly string[];
+}
+/**
+ * {@link MenuLinkValue} as Zod. Blocks models its own `LinkValue` as a plain TS
+ * type + structural guards (zod-free by design), so this is the first Zod
+ * encoding of it — narrowed to the three kinds a menu item may carry.
+ *
+ * There is deliberately NO `media` arm (see {@link MenuLinkValue}): a media
+ * link has no href seam at render time, so accepting one would store a
+ * permanently invisible item. `z.discriminatedUnion` rejects it with an
+ * `Invalid discriminator value. Expected 'entity' | 'url' | 'email'` issue —
+ * which names the allowed set without echoing the caller's own value back.
+ *
+ * `url` kinds run through `sanitizeHref`, the single source of truth for the
+ * href protocol allowlist (`http:`/`https:`/`mailto:`/`tel:` + relative
+ * paths); it returns `''` for anything it rejects, including
+ * protocol-relative `//evil.com` and obfuscated `java\nscript:`.
+ */
+declare const LinkValueSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+  kind: z.ZodLiteral<"entity">;
+  entity: z.ZodString;
+  id: z.ZodString;
+  anchor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  id: string;
+  kind: "entity";
+  entity: string;
+  anchor?: string | undefined;
+}, {
+  id: string;
+  kind: "entity";
+  entity: string;
+  anchor?: string | undefined;
+}>, z.ZodObject<{
+  kind: z.ZodLiteral<"url">;
+  url: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+}, "strip", z.ZodTypeAny, {
+  kind: "url";
+  url: string;
+}, {
+  kind: "url";
+  url: string;
+}>, z.ZodObject<{
+  kind: z.ZodLiteral<"email">;
+  email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  kind: "email";
+  email: string;
+}, {
+  kind: "email";
+  email: string;
+}>]>;
+/**
+ * The recursive per-node schema. Input is `unknown` (this parses untrusted
+ * JSONB), output is a fully-narrowed {@link MenuItem}. Unknown properties are
+ * STRIPPED by Zod's default object behavior, so writing the parse result back
+ * onto the payload also sanitizes it — nothing a caller invents gets stored.
+ */
+declare function buildMenuItemSchema(options: MenuSchemaOptions): z.ZodType<MenuItem, z.ZodTypeDef, unknown>;
+/** The whole tree — an array of {@link buildMenuItemSchema} nodes. */
+declare function buildMenuTreeSchema(options: MenuSchemaOptions): z.ZodType<MenuItem[], z.ZodTypeDef, unknown>;
+/** Result of {@link measureMenuTree}. */
+interface MenuTreeMeasurement {
+  /** Deepest nesting level; `0` for an empty tree, `1` for flat items. */
+  depth: number;
+  /** Total node count across every level. */
+  nodeCount: number;
+}
+/**
+ * Measure a (possibly untrusted) tree's depth + node count **iteratively**, so
+ * measuring can never blow the stack the way a recursive walk over a hostile
+ * payload would. Stops early once either hard bound is exceeded and reports
+ * the over-limit value — the caller turns that into a validation error.
+ *
+ * Accepts `unknown` on purpose: this runs BEFORE the Zod parse (bounding the
+ * work that parse will do), so it can't assume a well-formed shape.
+ */
+declare function measureMenuTree(tree: unknown): MenuTreeMeasurement;
+/**
+ * Cross-field check: does `tree` nest no deeper than the menu's own
+ * `maxDepth`? Lives outside the node schema because a per-node Zod refinement
+ * has no visibility of the sibling `maxDepth` COLUMN — the behavior calls this
+ * after the recursive parse.
+ */
+declare function validateTreeDepth(tree: unknown, maxDepth: number): boolean;
+//#endregion
+export { validateTreeDepth as _, MAX_ANCHOR_LENGTH as a, menuAcceptsEntityType as b, MAX_MENU_URL_LENGTH as c, MenuLinkValue as d, MenuSchemaOptions as f, measureMenuTree as g, buildMenuTreeSchema as h, LinkValueSchema as i, MenuItem as l, buildMenuItemSchema as m, BlockAnchor as n, MAX_MENU_DEPTH as o, MenuTreeMeasurement as p, DEFAULT_MENU_DEPTH as r, MAX_MENU_TREE_NODES as s, ANCHOR_PATTERN as t, MenuItemSummary as u, MAX_MENU_ENTITY_TYPE_WHITELIST as v, normalizeMenuEntityTypes as x, MenuEntityTypesSchema as y };
+//# sourceMappingURL=menu-item-schema-xXWZKw7t.d.mts.map

package/dist/menu-item-schema-xXWZKw7t.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-item-schema-xXWZKw7t.d.mts","names":[],"sources":["../src/menu-entity-types.ts","../src/menu-item-schema.ts"],"mappings":";;;;;ACqC+B;AAS/B;;;;AAAgC;AAWhC;;;;AAAgC;cDHnB,8BAAA;;;;ACuBiB;AAmB9B;;;;AAAgD;cD5BnC,qBAAA,EAAuB,CAAA,CAAE,OAAO,kBAAkB,CAAA,CAAE,UAAA;;;;;;;;;;;iBAwBjD,wBAAA,CAAyB,KAAc;;ACkC7B;AAgB1B;;;;;;;;;iBDpBgB,qBAAA,CAAsB,KAAA,WAAgB,UAAkB;;;;AAAA;;;;cCxF3D,cAAA;;cAGA,kBAAA;;AAHc;AAG3B;;;;AAA+B;cASlB,mBAAA;;;;AAAmB;AAWhC;;;;AAAgC;cAAnB,mBAAA;;;;AAoBiB;AAmB9B;;;;AAAgD;AA2BhD;;cA9Ca,iBAAA;;AAiDa;AAgB1B;;;;;cA9Ca,cAAA,EAAc,MAAqB;;;;;;;;;;;;;;;;AAiE5B;AAcpB;;;;;;;;AAWW;KA/DC,aAAA;EACN,IAAA;EAAgB,MAAA;EAAgB,EAAA;EAAY,MAAA;AAAA;EAC5C,IAAA;EAAa,GAAA;AAAA;EACb,IAAA;EAAe,KAAA;AAAA;;;;;;;;;;;;;;;KAgBT,QAAA;2DAEV,EAAA;EAEA,IAAA;EAiF0B;;;;;;;;EAxE1B,IAAA,GAAO,aAAA;EAEP,KAAA,EAAO,MAAA;EAEP,OAAA,GAAU,MAAA;EACV,MAAA;EACA,QAAA,EAAU,QAAA;AAAA;;;;;;;;;;;;UAcK,eAAA;;;;;;;EAOf,KAAA;;EAEA,MAAA;;EAEA,SAAA;AAAA;;;;;;UAQe,WAAA;;EAEf,MAAA;;EAEA,KAAK;AAAA;;UAIU,iBAAA;;;;;;EAMf,cAAc;AAAA;;;;;AAmHhB;;;;;;;;;;;;cAhGa,eAAA,EAAe,CAAA,CAAA,qBAAA,UAAA,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqN5B;;;;AAAiE;;AAAjE,iBArHgB,mBAAA,CACd,OAAA,EAAS,iBAAA,GACR,CAAA,CAAE,OAAA,CAAQ,QAAA,EAAU,CAAA,CAAE,UAAA;;iBAkDT,mBAAA,CACd,OAAA,EAAS,iBAAA,GACR,CAAA,CAAE,OAAA,CAAQ,QAAA,IAAY,CAAA,CAAE,UAAA;;UAKV,mBAAA;;EAEf,KAAA;;EAEA,SAAS;AAAA;;;;;;;;;;iBAYK,eAAA,CAAgB,IAAA,YAAgB,mBAAmB;;;;;;;iBA0CnD,iBAAA,CAAkB,IAAA,WAAe,QAAgB"}

package/dist/messages/en.json

@@ -0,0 +1,19 @@
+{
+  "Menus": {
+    "nav": {
+      "menus": "Menus"
+    },
+    "entity": {
+      "menu": "Menu",
+      "menus": "Menus",
+      "handle": "Handle",
+      "title": "Title",
+      "maxDepth": "Maximum depth",
+      "tree": "Items"
+    },
+    "itemKind": {
+      "link": "Link",
+      "header": "Header"
+    }
+  }
+}

package/dist/messages/et.json

@@ -0,0 +1,19 @@
+{
+  "Menus": {
+    "nav": {
+      "menus": "Menüüd"
+    },
+    "entity": {
+      "menu": "Menüü",
+      "menus": "Menüüd",
+      "handle": "Tunnus",
+      "title": "Pealkiri",
+      "maxDepth": "Maksimaalne sügavus",
+      "tree": "Elemendid"
+    },
+    "itemKind": {
+      "link": "Link",
+      "header": "Pealkiri"
+    }
+  }
+}

package/dist/messages/ru.json

@@ -0,0 +1,19 @@
+{
+  "Menus": {
+    "nav": {
+      "menus": "Меню"
+    },
+    "entity": {
+      "menu": "Меню",
+      "menus": "Меню",
+      "handle": "Идентификатор",
+      "title": "Название",
+      "maxDepth": "Максимальная глубина",
+      "tree": "Элементы"
+    },
+    "itemKind": {
+      "link": "Ссылка",
+      "header": "Заголовок"
+    }
+  }
+}

package/dist/resolve.d.mts

@@ -0,0 +1,205 @@
+import { ToolkitApp } from "@murumets-ee/core";
+
+//#region src/get-menu.d.ts
+/**
+ * `getMenu()` — turn a stored menu tree into a render-ready structure for one
+ * locale (plan/routing phase 11 §2), plus the pure `markActiveTrail()` helper
+ * (phase 11 §3).
+ *
+ * **Leaf module.** Every cross-package capability (the menu row read, the
+ * `toolkit_paths` forward index, the publish gate, live entity titles) arrives
+ * through the injected {@link MenuResolveDeps}; nothing here imports
+ * `@murumets-ee/core` or `@murumets-ee/content`. Concrete deps are built from a
+ * live app in `./menu-resolve-context.ts` — the same leaf/seam split
+ * `@murumets-ee/content`'s `paths/enumerate.ts` ↔ `paths/resolve-context.ts`
+ * uses, and the reason the deps' function types are declared structurally here
+ * rather than imported (assignability is still checked, at the seam).
+ *
+ * **Security.** The resolved output feeds PUBLIC page navigation, so it must
+ * never surface an unpublished or deleted document:
+ *  - the menu itself is read through a publish-filtered client (an unpublished
+ *    menu resolves to `null` — nothing renders),
+ *  - every entity-linked item must have BOTH a canonical path in
+ *    `toolkit_paths` for the requested locale AND survive the batched publish
+ *    gate; missing either → the item (and its subtree) is dropped,
+ *  - `url` / `email` targets are re-gated through the same `sanitizeHref`
+ *    protocol allowlist the write path uses, so a value that reached the column
+ *    by some route other than the entity API (a direct DB edit, a restored
+ *    dump) still cannot become a `javascript:` href,
+ *  - every filtering decision fails CLOSED — anything unresolvable is dropped,
+ *    never rendered with a placeholder.
+ *
+ * **No unbounded fan-out** (CLAUDE.md). Backend work is bounded by the number
+ * of distinct ENTITY TYPES in the tree, never by the number of items: the walk
+ * collects ids grouped by type, then issues at most THREE batched calls per
+ * group (forward index → publish gate → titles). The group count is itself hard-
+ * capped ({@link MAX_MENU_ENTITY_TYPES}) and the walk carries a node budget
+ * ({@link MAX_MENU_TREE_NODES}), so one render costs a fixed, small number of
+ * round-trips no matter what the stored tree looks like.
+ *
+ * **Read-time validation is per-node, not whole-tree.** The write path already
+ * runs `buildMenuTreeSchema()` (`menuTreeValidation()`), and this module
+ * deliberately does NOT re-run it: that schema whitelists locale KEYS against
+ * the app's configured locales, so re-parsing at read time would fail the WHOLE
+ * menu — site navigation gone — the moment an operator removes a locale from
+ * config after a menu was saved. The locale whitelist is a write-time authoring
+ * check with no read-time security value. What DOES matter at read time (node
+ * shape, the `LinkValue` protocol gate) is re-checked per node here, and a
+ * malformed node is dropped on its own without taking the menu down with it.
+ */
+/**
+ * Hard cap on the number of DISTINCT entity types one menu may fan out over.
+ *
+ * The batched pipeline costs three DB round-trips per type group, so this — not
+ * the item count — is what bounds a render's backend work. A navigation menu
+ * pointing at more than a handful of routable types is malformed by
+ * construction; types past the cap are dropped (their items disappear) and
+ * logged, never silently truncated.
+ */
+declare const MAX_MENU_ENTITY_TYPES = 16;
+/** One render-ready menu item (phase 11 §2 — exact shape). */
+interface ResolvedMenuItem {
+  /** The stored item's stable id (DND identity; also a stable React key). */
+  id: string;
+  kind: 'link' | 'header';
+  /** Resolved label: the per-locale override, else the live entity title. */
+  label: string;
+  /**
+   * Locale-relative canonical path from `toolkit_paths` (+ `#anchor` when set),
+   * external `url` / `email` targets verbatim (protocol-gated), `null` for
+   * `header` items.
+   */
+  href: string | null;
+  newTab: boolean;
+  /** Exact `currentPath` match on the path part (any `#anchor` ignored). */
+  isActive: boolean;
+  /** An ancestor BY TREE of the active item — never a path-prefix guess. */
+  inActiveTrail: boolean;
+  children: ResolvedMenuItem[];
+}
+/**
+ * A resolved menu.
+ *
+ * Phase 11 §2 names `ResolvedMenuItem` and uses `ResolvedMenu` as `getMenu`'s
+ * return type without spelling its fields out; this is the minimal wrapper that
+ * satisfies it — the requested `handle` (so a caller holding several resolved
+ * menus can tell them apart, and so `markActiveTrail` can round-trip a menu
+ * without losing its identity) plus the item forest. Deliberately carries no
+ * `maxDepth` / `title`: the depth clamp is already APPLIED in `items`, and a
+ * menu's admin-facing title is not a rendering concern.
+ */
+interface ResolvedMenu {
+  handle: string;
+  items: ResolvedMenuItem[];
+}
+/** Options for {@link getMenu} (phase 11 §2). */
+interface GetMenuOptions {
+  /** The locale to resolve labels, visibility and canonical paths for. */
+  locale: string;
+  /**
+   * The page being rendered, for active-trail marking. SSG frontends usually
+   * OMIT this (one build-time fetch) and call {@link markActiveTrail} per page.
+   */
+  currentPath?: string | undefined;
+}
+/** The projected `menu` row {@link getMenu} reads. */
+interface MenuRow {
+  /**
+   * The menu's own depth cap. Absent / out of range falls back to the entity
+   * default — the clamp is renderer-enforced independently of the editor
+   * (phase 07 §2.7), so a bad stored value can never widen it.
+   */
+  maxDepth?: number | null | undefined;
+  /** Raw `menu.tree` JSONB. Untrusted shape — validated per node during the walk. */
+  tree: unknown;
+}
+/**
+ * Structural minimum of a pino/toolkit logger. Declared here (rather than
+ * imported) so this module stays import-free; `app.logger.child(...)` satisfies
+ * it structurally.
+ */
+interface MenuResolveLogger {
+  warn(obj: object, msg: string): void;
+}
+/**
+ * Everything {@link getMenu} needs from the outside world.
+ *
+ * Function-shaped (not reader-shaped) on purpose: the concrete implementations
+ * live in `./menu-resolve-context.ts`, where assignability against
+ * `@murumets-ee/content`'s real `getCanonicalPaths` / `PublishFilter` is
+ * type-checked at the seam — so this module needs no `@murumets-ee/content`
+ * import and drift is still a build error.
+ */
+interface MenuResolveDeps {
+  /**
+   * Fetch the PUBLISHED menu row by handle, or `null`.
+   *
+   * The publish filter is the implementation's responsibility (the app-side
+   * factory reads through a publish-filtering `QueryClient`) — a draft menu
+   * must never resolve, per phase 11 §2.
+   */
+  getMenuRow: (handle: string) => Promise<MenuRow | null>;
+  /**
+   * Batched forward index read: which of `ids` have a canonical path in
+   * `locale`? Does NOT publish-filter — {@link MenuResolveDeps.filterPublished}
+   * is the required second step.
+   */
+  resolveCanonicalPaths: (entityType: string, ids: readonly string[], locale: string) => Promise<ReadonlyMap<string, string>>;
+  /** Batched publish gate: which of `ids` are published in `locale`? */
+  filterPublished: (entityType: string, ids: readonly string[], locale: string) => Promise<ReadonlySet<string>>;
+  /**
+   * Batched live-title read: `id → display title` for `locale`. Only called for
+   * the ids that actually need one (no per-locale label override), and never
+   * for `header` items (they have no linked entity to borrow a title from).
+   */
+  resolveTitles: (entityType: string, ids: readonly string[], locale: string) => Promise<ReadonlyMap<string, string>>;
+  /**
+   * Fallback locale for label overrides — the app's configured content
+   * `defaultLocale`. A label present only in the default locale still renders
+   * (the same locale → default fallback `mergeTranslations` gives entity data),
+   * instead of silently dropping a partially-translated item.
+   */
+  defaultLocale: string;
+  /** Optional — used to report DROPPED work (never silent truncation). */
+  logger?: MenuResolveLogger | undefined;
+}
+/**
+ * Mark `isActive` / `inActiveTrail` on a resolved menu for one page.
+ *
+ * PURE — no I/O, and the input menu is not mutated (a new tree is returned), so
+ * an SSG build can fetch a menu ONCE and mark it per page without the pages
+ * contaminating each other. `getMenu` calls this internally when
+ * `opts.currentPath` is given, so there is exactly one implementation of the
+ * ancestry walk.
+ *
+ * `isActive` is an EXACT match on the path part; `inActiveTrail` marks strict
+ * tree ancestors of an active item (an active item is not its own ancestor).
+ */
+declare function markActiveTrail(menu: ResolvedMenu, currentPath: string): ResolvedMenu;
+/**
+ * Resolve a stored menu into a render-ready tree for one locale (phase 11 §2).
+ *
+ * Returns `null` when the menu does not exist or is not published — a draft
+ * menu renders nowhere public. A published menu whose every item was filtered
+ * out returns an EMPTY item list, not `null`: "the menu exists but has nothing
+ * to show here" is a different fact from "there is no such menu".
+ *
+ * Filtering order (phase 11 §2, not reorderable): menu unpublished → `null`;
+ * `enabled[locale] === false` → dropped with its subtree; entity target deleted
+ * or unpublished-in-locale → dropped; header with no surviving children →
+ * dropped; depth clamped to the menu's own `maxDepth`.
+ */
+declare function getMenu(handle: string, opts: GetMenuOptions, deps: MenuResolveDeps): Promise<ResolvedMenu | null>;
+//#endregion
+//#region src/menu-resolve-context.d.ts
+/**
+ * Build the concrete {@link MenuResolveDeps} for an app.
+ *
+ * Cheap to call per request (it constructs no clients eagerly — each read
+ * builds its own `QueryClient`, matching `buildEnumerateDeps`'s per-call shape,
+ * so this never depends on plugin boot ORDER).
+ */
+declare function buildMenuResolveDeps(app: ToolkitApp): MenuResolveDeps;
+//#endregion
+export { type GetMenuOptions, MAX_MENU_ENTITY_TYPES, type MenuResolveDeps, type MenuResolveLogger, type MenuRow, type ResolvedMenu, type ResolvedMenuItem, buildMenuResolveDeps, getMenu, markActiveTrail };
+//# sourceMappingURL=resolve.d.mts.map

package/dist/resolve.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.mts","names":[],"sources":["../src/get-menu.ts","../src/menu-resolve-context.ts"],"mappings":";;;;;;AAqEA;;;;AAAkC;AAelC;;;;;;;;;;;;;;AAiB4B;AAc5B;;;;;;;;AAEyB;AAIzB;;;;AAOa;AAQb;;;;AAQM;AAQN;;;;;;;;AAC+B;AAY/B;;;;cAhGa,qBAAA;;UAeI,gBAAA;EAyGF;EAvGb,EAAA;EACA,IAAA;EAgHK;EA9GL,KAAA;EAuH0B;;;;;EAjH1B,IAAA;EACA,MAAA;EAoFE;EAlFF,QAAA;EAoFE;EAlFF,aAAA;EACA,QAAA,EAAU,gBAAgB;AAAA;;;;;;;;;;;;UAcX,YAAA;EACf,MAAA;EACA,KAAA,EAAO,gBAAgB;AAAA;AA2FG;AAAA,UAvFX,cAAA;EA+cc;EA7c7B,MAAA;EA6coF;;;;EAxcpF,WAAW;AAAA;AAwcyE;AAAA,UAhcrE,OAAA;EAqdY;;;;;EA/c3B,QAAA;EAmdQ;EAjdR,IAAI;AAAA;;;;;;UAQW,iBAAA;EACf,IAAA,CAAK,GAAA,UAAa,GAAA;AAAA;;;;AC7FpB;;;;;;UDyGiB,eAAA;ECzGqD;AAAA;;;;;;EDiHpE,UAAA,GAAa,MAAA,aAAmB,OAAA,CAAQ,OAAA;;;;;;EAMxC,qBAAA,GACE,UAAA,UACA,GAAA,qBACA,MAAA,aACG,OAAA,CAAQ,WAAA;;EAEb,eAAA,GACE,UAAA,UACA,GAAA,qBACA,MAAA,aACG,OAAA,CAAQ,WAAA;;;;;;EAMb,aAAA,GACE,UAAA,UACA,GAAA,qBACA,MAAA,aACG,OAAA,CAAQ,WAAA;;;;;;;EAOb,aAAA;;EAEA,MAAA,GAAS,iBAAA;AAAA;;;;;;;;;;;;;iBAwXK,eAAA,CAAgB,IAAA,EAAM,YAAA,EAAc,WAAA,WAAsB,YAAY;;;;;;;;;;;;;;iBAqBhE,OAAA,CACpB,MAAA,UACA,IAAA,EAAM,cAAA,EACN,IAAA,EAAM,eAAA,GACL,OAAA,CAAQ,YAAA;;;;;;;;AA5ec;AAIzB;iBC7DgB,oBAAA,CAAqB,GAAA,EAAK,UAAA,GAAa,eAAe"}

package/dist/resolve.mjs

@@ -0,0 +1,2 @@
+import{s as e}from"./menu-entity-types-BnKnKbif.mjs";import{t}from"./entity-BxLeqoBC.mjs";import{resolveLinkHref as n}from"@murumets-ee/blocks/links";import{getContentConfig as r}from"@murumets-ee/content/plugin";import{getEntityTitleField as i}from"@murumets-ee/entity";import{buildCanonicalPathsBatchDeps as a,buildEnumerateDeps as o,getCanonicalPaths as s}from"@murumets-ee/content/resolve";import{QueryClient as c}from"@murumets-ee/entity/query";import{eq as l,inArray as u}from"drizzle-orm";const d=16;function f(e,t,n){if(typeof e!=`object`||!e||Array.isArray(e))return;let r=e;for(let e of t===n?[t]:[t,n]){if(!Object.hasOwn(r,e))continue;let t=r[e];if(typeof t==`string`&&t.length>0)return t}}function p(e,t){if(typeof e!=`object`||!e||Array.isArray(e))return;let n=e;if(!Object.hasOwn(n,t))return;let r=n[t];return typeof r==`boolean`?r:void 0}function m(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function h(t,n,r,i){let a=new Map,o=new Map,s=500,c=0;function l(e,t,n){let r=e.get(t);r?r.add(n):e.set(t,new Set([n]))}function u(t,d){if(d>i||!Array.isArray(t))return[];let h=t,g=[];for(let t of h){if(s<=0){c++;continue}if(!m(t))continue;let i=t.id,h=t.kind;if(typeof i!=`string`||i.length===0||h!==`link`&&h!==`header`||p(t.enabled,n)===!1)continue;s--;let _;if(h===`link`){let n=e.safeParse(t.link);if(!n.success)continue;_=n.data}else if(t.link!==void 0)continue;let v=u(t.children,d+1);_?.kind===`entity`&&(l(a,_.entity,_.id),f(t.label,n,r)===void 0&&l(o,_.entity,_.id)),g.push({id:i,kind:h,link:_,label:t.label,newTab:t.newTab===!0,children:v})}return g}return{nodes:u(t,1),idsByType:a,titleIdsByType:o,droppedForBudget:c}}async function g(e,t,n,r){let i=new Map,a=new Map,o=new Map,s=[...e.idsByType.entries()];return s.length>16&&n.logger?.warn({handle:r,locale:t,entityTypes:s.length,cap:16},`menu resolution dropped entity-type groups over the fan-out cap`),await Promise.all(s.slice(0,16).map(async([r,s])=>{let c=[...s],l=await n.resolveCanonicalPaths(r,c,t);if(i.set(r,l),l.size===0)return;let u=[...l.keys()],d=await n.filterPublished(r,u,t);a.set(r,d);let f=e.titleIdsByType.get(r);if(f===void 0)return;let p=u.filter(e=>f.has(e)&&d.has(e));p.length!==0&&o.set(r,await n.resolveTitles(r,p,t))})),{paths:i,published:a,titles:o}}function _(e,t,r,i){let a=[];for(let o of e){let e=_(o.children,t,r,i),s=f(o.label,t,i.defaultLocale);if(o.kind===`header`){if(e.length===0||s===void 0)continue;a.push({id:o.id,kind:`header`,label:s,href:null,newTab:!1,isActive:!1,inActiveTrail:!1,children:e});continue}let c=o.link;if(c===void 0)continue;let l,u=s;if(c.kind===`entity`){let e=r.paths.get(c.entity)?.get(c.id);if(e===void 0||r.published.get(c.entity)?.has(c.id)!==!0)continue;l=c.anchor===void 0?e:`${e}#${c.anchor}`,u??=r.titles.get(c.entity)?.get(c.id)}else l=n(c);l===null||l.length===0||u===void 0||u.length===0||a.push({id:o.id,kind:`link`,label:u,href:l,newTab:o.newTab,isActive:!1,inActiveTrail:!1,children:e})}return a}function v(e){let t=e.indexOf(`#`),n=t===-1?e:e.slice(0,t);return n.length>1&&n.endsWith(`/`)?n.slice(0,-1):n}function y(e,t){let n=!1;return{items:e.map(e=>{let r=y(e.children,t),i=e.href!==null&&v(e.href)===t,a=r.containsActive;return(i||a)&&(n=!0),{...e,isActive:i,inActiveTrail:a,children:r.items}}),containsActive:n}}function b(e,t){return{...e,items:y(e.items,v(t)).items}}async function x(e,t,n){if(e.length===0||e.length>128)return null;let r=await n.getMenuRow(e);if(r===null)return null;let i=r.maxDepth,a=typeof i==`number`&&Number.isInteger(i)&&i>=1?Math.min(i,6):3,o=h(r.tree,t.locale,n.defaultLocale,a);o.droppedForBudget>0&&n.logger?.warn({handle:e,locale:t.locale,dropped:o.droppedForBudget,cap:500},`menu resolution dropped items over the node budget`);let s=await g(o,t.locale,n,e),c={handle:e,items:_(o.nodes,t.locale,s,n)};return t.currentPath===void 0?c:b(c,t.currentPath)}function S(e,t){return e[t]}const C=()=>({user:{id:`system`,groups:[`admin`]},checker:()=>!0});function w(e){let n=e.db.readOnly,d=a(e),{filterPublished:f}=o(e);return{getMenuRow:async r=>{let i=new c({entity:t,db:n,logger:e.logger.child({resolve:`menu`}),contextResolver:C}),a=(await i.findMany({where:l(S(i.getTable(),`handle`),r),limit:1}))[0];return a===void 0?null:{maxDepth:a.maxDepth,tree:a.tree}},resolveCanonicalPaths:(e,t,n)=>s(e,t,n,d),filterPublished:f,resolveTitles:async(t,r,a)=>{let o=new Map;if(r.length===0)return o;let s=e.entities.get(t);if(s===void 0)return o;let l=i(s);if(l===`id`)return o;let d=new c({entity:s,db:n,logger:e.logger.child({resolve:`menu-title`,entity:t}),contextResolver:C}),f=S(d.getTable(),`id`);for(let e=0;e<r.length;e+=500){let t=r.slice(e,e+500),n=await d.findMany({where:u(f,[...t]),locale:a,limit:t.length});for(let e of n){let t=e,n=t.id,r=t[l];typeof n==`string`&&typeof r==`string`&&r.length>0&&o.set(n,r)}}return o},defaultLocale:r().defaultLocale,logger:e.logger.child({resolve:`menu`})}}export{d as MAX_MENU_ENTITY_TYPES,w as buildMenuResolveDeps,x as getMenu,b as markActiveTrail};
+//# sourceMappingURL=resolve.mjs.map