@frigear-nu/menu 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# @frigear-nu/menu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Named, shareable navigation menus. A **menu** (`main`, `dashboard`, `account`, ...) is a named
+collection of items, filled by one or more **sources** - Nuxt Content, other modules (at build
+time, or dynamically at runtime), or both at once (content as the base, modules appending). This
+package is presentation-free: it only exposes data (`useMenu`) - `description`/`icon` are optional
+fields a consumer may render however it likes, or ignore.
+
+## Quick Setup
+
+Install the module to your Nuxt application with one command:
+
+```bash
+npx nuxt module add @frigear-nu/menu
+```
+
+## Vocabulary
+
+- **Menu** - a named collection of items (`main`, `dashboard`, `account`, ...).
+- **Group** - the part after a menu's first dot. `dashboard.more` addresses group `more` of menu
+  `dashboard`.
+- **Source** - anything that fills a menu: Nuxt Content, `extendMenu`, or a module's
+  `runtime/menus.ts` file.
+
+## Contributing items from another module
+
+### Static items, known at build time
+
+```ts
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { extendMenu } from '@frigear-nu/menu/utils'
+
+export default defineNuxtModule({
+  meta: { name: '@frigear-nu/example' },
+  setup(options, nuxt) {
+    // `'dashboard.more'` is parsed as menu `dashboard`, group `more` (split on the first dot only).
+    extendMenu(nuxt, 'dashboard.more', [
+      { label: 'Billing', description: 'Manage your subscription', to: '/billing' },
+    ])
+  },
+})
+```
+
+### Dynamic items, needing runtime context (e.g. `useRuntimeConfig`)
+
+```ts
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerMenuSource } from '@frigear-nu/menu/utils'
+
+export default defineNuxtModule({
+  meta: { name: '@frigear-nu/example' },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    registerMenuSource(nuxt, {
+      file: resolver.resolve('./runtime/menus'),
+      menu: 'dashboard',
+    })
+  },
+})
+```
+
+```ts
+// runtime/menus.ts
+import { defineMenuSource, extendMenuItem } from '@frigear-nu/menu/utils'
+
+export default defineMenuSource((items) => {
+  const config = useRuntimeConfig().public.example
+
+  // Pushed into the `dashboard` menu's root group.
+  if (config?.enabled) items.push({ label: 'Example', to: '/example' })
+
+  // Pushed into a named group (in this or another menu) instead - created automatically if it
+  // doesn't already exist. `extendMenuItem` pushes into shared app state, so it only works from
+  // code that actually runs as part of the Nuxt app (like this file) - not from a module's own
+  // build-time `setup()` (use `extendMenu` there instead).
+  extendMenuItem('dashboard.more', { label: 'Security', to: '/security' })
+})
+```
+
+Registration order between modules doesn't matter for either approach - items are only merged
+once every module has finished setting up.
+
+## Nuxt Content source
+
+Enable the `@nuxt/content`-backed source for a menu (requires `@nuxt/content` to be installed):
+
+```ts
+export default defineNuxtConfig({
+  menus: {
+    content: {
+      // Reads `config.navigation` (the collection/field defined by `@frigear-nu/base`).
+      main: true,
+      // ...or a custom collection/field:
+      dashboard: { collection: 'dashboard', field: 'tiles' },
+    },
+  },
+})
+```
+
+Content items are localized automatically when `@nuxtjs/i18n` is configured with `locales`,
+following the same `config` -> `config_en` collection-suffix convention as `@frigear-nu/base`.
+
+## Reading a menu
+
+`useMenu` is auto-imported. It returns the same shape as `useAsyncData`
+(`{ data, pending, error, refresh }`) - rendering is entirely up to the consumer:
+
+```vue
+<script setup lang="ts">
+const { data: items } = useMenu('main')
+const { data: more } = useMenu('dashboard.more')
+</script>
+
+<template>
+  <nav>
+    <NuxtLink
+      v-for="item in items"
+      :key="item.id"
+      :to="item.to"
+    >
+      {{ item.label }}
+    </NuxtLink>
+  </nav>
+</template>
+```
+
+Items are sorted by `order` (ascending; items without an `order` render last, in registration
+order).
+
+### Wildcard reads
+
+A path ending in `.*` reads every matching group, flattened into one list, instead of a single
+exact group - useful for rendering a whole menu "tree" at once:
+
+```ts
+// Every group of the `dashboard` menu (root group included).
+const { data: all } = useMenu('dashboard.*')
+
+// `account` and every group nested under it (e.g. `dashboard.account.sub`), but not sibling
+// groups like `dashboard.more`.
+const { data: accountTree } = useMenu('dashboard.account.*')
+```
+
+Wildcards are only supported when reading a menu - `extendMenu`/`extendMenuItem` reject a
+wildcard path, since items can only ever be registered into one exact group.

package/dist/module.d.mts

@@ -0,0 +1,100 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+/**
+ * A single menu entry. Deliberately framework-agnostic (no Vue/Nuxt types) and presentation-free -
+ * `description`/`icon` are optional fields a view may use or ignore, but the data never encodes
+ * how it's rendered (no colors, no markup).
+ */
+type MenuItem = {
+    /**
+     * Stable identifier, useful for `:key` bindings or for overriding/removing an item later.
+     * When omitted it's derived deterministically from `to` (if present) or a slug of `label`.
+     */
+    id?: string;
+    /**
+     * Matches the `label` field of `@frigear-nu/base`'s `config` content collection `navigation`
+     * entries, so content-sourced and module-sourced items share the exact same shape.
+     */
+    label: string;
+    description?: string;
+    icon?: string;
+    to?: string;
+    external?: boolean;
+    tags?: string[];
+    /** Lower numbers render first. Items without an `order` are rendered last, in registration order. */
+    order?: number;
+    /**
+     * The group (the part after the menu's first dot) this item belongs to. Set automatically from
+     * the path passed to `extendMenu`/`extendMenuItem`, but an explicit value here always wins.
+     */
+    group?: string;
+    meta?: Record<string, unknown>;
+};
+/** A named collection of `MenuItem`s, keyed by group (`''` for the root group). */
+type Menu = Record<string, MenuItem[]>;
+/**
+ * A module's `runtime/menus.ts` file exports a default function matching this signature, wrapped
+ * in `defineMenuSource` for typing/DX. It receives the registered menu's root group items array
+ * directly, so pushing an item there is as simple as `items.push({ ... })`. Use the auto-imported
+ * `extendMenuItem(path, item)` to push into a named group (in this or another menu) instead.
+ */
+type MenuSource = (items: MenuItem[]) => void | Promise<void>;
+type MenuContentSourceOptions = {
+    /** Content collection to read the menu's base items from. Defaults to `'config'`. */
+    collection?: string;
+    /** Field on the collection holding the `MenuItem[]`. Defaults to `'navigation'`. */
+    field?: string;
+};
+type ModuleOptions = {
+    /**
+     * Enables the `@nuxt/content`-backed source for one or more menus. Maps a menu name to `true`
+     * (use the default `config` collection's `navigation` field) or a `{ collection, field }` pair
+     * to read from a different collection/field. Requires `@nuxt/content` to be installed - a
+     * clear build-time error is thrown otherwise.
+     */
+    content?: Record<string, boolean | MenuContentSourceOptions>;
+};
+
+type ResolvedMenuContentSource = { collection: string, field: string }
+
+declare module '@nuxt/schema' {
+  interface NuxtConfig {
+    menus?: ModuleOptions
+  }
+
+  interface NuxtOptions {
+    menus?: ModuleOptions & {
+      _extensions?: Record<string, Record<string, MenuItem[]>>
+      _sources?: Array<{ menu: string, file: string }>
+    }
+  }
+
+  interface PublicRuntimeConfig {
+    menus?: {
+      content?: Record<string, ResolvedMenuContentSource>
+    }
+  }
+
+  interface NuxtHooks {
+    /** Called every time `extendMenu` registers items into a menu. */
+    'menus:extend': (menu: string, items: MenuItem[]) => void
+    /**
+     * Called once, after every module has finished setting up, with every menu's final
+     * statically-registered items (menu name -> group -> items). Dynamic `runtime/menus.ts`
+     * sources and content-sourced items aren't included, since those only resolve at render time.
+     */
+    'menus:resolved': (menus: Record<string, Record<string, MenuItem[]>>) => void
+  }
+}
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    /** Called whenever `useMenu` resolves a menu's items, right before they're handed to a view. */
+    'menus:visible': (menu: string) => void
+  }
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { Menu, MenuContentSourceOptions, MenuItem, MenuSource, ModuleOptions, ResolvedMenuContentSource };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/menu",
+  "configKey": "menus",
+  "version": "0.0.3",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,66 @@
+import { defineNuxtModule, createResolver, addImports, hasNuxtModule, addTypeTemplate, addTemplate, addPlugin, addServerImports } from '@nuxt/kit';
+import { registerModule } from '@frigear-nu/module-kit/utils';
+
+const DEFAULT_CONTENT_COLLECTION = "config";
+const DEFAULT_CONTENT_FIELD = "navigation";
+const module$1 = defineNuxtModule({
+  meta: { name: "@frigear-nu/menu", configKey: "menus" },
+  async setup(options, nuxt) {
+    registerModule("@frigear-nu/menu", nuxt);
+    const resolver = createResolver(import.meta.url);
+    addImports([
+      { name: "useMenu", from: resolver.resolve("./runtime/app/composables/useMenu") },
+      { name: "extendMenuItem", from: resolver.resolve("./runtime/app/utils/extend") }
+    ]);
+    const contentEntries = Object.entries(options.content ?? {});
+    if (contentEntries.length > 0 && !hasNuxtModule("@nuxt/content")) {
+      throw new Error("[@frigear-nu/menu] `content` is configured for one or more menus, but `@nuxt/content` module is not installed. Please install @nuxt/content or remove the `content` option.");
+    }
+    nuxt.options.runtimeConfig.public.menus = {
+      content: Object.fromEntries(
+        contentEntries.map(([menu, source]) => {
+          const explicit = typeof source === "object" ? source : void 0;
+          return [
+            menu,
+            {
+              collection: explicit?.collection ?? DEFAULT_CONTENT_COLLECTION,
+              field: explicit?.field ?? DEFAULT_CONTENT_FIELD
+            }
+          ];
+        })
+      )
+    };
+    addTypeTemplate({
+      filename: "types/menus-sources.d.ts",
+      getContents: () => `declare module '#menus/sources' {
+  import type { MenuItem, MenuSource } from ${JSON.stringify(resolver.resolve("./types"))}
+  export const staticItems: Record<string, Record<string, MenuItem[]>>
+  export const sources: Array<{ menu: string, source: MenuSource }>
+}
+`
+    });
+    nuxt.hook("modules:done", () => {
+      const staticItems = nuxt.options.menus?._extensions ?? {};
+      const sources = Array.isArray(nuxt.options.menus?._sources) ? nuxt.options.menus._sources : [];
+      const sourcesTemplate = addTemplate({
+        filename: "#menus/sources.mjs",
+        write: true,
+        getContents: () => `
+export const staticItems = ${JSON.stringify(staticItems)}
+${sources.map((source, index) => `import source${index} from ${JSON.stringify(source.file)}`).join("\n")}
+export const sources = [${sources.map((source, index) => `{ menu: ${JSON.stringify(source.menu)}, source: source${index} }`).join(", ")}]
+`
+      });
+      nuxt.options.alias["#menus/sources"] = sourcesTemplate.dst;
+      nuxt.callHook("menus:resolved", staticItems);
+    });
+    addPlugin(resolver.resolve("./runtime/app/plugins/menus"));
+    addServerImports({
+      name: "useMenu",
+      from: resolver.resolve("./runtime/server/utils"),
+      as: "useMenu"
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/composables/useMenu.d.ts

@@ -0,0 +1,22 @@
+import type { MenuItem } from '../../../types.js';
+import type { AsyncData, NuxtError } from 'nuxt/app';
+/**
+ * Reads a menu's (or menu group's) items, merged from every configured source - items registered
+ * at build time through `extendMenu`, items pushed by a module's `runtime/menus.ts` source, and
+ * (when enabled) the `@nuxt/content`-backed source - sorted by `order` (ascending, undefined
+ * last, in registration order).
+ *
+ * Addressed as `menu` (root group) or `menu.group` (parsed on the first dot only, e.g.
+ * `'dashboard.more'` reads group `more` of menu `dashboard`). A path ending in `.*` reads every
+ * matching group instead, flattened into a single list: `'dashboard.*'` reads every group of
+ * `dashboard`, `'dashboard.account.*'` reads `account` and every group nested under it. Re-evaluates
+ * when the content locale changes, and returns the same shape as `useAsyncData` (`{ data, pending,
+ * error, refresh }`).
+ *
+ * ```ts
+ * const { data: items } = useMenu('main')
+ * const { data: more } = useMenu('dashboard.more')
+ * const { data: all } = useMenu('dashboard.*')
+ * ```
+ */
+export declare const useMenu: (path: string) => AsyncData<MenuItem[], NuxtError<unknown> | undefined>;

package/dist/runtime/app/composables/useMenu.js

@@ -0,0 +1,40 @@
+import { computed, unref } from "vue";
+import { useAsyncData, useNuxtApp, useRuntimeConfig } from "#imports";
+import { collectMenuItems, matchesMenuGroup, parseMenuPath, sortByOrder } from "../../utils/menu.js";
+import { menus } from "../utils/state.js";
+function useMenuLocale() {
+  const nuxtApp = useNuxtApp();
+  return computed(() => nuxtApp.$i18n?.locale?.value);
+}
+function localizedCollectionName(name, locale) {
+  return locale ? `${name}_${locale.replace(/-/g, "_")}` : name;
+}
+async function loadContentItems(menu, parsed, locale) {
+  const config = useRuntimeConfig().public.menus ?? {};
+  const source = config.content?.[menu];
+  if (!source) return [];
+  const collection = localizedCollectionName(source.collection, locale);
+  const entry = await queryCollection(collection).first();
+  const items = entry?.[source.field] ?? [];
+  return items.filter((item) => {
+    const group = item.group ?? "";
+    return parsed.wildcard ? matchesMenuGroup(group, parsed.group) : group === parsed.group;
+  });
+}
+export const useMenu = (path) => {
+  const parsed = parseMenuPath(path);
+  const { menu } = parsed;
+  const locale = useMenuLocale();
+  const nuxtApp = useNuxtApp();
+  return useAsyncData(
+    () => `menu:${path}:${locale.value ?? ""}`,
+    async () => {
+      const registered = collectMenuItems(menus[menu], parsed);
+      const content = await loadContentItems(menu, parsed, unref(locale));
+      const result = sortByOrder([...content, ...registered]);
+      await nuxtApp.callHook("menus:visible", menu);
+      return result;
+    },
+    { watch: [locale] }
+  );
+};

package/dist/runtime/app/plugins/menus.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Populates the shared menu state consumed by `useMenu`: first with every item registered at
+ * build time (`extendMenu`), then by running every registered module's dynamic `runtime/menus.ts`
+ * source once per app instance (server: once per request, client: once on hydration). Resets the
+ * state first so repeated runs within the same server process (e.g. concurrent requests) don't
+ * accumulate duplicate items.
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/app/plugins/menus.js

@@ -0,0 +1,19 @@
+import { defineNuxtPlugin } from "#imports";
+import { staticItems, sources } from "#menus/sources";
+import { pushMenuItems, resetMenus } from "../utils/state.js";
+export default defineNuxtPlugin({
+  name: "frigear-nu:menus",
+  async setup() {
+    resetMenus();
+    for (const [menu, groups] of Object.entries(staticItems)) {
+      for (const [group, items] of Object.entries(groups)) {
+        if (items.length > 0) pushMenuItems(menu, group, items);
+      }
+    }
+    for (const { menu, source } of sources) {
+      const items = [];
+      await source(items);
+      if (items.length > 0) pushMenuItems(menu, "", items);
+    }
+  }
+});

package/dist/runtime/app/utils/extend.d.ts

@@ -0,0 +1,8 @@
+import type { MenuItem } from '../../../types.js';
+/**
+ * Pushes one (or more) item(s) into a menu's group, creating both if they don't exist yet. Paths
+ * are addressed as `menu` (root group) or `menu.group` (parsed on the first dot only - e.g.
+ * `'dashboard.more'` is menu `dashboard`, group `more`). Auto-imported, so it can be called
+ * directly from a module's `runtime/menus.ts` source (see `defineMenuSource`) or from app code.
+ */
+export declare function extendMenuItem(path: string, item: MenuItem | MenuItem[]): void;

package/dist/runtime/app/utils/extend.js

@@ -0,0 +1,9 @@
+import { parseMenuPath } from "../../utils/menu.js";
+import { pushMenuItems } from "./state.js";
+export function extendMenuItem(path, item) {
+  const { menu, group, wildcard } = parseMenuPath(path);
+  if (wildcard) {
+    throw new Error(`[@frigear-nu/menu] Cannot register items into wildcard path "${path}" - wildcards are only supported when reading a menu via \`useMenu\`.`);
+  }
+  pushMenuItems(menu, group, item);
+}

package/dist/runtime/app/utils/state.d.ts

@@ -0,0 +1,14 @@
+import type { MenuItem } from '../../../types.js';
+/**
+ * Shared, module-scoped reactive state holding every menu's items, keyed by menu name then by
+ * group (`''` for the root group). Populated client-side (and once per SSR request) by the
+ * `menus` plugin, which runs every registered dynamic source.
+ */
+export declare const menus: Record<string, Record<string, MenuItem[]>>;
+export declare function pushMenuItems(menu: string, group: string, items: MenuItem | MenuItem[]): void;
+/**
+ * Empties every registered menu/group's items in place, keeping the same reactive object/array
+ * instances around rather than deleting keys, so each source run starts from a clean slate
+ * without accumulating duplicates across repeated runs (e.g. concurrent server requests).
+ */
+export declare function resetMenus(): void;

package/dist/runtime/app/utils/state.js

@@ -0,0 +1,12 @@
+import { reactive } from "vue";
+export const menus = reactive({});
+export function pushMenuItems(menu, group, items) {
+  const groups = menus[menu] ??= {};
+  const list = groups[group] ??= [];
+  list.push(...Array.isArray(items) ? items : [items]);
+}
+export function resetMenus() {
+  for (const groups of Object.values(menus)) {
+    for (const list of Object.values(groups)) list.length = 0;
+  }
+}

package/dist/runtime/server/utils.d.ts

@@ -0,0 +1,3 @@
+import { type MenuItem } from '../utils/menu.js';
+import type { H3Event } from 'h3';
+export declare const useMenu: (event: H3Event, path: string) => Promise<MenuItem[]>;

package/dist/runtime/server/utils.js

@@ -0,0 +1,27 @@
+import { collectMenuItems, matchesMenuGroup, parseMenuPath, sortByOrder } from "../utils/menu.js";
+import { useRuntimeConfig } from "nitropack/runtime";
+export const useMenu = async (event, path) => {
+  const parsed = parseMenuPath(path);
+  const { menu } = parsed;
+  const config = useRuntimeConfig(event);
+  const menus = config.public.menus;
+  const registered = collectMenuItems(menus[menu], parsed);
+  const content = await loadContentItems(menu, parsed, "");
+  const result = sortByOrder([...registered, ...content]);
+  return result;
+};
+function localizedCollectionName(name, locale) {
+  return locale ? `${name}_${locale.replace(/-/g, "_")}` : name;
+}
+async function loadContentItems(menu, parsed, locale) {
+  const config = useRuntimeConfig().public.menus ?? {};
+  const source = config.content?.[menu];
+  if (!source) return [];
+  const collection = localizedCollectionName(source.collection, locale);
+  const entry = await queryCollection(collection).first();
+  const items = entry?.[source.field] ?? [];
+  return items.filter((item) => {
+    const group = item.group ?? "";
+    return parsed.wildcard ? matchesMenuGroup(group, parsed.group) : group === parsed.group;
+  });
+}

package/dist/runtime/utils/index.d.ts

@@ -0,0 +1,5 @@
+import type { MenuItem } from './menu.js';
+export { extendMenu, defineMenuSource, registerMenuSource, parseMenuPath, deriveMenuItemId } from './menu.js';
+export type { MenuItem, MenuSource, RegisterMenuSourceOptions, ParsedMenuPath } from './menu.js';
+export { extendMenuItem } from '../app/utils/extend.js';
+export declare const defineMenuItem: <T extends MenuItem>(item: T) => T;

package/dist/runtime/utils/index.js

@@ -0,0 +1,3 @@
+export { extendMenu, defineMenuSource, registerMenuSource, parseMenuPath, deriveMenuItemId } from "./menu.js";
+export { extendMenuItem } from "../app/utils/extend.js";
+export const defineMenuItem = (item) => item;

package/dist/runtime/utils/menu.d.ts

@@ -0,0 +1,85 @@
+import type { Nuxt } from '@nuxt/schema';
+import type { MenuItem, MenuSource } from '../../types.js';
+export type { MenuItem, MenuSource } from '../../types.js';
+export type ParsedMenuPath = {
+    menu: string;
+    group: string;
+    /**
+     * Whether `path` ended in a wildcard group (`'dashboard.*'` or `'dashboard.account.*'`) -
+     * matching that group and every group nested under it, rather than a single exact group.
+     */
+    wildcard: boolean;
+};
+/**
+ * Splits a menu path on its *first* dot only, so `'a.b.c'` resolves to menu `'a'`, group `'b.c'`.
+ * The group becomes the default group for items registered through that path - an explicit
+ * `item.group` always wins.
+ *
+ * A path ending in `.*` is parsed as a wildcard instead: `'dashboard.*'` resolves to menu
+ * `dashboard`, every group (`wildcard: true`, `group: ''`); `'dashboard.account.*'` resolves to
+ * every group that is (or is nested under) `account`. Only `useMenu` understands wildcards -
+ * `extendMenu`/`extendMenuItem` reject them, since items can only ever be registered into one
+ * exact group.
+ */
+export declare function parseMenuPath(path: string): ParsedMenuPath;
+/**
+ * Whether `group` is matched by a wildcard's `prefix` (the `group` resolved by `parseMenuPath`
+ * for a wildcard path) - the prefix itself, or anything nested under it. An empty `prefix`
+ * (`'dashboard.*'`) matches every group.
+ */
+export declare function matchesMenuGroup(group: string, prefix: string): boolean;
+/**
+ * Resolves every item addressed by a parsed menu path out of that menu's groups - a single
+ * group's items for a plain path, or every matching group's items (flattened, unsorted) for a
+ * wildcard path.
+ */
+export declare function collectMenuItems(groups: Record<string, MenuItem[]> | undefined, parsed: ParsedMenuPath): MenuItem[];
+export declare function sortByOrder(items: MenuItem[]): MenuItem[];
+/** Deterministic id for an item missing one: its `to` if present, else a slug of its `label`. */
+export declare function deriveMenuItemId(item: MenuItem): string;
+/**
+ * Build-time API for other modules to contribute static items to a menu, without the host app
+ * wiring anything. Call it once during a module's own `setup()`:
+ *
+ * ```ts
+ * import { extendMenu } from '@frigear-nu/menu/utils'
+ *
+ * export default defineNuxtModule({
+ *   setup(options, nuxt) {
+ *     extendMenu(nuxt, 'dashboard.more', [
+ *       { label: 'Billing', description: 'Manage your subscription' },
+ *     ])
+ *   },
+ * })
+ * ```
+ *
+ * `'dashboard.more'` is parsed as menu `dashboard`, group `more` (split on the *first* dot only).
+ */
+export declare function extendMenu(nuxt: Nuxt, path: string, items: MenuItem | MenuItem[]): void;
+/**
+ * A typed identity helper for authoring a module's `runtime/menus.ts` source file. It exists
+ * purely for type inference/DX - it returns the function unchanged.
+ *
+ * ```ts
+ * // runtime/menus.ts
+ * export default defineMenuSource((items) => {
+ *   const config = useRuntimeConfig().public.example
+ *   if (config?.enabled) items.push({ label: 'Example', to: '/example' })
+ * })
+ * ```
+ */
+export declare const defineMenuSource: (source: MenuSource) => MenuSource;
+export type RegisterMenuSourceOptions = {
+    /** Resolved path to the module's `runtime/menus.ts` source file. */
+    file: string;
+    /** Menu this source's root group items are pushed into. */
+    menu: string;
+};
+/**
+ * Registers a module's menu source so `@frigear-nu/menu` runs it alongside every other
+ * registered source, merging the result into the named menu. Modules call this once during their
+ * own `setup()` - registration order doesn't matter, since sources are only resolved once every
+ * module has finished setting up. `options.file` must already be a resolved path (for example via
+ * `createResolver(import.meta.url).resolve(...)`).
+ */
+export declare const registerMenuSource: (nuxt: Nuxt, options: RegisterMenuSourceOptions) => void;

package/dist/runtime/utils/menu.js

@@ -0,0 +1,83 @@
+export function parseMenuPath(path) {
+  const dotIndex = path.indexOf(".");
+  if (dotIndex === -1) return { menu: path, group: "", wildcard: false };
+  const menu = path.slice(0, dotIndex);
+  const rest = path.slice(dotIndex + 1);
+  if (rest === "*") return { menu, group: "", wildcard: true };
+  if (rest.endsWith(".*")) return { menu, group: rest.slice(0, -2), wildcard: true };
+  return { menu, group: rest, wildcard: false };
+}
+export function matchesMenuGroup(group, prefix) {
+  if (prefix === "") return true;
+  return group === prefix || group.startsWith(`${prefix}.`);
+}
+export function collectMenuItems(groups, parsed) {
+  if (!groups) return [];
+  if (!parsed.wildcard) return groups[parsed.group] ?? [];
+  const matched = [];
+  for (const [group, items] of Object.entries(groups)) {
+    if (matchesMenuGroup(group, parsed.group)) matched.push(...items);
+  }
+  return matched;
+}
+export function sortByOrder(items) {
+  return [...items].sort((a, b) => {
+    if (a.order === void 0 && b.order === void 0) return 0;
+    if (a.order === void 0) return 1;
+    if (b.order === void 0) return -1;
+    return a.order - b.order;
+  });
+}
+function slugify(value) {
+  let result = "";
+  let lastWasDash = true;
+  for (const char of value.toLowerCase()) {
+    const isAlphanumeric = char >= "a" && char <= "z" || char >= "0" && char <= "9";
+    if (isAlphanumeric) {
+      result += char;
+      lastWasDash = false;
+    } else if (!lastWasDash) {
+      result += "-";
+      lastWasDash = true;
+    }
+  }
+  return lastWasDash ? result.slice(0, -1) : result;
+}
+export function deriveMenuItemId(item) {
+  return item.id ?? item.to ?? slugify(item.label);
+}
+function normalizeItems(group, items) {
+  const list = Array.isArray(items) ? items : [items];
+  const seen = /* @__PURE__ */ new Set();
+  return list.map((item) => {
+    const normalized = { group, ...item };
+    const id = deriveMenuItemId(normalized);
+    if (import.meta.dev !== false && seen.has(id)) {
+      console.warn(`[@frigear-nu/menu] Duplicate menu item id "${id}" registered in the same batch.`);
+    }
+    seen.add(id);
+    return { ...normalized, id };
+  });
+}
+export function extendMenu(nuxt, path, items) {
+  const { menu, group, wildcard } = parseMenuPath(path);
+  if (wildcard) {
+    throw new Error(`[@frigear-nu/menu] Cannot register items into wildcard path "${path}" - wildcards are only supported when reading a menu via \`useMenu\`.`);
+  }
+  const normalized = normalizeItems(group, items);
+  nuxt.options.menus ||= {};
+  const extensions = nuxt.options.menus._extensions ||= {};
+  const groups = extensions[menu] ||= {};
+  const list = groups[group] ||= [];
+  list.push(...normalized);
+  nuxt.callHook("menus:extend", menu, normalized);
+}
+export const defineMenuSource = (source) => source;
+export const registerMenuSource = (nuxt, options) => {
+  nuxt.options.menus ||= {};
+  const sources = Array.isArray(nuxt.options.menus._sources) ? nuxt.options.menus._sources : [];
+  nuxt.options.menus._sources = sources;
+  if (!sources.some((source) => source.menu === options.menu && source.file === options.file)) {
+    sources.push({ menu: options.menu, file: options.file });
+  }
+};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type Menu, type MenuContentSourceOptions, type MenuItem, type MenuSource, type ModuleOptions, type ResolvedMenuContentSource } from './module.mjs'

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@frigear-nu/menu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.3",
+  "description": "Named, shareable navigation menus - modules contribute items (extendMenu / a runtime/menus.ts source) and/or Nuxt Content, consumers read them via useMenu and render them however they like.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/menu"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/index.d.ts",
+      "import": "./dist/runtime/utils/index.js",
+      "default": "./dist/runtime/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.6.0",
+    "@frigear-nu/module-kit": "0.1.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }