@scalar/workspace-store 0.17.1 → 0.18.0

package/dist/helpers/overrides-proxy.js

@@ -1,25 +1,35 @@
 import { isObject } from "../helpers/general.js";
 const isOverridesProxy = Symbol("isOverridesProxy");
-const createOverridesProxy = (targetObject, overrides) => {
-  if (!targetObject || typeof targetObject !== "object") {
-    return targetObject;
+const getOverridesTarget = Symbol("getOverridesTarget");
+const createOverridesProxy = (target, options, args = {
+  cache: /* @__PURE__ */ new WeakMap()
+}) => {
+  if (!target || typeof target !== "object") {
+    return target;
   }
+  if (args.cache.has(target)) {
+    return args.cache.get(target);
+  }
+  const { overrides } = options ?? {};
   const handler = {
-    get(target, prop, receiver) {
+    get(target2, prop, receiver) {
       if (prop === isOverridesProxy) {
         return true;
       }
-      if (prop === TARGET_SYMBOL) {
-        return target;
+      if (prop === getOverridesTarget) {
+        return target2;
+      }
+      const value = Reflect.get(target2, prop, receiver);
+      if (isOverridesProxyObject(value)) {
+        return value;
       }
-      const value = Reflect.get(target, prop, receiver);
       if (!isObject(value)) {
         return Reflect.get(overrides ?? {}, prop) ?? value;
       }
-      return createOverridesProxy(value, Reflect.get(overrides ?? {}, prop));
+      return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args);
     },
-    set(target, prop, value, receiver) {
-      if (prop === isOverridesProxy || prop === TARGET_SYMBOL) {
+    set(target2, prop, value, receiver) {
+      if (prop === isOverridesProxy || prop === getOverridesTarget) {
         return false;
       }
       const hasOverride = overrides && Reflect.has(overrides, prop);
@@ -28,21 +38,26 @@ const createOverridesProxy = (targetObject, overrides) => {
         overrides[prop] = value;
         return true;
       }
-      return Reflect.set(target, prop, value, receiver);
+      return Reflect.set(target2, prop, value, receiver);
     }
   };
-  return new Proxy(targetObject, handler);
+  const proxy = new Proxy(target, handler);
+  args.cache.set(target, proxy);
+  return proxy;
+};
+const isOverridesProxyObject = (obj) => {
+  return typeof obj === "object" && obj !== null && obj[isOverridesProxy] === true;
 };
-const TARGET_SYMBOL = Symbol("overridesProxyTarget");
-function unpackOverridesProxy(obj) {
-  if (obj[isOverridesProxy]) {
-    return obj[TARGET_SYMBOL];
+function unpackOverridesProxy(input) {
+  if (input[isOverridesProxy]) {
+    return input[getOverridesTarget];
   }
-  return obj;
+  return input;
 }
 export {
-  TARGET_SYMBOL,
   createOverridesProxy,
+  getOverridesTarget,
+  isOverridesProxyObject,
   unpackOverridesProxy
 };
 //# sourceMappingURL=overrides-proxy.js.map

package/dist/helpers/overrides-proxy.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/helpers/overrides-proxy.ts"],
-  "sourcesContent": ["import { type UnknownObject, isObject } from '@/helpers/general'\n\nconst isOverridesProxy = Symbol('isOverridesProxy')\n\n/**\n * Recursively makes all properties of a type optional.\n *\n * - If T is an object, recursively applies DeepPartial to each property, making them optional.\n * - Otherwise, T is returned as-is.\n *\n * @template T - The type to make deeply partial (optional).\n * @example\n * type Example = { a: { b: number } }\n * type PartialExample = DeepPartial<Example>\n * // Result: { a?: { b?: number } }\n */\nexport type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T\n\n/**\n * Creates a proxy object that overlays \"overrides\" on top of a target object.\n *\n * - When reading a property, if an override exists, it is returned; otherwise, the original value is returned.\n * - When writing to a property, if an override exists, it is updated; otherwise, the original object is updated.\n * - This works recursively for nested objects, so overrides can be deeply partial.\n * - Special symbols are used to identify the proxy and to access the original target.\n *\n * @template T - The type of the target object.\n * @param targetObject - The original object to proxy.\n * @param overrides - An optional object containing override values (deeply partial).\n * @returns A proxy object that reflects overrides on top of the target.\n *\n * @example\n * const original = { a: 1, b: { c: 2 } }\n * const overrides = { b: { c: 42 } }\n * const proxy = createOverridesProxy(original, overrides)\n *\n * console.log(proxy.a) // 1 (from original)\n * console.log(proxy.b.c) // 42 (from overrides)\n *\n * proxy.a = 100\n * console.log(original.a) // 100\n *\n * proxy.b.c = 99\n * console.log(overrides.b.c) // 99\n */\nexport const createOverridesProxy = <T extends Record<string, unknown>>(\n  targetObject: T,\n  overrides?: DeepPartial<T>,\n): T => {\n  if (!targetObject || typeof targetObject !== 'object') {\n    return targetObject\n  }\n\n  // Proxy handler to intercept get/set operations\n  const handler: ProxyHandler<T> = {\n    get(target, prop, receiver) {\n      // Special symbol to identify this as an overrides proxy\n      if (prop === isOverridesProxy) {\n        return true\n      }\n\n      // Special symbol to access the original target object\n      if (prop === TARGET_SYMBOL) {\n        return target\n      }\n\n      const value = Reflect.get(target, prop, receiver)\n\n      // If the value is not an object, return the override if it exists, else the original value\n      if (!isObject(value)) {\n        return Reflect.get(overrides ?? {}, prop) ?? value\n      }\n\n      // For nested objects, recursively create a proxy with the corresponding overrides\n      return createOverridesProxy(value, Reflect.get(overrides ?? {}, prop))\n    },\n\n    set(target, prop, value, receiver) {\n      // Prevent setting special symbols\n      if (prop === isOverridesProxy || prop === TARGET_SYMBOL) {\n        return false\n      }\n\n      // If an override exists for this property, update it\n      const hasOverride = overrides && Reflect.has(overrides, prop)\n\n      if (hasOverride && overrides && typeof overrides === 'object') {\n        ;(overrides as any)[prop] = value\n        return true\n      }\n\n      // Otherwise, update the original target\n      return Reflect.set(target, prop, value, receiver)\n    },\n  }\n\n  // Return the proxy object\n  return new Proxy<T>(targetObject, handler)\n}\n\nexport const TARGET_SYMBOL = Symbol('overridesProxyTarget')\nexport function unpackOverridesProxy<T extends UnknownObject>(obj: T): T {\n  if ((obj as T & { [isOverridesProxy]: boolean | undefined })[isOverridesProxy]) {\n    return (obj as T & { [TARGET_SYMBOL]: T })[TARGET_SYMBOL]\n  }\n\n  return obj\n}\n"],
-  "mappings": "AAAA,SAA6B,gBAAgB;AAE7C,MAAM,mBAAmB,OAAO,kBAAkB;AA2C3C,MAAM,uBAAuB,CAClC,cACA,cACM;AACN,MAAI,CAAC,gBAAgB,OAAO,iBAAiB,UAAU;AACrD,WAAO;AAAA,EACT;AAGA,QAAM,UAA2B;AAAA,IAC/B,IAAI,QAAQ,MAAM,UAAU;AAE1B,UAAI,SAAS,kBAAkB;AAC7B,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,eAAe;AAC1B,eAAO;AAAA,MACT;AAEA,YAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,QAAQ;AAGhD,UAAI,CAAC,SAAS,KAAK,GAAG;AACpB,eAAO,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,KAAK;AAAA,MAC/C;AAGA,aAAO,qBAAqB,OAAO,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,CAAC;AAAA,IACvE;AAAA,IAEA,IAAI,QAAQ,MAAM,OAAO,UAAU;AAEjC,UAAI,SAAS,oBAAoB,SAAS,eAAe;AACvD,eAAO;AAAA,MACT;AAGA,YAAM,cAAc,aAAa,QAAQ,IAAI,WAAW,IAAI;AAE5D,UAAI,eAAe,aAAa,OAAO,cAAc,UAAU;AAC7D;AAAC,QAAC,UAAkB,IAAI,IAAI;AAC5B,eAAO;AAAA,MACT;AAGA,aAAO,QAAQ,IAAI,QAAQ,MAAM,OAAO,QAAQ;AAAA,IAClD;AAAA,EACF;AAGA,SAAO,IAAI,MAAS,cAAc,OAAO;AAC3C;AAEO,MAAM,gBAAgB,OAAO,sBAAsB;AACnD,SAAS,qBAA8C,KAAW;AACvE,MAAK,IAAwD,gBAAgB,GAAG;AAC9E,WAAQ,IAAmC,aAAa;AAAA,EAC1D;AAEA,SAAO;AACT;",
-  "names": []
+  "sourcesContent": ["import { isObject } from '@/helpers/general'\n\nconst isOverridesProxy = Symbol('isOverridesProxy')\nexport const getOverridesTarget = Symbol('getOverridesTarget')\n\n/**\n * Recursively makes all properties of a type optional.\n *\n * - If T is an object, recursively applies DeepPartial to each property, making them optional.\n * - Otherwise, T is returned as-is.\n *\n * @template T - The type to make deeply partial (optional).\n * @example\n * type Example = { a: { b: number } }\n * type PartialExample = DeepPartial<Example>\n * // Result: { a?: { b?: number } }\n */\nexport type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T\n\n/**\n * Creates a proxy object that overlays \"overrides\" on top of a target object.\n *\n * - When reading a property, if an override exists, it is returned; otherwise, the original value is returned.\n * - When writing to a property, if an override exists, it is updated; otherwise, the original object is updated.\n * - This works recursively for nested objects, so overrides can be deeply partial.\n * - Special symbols are used to identify the proxy and to access the original target.\n *\n * @template T - The type of the target object.\n * @param target - The original object to proxy.\n * @param overrides - An optional object containing override values (deeply partial).\n * @returns A proxy object that reflects overrides on top of the target.\n *\n * @example\n * const original = { a: 1, b: { c: 2 } }\n * const overrides = { b: { c: 42 } }\n * const proxy = createOverridesProxy(original, { overrides })\n *\n * console.log(proxy.a) // 1 (from original)\n * console.log(proxy.b.c) // 42 (from overrides)\n *\n * proxy.a = 100\n * console.log(original.a) // 100\n *\n * proxy.b.c = 99\n * console.log(overrides.b.c) // 99\n */\nexport const createOverridesProxy = <T extends Record<string, unknown>>(\n  target: T,\n  options?: {\n    overrides?: DeepPartial<T>\n  },\n  args: {\n    cache: WeakMap<object, any>\n  } = {\n    cache: new WeakMap(),\n  },\n): T => {\n  if (!target || typeof target !== 'object') {\n    return target\n  }\n\n  // Return existing proxy for the same target to ensure referential stability\n  if (args.cache.has(target)) {\n    return args.cache.get(target)!\n  }\n\n  const { overrides } = options ?? {}\n\n  // Proxy handler to intercept get/set operations\n  const handler: ProxyHandler<T> = {\n    get(target, prop, receiver) {\n      // Special symbol to identify this as an overrides proxy\n      if (prop === isOverridesProxy) {\n        return true\n      }\n\n      // Special symbol to access the original target object\n      if (prop === getOverridesTarget) {\n        return target\n      }\n\n      const value = Reflect.get(target, prop, receiver)\n\n      // Return early if the value is already an overrides proxy\n      if (isOverridesProxyObject(value)) {\n        return value\n      }\n\n      // If the value is not an object, return the override if it exists, else the original value\n      if (!isObject(value)) {\n        return Reflect.get(overrides ?? {}, prop) ?? value\n      }\n\n      // For nested objects, recursively create a proxy with the corresponding overrides\n      return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args)\n    },\n\n    set(target, prop, value, receiver) {\n      // Prevent setting special symbols\n      if (prop === isOverridesProxy || prop === getOverridesTarget) {\n        return false\n      }\n\n      // If an override exists for this property, update it\n      const hasOverride = overrides && Reflect.has(overrides, prop)\n\n      if (hasOverride && overrides && typeof overrides === 'object') {\n        ;(overrides as any)[prop] = value\n        return true\n      }\n\n      // Otherwise, update the original target\n      return Reflect.set(target, prop, value, receiver)\n    },\n  }\n\n  // Return the proxy object\n  const proxy = new Proxy<T>(target, handler)\n  args.cache.set(target, proxy)\n  return proxy\n}\n\nexport const isOverridesProxyObject = (obj: unknown): boolean => {\n  return typeof obj === 'object' && obj !== null && (obj as { [isOverridesProxy]: boolean })[isOverridesProxy] === true\n}\n\n/**\n * Unpacks an object from the overrides proxy, returning the original (unproxied) target object.\n * If the input is not an overrides proxy, returns the object as-is.\n *\n * @param input - The potentially proxied object\n * @returns The original unproxied target object or the input object\n */\nexport function unpackOverridesProxy<T>(input: T): T {\n  if ((input as T & { [isOverridesProxy]: boolean | undefined })[isOverridesProxy]) {\n    return (input as T & { [getOverridesTarget]: T })[getOverridesTarget]\n  }\n\n  return input\n}\n"],
+  "mappings": "AAAA,SAAS,gBAAgB;AAEzB,MAAM,mBAAmB,OAAO,kBAAkB;AAC3C,MAAM,qBAAqB,OAAO,oBAAoB;AA2CtD,MAAM,uBAAuB,CAClC,QACA,SAGA,OAEI;AAAA,EACF,OAAO,oBAAI,QAAQ;AACrB,MACM;AACN,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,WAAO;AAAA,EACT;AAGA,MAAI,KAAK,MAAM,IAAI,MAAM,GAAG;AAC1B,WAAO,KAAK,MAAM,IAAI,MAAM;AAAA,EAC9B;AAEA,QAAM,EAAE,UAAU,IAAI,WAAW,CAAC;AAGlC,QAAM,UAA2B;AAAA,IAC/B,IAAIA,SAAQ,MAAM,UAAU;AAE1B,UAAI,SAAS,kBAAkB;AAC7B,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,oBAAoB;AAC/B,eAAOA;AAAA,MACT;AAEA,YAAM,QAAQ,QAAQ,IAAIA,SAAQ,MAAM,QAAQ;AAGhD,UAAI,uBAAuB,KAAK,GAAG;AACjC,eAAO;AAAA,MACT;AAGA,UAAI,CAAC,SAAS,KAAK,GAAG;AACpB,eAAO,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,KAAK;AAAA,MAC/C;AAGA,aAAO,qBAAqB,OAAO,EAAE,WAAW,QAAQ,IAAI,aAAa,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI;AAAA,IAC5F;AAAA,IAEA,IAAIA,SAAQ,MAAM,OAAO,UAAU;AAEjC,UAAI,SAAS,oBAAoB,SAAS,oBAAoB;AAC5D,eAAO;AAAA,MACT;AAGA,YAAM,cAAc,aAAa,QAAQ,IAAI,WAAW,IAAI;AAE5D,UAAI,eAAe,aAAa,OAAO,cAAc,UAAU;AAC7D;AAAC,QAAC,UAAkB,IAAI,IAAI;AAC5B,eAAO;AAAA,MACT;AAGA,aAAO,QAAQ,IAAIA,SAAQ,MAAM,OAAO,QAAQ;AAAA,IAClD;AAAA,EACF;AAGA,QAAM,QAAQ,IAAI,MAAS,QAAQ,OAAO;AAC1C,OAAK,MAAM,IAAI,QAAQ,KAAK;AAC5B,SAAO;AACT;AAEO,MAAM,yBAAyB,CAAC,QAA0B;AAC/D,SAAO,OAAO,QAAQ,YAAY,QAAQ,QAAS,IAAwC,gBAAgB,MAAM;AACnH;AASO,SAAS,qBAAwB,OAAa;AACnD,MAAK,MAA0D,gBAAgB,GAAG;AAChF,WAAQ,MAA0C,kBAAkB;AAAA,EACtE;AAEA,SAAO;AACT;",
+  "names": ["target"]
 }

package/dist/helpers/unpack-proxy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,
+ * returning the "raw" plain object or array.
+ */
+export declare const unpackProxyObject: <T extends object | Array<unknown>>(input: T) => T;
+//# sourceMappingURL=unpack-proxy.d.ts.map

package/dist/helpers/unpack-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/unpack-proxy.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,KAAG,CACV,CAAA"}

package/dist/helpers/unpack-proxy.js

@@ -0,0 +1,9 @@
+import { getRaw } from "@scalar/json-magic/magic-proxy";
+import { toRaw } from "vue";
+import { unpackDetectChangesProxy } from "../helpers/detect-changes-proxy.js";
+import { unpackOverridesProxy } from "../helpers/overrides-proxy.js";
+const unpackProxyObject = (input) => unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(input))));
+export {
+  unpackProxyObject
+};
+//# sourceMappingURL=unpack-proxy.js.map

package/dist/helpers/unpack-proxy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/helpers/unpack-proxy.ts"],
+  "sourcesContent": ["import { getRaw } from '@scalar/json-magic/magic-proxy'\nimport { toRaw } from 'vue'\n\nimport { unpackDetectChangesProxy } from '@/helpers/detect-changes-proxy'\nimport { unpackOverridesProxy } from '@/helpers/overrides-proxy'\n\n/**\n * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,\n * returning the \"raw\" plain object or array.\n */\nexport const unpackProxyObject = <T extends object | Array<unknown>>(input: T): T =>\n  unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(input))))\n"],
+  "mappings": "AAAA,SAAS,cAAc;AACvB,SAAS,aAAa;AAEtB,SAAS,gCAAgC;AACzC,SAAS,4BAA4B;AAM9B,MAAM,oBAAoB,CAAoC,UACnE,yBAAyB,MAAM,OAAO,qBAAqB,KAAK,CAAC,CAAC,CAAC;",
+  "names": []
+}

package/dist/navigation/get-navigation-options.d.ts

@@ -5,5 +5,5 @@ import type { DocumentConfiguration } from '../schemas/workspace-specification/c
  * how IDs and slugs are generated for tags, headings, models, operations, and webhooks.
  * The returned options can be influenced by the provided DocumentConfiguration
  */
-export declare const getNavigationOptions: (config?: DocumentConfiguration) => TraverseSpecOptions;
+export declare const getNavigationOptions: (documentName: string, config?: DocumentConfiguration) => TraverseSpecOptions;
 //# sourceMappingURL=get-navigation-options.d.ts.map

package/dist/navigation/get-navigation-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-navigation-options.d.ts","sourceRoot":"","sources":["../../src/navigation/get-navigation-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAA;AAErF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,qBAAqB,KAAG,mBAsHrE,CAAA"}
+{"version":3,"file":"get-navigation-options.d.ts","sourceRoot":"","sources":["../../src/navigation/get-navigation-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAE7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAA;AAErF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,MAAM,EAAE,SAAS,qBAAqB,KAAG,mBAkH3F,CAAA"}

package/dist/navigation/get-navigation-options.js

@@ -1,62 +1,78 @@
 import { slug } from "github-slugger";
-const getNavigationOptions = (config) => {
+const getNavigationOptions = (documentName, config) => {
   const referenceConfig = config?.["x-scalar-reference-config"];
-  const getTagIdDefault = (tag) => {
-    const generateTagSlug = referenceConfig?.generateTagSlug;
-    if (generateTagSlug) {
-      return `tag/${generateTagSlug(tag)}`;
+  const generateId = (props) => {
+    const documentId = `${slug(documentName)}`;
+    if (props.type === "text") {
+      if (referenceConfig?.generateHeadingSlug) {
+        return referenceConfig?.generateHeadingSlug({ slug: props.slug });
+      }
+      if (props.slug) {
+        return `${documentId}/description/${props.slug}`;
+      }
+      return `${documentId}/`;
     }
-    return `tag/${slug(tag.name ?? "")}`;
-  };
-  const getHeadingIdDefault = (heading) => {
-    const generateHeadingSlug = referenceConfig?.generateHeadingSlug;
-    if (generateHeadingSlug) {
-      return `${generateHeadingSlug(heading)}`;
+    if (props.type === "tag") {
+      if (referenceConfig?.generateTagSlug) {
+        return `${documentId}/tag/${referenceConfig.generateTagSlug(props.tag)}`;
+      }
+      return `${documentId}/tag/${slug(props.tag.name ?? "")}`;
     }
-    if (heading.slug) {
-      return `description/${heading.slug}`;
+    if (props.type === "operation") {
+      const tagId = `${generateId({
+        type: "tag",
+        tag: props.parentTag.tag,
+        parentId: props.parentTag.id
+      })}`;
+      if (referenceConfig?.generateOperationSlug) {
+        return `${tagId}/${referenceConfig.generateOperationSlug({
+          path: props.path,
+          operationId: props.operation.operationId,
+          method: props.method,
+          summary: props.operation.summary
+        })}`;
+      }
+      return `${tagId}/${props.method}${props.path}`;
     }
-    return "";
-  };
-  const getModelIdDefault = (model, parentTag) => {
-    const generateModelSlug = referenceConfig?.generateModelSlug;
-    if (!model?.name) {
-      return "models";
+    if (props.type === "webhook") {
+      const prefixTag = props.parentTag ? `${generateId({
+        type: "tag",
+        parentId: props.parentTag.id,
+        tag: props.parentTag.tag
+      })}/` : `${documentId}/`;
+      if (referenceConfig?.generateWebhookSlug) {
+        return `${prefixTag}webhook/${referenceConfig.generateWebhookSlug({
+          name: props.name,
+          method: props.method
+        })}`;
+      }
+      return `${prefixTag}webhook/${props.method}/${slug(props.name)}`;
     }
-    const prefixTag = parentTag ? `${getTagId(parentTag)}/` : "";
-    if (generateModelSlug) {
-      return `${prefixTag}model/${generateModelSlug(model)}`;
+    if (props.type === "model") {
+      if (!props.name) {
+        return `${documentId}/models`;
+      }
+      const prefixTag = props.parentTag ? `${generateId({
+        type: "tag",
+        parentId: props.parentTag.id,
+        tag: props.parentTag.tag
+      })}/` : `${documentId}/`;
+      if (referenceConfig?.generateModelSlug) {
+        return `${prefixTag}model/${referenceConfig.generateModelSlug({
+          name: props.name
+        })}`;
+      }
+      return `${prefixTag}model/${slug(props.name)}`;
     }
-    return `${prefixTag}model/${slug(model.name)}`;
-  };
-  const getOperationIdDefault = (operation, parentTag) => {
-    const generateOperationSlug = referenceConfig?.generateOperationSlug;
-    if (generateOperationSlug) {
-      return `${getTagId(parentTag)}/${generateOperationSlug({
-        path: operation.path,
-        operationId: operation.operationId,
-        method: operation.method,
-        summary: operation.summary
-      })}`;
-    }
-    return `${getTagId(parentTag)}/${operation.method}${operation.path}`;
-  };
-  const getWebhookIdDefault = (webhook, parentTag) => {
-    const generateWebhookSlug = referenceConfig?.generateWebhookSlug;
-    if (!webhook?.name) {
-      return "webhooks";
+    if (props.type === "example") {
+      return `${props.parentId}/example/${slug(props.name)}`;
     }
-    const prefixTag = parentTag ? `${getTagId(parentTag)}/` : "";
-    if (generateWebhookSlug) {
-      return `${prefixTag}webhook/${generateWebhookSlug(webhook)}`;
+    if (props.type === "document") {
+      return documentId;
     }
-    return `${prefixTag}webhook/${webhook.method}/${slug(webhook.name)}`;
+    console.warn("[WARNING]: unhandled id generation for navigation item:", props);
+    return "unknown-id";
   };
-  const getHeadingId = referenceConfig?.getHeadingId ?? getHeadingIdDefault;
-  const getModelId = referenceConfig?.getModelId ?? getModelIdDefault;
-  const getOperationId = referenceConfig?.getOperationId ?? getOperationIdDefault;
-  const getWebhookId = referenceConfig?.getWebhookId ?? getWebhookIdDefault;
-  const getTagId = referenceConfig?.getTagId ?? getTagIdDefault;
   const hideModels = referenceConfig?.features?.showModels === false;
   const operationsSorter = referenceConfig?.operationsSorter;
   const tagsSorter = referenceConfig?.tagSort;
@@ -64,11 +80,7 @@ const getNavigationOptions = (config) => {
     hideModels,
     operationsSorter,
     tagsSorter,
-    getHeadingId,
-    getModelId,
-    getOperationId,
-    getWebhookId,
-    getTagId
+    generateId
   };
 };
 export {

package/dist/navigation/get-navigation-options.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/navigation/get-navigation-options.ts"],
-  "sourcesContent": ["import { slug } from 'github-slugger'\n\nimport type { TraverseSpecOptions } from '@/navigation/types'\nimport type { DocumentConfiguration } from '@/schemas/workspace-specification/config'\n\n/**\n * Returns options for traversing an OpenAPI document, allowing customization of\n * how IDs and slugs are generated for tags, headings, models, operations, and webhooks.\n * The returned options can be influenced by the provided DocumentConfiguration\n */\nexport const getNavigationOptions = (config?: DocumentConfiguration): TraverseSpecOptions => {\n  const referenceConfig = config?.['x-scalar-reference-config']\n\n  /**\n   * Generate a tag id.\n   * If a custom generateTagSlug function is provided in the referenceConfig, use it to generate the tag slug.\n   * Otherwise, fall back to using the default slug function from 'github-slugger' on the tag name.\n   */\n  const getTagIdDefault: TraverseSpecOptions['getTagId'] = (tag) => {\n    const generateTagSlug = referenceConfig?.generateTagSlug\n    if (generateTagSlug) {\n      return `tag/${generateTagSlug(tag)}`\n    }\n    return `tag/${slug(tag.name ?? '')}`\n  }\n\n  /**\n   * Generate a heading id.\n   * If a custom generateHeadingSlug function is provided in the referenceConfig, use it to generate the heading slug.\n   * Otherwise, if the heading has a slug property, prefix it with 'description/'.\n   * If neither is available, return an empty string.\n   */\n  const getHeadingIdDefault: TraverseSpecOptions['getHeadingId'] = (heading) => {\n    const generateHeadingSlug = referenceConfig?.generateHeadingSlug\n\n    if (generateHeadingSlug) {\n      return `${generateHeadingSlug(heading)}`\n    }\n\n    if (heading.slug) {\n      return `description/${heading.slug}`\n    }\n    return ''\n  }\n\n  /**\n   * Generate a model id.\n   * If a custom generateModelSlug function is provided in the referenceConfig, use it to generate the model slug.\n   * If the model does not have a name, return 'models'.\n   * Otherwise, prefix with the tag (if provided) and use the default slug function from 'github-slugger' on the model name.\n   */\n  const getModelIdDefault: TraverseSpecOptions['getModelId'] = (model, parentTag) => {\n    const generateModelSlug = referenceConfig?.generateModelSlug\n\n    if (!model?.name) {\n      return 'models'\n    }\n\n    // Prefix with the tag if we have one\n    const prefixTag = parentTag ? `${getTagId(parentTag)}/` : ''\n\n    if (generateModelSlug) {\n      return `${prefixTag}model/${generateModelSlug(model)}`\n    }\n    return `${prefixTag}model/${slug(model.name)}`\n  }\n\n  /**\n   * Generate an operation id.\n   * If a custom generateOperationSlug function is provided in the referenceConfig, use it to generate the operation slug.\n   * Otherwise, use the default format: <tagId>/<method><path>\n   */\n  const getOperationIdDefault: TraverseSpecOptions['getOperationId'] = (operation, parentTag) => {\n    const generateOperationSlug = referenceConfig?.generateOperationSlug\n    if (generateOperationSlug) {\n      return `${getTagId(parentTag)}/${generateOperationSlug({\n        path: operation.path,\n        operationId: operation.operationId,\n        method: operation.method,\n        summary: operation.summary,\n      })}`\n    }\n\n    return `${getTagId(parentTag)}/${operation.method}${operation.path}`\n  }\n\n  /**\n   * Generate a webhook id.\n   * If a custom generateWebhookSlug function is provided in the referenceConfig, use it to generate the webhook slug.\n   * If the webhook does not have a name, return 'webhooks'.\n   * Otherwise, prefix with the tag (if provided) and use the default slug function from 'github-slugger' on the webhook name.\n   */\n  const getWebhookIdDefault: TraverseSpecOptions['getWebhookId'] = (webhook, parentTag) => {\n    const generateWebhookSlug = referenceConfig?.generateWebhookSlug\n\n    if (!webhook?.name) {\n      return 'webhooks'\n    }\n\n    // Prefix with the tag if we have one\n    const prefixTag = parentTag ? `${getTagId(parentTag)}/` : ''\n\n    if (generateWebhookSlug) {\n      return `${prefixTag}webhook/${generateWebhookSlug(webhook)}`\n    }\n    return `${prefixTag}webhook/${webhook.method}/${slug(webhook.name)}`\n  }\n\n  const getHeadingId = referenceConfig?.getHeadingId ?? getHeadingIdDefault\n  const getModelId = referenceConfig?.getModelId ?? getModelIdDefault\n  const getOperationId = referenceConfig?.getOperationId ?? getOperationIdDefault\n  const getWebhookId = referenceConfig?.getWebhookId ?? getWebhookIdDefault\n  const getTagId = referenceConfig?.getTagId ?? getTagIdDefault\n\n  const hideModels = referenceConfig?.features?.showModels === false\n  const operationsSorter: TraverseSpecOptions['operationsSorter'] = referenceConfig?.operationsSorter\n  const tagsSorter: TraverseSpecOptions['tagsSorter'] = referenceConfig?.tagSort\n\n  return {\n    hideModels,\n    operationsSorter,\n    tagsSorter,\n    getHeadingId,\n    getModelId,\n    getOperationId,\n    getWebhookId,\n    getTagId,\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,YAAY;AAUd,MAAM,uBAAuB,CAAC,WAAwD;AAC3F,QAAM,kBAAkB,SAAS,2BAA2B;AAO5D,QAAM,kBAAmD,CAAC,QAAQ;AAChE,UAAM,kBAAkB,iBAAiB;AACzC,QAAI,iBAAiB;AACnB,aAAO,OAAO,gBAAgB,GAAG,CAAC;AAAA,IACpC;AACA,WAAO,OAAO,KAAK,IAAI,QAAQ,EAAE,CAAC;AAAA,EACpC;AAQA,QAAM,sBAA2D,CAAC,YAAY;AAC5E,UAAM,sBAAsB,iBAAiB;AAE7C,QAAI,qBAAqB;AACvB,aAAO,GAAG,oBAAoB,OAAO,CAAC;AAAA,IACxC;AAEA,QAAI,QAAQ,MAAM;AAChB,aAAO,eAAe,QAAQ,IAAI;AAAA,IACpC;AACA,WAAO;AAAA,EACT;AAQA,QAAM,oBAAuD,CAAC,OAAO,cAAc;AACjF,UAAM,oBAAoB,iBAAiB;AAE3C,QAAI,CAAC,OAAO,MAAM;AAChB,aAAO;AAAA,IACT;AAGA,UAAM,YAAY,YAAY,GAAG,SAAS,SAAS,CAAC,MAAM;AAE1D,QAAI,mBAAmB;AACrB,aAAO,GAAG,SAAS,SAAS,kBAAkB,KAAK,CAAC;AAAA,IACtD;AACA,WAAO,GAAG,SAAS,SAAS,KAAK,MAAM,IAAI,CAAC;AAAA,EAC9C;AAOA,QAAM,wBAA+D,CAAC,WAAW,cAAc;AAC7F,UAAM,wBAAwB,iBAAiB;AAC/C,QAAI,uBAAuB;AACzB,aAAO,GAAG,SAAS,SAAS,CAAC,IAAI,sBAAsB;AAAA,QACrD,MAAM,UAAU;AAAA,QAChB,aAAa,UAAU;AAAA,QACvB,QAAQ,UAAU;AAAA,QAClB,SAAS,UAAU;AAAA,MACrB,CAAC,CAAC;AAAA,IACJ;AAEA,WAAO,GAAG,SAAS,SAAS,CAAC,IAAI,UAAU,MAAM,GAAG,UAAU,IAAI;AAAA,EACpE;AAQA,QAAM,sBAA2D,CAAC,SAAS,cAAc;AACvF,UAAM,sBAAsB,iBAAiB;AAE7C,QAAI,CAAC,SAAS,MAAM;AAClB,aAAO;AAAA,IACT;AAGA,UAAM,YAAY,YAAY,GAAG,SAAS,SAAS,CAAC,MAAM;AAE1D,QAAI,qBAAqB;AACvB,aAAO,GAAG,SAAS,WAAW,oBAAoB,OAAO,CAAC;AAAA,IAC5D;AACA,WAAO,GAAG,SAAS,WAAW,QAAQ,MAAM,IAAI,KAAK,QAAQ,IAAI,CAAC;AAAA,EACpE;AAEA,QAAM,eAAe,iBAAiB,gBAAgB;AACtD,QAAM,aAAa,iBAAiB,cAAc;AAClD,QAAM,iBAAiB,iBAAiB,kBAAkB;AAC1D,QAAM,eAAe,iBAAiB,gBAAgB;AACtD,QAAM,WAAW,iBAAiB,YAAY;AAE9C,QAAM,aAAa,iBAAiB,UAAU,eAAe;AAC7D,QAAM,mBAA4D,iBAAiB;AACnF,QAAM,aAAgD,iBAAiB;AAEvE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
+  "sourcesContent": ["import { slug } from 'github-slugger'\n\nimport type { TraverseSpecOptions } from '@/navigation/types'\nimport type { IdGenerator } from '@/schemas/navigation'\nimport type { DocumentConfiguration } from '@/schemas/workspace-specification/config'\n\n/**\n * Returns options for traversing an OpenAPI document, allowing customization of\n * how IDs and slugs are generated for tags, headings, models, operations, and webhooks.\n * The returned options can be influenced by the provided DocumentConfiguration\n */\nexport const getNavigationOptions = (documentName: string, config?: DocumentConfiguration): TraverseSpecOptions => {\n  const referenceConfig = config?.['x-scalar-reference-config']\n\n  const generateId: IdGenerator = (props) => {\n    const documentId = `${slug(documentName)}`\n\n    // -------- Default text id generation logic --------\n    if (props.type === 'text') {\n      if (referenceConfig?.generateHeadingSlug) {\n        return referenceConfig?.generateHeadingSlug({ slug: props.slug })\n      }\n\n      if (props.slug) {\n        return `${documentId}/description/${props.slug}`\n      }\n\n      return `${documentId}/`\n    }\n\n    // -------- Default tag id generation logic --------\n    if (props.type === 'tag') {\n      if (referenceConfig?.generateTagSlug) {\n        return `${documentId}/tag/${referenceConfig.generateTagSlug(props.tag)}`\n      }\n\n      return `${documentId}/tag/${slug(props.tag.name ?? '')}`\n    }\n\n    // -------- Default operation id generation logic --------\n    if (props.type === 'operation') {\n      const tagId = `${generateId({\n        type: 'tag',\n        tag: props.parentTag.tag,\n        parentId: props.parentTag.id,\n      })}`\n\n      if (referenceConfig?.generateOperationSlug) {\n        return `${tagId}/${referenceConfig.generateOperationSlug({\n          path: props.path,\n          operationId: props.operation.operationId,\n          method: props.method,\n          summary: props.operation.summary,\n        })}`\n      }\n\n      return `${tagId}/${props.method}${props.path}`\n    }\n\n    // -------- Default webhook id generation logic --------\n    if (props.type === 'webhook') {\n      const prefixTag = props.parentTag\n        ? `${generateId({\n            type: 'tag',\n            parentId: props.parentTag.id,\n            tag: props.parentTag.tag,\n          })}/`\n        : `${documentId}/`\n\n      if (referenceConfig?.generateWebhookSlug) {\n        return `${prefixTag}webhook/${referenceConfig.generateWebhookSlug({\n          name: props.name,\n          method: props.method,\n        })}`\n      }\n\n      return `${prefixTag}webhook/${props.method}/${slug(props.name)}`\n    }\n\n    // -------- Default model id generation logic --------\n    if (props.type === 'model') {\n      if (!props.name) {\n        return `${documentId}/models`\n      }\n\n      const prefixTag = props.parentTag\n        ? `${generateId({\n            type: 'tag',\n            parentId: props.parentTag.id,\n            tag: props.parentTag.tag,\n          })}/`\n        : `${documentId}/`\n\n      if (referenceConfig?.generateModelSlug) {\n        return `${prefixTag}model/${referenceConfig.generateModelSlug({\n          name: props.name,\n        })}`\n      }\n\n      return `${prefixTag}model/${slug(props.name)}`\n    }\n\n    if (props.type === 'example') {\n      return `${props.parentId}/example/${slug(props.name)}`\n    }\n\n    if (props.type === 'document') {\n      // -------- Default document id generation logic --------\n      return documentId\n    }\n\n    console.warn('[WARNING]: unhandled id generation for navigation item:', props)\n    return 'unknown-id'\n  }\n\n  const hideModels = referenceConfig?.features?.showModels === false\n  const operationsSorter: TraverseSpecOptions['operationsSorter'] = referenceConfig?.operationsSorter\n  const tagsSorter: TraverseSpecOptions['tagsSorter'] = referenceConfig?.tagSort\n\n  return {\n    hideModels,\n    operationsSorter,\n    tagsSorter,\n    generateId,\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,YAAY;AAWd,MAAM,uBAAuB,CAAC,cAAsB,WAAwD;AACjH,QAAM,kBAAkB,SAAS,2BAA2B;AAE5D,QAAM,aAA0B,CAAC,UAAU;AACzC,UAAM,aAAa,GAAG,KAAK,YAAY,CAAC;AAGxC,QAAI,MAAM,SAAS,QAAQ;AACzB,UAAI,iBAAiB,qBAAqB;AACxC,eAAO,iBAAiB,oBAAoB,EAAE,MAAM,MAAM,KAAK,CAAC;AAAA,MAClE;AAEA,UAAI,MAAM,MAAM;AACd,eAAO,GAAG,UAAU,gBAAgB,MAAM,IAAI;AAAA,MAChD;AAEA,aAAO,GAAG,UAAU;AAAA,IACtB;AAGA,QAAI,MAAM,SAAS,OAAO;AACxB,UAAI,iBAAiB,iBAAiB;AACpC,eAAO,GAAG,UAAU,QAAQ,gBAAgB,gBAAgB,MAAM,GAAG,CAAC;AAAA,MACxE;AAEA,aAAO,GAAG,UAAU,QAAQ,KAAK,MAAM,IAAI,QAAQ,EAAE,CAAC;AAAA,IACxD;AAGA,QAAI,MAAM,SAAS,aAAa;AAC9B,YAAM,QAAQ,GAAG,WAAW;AAAA,QAC1B,MAAM;AAAA,QACN,KAAK,MAAM,UAAU;AAAA,QACrB,UAAU,MAAM,UAAU;AAAA,MAC5B,CAAC,CAAC;AAEF,UAAI,iBAAiB,uBAAuB;AAC1C,eAAO,GAAG,KAAK,IAAI,gBAAgB,sBAAsB;AAAA,UACvD,MAAM,MAAM;AAAA,UACZ,aAAa,MAAM,UAAU;AAAA,UAC7B,QAAQ,MAAM;AAAA,UACd,SAAS,MAAM,UAAU;AAAA,QAC3B,CAAC,CAAC;AAAA,MACJ;AAEA,aAAO,GAAG,KAAK,IAAI,MAAM,MAAM,GAAG,MAAM,IAAI;AAAA,IAC9C;AAGA,QAAI,MAAM,SAAS,WAAW;AAC5B,YAAM,YAAY,MAAM,YACpB,GAAG,WAAW;AAAA,QACZ,MAAM;AAAA,QACN,UAAU,MAAM,UAAU;AAAA,QAC1B,KAAK,MAAM,UAAU;AAAA,MACvB,CAAC,CAAC,MACF,GAAG,UAAU;AAEjB,UAAI,iBAAiB,qBAAqB;AACxC,eAAO,GAAG,SAAS,WAAW,gBAAgB,oBAAoB;AAAA,UAChE,MAAM,MAAM;AAAA,UACZ,QAAQ,MAAM;AAAA,QAChB,CAAC,CAAC;AAAA,MACJ;AAEA,aAAO,GAAG,SAAS,WAAW,MAAM,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;AAAA,IAChE;AAGA,QAAI,MAAM,SAAS,SAAS;AAC1B,UAAI,CAAC,MAAM,MAAM;AACf,eAAO,GAAG,UAAU;AAAA,MACtB;AAEA,YAAM,YAAY,MAAM,YACpB,GAAG,WAAW;AAAA,QACZ,MAAM;AAAA,QACN,UAAU,MAAM,UAAU;AAAA,QAC1B,KAAK,MAAM,UAAU;AAAA,MACvB,CAAC,CAAC,MACF,GAAG,UAAU;AAEjB,UAAI,iBAAiB,mBAAmB;AACtC,eAAO,GAAG,SAAS,SAAS,gBAAgB,kBAAkB;AAAA,UAC5D,MAAM,MAAM;AAAA,QACd,CAAC,CAAC;AAAA,MACJ;AAEA,aAAO,GAAG,SAAS,SAAS,KAAK,MAAM,IAAI,CAAC;AAAA,IAC9C;AAEA,QAAI,MAAM,SAAS,WAAW;AAC5B,aAAO,GAAG,MAAM,QAAQ,YAAY,KAAK,MAAM,IAAI,CAAC;AAAA,IACtD;AAEA,QAAI,MAAM,SAAS,YAAY;AAE7B,aAAO;AAAA,IACT;AAEA,YAAQ,KAAK,2DAA2D,KAAK;AAC7E,WAAO;AAAA,EACT;AAEA,QAAM,aAAa,iBAAiB,UAAU,eAAe;AAC7D,QAAM,mBAA4D,iBAAiB;AACnF,QAAM,aAAgD,iBAAiB;AAEvE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
   "names": []
 }

package/dist/navigation/helpers/get-tag.d.ts

@@ -1,4 +1,4 @@
-import type { TagsMap } from '../../navigation/types.js';
+import type { TagsMap, TraverseSpecOptions } from '../../navigation/types.js';
 type TagMapValue = NonNullable<TagsMap extends Map<string, infer V> ? V : never>;
 /**
  * Gets or creates a tag in the tags dictionary.
@@ -8,6 +8,11 @@ type TagMapValue = NonNullable<TagsMap extends Map<string, infer V> ? V : never>
  * @param name - Name of the tag to get or create
  * @returns The tag object for the given name
  */
-export declare const getTag: (tagsMap: TagsMap, name: string) => TagMapValue;
+export declare const getTag: ({ tagsMap, name, documentId, generateId, }: {
+    tagsMap: TagsMap;
+    name: string;
+    documentId: string;
+    generateId: TraverseSpecOptions["generateId"];
+}) => TagMapValue;
 export {};
 //# sourceMappingURL=get-tag.d.ts.map

package/dist/navigation/helpers/get-tag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-tag.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/get-tag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAEjD,KAAK,WAAW,GAAG,WAAW,CAAC,OAAO,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,SAAS,OAAO,EAAE,MAAM,MAAM,KAAG,WAMvD,CAAA"}
+{"version":3,"file":"get-tag.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/get-tag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAEtE,KAAK,WAAW,GAAG,WAAW,CAAC,OAAO,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,4CAKpB;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;CAC9C,KAAG,WAeH,CAAA"}

package/dist/navigation/helpers/get-tag.js

@@ -1,6 +1,20 @@
-const getTag = (tagsMap, name) => {
+const getTag = ({
+  tagsMap,
+  name,
+  documentId,
+  generateId
+}) => {
   if (!tagsMap.get(name)) {
-    tagsMap.set(name, { entries: [], tag: { name } });
+    tagsMap.set(name, {
+      id: generateId({
+        type: "tag",
+        tag: { name },
+        parentId: documentId
+      }),
+      parentId: documentId,
+      entries: [],
+      tag: { name }
+    });
   }
   return tagsMap.get(name);
 };

package/dist/navigation/helpers/get-tag.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/navigation/helpers/get-tag.ts"],
-  "sourcesContent": ["import type { TagsMap } from '@/navigation/types'\n\ntype TagMapValue = NonNullable<TagsMap extends Map<string, infer V> ? V : never>\n\n/**\n * Gets or creates a tag in the tags dictionary.\n * If the tag doesn't exist, it creates a new tag object with the given name.\n *\n * @param tagsDict - Map of tag names to tag objects\n * @param name - Name of the tag to get or create\n * @returns The tag object for the given name\n */\nexport const getTag = (tagsMap: TagsMap, name: string): TagMapValue => {\n  if (!tagsMap.get(name)) {\n    tagsMap.set(name, { entries: [], tag: { name } })\n  }\n\n  return tagsMap.get(name)! // We can safely assert non-null since we just set the value if it didn't exist\n}\n"],
-  "mappings": "AAYO,MAAM,SAAS,CAAC,SAAkB,SAA8B;AACrE,MAAI,CAAC,QAAQ,IAAI,IAAI,GAAG;AACtB,YAAQ,IAAI,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC;AAAA,EAClD;AAEA,SAAO,QAAQ,IAAI,IAAI;AACzB;",
+  "sourcesContent": ["import type { TagsMap, TraverseSpecOptions } from '@/navigation/types'\n\ntype TagMapValue = NonNullable<TagsMap extends Map<string, infer V> ? V : never>\n\n/**\n * Gets or creates a tag in the tags dictionary.\n * If the tag doesn't exist, it creates a new tag object with the given name.\n *\n * @param tagsDict - Map of tag names to tag objects\n * @param name - Name of the tag to get or create\n * @returns The tag object for the given name\n */\nexport const getTag = ({\n  tagsMap,\n  name,\n  documentId,\n  generateId,\n}: {\n  tagsMap: TagsMap\n  name: string\n  documentId: string\n  generateId: TraverseSpecOptions['generateId']\n}): TagMapValue => {\n  if (!tagsMap.get(name)) {\n    tagsMap.set(name, {\n      id: generateId({\n        type: 'tag',\n        tag: { name },\n        parentId: documentId,\n      }),\n      parentId: documentId,\n      entries: [],\n      tag: { name },\n    })\n  }\n\n  return tagsMap.get(name)! // We can safely assert non-null since we just set the value if it didn't exist\n}\n"],
+  "mappings": "AAYO,MAAM,SAAS,CAAC;AAAA,EACrB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAKmB;AACjB,MAAI,CAAC,QAAQ,IAAI,IAAI,GAAG;AACtB,YAAQ,IAAI,MAAM;AAAA,MAChB,IAAI,WAAW;AAAA,QACb,MAAM;AAAA,QACN,KAAK,EAAE,KAAK;AAAA,QACZ,UAAU;AAAA,MACZ,CAAC;AAAA,MACD,UAAU;AAAA,MACV,SAAS,CAAC;AAAA,MACV,KAAK,EAAE,KAAK;AAAA,IACd,CAAC;AAAA,EACH;AAEA,SAAO,QAAQ,IAAI,IAAI;AACzB;",
   "names": []
 }

package/dist/navigation/helpers/traverse-description.d.ts

@@ -1,5 +1,6 @@
-import type { Heading } from '../../navigation/types.js';
+import type { TraverseSpecOptions } from '../../navigation/types.js';
 import type { TraversedDescription } from '../../schemas/navigation.js';
+import type { InfoObject } from '../../schemas/v3.1/strict/info.js';
 export declare const DEFAULT_INTRODUCTION_SLUG = "introduction";
 /**
  * Creates a hierarchical navigation structure from markdown headings in an OpenAPI description.
@@ -16,5 +17,9 @@ export declare const DEFAULT_INTRODUCTION_SLUG = "introduction";
  * @param getHeadingId - Function to generate unique IDs for headings
  * @returns Array of navigation entries with their hierarchy
  */
-export declare const traverseDescription: (description: string | undefined, getHeadingId: (heading: Heading) => string) => TraversedDescription[];
+export declare const traverseDescription: ({ generateId, parentId, info, }: {
+    generateId: TraverseSpecOptions["generateId"];
+    parentId: string;
+    info: InfoObject;
+}) => TraversedDescription[];
 //# sourceMappingURL=traverse-description.d.ts.map

package/dist/navigation/helpers/traverse-description.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traverse-description.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-description.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhE,eAAO,MAAM,yBAAyB,iBAAiB,CAAA;AAEvD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,MAAM,GAAG,SAAS,EAC/B,cAAc,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,KACzC,oBAAoB,EAsDtB,CAAA"}
+{"version":3,"file":"traverse-description.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-description.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAE5D,eAAO,MAAM,yBAAyB,iBAAiB,CAAA;AAEvD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,iCAIjC;IACD,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,UAAU,CAAA;CACjB,KAAG,oBAAoB,EAoEvB,CAAA"}

package/dist/navigation/helpers/traverse-description.js

@@ -1,20 +1,31 @@
 import { getHeadingsFromMarkdown, getLowestHeadingLevel } from "../../navigation/helpers/utils.js";
 const DEFAULT_INTRODUCTION_SLUG = "introduction";
-const traverseDescription = (description, getHeadingId) => {
-  if (!description?.trim()) {
+const traverseDescription = ({
+  generateId,
+  parentId,
+  info
+}) => {
+  if (!info.description?.trim()) {
     return [];
   }
-  const headings = getHeadingsFromMarkdown(description);
+  const headings = getHeadingsFromMarkdown(info.description);
   const lowestLevel = getLowestHeadingLevel(headings);
   const entries = [];
   let currentParent = null;
-  if (description && !description.trim().startsWith("#")) {
+  if (info.description && !info.description.trim().startsWith("#")) {
     const heading = {
       depth: 1,
       value: "Introduction",
       slug: DEFAULT_INTRODUCTION_SLUG
     };
-    const id = getHeadingId(heading);
+    const id = generateId({
+      type: "text",
+      depth: heading.depth,
+      slug: heading.slug,
+      parentId,
+      info,
+      value: heading.value
+    });
     const title = heading.value;
     const entry = {
       id,
@@ -28,7 +39,14 @@ const traverseDescription = (description, getHeadingId) => {
       continue;
     }
     const entry = {
-      id: getHeadingId(heading),
+      id: generateId({
+        type: "text",
+        depth: heading.depth,
+        slug: heading.slug,
+        parentId,
+        info,
+        value: heading.value
+      }),
       title: heading.value,
       type: "text"
     };

package/dist/navigation/helpers/traverse-description.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/navigation/helpers/traverse-description.ts"],
-  "sourcesContent": ["import { getHeadingsFromMarkdown, getLowestHeadingLevel } from '@/navigation/helpers/utils'\nimport type { Heading } from '@/navigation/types'\nimport type { TraversedDescription } from '@/schemas/navigation'\n\nexport const DEFAULT_INTRODUCTION_SLUG = 'introduction'\n\n/**\n * Creates a hierarchical navigation structure from markdown headings in an OpenAPI description.\n *\n * The function processes markdown headings to create a two-level navigation tree:\n * - Level 1: Main sections (based on the lowest heading level found)\n * - Level 2: Subsections (one level deeper than the main sections)\n *\n * If the description starts with content rather than a heading, an \"Introduction\" section\n * is automatically added as the first entry.\n *\n * @param description - The markdown description text to process\n * @param entitiesMap - Map to store heading IDs and titles for mobile header navigation\n * @param getHeadingId - Function to generate unique IDs for headings\n * @returns Array of navigation entries with their hierarchy\n */\nexport const traverseDescription = (\n  description: string | undefined,\n  getHeadingId: (heading: Heading) => string,\n): TraversedDescription[] => {\n  if (!description?.trim()) {\n    return []\n  }\n\n  const headings = getHeadingsFromMarkdown(description)\n  const lowestLevel = getLowestHeadingLevel(headings)\n\n  const entries: TraversedDescription[] = []\n  let currentParent: TraversedDescription | null = null\n\n  // Add \"Introduction\" as the first heading\n  if (description && !description.trim().startsWith('#')) {\n    const heading: Heading = {\n      depth: 1,\n      value: 'Introduction',\n      slug: DEFAULT_INTRODUCTION_SLUG,\n    }\n\n    const id = getHeadingId(heading)\n    const title = heading.value\n\n    const entry = {\n      id,\n      title,\n      type: 'text',\n    } satisfies TraversedDescription\n\n    // Push to entries\n    entries.push(entry)\n  }\n\n  // Traverse for the rest\n  for (const heading of headings) {\n    if (heading.depth !== lowestLevel && heading.depth !== lowestLevel + 1) {\n      continue\n    }\n\n    const entry: TraversedDescription = {\n      id: getHeadingId(heading),\n      title: heading.value,\n      type: 'text',\n    }\n\n    if (heading.depth === lowestLevel) {\n      entry.children = []\n      entries.push(entry)\n      currentParent = entry\n    } else if (currentParent) {\n      currentParent.children?.push(entry)\n    }\n  }\n\n  return entries\n}\n"],
-  "mappings": "AAAA,SAAS,yBAAyB,6BAA6B;AAIxD,MAAM,4BAA4B;AAiBlC,MAAM,sBAAsB,CACjC,aACA,iBAC2B;AAC3B,MAAI,CAAC,aAAa,KAAK,GAAG;AACxB,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,WAAW,wBAAwB,WAAW;AACpD,QAAM,cAAc,sBAAsB,QAAQ;AAElD,QAAM,UAAkC,CAAC;AACzC,MAAI,gBAA6C;AAGjD,MAAI,eAAe,CAAC,YAAY,KAAK,EAAE,WAAW,GAAG,GAAG;AACtD,UAAM,UAAmB;AAAA,MACvB,OAAO;AAAA,MACP,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAEA,UAAM,KAAK,aAAa,OAAO;AAC/B,UAAM,QAAQ,QAAQ;AAEtB,UAAM,QAAQ;AAAA,MACZ;AAAA,MACA;AAAA,MACA,MAAM;AAAA,IACR;AAGA,YAAQ,KAAK,KAAK;AAAA,EACpB;AAGA,aAAW,WAAW,UAAU;AAC9B,QAAI,QAAQ,UAAU,eAAe,QAAQ,UAAU,cAAc,GAAG;AACtE;AAAA,IACF;AAEA,UAAM,QAA8B;AAAA,MAClC,IAAI,aAAa,OAAO;AAAA,MACxB,OAAO,QAAQ;AAAA,MACf,MAAM;AAAA,IACR;AAEA,QAAI,QAAQ,UAAU,aAAa;AACjC,YAAM,WAAW,CAAC;AAClB,cAAQ,KAAK,KAAK;AAClB,sBAAgB;AAAA,IAClB,WAAW,eAAe;AACxB,oBAAc,UAAU,KAAK,KAAK;AAAA,IACpC;AAAA,EACF;AAEA,SAAO;AACT;",
+  "sourcesContent": ["import { getHeadingsFromMarkdown, getLowestHeadingLevel } from '@/navigation/helpers/utils'\nimport type { Heading, TraverseSpecOptions } from '@/navigation/types'\nimport type { TraversedDescription } from '@/schemas/navigation'\nimport type { InfoObject } from '@/schemas/v3.1/strict/info'\n\nexport const DEFAULT_INTRODUCTION_SLUG = 'introduction'\n\n/**\n * Creates a hierarchical navigation structure from markdown headings in an OpenAPI description.\n *\n * The function processes markdown headings to create a two-level navigation tree:\n * - Level 1: Main sections (based on the lowest heading level found)\n * - Level 2: Subsections (one level deeper than the main sections)\n *\n * If the description starts with content rather than a heading, an \"Introduction\" section\n * is automatically added as the first entry.\n *\n * @param description - The markdown description text to process\n * @param entitiesMap - Map to store heading IDs and titles for mobile header navigation\n * @param getHeadingId - Function to generate unique IDs for headings\n * @returns Array of navigation entries with their hierarchy\n */\nexport const traverseDescription = ({\n  generateId,\n  parentId,\n  info,\n}: {\n  generateId: TraverseSpecOptions['generateId']\n  parentId: string\n  info: InfoObject\n}): TraversedDescription[] => {\n  if (!info.description?.trim()) {\n    return []\n  }\n\n  const headings = getHeadingsFromMarkdown(info.description)\n  const lowestLevel = getLowestHeadingLevel(headings)\n\n  const entries: TraversedDescription[] = []\n  let currentParent: TraversedDescription | null = null\n\n  // Add \"Introduction\" as the first heading\n  if (info.description && !info.description.trim().startsWith('#')) {\n    const heading: Heading = {\n      depth: 1,\n      value: 'Introduction',\n      slug: DEFAULT_INTRODUCTION_SLUG,\n    }\n\n    const id = generateId({\n      type: 'text',\n      depth: heading.depth,\n      slug: heading.slug,\n      parentId: parentId,\n      info: info,\n      value: heading.value,\n    })\n    const title = heading.value\n\n    const entry = {\n      id,\n      title,\n      type: 'text',\n    } satisfies TraversedDescription\n\n    // Push to entries\n    entries.push(entry)\n  }\n\n  // Traverse for the rest\n  for (const heading of headings) {\n    if (heading.depth !== lowestLevel && heading.depth !== lowestLevel + 1) {\n      continue\n    }\n\n    const entry: TraversedDescription = {\n      id: generateId({\n        type: 'text',\n        depth: heading.depth,\n        slug: heading.slug,\n        parentId: parentId,\n        info: info,\n        value: heading.value,\n      }),\n      title: heading.value,\n      type: 'text',\n    }\n\n    if (heading.depth === lowestLevel) {\n      entry.children = []\n      entries.push(entry)\n      currentParent = entry\n    } else if (currentParent) {\n      currentParent.children?.push(entry)\n    }\n  }\n\n  return entries\n}\n"],
+  "mappings": "AAAA,SAAS,yBAAyB,6BAA6B;AAKxD,MAAM,4BAA4B;AAiBlC,MAAM,sBAAsB,CAAC;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF,MAI8B;AAC5B,MAAI,CAAC,KAAK,aAAa,KAAK,GAAG;AAC7B,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,WAAW,wBAAwB,KAAK,WAAW;AACzD,QAAM,cAAc,sBAAsB,QAAQ;AAElD,QAAM,UAAkC,CAAC;AACzC,MAAI,gBAA6C;AAGjD,MAAI,KAAK,eAAe,CAAC,KAAK,YAAY,KAAK,EAAE,WAAW,GAAG,GAAG;AAChE,UAAM,UAAmB;AAAA,MACvB,OAAO;AAAA,MACP,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAEA,UAAM,KAAK,WAAW;AAAA,MACpB,MAAM;AAAA,MACN,OAAO,QAAQ;AAAA,MACf,MAAM,QAAQ;AAAA,MACd;AAAA,MACA;AAAA,MACA,OAAO,QAAQ;AAAA,IACjB,CAAC;AACD,UAAM,QAAQ,QAAQ;AAEtB,UAAM,QAAQ;AAAA,MACZ;AAAA,MACA;AAAA,MACA,MAAM;AAAA,IACR;AAGA,YAAQ,KAAK,KAAK;AAAA,EACpB;AAGA,aAAW,WAAW,UAAU;AAC9B,QAAI,QAAQ,UAAU,eAAe,QAAQ,UAAU,cAAc,GAAG;AACtE;AAAA,IACF;AAEA,UAAM,QAA8B;AAAA,MAClC,IAAI,WAAW;AAAA,QACb,MAAM;AAAA,QACN,OAAO,QAAQ;AAAA,QACf,MAAM,QAAQ;AAAA,QACd;AAAA,QACA;AAAA,QACA,OAAO,QAAQ;AAAA,MACjB,CAAC;AAAA,MACD,OAAO,QAAQ;AAAA,MACf,MAAM;AAAA,IACR;AAEA,QAAI,QAAQ,UAAU,aAAa;AACjC,YAAM,WAAW,CAAC;AAClB,cAAQ,KAAK,KAAK;AAClB,sBAAgB;AAAA,IAClB,WAAW,eAAe;AACxB,oBAAc,UAAU,KAAK,KAAK;AAAA,IACpC;AAAA,EACF;AAEA,SAAO;AACT;",
   "names": []
 }

package/dist/navigation/helpers/traverse-document.d.ts

@@ -10,7 +10,10 @@ import type { DocumentConfiguration } from '../../schemas/workspace-specificatio
  * - Tag-based organization of operations and webhooks
  * - Optional schema/model documentation
  */
-export declare const traverseDocument: (document: OpenApiDocument, config?: DocumentConfiguration) => {
-    entries: TraversedEntry[];
+export declare const traverseDocument: (documentName: string, document: OpenApiDocument, config?: DocumentConfiguration) => {
+    id: string;
+    type: "document";
+    title: string;
+    children: TraversedEntry[];
 };
 //# sourceMappingURL=traverse-document.d.ts.map

package/dist/navigation/helpers/traverse-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traverse-document.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAA;AAQrF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,eAAe,EAAE,SAAS,qBAAqB;;CAiDzF,CAAA"}
+{"version":3,"file":"traverse-document.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAA;AAQrF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,cAAc,MAAM,EAAE,UAAU,eAAe,EAAE,SAAS,qBAAqB;;;;;CA6F/G,CAAA"}