fumadocs-openapi 10.4.0 → 10.5.0

package/dist/utils/pages/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","names":[],"sources":["../../../src/utils/pages/builder.ts"],"sourcesContent":["import type { ProcessedDocument } from '@/utils/process-document';\nimport type { OpenAPIServer } from '@/server';\nimport type { OperationItem, WebhookItem } from '@/ui/api-page';\nimport type { Document, OperationObject, PathItemObject, TagObject } from '@/types';\nimport { getTagDisplayName, methodKeys, type NoReference } from '@/utils/schema';\nimport { idToTitle } from '@/utils/id-to-title';\n\ninterface BaseEntry {\n  path: string;\n  schemaId: string;\n  info: {\n    title: string;\n    description?: string;\n  };\n}\n\nexport interface OperationOutput extends BaseEntry {\n  type: 'operation';\n  item: OperationItem;\n}\n\nexport interface WebhookOutput extends BaseEntry {\n  type: 'webhook';\n  item: WebhookItem;\n}\n\nexport interface TagOutput extends BaseEntry {\n  type: 'tag';\n  tag: string;\n  rawTag: TagObject;\n  operations: OperationItem[];\n  webhooks: WebhookItem[];\n}\n\nexport interface OutputGroup extends BaseEntry {\n  type: 'group';\n  operations: OperationItem[];\n  webhooks: WebhookItem[];\n}\n\nexport type OutputEntry = TagOutput | OperationOutput | WebhookOutput | OutputGroup;\n\nexport interface PagesBuilderConfig {\n  toPages: (builder: PagesBuilder) => void;\n}\n\nexport interface PagesBuilder {\n  /**\n   * the input ID in OpenAPI server\n   */\n  id: string;\n  document: ProcessedDocument;\n  /**\n   * add output entry.\n   *\n   * When the `path` property is unspecified, it will generate one.\n   */\n  create: (entry: OutputEntry) => void;\n\n  /**\n   * get file path from operation path, useful for generating output paths.\n   */\n  routePathToFilePath: (path: string) => string;\n\n  /**\n   * Extract useful info for rendering\n   */\n  extract: () => ExtractedInfo;\n  fromExtractedWebhook: (item: WebhookItem) =>\n    | {\n        get displayName(): string;\n        pathItem: NoReference<PathItemObject>;\n        operation: NoReference<OperationObject>;\n      }\n    | undefined;\n  fromExtractedOperation: (item: OperationItem) =>\n    | {\n        get displayName(): string;\n        pathItem: NoReference<PathItemObject>;\n        operation: NoReference<OperationObject>;\n      }\n    | undefined;\n  fromTag: (tag: TagObject) => {\n    get displayName(): string;\n  };\n  fromTagName: (tag: string) =>\n    | {\n        info: TagObject;\n        get displayName(): string;\n      }\n    | undefined;\n}\n\ninterface ExtractedInfo {\n  webhooks: (WebhookItem & { tags?: string[] })[];\n  operations: (OperationItem & {\n    tags?: string[];\n  })[];\n}\n\nexport async function fromServer(\n  server: OpenAPIServer,\n  config: PagesBuilderConfig,\n): Promise<Record<string, OutputEntry[]>> {\n  const schemas = await server.getSchemas();\n  const generated: Record<string, OutputEntry[]> = {};\n\n  const entries = Object.entries(schemas);\n  if (entries.length === 0) {\n    throw new Error('No input files found.');\n  }\n\n  for (const [id, schema] of entries) {\n    generated[id] = fromSchema(id, schema, config);\n  }\n\n  return generated;\n}\n\nexport function fromSchema(\n  schemaId: string,\n  processed: ProcessedDocument,\n  config: PagesBuilderConfig,\n): OutputEntry[] {\n  const files: OutputEntry[] = [];\n  const { toPages } = config;\n  const { dereferenced } = processed;\n\n  toPages({\n    id: schemaId,\n    document: processed,\n    create(entry) {\n      files.push(entry);\n    },\n    extract: () => extractInfo(dereferenced),\n    routePathToFilePath(path) {\n      return path\n        .toLowerCase()\n        .replaceAll('.', '-')\n        .split('/')\n        .flatMap((v) => {\n          if (v.startsWith('{') && v.endsWith('}')) return v.slice(1, -1);\n          if (v.length === 0) return [];\n          return v;\n        })\n        .join('/');\n    },\n    fromExtractedWebhook(item) {\n      const pathItem = dereferenced.webhooks?.[item.name];\n      if (!pathItem) return;\n      const operation = pathItem?.[item.method];\n      if (!operation) return;\n      return {\n        pathItem,\n        operation,\n        get displayName() {\n          return operation.summary || pathItem.summary || idToTitle(item.name);\n        },\n      };\n    },\n    fromExtractedOperation(item) {\n      const pathItem = dereferenced.paths?.[item.path];\n      if (!pathItem) return;\n      const operation = pathItem?.[item.method];\n      if (!operation) return;\n      return {\n        pathItem,\n        operation,\n        get displayName() {\n          return (\n            operation.summary ||\n            pathItem.summary ||\n            (operation.operationId ? idToTitle(operation.operationId) : item.path)\n          );\n        },\n      };\n    },\n    fromTag(tag) {\n      return {\n        get displayName() {\n          return getTagDisplayName(tag);\n        },\n      };\n    },\n    fromTagName(name) {\n      const tag = dereferenced.tags?.find((item) => item.name === name);\n      if (!tag) return;\n\n      return {\n        info: tag,\n        ...this.fromTag(tag),\n      };\n    },\n  });\n\n  return files;\n}\n\nfunction extractInfo(document: NoReference<Document>): ExtractedInfo {\n  const result: ExtractedInfo = { webhooks: [], operations: [] };\n\n  for (const [path, pathItem] of Object.entries(document.paths ?? {})) {\n    if (!pathItem) continue;\n\n    for (const methodKey of methodKeys) {\n      if (!pathItem[methodKey]) continue;\n\n      result.operations.push({\n        method: methodKey,\n        path,\n        tags: pathItem[methodKey]?.tags,\n      });\n    }\n  }\n\n  for (const [name, pathItem] of Object.entries(document.webhooks ?? {})) {\n    if (!pathItem) continue;\n\n    for (const methodKey of methodKeys) {\n      if (!pathItem[methodKey]) continue;\n\n      result.webhooks.push({\n        method: methodKey,\n        name,\n        tags: pathItem[methodKey]?.tags,\n      });\n    }\n  }\n\n  return result;\n}\n"],"mappings":";;;AAoGA,eAAsB,WACpB,QACA,QACwC;CACxC,MAAM,UAAU,MAAM,OAAO,YAAY;CACzC,MAAM,YAA2C,EAAE;CAEnD,MAAM,UAAU,OAAO,QAAQ,QAAQ;AACvC,KAAI,QAAQ,WAAW,EACrB,OAAM,IAAI,MAAM,wBAAwB;AAG1C,MAAK,MAAM,CAAC,IAAI,WAAW,QACzB,WAAU,MAAM,WAAW,IAAI,QAAQ,OAAO;AAGhD,QAAO;;AAGT,SAAgB,WACd,UACA,WACA,QACe;CACf,MAAM,QAAuB,EAAE;CAC/B,MAAM,EAAE,YAAY;CACpB,MAAM,EAAE,iBAAiB;AAEzB,SAAQ;EACN,IAAI;EACJ,UAAU;EACV,OAAO,OAAO;AACZ,SAAM,KAAK,MAAM;;EAEnB,eAAe,YAAY,aAAa;EACxC,oBAAoB,MAAM;AACxB,UAAO,KACJ,aAAa,CACb,WAAW,KAAK,IAAI,CACpB,MAAM,IAAI,CACV,SAAS,MAAM;AACd,QAAI,EAAE,WAAW,IAAI,IAAI,EAAE,SAAS,IAAI,CAAE,QAAO,EAAE,MAAM,GAAG,GAAG;AAC/D,QAAI,EAAE,WAAW,EAAG,QAAO,EAAE;AAC7B,WAAO;KACP,CACD,KAAK,IAAI;;EAEd,qBAAqB,MAAM;GACzB,MAAM,WAAW,aAAa,WAAW,KAAK;AAC9C,OAAI,CAAC,SAAU;GACf,MAAM,YAAY,WAAW,KAAK;AAClC,OAAI,CAAC,UAAW;AAChB,UAAO;IACL;IACA;IACA,IAAI,cAAc;AAChB,YAAO,UAAU,WAAW,SAAS,WAAW,UAAU,KAAK,KAAK;;IAEvE;;EAEH,uBAAuB,MAAM;GAC3B,MAAM,WAAW,aAAa,QAAQ,KAAK;AAC3C,OAAI,CAAC,SAAU;GACf,MAAM,YAAY,WAAW,KAAK;AAClC,OAAI,CAAC,UAAW;AAChB,UAAO;IACL;IACA;IACA,IAAI,cAAc;AAChB,YACE,UAAU,WACV,SAAS,YACR,UAAU,cAAc,UAAU,UAAU,YAAY,GAAG,KAAK;;IAGtE;;EAEH,QAAQ,KAAK;AACX,UAAO,EACL,IAAI,cAAc;AAChB,WAAO,kBAAkB,IAAI;MAEhC;;EAEH,YAAY,MAAM;GAChB,MAAM,MAAM,aAAa,MAAM,MAAM,SAAS,KAAK,SAAS,KAAK;AACjE,OAAI,CAAC,IAAK;AAEV,UAAO;IACL,MAAM;IACN,GAAG,KAAK,QAAQ,IAAI;IACrB;;EAEJ,CAAC;AAEF,QAAO;;AAGT,SAAS,YAAY,UAAgD;CACnE,MAAM,SAAwB;EAAE,UAAU,EAAE;EAAE,YAAY,EAAE;EAAE;AAE9D,MAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,SAAS,SAAS,EAAE,CAAC,EAAE;AACnE,MAAI,CAAC,SAAU;AAEf,OAAK,MAAM,aAAa,YAAY;AAClC,OAAI,CAAC,SAAS,WAAY;AAE1B,UAAO,WAAW,KAAK;IACrB,QAAQ;IACR;IACA,MAAM,SAAS,YAAY;IAC5B,CAAC;;;AAIN,MAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,SAAS,YAAY,EAAE,CAAC,EAAE;AACtE,MAAI,CAAC,SAAU;AAEf,OAAK,MAAM,aAAa,YAAY;AAClC,OAAI,CAAC,SAAS,WAAY;AAE1B,UAAO,SAAS,KAAK;IACnB,QAAQ;IACR;IACA,MAAM,SAAS,YAAY;IAC5B,CAAC;;;AAIN,QAAO"}
+{"version":3,"file":"builder.js","names":[],"sources":["../../../src/utils/pages/builder.ts"],"sourcesContent":["import type { ProcessedDocument } from '@/utils/process-document';\nimport type { OpenAPIServer } from '@/server';\nimport type { OperationItem, WebhookItem } from '@/ui/api-page';\nimport type { OperationObject, PathItemObject, TagObject } from '@/types';\nimport { getTagDisplayName, methodKeys, type NoReference } from '@/utils/schema';\nimport { idToTitle } from '@/utils/id-to-title';\n\ninterface BaseEntry {\n  path: string;\n  schemaId: string;\n  info: {\n    title: string;\n    description?: string;\n  };\n}\n\nexport interface OperationOutput extends BaseEntry {\n  type: 'operation';\n  item: OperationItem;\n}\n\nexport interface WebhookOutput extends BaseEntry {\n  type: 'webhook';\n  item: WebhookItem;\n}\n\nexport interface PageOutput extends BaseEntry {\n  type: 'page';\n  operations: OperationItem[];\n  webhooks: WebhookItem[];\n  /** tag info if the page is generated from a tag. */\n  tag?: TagObject;\n}\n\nexport interface OutputGroup extends BaseEntry {\n  type: 'group';\n  entries: OutputEntry[];\n  /** tag info if the group is generated from a tag. */\n  tag?: TagObject;\n}\n\nexport type OutputEntry = PageOutput | OperationOutput | WebhookOutput | OutputGroup;\n\nexport interface PagesBuilderConfig {\n  toPages: (builder: PagesBuilder) => void;\n}\n\nexport interface PagesBuilder {\n  /**\n   * the input ID in OpenAPI server\n   */\n  id: string;\n  document: ProcessedDocument;\n  /**\n   * add output entry.\n   */\n  create: (entry: OutputEntry) => void;\n\n  /**\n   * get file path from operation path, useful for generating output paths.\n   */\n  routePathToFilePath: (path: string) => string;\n\n  /**\n   * Extract useful info for rendering\n   */\n  extract: () => ExtractedInfo;\n  fromExtractedWebhook: (item: WebhookItem) =>\n    | {\n        get displayName(): string;\n        pathItem: NoReference<PathItemObject>;\n        operation: NoReference<OperationObject>;\n      }\n    | undefined;\n  fromExtractedOperation: (item: OperationItem) =>\n    | {\n        get displayName(): string;\n        pathItem: NoReference<PathItemObject>;\n        operation: NoReference<OperationObject>;\n      }\n    | undefined;\n  fromTag: (tag: TagObject) => {\n    get displayName(): string;\n  };\n  fromTagName: (tag: string) =>\n    | {\n        info: TagObject;\n        get displayName(): string;\n      }\n    | undefined;\n}\n\ninterface ExtractedInfo {\n  webhooks: (WebhookItem & { tags?: string[] })[];\n  operations: (OperationItem & {\n    tags?: string[];\n  })[];\n}\n\nexport async function fromServer(\n  server: OpenAPIServer,\n  config: PagesBuilderConfig,\n): Promise<Record<string, OutputEntry[]>> {\n  const schemas = await server.getSchemas();\n  const generated: Record<string, OutputEntry[]> = {};\n\n  const entries = Object.entries(schemas);\n  if (entries.length === 0) {\n    throw new Error('No input files found.');\n  }\n\n  for (const [id, schema] of entries) {\n    generated[id] = fromSchema(id, schema, config);\n  }\n\n  return generated;\n}\n\nexport function fromSchema(\n  schemaId: string,\n  processed: ProcessedDocument,\n  config: PagesBuilderConfig,\n): OutputEntry[] {\n  const files: OutputEntry[] = [];\n  const { toPages } = config;\n  const { dereferenced } = processed;\n\n  toPages({\n    id: schemaId,\n    document: processed,\n    create(entry) {\n      files.push(entry);\n    },\n    extract() {\n      const result: ExtractedInfo = { webhooks: [], operations: [] };\n\n      for (const [path, pathItem] of Object.entries(dereferenced.paths ?? {})) {\n        if (!pathItem) continue;\n\n        for (const methodKey of methodKeys) {\n          if (!pathItem[methodKey]) continue;\n\n          result.operations.push({\n            method: methodKey,\n            path,\n            tags: pathItem[methodKey]?.tags,\n          });\n        }\n      }\n\n      for (const [name, pathItem] of Object.entries(dereferenced.webhooks ?? {})) {\n        if (!pathItem) continue;\n\n        for (const methodKey of methodKeys) {\n          if (!pathItem[methodKey]) continue;\n\n          result.webhooks.push({\n            method: methodKey,\n            name,\n            tags: pathItem[methodKey]?.tags,\n          });\n        }\n      }\n\n      return result;\n    },\n    routePathToFilePath(path) {\n      return path\n        .toLowerCase()\n        .replaceAll('.', '-')\n        .split('/')\n        .flatMap((v) => {\n          if (v.startsWith('{') && v.endsWith('}')) return v.slice(1, -1);\n          if (v.length === 0) return [];\n          return v;\n        })\n        .join('/');\n    },\n    fromExtractedWebhook(item) {\n      const pathItem = dereferenced.webhooks?.[item.name];\n      if (!pathItem) return;\n      const operation = pathItem?.[item.method];\n      if (!operation) return;\n      return {\n        pathItem,\n        operation,\n        get displayName() {\n          return operation.summary || pathItem.summary || idToTitle(item.name);\n        },\n      };\n    },\n    fromExtractedOperation(item) {\n      const pathItem = dereferenced.paths?.[item.path];\n      if (!pathItem) return;\n      const operation = pathItem?.[item.method];\n      if (!operation) return;\n      return {\n        pathItem,\n        operation,\n        get displayName() {\n          return (\n            operation.summary ||\n            pathItem.summary ||\n            (operation.operationId ? idToTitle(operation.operationId) : item.path)\n          );\n        },\n      };\n    },\n    fromTag(tag) {\n      return {\n        get displayName() {\n          return getTagDisplayName(tag);\n        },\n      };\n    },\n    fromTagName(name) {\n      const tag = dereferenced.tags?.find((item) => item.name === name);\n      if (!tag) return;\n\n      return {\n        info: tag,\n        ...this.fromTag(tag),\n      };\n    },\n  });\n\n  return files;\n}\n"],"mappings":";;;AAmGA,eAAsB,WACpB,QACA,QACwC;CACxC,MAAM,UAAU,MAAM,OAAO,YAAY;CACzC,MAAM,YAA2C,EAAE;CAEnD,MAAM,UAAU,OAAO,QAAQ,QAAQ;AACvC,KAAI,QAAQ,WAAW,EACrB,OAAM,IAAI,MAAM,wBAAwB;AAG1C,MAAK,MAAM,CAAC,IAAI,WAAW,QACzB,WAAU,MAAM,WAAW,IAAI,QAAQ,OAAO;AAGhD,QAAO;;AAGT,SAAgB,WACd,UACA,WACA,QACe;CACf,MAAM,QAAuB,EAAE;CAC/B,MAAM,EAAE,YAAY;CACpB,MAAM,EAAE,iBAAiB;AAEzB,SAAQ;EACN,IAAI;EACJ,UAAU;EACV,OAAO,OAAO;AACZ,SAAM,KAAK,MAAM;;EAEnB,UAAU;GACR,MAAM,SAAwB;IAAE,UAAU,EAAE;IAAE,YAAY,EAAE;IAAE;AAE9D,QAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,aAAa,SAAS,EAAE,CAAC,EAAE;AACvE,QAAI,CAAC,SAAU;AAEf,SAAK,MAAM,aAAa,YAAY;AAClC,SAAI,CAAC,SAAS,WAAY;AAE1B,YAAO,WAAW,KAAK;MACrB,QAAQ;MACR;MACA,MAAM,SAAS,YAAY;MAC5B,CAAC;;;AAIN,QAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,aAAa,YAAY,EAAE,CAAC,EAAE;AAC1E,QAAI,CAAC,SAAU;AAEf,SAAK,MAAM,aAAa,YAAY;AAClC,SAAI,CAAC,SAAS,WAAY;AAE1B,YAAO,SAAS,KAAK;MACnB,QAAQ;MACR;MACA,MAAM,SAAS,YAAY;MAC5B,CAAC;;;AAIN,UAAO;;EAET,oBAAoB,MAAM;AACxB,UAAO,KACJ,aAAa,CACb,WAAW,KAAK,IAAI,CACpB,MAAM,IAAI,CACV,SAAS,MAAM;AACd,QAAI,EAAE,WAAW,IAAI,IAAI,EAAE,SAAS,IAAI,CAAE,QAAO,EAAE,MAAM,GAAG,GAAG;AAC/D,QAAI,EAAE,WAAW,EAAG,QAAO,EAAE;AAC7B,WAAO;KACP,CACD,KAAK,IAAI;;EAEd,qBAAqB,MAAM;GACzB,MAAM,WAAW,aAAa,WAAW,KAAK;AAC9C,OAAI,CAAC,SAAU;GACf,MAAM,YAAY,WAAW,KAAK;AAClC,OAAI,CAAC,UAAW;AAChB,UAAO;IACL;IACA;IACA,IAAI,cAAc;AAChB,YAAO,UAAU,WAAW,SAAS,WAAW,UAAU,KAAK,KAAK;;IAEvE;;EAEH,uBAAuB,MAAM;GAC3B,MAAM,WAAW,aAAa,QAAQ,KAAK;AAC3C,OAAI,CAAC,SAAU;GACf,MAAM,YAAY,WAAW,KAAK;AAClC,OAAI,CAAC,UAAW;AAChB,UAAO;IACL;IACA;IACA,IAAI,cAAc;AAChB,YACE,UAAU,WACV,SAAS,YACR,UAAU,cAAc,UAAU,UAAU,YAAY,GAAG,KAAK;;IAGtE;;EAEH,QAAQ,KAAK;AACX,UAAO,EACL,IAAI,cAAc;AAChB,WAAO,kBAAkB,IAAI;MAEhC;;EAEH,YAAY,MAAM;GAChB,MAAM,MAAM,aAAa,MAAM,MAAM,SAAS,KAAK,SAAS,KAAK;AACjE,OAAI,CAAC,IAAK;AAEV,UAAO;IACL,MAAM;IACN,GAAG,KAAK,QAAQ,IAAI;IACrB;;EAEJ,CAAC;AAEF,QAAO"}

package/dist/utils/pages/preset-auto.d.ts

@@ -1,4 +1,5 @@
-import { OperationOutput, OutputGroup, PagesBuilder, PagesBuilderConfig, TagOutput, WebhookOutput } from "./builder.js";
+import { OperationOutput, PageOutput, PagesBuilder, PagesBuilderConfig, WebhookOutput } from "./builder.js";
+import { DistributiveOmit } from "../../types.js";
 import { ProcessedDocument } from "../process-document.js";
 
 //#region src/utils/pages/preset-auto.d.ts
@@ -16,7 +17,7 @@ interface OperationConfig extends BaseConfig {
    *
    * @defaultValue 'none'
    */
-  groupBy?: 'tag' | 'route' | 'none' | ((entry: OperationOutput | WebhookOutput) => string);
+  groupBy?: 'tag' | 'route' | 'none' | ((entry: DistributiveOmit<OperationOutput | WebhookOutput, 'path'>) => string);
   /**
    * Specify name for output file
    */
@@ -30,7 +31,7 @@ interface TagConfig extends BaseConfig {
   /**
    * Specify name for output file
    */
-  name?: NameFn<TagOutput> | NameFnOptions;
+  name?: NameFn<PageOutput> | NameFnOptions;
 }
 interface SchemaConfig extends BaseConfig {
   /**
@@ -40,12 +41,12 @@ interface SchemaConfig extends BaseConfig {
   /**
    * Specify name for output file
    */
-  name?: NameFn<OutputGroup> | NameFnOptions;
+  name?: NameFn<PageOutput> | NameFnOptions;
 }
 type SchemaToPagesOptions = SchemaConfig | TagConfig | OperationConfig | ({
   per: 'custom';
 } & PagesBuilderConfig);
-type NameFn<Entry> = (this: PagesBuilder, output: Entry, document: ProcessedDocument['dereferenced']) => string;
+type NameFn<Entry extends OperationOutput | WebhookOutput | PageOutput = OperationOutput | WebhookOutput | PageOutput> = (this: PagesBuilder, output: DistributiveOmit<Entry, 'path'>, document: ProcessedDocument['dereferenced']) => string;
 interface NameFnOptions {
   /**
    * The version of algorithm used to generate file paths.

package/dist/utils/pages/preset-auto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preset-auto.d.ts","names":[],"sources":["../../../src/utils/pages/preset-auto.ts"],"mappings":";;;;UAaU,eAAA,SAAwB,UAAA;;AAHH;;EAO7B,GAAA;EAW8C;;;;;;;;;EAA9C,OAAA,gCAAuC,KAAA,EAAO,eAAA,GAAkB,aAAA;EAXhE;;;EAgBA,IAAA,GAAO,MAAA,CAAO,eAAA,GAAkB,aAAA,IAAiB,aAAA;AAAA;AAAA,UAGzC,SAAA,SAAkB,UAAA;EAHnB;;;EAOP,GAAA;EAP8D;;AAAA;EAY9D,IAAA,GAAO,MAAA,CAAO,SAAA,IAAa,aAAA;AAAA;AAAA,UAGnB,YAAA,SAAqB,UAAA;EAHtB;;;EAOP,GAAA;EAhBoC;;;EAqBpC,IAAA,GAAO,MAAA,CAAO,WAAA,IAAe,aAAA;AAAA;AAAA,KAGnB,oBAAA,GACR,YAAA,GACA,SAAA,GACA,eAAA;EAEE,GAAA;AAAA,IACE,kBAAA;AAAA,KAEH,MAAA,WACH,IAAA,EAAM,YAAA,EACN,MAAA,EAAQ,KAAA,EACR,QAAA,EAAU,iBAAA;AAAA,UAGF,aAAA;EA1Ba;;;;;;;;EAmCrB,SAAA;AAAA;AAAA,UAGQ,UAAA;EA7BD;;;;;EAmCP,OAAA,IAAW,IAAA;AAAA;AAAA,iBAGG,gBAAA,CAAiB,OAAA,EAAS,oBAAA,GAAuB,kBAAA"}
+{"version":3,"file":"preset-auto.d.ts","names":[],"sources":["../../../src/utils/pages/preset-auto.ts"],"mappings":";;;;;UAcU,eAAA,SAAwB,UAAA;;AAFc;;EAM9C,GAAA;EAe8B;;;;;;;;;EAJ9B,OAAA,gCAIM,KAAA,EAAO,gBAAA,CAAiB,eAAA,GAAkB,aAAA;EAnBhB;;;EAwBhC,IAAA,GAAO,MAAA,CAAO,eAAA,GAAkB,aAAA,IAAiB,aAAA;AAAA;AAAA,UAGzC,SAAA,SAAkB,UAAA;EARpB;;;EAYN,GAAA;EAPgC;;;EAYhC,IAAA,GAAO,MAAA,CAAO,UAAA,IAAc,aAAA;AAAA;AAAA,UAGpB,YAAA,SAAqB,UAAA;;;;EAI7B,GAAA;EAhB0B;;;EAqB1B,IAAA,GAAO,MAAA,CAAO,UAAA,IAAc,aAAA;AAAA;AAAA,KAGlB,oBAAA,GACR,YAAA,GACA,SAAA,GACA,eAAA;EAEE,GAAA;AAAA,IACE,kBAAA;AAAA,KAEH,MAAA,eACW,eAAA,GAAkB,aAAA,GAAgB,UAAA,GAC5C,eAAA,GACA,aAAA,GACA,UAAA,KAEJ,IAAA,EAAM,YAAA,EACN,MAAA,EAAQ,gBAAA,CAAiB,KAAA,WACzB,QAAA,EAAU,iBAAA;AAAA,UAGF,aAAA;EAlCiC;AAAA;;;;;;;EA2CzC,SAAA;AAAA;AAAA,UAGQ,UAAA;EAvCR;;;;;EA6CA,OAAA,IAAW,IAAA;AAAA;AAAA,iBAGG,gBAAA,CAAiB,OAAA,EAAS,oBAAA,GAAuB,kBAAA"}

package/dist/utils/pages/preset-auto.js

@@ -1,5 +1,5 @@
 import { isUrl } from "../url.js";
-import * as path from "node:path";
+import * as path$1 from "node:path";
 //#region src/utils/pages/preset-auto.ts
 function createAutoPreset(options) {
 	if (options.per === "custom") return options;
@@ -11,43 +11,114 @@ function createAutoPreset(options) {
 	else {
 		const { algorithm = "v2" } = options.name ?? {};
 		nameFn = function(result, document) {
-			if (result.type === "tag") return slugify(result.tag);
-			if (result.type === "group") {
+			if (result.type === "page") {
+				if (result.tag) return slugify(result.tag.name);
 				const schemaId = result.schemaId;
-				return isUrl(schemaId) ? "index" : path.basename(schemaId, path.extname(schemaId));
+				return isUrl(schemaId) ? "index" : path$1.basename(schemaId, path$1.extname(schemaId));
 			}
 			if (result.type === "operation") {
 				const operation = document.paths[result.item.path][result.item.method];
 				if (algorithm === "v2" && operation.operationId) return operation.operationId;
-				return path.join(this.routePathToFilePath(result.item.path), result.item.method.toLowerCase());
+				return path$1.join(this.routePathToFilePath(result.item.path), result.item.method.toLowerCase());
 			}
 			const hook = document.webhooks[result.item.name][result.item.method];
 			if (algorithm === "v2" && hook.operationId) return hook.operationId;
 			return slugify(result.item.name);
 		};
 	}
-	function groupOutput(builder, entry) {
+	function group(builder, entries) {
+		const groups = /* @__PURE__ */ new Map();
+		const rest = [];
 		const { dereferenced } = builder.document;
 		const { groupBy = "none" } = options;
-		if (groupBy === "route") return [path.join(builder.routePathToFilePath(entry.type === "operation" ? entry.item.path : entry.item.name), `${entry.item.method.toLowerCase()}.mdx`)];
-		const file = nameFn.call(builder, entry, dereferenced);
-		if (groupBy === "tag") {
-			let tags = entry.type === "operation" ? dereferenced.paths[entry.item.path][entry.item.method].tags : dereferenced.webhooks[entry.item.name][entry.item.method].tags;
-			if (!tags || tags.length === 0) {
-				console.warn("When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.");
-				tags = ["unknown"];
+		for (const entry of entries) switch (groupBy) {
+			case "route": {
+				const groupName = builder.routePathToFilePath(entry.type === "operation" ? entry.item.path : entry.item.name);
+				let group = groups.get(groupName);
+				if (!group) {
+					group = {
+						type: "group",
+						info: { title: groupName },
+						entries: [],
+						schemaId: builder.id,
+						path: groupName
+					};
+					groups.set(groupName, group);
+				}
+				group.entries.push({
+					...entry,
+					path: path$1.join(groupName, `${entry.item.method.toLowerCase()}.mdx`)
+				});
+				break;
+			}
+			case "tag": {
+				let tags = entry.type === "operation" ? dereferenced.paths[entry.item.path][entry.item.method].tags : dereferenced.webhooks[entry.item.name][entry.item.method].tags;
+				if (!tags || tags.length === 0) {
+					console.warn("When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.");
+					tags = ["unknown"];
+				}
+				for (const tag of tags) {
+					const groupName = slugify(tag);
+					const { displayName, info } = builder.fromTagName(tag);
+					let group = groups.get(groupName);
+					if (!group) {
+						group = {
+							type: "group",
+							info: {
+								title: displayName,
+								description: info.description
+							},
+							tag: info,
+							entries: [],
+							schemaId: builder.id,
+							path: groupName
+						};
+						groups.set(groupName, group);
+					}
+					group.entries.push({
+						...entry,
+						path: path$1.join(groupName, `${nameFn.call(builder, entry, dereferenced)}.mdx`)
+					});
+				}
+				break;
+			}
+			default: {
+				const fileName = `${nameFn.call(builder, entry, dereferenced)}.mdx`;
+				if (typeof groupBy === "function") {
+					const groupDisplayName = groupBy(entry);
+					const groupName = slugify(groupDisplayName);
+					let group = groups.get(groupName);
+					if (!group) {
+						group = {
+							type: "group",
+							info: { title: groupDisplayName },
+							entries: [],
+							schemaId: builder.id,
+							path: groupName
+						};
+						groups.set(groupName, group);
+					}
+					group.entries.push({
+						...entry,
+						path: path$1.join(groupName, fileName)
+					});
+					break;
+				}
+				rest.push({
+					...entry,
+					path: fileName
+				});
 			}
-			return tags.map((tag) => path.join(slugify(tag), `${file}.mdx`));
 		}
-		if (typeof groupBy === "function") return [path.join(slugify(groupBy(entry)), `${file}.mdx`)];
-		return [`${file}.mdx`];
+		rest.push(...groups.values());
+		return rest;
 	}
 	return { toPages(builder) {
 		const { dereferenced } = builder.document;
 		const items = builder.extract();
 		if (options.per === "file") {
 			const entry = {
-				type: "group",
+				type: "page",
 				schemaId: builder.id,
 				path: "",
 				info: {
@@ -56,7 +127,7 @@ function createAutoPreset(options) {
 				},
 				...items
 			};
-			entry.path = nameFn.call(builder, entry, dereferenced) + ".mdx";
+			entry.path = `${nameFn.call(builder, entry, dereferenced)}.mdx`;
 			builder.create(entry);
 			return;
 		}
@@ -65,7 +136,7 @@ function createAutoPreset(options) {
 			for (const tag of tags) {
 				const { displayName } = builder.fromTag(tag);
 				const entry = {
-					type: "tag",
+					type: "page",
 					path: "",
 					schemaId: builder.id,
 					info: {
@@ -74,48 +145,39 @@ function createAutoPreset(options) {
 					},
 					webhooks: items.webhooks.filter((webhook) => webhook.tags?.includes(tag.name)),
 					operations: items.operations.filter((op) => op.tags?.includes(tag.name)),
-					tag: tag.name,
-					rawTag: tag
+					tag
 				};
-				entry.path = nameFn.call(builder, entry, dereferenced) + ".mdx";
+				entry.path = `${nameFn.call(builder, entry, dereferenced)}.mdx`;
 				builder.create(entry);
 			}
 			return;
 		}
+		const entries = [];
 		for (const op of items.operations) {
 			const { pathItem, operation, displayName } = builder.fromExtractedOperation(op);
-			const entry = {
+			entries.push({
 				type: "operation",
 				schemaId: builder.id,
 				item: op,
-				path: "",
 				info: {
 					title: displayName,
 					description: operation.description ?? pathItem.description
 				}
-			};
-			for (const outputPath of groupOutput(builder, entry)) builder.create({
-				...entry,
-				path: outputPath
 			});
 		}
 		for (const webhook of items.webhooks) {
 			const { pathItem, operation, displayName } = builder.fromExtractedWebhook(webhook);
-			const entry = {
+			entries.push({
 				type: "webhook",
 				schemaId: builder.id,
 				info: {
 					title: displayName,
 					description: operation.description ?? pathItem.description
 				},
-				item: webhook,
-				path: ""
-			};
-			for (const outputPath of groupOutput(builder, entry)) builder.create({
-				...entry,
-				path: outputPath
+				item: webhook
 			});
 		}
+		for (const entry of group(builder, entries)) builder.create(entry);
 	} };
 }
 //#endregion

package/dist/utils/pages/preset-auto.js.map

@@ -1 +1 @@
-{"version":3,"file":"preset-auto.js","names":[],"sources":["../../../src/utils/pages/preset-auto.ts"],"sourcesContent":["import * as path from 'node:path';\nimport type { ProcessedDocument } from '@/utils/process-document';\nimport type {\n  OperationOutput,\n  OutputEntry,\n  OutputGroup,\n  PagesBuilder,\n  PagesBuilderConfig,\n  TagOutput,\n  WebhookOutput,\n} from '@/utils/pages/builder';\nimport { isUrl } from '@/utils/url';\n\ninterface OperationConfig extends BaseConfig {\n  /**\n   * Generate a page for each API endpoint/operation (default).\n   */\n  per?: 'operation';\n\n  /**\n   * Group output using folders (Only works on `operation` mode)\n   * - tag: `{tag}/{file}`\n   * - route: `{endpoint}/{method}` (it will ignore the `name` option)\n   * - none: `{file}` (default)\n   * - a function that aligns group name (folder path) to each entry\n   *\n   * @defaultValue 'none'\n   */\n  groupBy?: 'tag' | 'route' | 'none' | ((entry: OperationOutput | WebhookOutput) => string);\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<OperationOutput | WebhookOutput> | NameFnOptions;\n}\n\ninterface TagConfig extends BaseConfig {\n  /**\n   * Generate a page for each tag.\n   */\n  per: 'tag';\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<TagOutput> | NameFnOptions;\n}\n\ninterface SchemaConfig extends BaseConfig {\n  /**\n   * Generate a page for each schema file.\n   */\n  per: 'file';\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<OutputGroup> | NameFnOptions;\n}\n\nexport type SchemaToPagesOptions =\n  | SchemaConfig\n  | TagConfig\n  | OperationConfig\n  | ({\n      per: 'custom';\n    } & PagesBuilderConfig);\n\ntype NameFn<Entry> = (\n  this: PagesBuilder,\n  output: Entry,\n  document: ProcessedDocument['dereferenced'],\n) => string;\n\ninterface NameFnOptions {\n  /**\n   * The version of algorithm used to generate file paths.\n   *\n   * v1: Fumadocs OpenAPI v8\n   * v2: Fumadocs OpenAPI v9\n   *\n   * @defaultValue v2\n   */\n  algorithm?: 'v2' | 'v1';\n}\n\ninterface BaseConfig {\n  /**\n   * Custom function to convert names into file names.\n   *\n   * By default, it only escapes whitespaces and upper case (English) characters\n   */\n  slugify?: (name: string) => string;\n}\n\nexport function createAutoPreset(options: SchemaToPagesOptions): PagesBuilderConfig {\n  if (options.per === 'custom') return options;\n  const {\n    slugify = (s) => {\n      return s.replace(/\\s+/g, '-').toLowerCase();\n    },\n  } = options;\n  let nameFn: NameFn<OutputEntry>;\n\n  if (typeof options.name === 'function') {\n    nameFn = options.name as NameFn<OutputEntry>;\n  } else {\n    const { algorithm = 'v2' } = options.name ?? {};\n\n    nameFn = function (result, document) {\n      if (result.type === 'tag') {\n        return slugify(result.tag);\n      }\n\n      if (result.type === 'group') {\n        const schemaId = result.schemaId;\n\n        return isUrl(schemaId) ? 'index' : path.basename(schemaId, path.extname(schemaId));\n      }\n\n      if (result.type === 'operation') {\n        const operation = document.paths![result.item.path]![result.item.method]!;\n\n        if (algorithm === 'v2' && operation.operationId) {\n          return operation.operationId;\n        }\n\n        return path.join(\n          this.routePathToFilePath(result.item.path),\n          result.item.method.toLowerCase(),\n        );\n      }\n\n      const hook = document.webhooks![result.item.name][result.item.method]!;\n\n      if (algorithm === 'v2' && hook.operationId) {\n        return hook.operationId;\n      }\n\n      return slugify(result.item.name);\n    };\n  }\n\n  function groupOutput(builder: PagesBuilder, entry: OperationOutput | WebhookOutput): string[] {\n    const { dereferenced } = builder.document;\n    const { groupBy = 'none' } = options as OperationConfig;\n\n    if (groupBy === 'route') {\n      return [\n        path.join(\n          builder.routePathToFilePath(\n            entry.type === 'operation' ? entry.item.path : entry.item.name,\n          ),\n          `${entry.item.method.toLowerCase()}.mdx`,\n        ),\n      ];\n    }\n\n    const file = nameFn.call(builder, entry, dereferenced);\n    if (groupBy === 'tag') {\n      let tags =\n        entry.type === 'operation'\n          ? dereferenced.paths![entry.item.path]![entry.item.method]!.tags\n          : dereferenced.webhooks![entry.item.name][entry.item.method]!.tags;\n\n      if (!tags || tags.length === 0) {\n        console.warn(\n          'When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.',\n        );\n\n        tags = ['unknown'];\n      }\n\n      return tags.map((tag) => path.join(slugify(tag), `${file}.mdx`));\n    }\n\n    if (typeof groupBy === 'function') {\n      return [path.join(slugify(groupBy(entry)), `${file}.mdx`)];\n    }\n\n    return [`${file}.mdx`];\n  }\n\n  return {\n    toPages(builder) {\n      const { dereferenced } = builder.document;\n      const items = builder.extract();\n\n      if (options.per === 'file') {\n        const entry: OutputGroup = {\n          type: 'group',\n          schemaId: builder.id,\n          path: '',\n          info: {\n            title: dereferenced.info?.title ?? 'Unknown',\n            description: dereferenced.info?.description,\n          },\n          ...items,\n        };\n        entry.path = nameFn.call(builder, entry, dereferenced) + '.mdx';\n        builder.create(entry);\n        return;\n      }\n\n      if (options.per === 'tag') {\n        const tags = dereferenced.tags ?? [];\n        for (const tag of tags) {\n          const { displayName } = builder.fromTag(tag);\n          const entry: TagOutput = {\n            type: 'tag',\n            path: '',\n            schemaId: builder.id,\n            info: {\n              title: displayName,\n              description: tag.description,\n            },\n            webhooks: items.webhooks.filter((webhook) => webhook.tags?.includes(tag.name!)),\n            operations: items.operations.filter((op) => op.tags?.includes(tag.name!)),\n            tag: tag.name!,\n            rawTag: tag,\n          };\n\n          entry.path = nameFn.call(builder, entry, dereferenced) + '.mdx';\n          builder.create(entry);\n        }\n\n        return;\n      }\n\n      for (const op of items.operations) {\n        const { pathItem, operation, displayName } = builder.fromExtractedOperation(op)!;\n\n        const entry: OperationOutput = {\n          type: 'operation',\n          schemaId: builder.id,\n          item: op,\n          path: '',\n          info: {\n            title: displayName,\n            description: operation.description ?? pathItem.description,\n          },\n        };\n\n        for (const outputPath of groupOutput(builder, entry)) {\n          builder.create({ ...entry, path: outputPath });\n        }\n      }\n\n      for (const webhook of items.webhooks) {\n        const { pathItem, operation, displayName } = builder.fromExtractedWebhook(webhook)!;\n\n        const entry: WebhookOutput = {\n          type: 'webhook',\n          schemaId: builder.id,\n          info: {\n            title: displayName,\n            description: operation.description ?? pathItem.description,\n          },\n          item: webhook,\n          path: '',\n        };\n\n        for (const outputPath of groupOutput(builder, entry)) {\n          builder.create({ ...entry, path: outputPath });\n        }\n      }\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"preset-auto.js","names":["path"],"sources":["../../../src/utils/pages/preset-auto.ts"],"sourcesContent":["import * as path from 'node:path';\nimport type { ProcessedDocument } from '@/utils/process-document';\nimport type {\n  OperationOutput,\n  OutputEntry,\n  OutputGroup,\n  PageOutput,\n  PagesBuilder,\n  PagesBuilderConfig,\n  WebhookOutput,\n} from '@/utils/pages/builder';\nimport { isUrl } from '@/utils/url';\nimport type { DistributiveOmit } from '@/types';\n\ninterface OperationConfig extends BaseConfig {\n  /**\n   * Generate a page for each API endpoint/operation (default).\n   */\n  per?: 'operation';\n\n  /**\n   * Group output using folders (Only works on `operation` mode)\n   * - tag: `{tag}/{file}`\n   * - route: `{endpoint}/{method}` (it will ignore the `name` option)\n   * - none: `{file}` (default)\n   * - a function that aligns group name (folder path) to each entry\n   *\n   * @defaultValue 'none'\n   */\n  groupBy?:\n    | 'tag'\n    | 'route'\n    | 'none'\n    | ((entry: DistributiveOmit<OperationOutput | WebhookOutput, 'path'>) => string);\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<OperationOutput | WebhookOutput> | NameFnOptions;\n}\n\ninterface TagConfig extends BaseConfig {\n  /**\n   * Generate a page for each tag.\n   */\n  per: 'tag';\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<PageOutput> | NameFnOptions;\n}\n\ninterface SchemaConfig extends BaseConfig {\n  /**\n   * Generate a page for each schema file.\n   */\n  per: 'file';\n\n  /**\n   * Specify name for output file\n   */\n  name?: NameFn<PageOutput> | NameFnOptions;\n}\n\nexport type SchemaToPagesOptions =\n  | SchemaConfig\n  | TagConfig\n  | OperationConfig\n  | ({\n      per: 'custom';\n    } & PagesBuilderConfig);\n\ntype NameFn<\n  Entry extends OperationOutput | WebhookOutput | PageOutput =\n    | OperationOutput\n    | WebhookOutput\n    | PageOutput,\n> = (\n  this: PagesBuilder,\n  output: DistributiveOmit<Entry, 'path'>,\n  document: ProcessedDocument['dereferenced'],\n) => string;\n\ninterface NameFnOptions {\n  /**\n   * The version of algorithm used to generate file paths.\n   *\n   * v1: Fumadocs OpenAPI v8\n   * v2: Fumadocs OpenAPI v9\n   *\n   * @defaultValue v2\n   */\n  algorithm?: 'v2' | 'v1';\n}\n\ninterface BaseConfig {\n  /**\n   * Custom function to convert names into file names.\n   *\n   * By default, it only escapes whitespaces and upper case (English) characters\n   */\n  slugify?: (name: string) => string;\n}\n\nexport function createAutoPreset(options: SchemaToPagesOptions): PagesBuilderConfig {\n  if (options.per === 'custom') return options;\n  const {\n    slugify = (s) => {\n      return s.replace(/\\s+/g, '-').toLowerCase();\n    },\n  } = options;\n  let nameFn: NameFn;\n\n  if (typeof options.name === 'function') {\n    nameFn = options.name as NameFn;\n  } else {\n    const { algorithm = 'v2' } = options.name ?? {};\n\n    nameFn = function (result, document) {\n      if (result.type === 'page') {\n        if (result.tag) return slugify(result.tag.name!);\n        const schemaId = result.schemaId;\n\n        return isUrl(schemaId) ? 'index' : path.basename(schemaId, path.extname(schemaId));\n      }\n\n      if (result.type === 'operation') {\n        const operation = document.paths![result.item.path]![result.item.method]!;\n\n        if (algorithm === 'v2' && operation.operationId) {\n          return operation.operationId;\n        }\n\n        return path.join(\n          this.routePathToFilePath(result.item.path),\n          result.item.method.toLowerCase(),\n        );\n      }\n\n      const hook = document.webhooks![result.item.name][result.item.method]!;\n\n      if (algorithm === 'v2' && hook.operationId) {\n        return hook.operationId;\n      }\n\n      return slugify(result.item.name);\n    };\n  }\n\n  function group(\n    builder: PagesBuilder,\n    entries: DistributiveOmit<OperationOutput | WebhookOutput, 'path'>[],\n  ): OutputEntry[] {\n    const groups = new Map<string, OutputGroup>();\n    const rest: OutputEntry[] = [];\n    const { dereferenced } = builder.document;\n    const { groupBy = 'none' } = options as OperationConfig;\n\n    for (const entry of entries) {\n      switch (groupBy) {\n        case 'route': {\n          const groupName = builder.routePathToFilePath(\n            entry.type === 'operation' ? entry.item.path : entry.item.name,\n          );\n\n          let group = groups.get(groupName);\n          if (!group) {\n            group = {\n              type: 'group',\n              info: { title: groupName },\n              entries: [],\n              schemaId: builder.id,\n              path: groupName,\n            };\n            groups.set(groupName, group);\n          }\n\n          group.entries.push({\n            ...entry,\n            path: path.join(groupName, `${entry.item.method.toLowerCase()}.mdx`),\n          });\n          break;\n        }\n        case 'tag': {\n          let tags =\n            entry.type === 'operation'\n              ? dereferenced.paths![entry.item.path]![entry.item.method]!.tags\n              : dereferenced.webhooks![entry.item.name][entry.item.method]!.tags;\n\n          if (!tags || tags.length === 0) {\n            console.warn(\n              'When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.',\n            );\n\n            tags = ['unknown'];\n          }\n\n          for (const tag of tags) {\n            const groupName = slugify(tag);\n            const { displayName, info } = builder.fromTagName(tag)!;\n            let group = groups.get(groupName);\n            if (!group) {\n              group = {\n                type: 'group',\n                info: { title: displayName, description: info.description },\n                tag: info,\n                entries: [],\n                schemaId: builder.id,\n                path: groupName,\n              };\n              groups.set(groupName, group);\n            }\n\n            group.entries.push({\n              ...entry,\n              path: path.join(groupName, `${nameFn.call(builder, entry, dereferenced)}.mdx`),\n            });\n          }\n\n          break;\n        }\n        default: {\n          const fileName = `${nameFn.call(builder, entry, dereferenced)}.mdx`;\n\n          if (typeof groupBy === 'function') {\n            const groupDisplayName = groupBy(entry);\n            const groupName = slugify(groupDisplayName);\n\n            let group = groups.get(groupName);\n            if (!group) {\n              group = {\n                type: 'group',\n                info: { title: groupDisplayName },\n                entries: [],\n                schemaId: builder.id,\n                path: groupName,\n              };\n              groups.set(groupName, group);\n            }\n\n            group.entries.push({\n              ...entry,\n              path: path.join(groupName, fileName),\n            });\n            break;\n          }\n\n          rest.push({\n            ...entry,\n            path: fileName,\n          });\n        }\n      }\n    }\n\n    rest.push(...groups.values());\n    return rest;\n  }\n\n  return {\n    toPages(builder) {\n      const { dereferenced } = builder.document;\n      const items = builder.extract();\n\n      if (options.per === 'file') {\n        const entry: PageOutput = {\n          type: 'page',\n          schemaId: builder.id,\n          path: '',\n          info: {\n            title: dereferenced.info?.title ?? 'Unknown',\n            description: dereferenced.info?.description,\n          },\n          ...items,\n        };\n        entry.path = `${nameFn.call(builder, entry, dereferenced)}.mdx`;\n        builder.create(entry);\n        return;\n      }\n\n      if (options.per === 'tag') {\n        const tags = dereferenced.tags ?? [];\n\n        for (const tag of tags) {\n          const { displayName } = builder.fromTag(tag);\n          const entry: PageOutput = {\n            type: 'page',\n            path: '',\n            schemaId: builder.id,\n            info: {\n              title: displayName,\n              description: tag.description,\n            },\n            webhooks: items.webhooks.filter((webhook) => webhook.tags?.includes(tag.name!)),\n            operations: items.operations.filter((op) => op.tags?.includes(tag.name!)),\n            tag,\n          };\n\n          entry.path = `${nameFn.call(builder, entry, dereferenced)}.mdx`;\n          builder.create(entry);\n        }\n\n        return;\n      }\n\n      const entries: DistributiveOmit<OperationOutput | WebhookOutput, 'path'>[] = [];\n      for (const op of items.operations) {\n        const { pathItem, operation, displayName } = builder.fromExtractedOperation(op)!;\n\n        entries.push({\n          type: 'operation',\n          schemaId: builder.id,\n          item: op,\n          info: {\n            title: displayName,\n            description: operation.description ?? pathItem.description,\n          },\n        });\n      }\n\n      for (const webhook of items.webhooks) {\n        const { pathItem, operation, displayName } = builder.fromExtractedWebhook(webhook)!;\n\n        entries.push({\n          type: 'webhook',\n          schemaId: builder.id,\n          info: {\n            title: displayName,\n            description: operation.description ?? pathItem.description,\n          },\n          item: webhook,\n        });\n      }\n\n      for (const entry of group(builder, entries)) {\n        builder.create(entry);\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/utils/pages/to-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-text.d.ts","names":[],"sources":["../../../src/utils/pages/to-text.ts"],"mappings":";;UASiB,kBAAA;;AAAjB;;EAIE,OAAA;IACE,KAAA;IACA,IAAA;EAAA;EAAA;;;;;EAQF,WAAA,IACE,KAAA,UACA,WAAA,sBACA,OAAA,EAAS,eAAA,KACN,MAAA;EAAA;;;;;AAkIP;;EAzHE,kBAAA;EA4HkB;;;;;;;;EAlHlB,mBAAA;AAAA;AAAA,KA+GU,eAAA;EAEN,IAAA;EACA,GAAA,EAAK,SAAA;AAAA;EAGL,IAAA;AAAA;EAGA,IAAA;AAAA"}
+{"version":3,"file":"to-text.d.ts","names":[],"sources":["../../../src/utils/pages/to-text.ts"],"mappings":";;UASiB,kBAAA;;AAAjB;;EAIE,OAAA;IACE,KAAA;IACA,IAAA;EAAA;EAAA;;;;;EAQF,WAAA,IACE,KAAA,UACA,WAAA,sBACA,OAAA,EAAS,eAAA,KACN,MAAA;EAAA;;;;;AAqHP;;EA5GE,kBAAA;EA+GkB;;;;;;;;EArGlB,mBAAA;AAAA;AAAA,KAkGU,eAAA;EAEN,IAAA;EACA,GAAA,EAAK,SAAA;AAAA;EAGL,IAAA;AAAA;EAGA,IAAA;AAAA"}

package/dist/utils/pages/to-text.js

@@ -8,25 +8,17 @@ function toText(entry, processed, options = {}) {
 			...options,
 			...entry.info
 		}, { type: "operation" });
-		case "group": return generatePage(entry.schemaId, processed, {
+		case "page": return generatePage(entry.schemaId, processed, {
 			operations: entry.operations,
 			webhooks: entry.webhooks,
 			showTitle: true
 		}, {
 			...options,
 			...entry.info
-		}, { type: "file" });
-		case "tag": return generatePage(entry.schemaId, processed, {
-			operations: entry.operations,
-			webhooks: entry.webhooks,
-			showTitle: true
-		}, {
-			...options,
-			...entry.info
-		}, {
+		}, entry.tag ? {
 			type: "tag",
-			tag: entry.rawTag
-		});
+			tag: entry.tag
+		} : { type: "file" });
 		case "webhook": return generatePage(entry.schemaId, processed, { webhooks: [entry.item] }, {
 			...options,
 			...entry.info

package/dist/utils/pages/to-text.js.map

@@ -1 +1 @@
-{"version":3,"file":"to-text.js","names":[],"sources":["../../../src/utils/pages/to-text.ts"],"sourcesContent":["import type { ApiPageProps, OperationItem, WebhookItem } from '@/ui/api-page';\nimport type { ProcessedDocument } from '@/utils/process-document';\nimport type { TagObject } from '@/types';\nimport { dump } from 'js-yaml';\nimport { removeUndefined } from '@/utils/remove-undefined';\nimport type { OutputEntry } from '@/utils/pages/builder';\nimport type { InternalOpenAPIMeta } from '@/server/source-api';\nimport { toStaticData } from '@/utils/pages/to-static-data';\n\nexport interface PagesToTextOptions {\n  /**\n   * Additional imports of your MDX components.\n   */\n  imports?: {\n    names: string[];\n    from: string;\n  }[];\n\n  /**\n   * Customise frontmatter.\n   *\n   * A `full: true` property will be added by default.\n   */\n  frontmatter?: (\n    title: string,\n    description: string | undefined,\n    context: DocumentContext,\n  ) => Record<string, unknown>;\n\n  /**\n   * Add description to document body.\n   *\n   * We recommend but don't enable it by default because some OpenAPI schemas have invalid description that breaks MDX syntax.\n   *\n   * @defaultValue false\n   */\n  includeDescription?: boolean;\n\n  /**\n   * Add a comment to the top of generated files indicating they are auto-generated.\n   * - `true`: Adds a standardized comment\n   * - `false`: No comment is added\n   * - `string`: Adds the provided custom comment\n   *\n   * @defaultValue true\n   */\n  addGeneratedComment?: boolean | string;\n}\n\nexport function toText(\n  entry: OutputEntry,\n  processed: ProcessedDocument,\n  options: PagesToTextOptions = {},\n) {\n  switch (entry.type) {\n    case 'operation':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          operations: [entry.item],\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'operation',\n        },\n      );\n    case 'group':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          operations: entry.operations,\n          webhooks: entry.webhooks,\n          showTitle: true,\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'file',\n        },\n      );\n    case 'tag':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          operations: entry.operations,\n          webhooks: entry.webhooks,\n          showTitle: true,\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'tag',\n          tag: entry.rawTag,\n        },\n      );\n    case 'webhook':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          webhooks: [entry.item],\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'operation',\n        },\n      );\n  }\n}\n\nexport function generateDocument(\n  frontmatter: unknown,\n  content: string,\n  options: PagesToTextOptions,\n): string {\n  const { addGeneratedComment = true, imports } = options;\n  const out: string[] = [];\n  const banner = dump(removeUndefined(frontmatter as object)).trimEnd();\n  if (banner.length > 0) out.push(`---\\n${banner}\\n---`);\n\n  if (addGeneratedComment) {\n    let commentContent =\n      'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';\n\n    if (typeof addGeneratedComment === 'string') {\n      commentContent = addGeneratedComment;\n    }\n\n    commentContent = commentContent.replaceAll('/', '\\\\/');\n    out.push(`{/* ${commentContent} */}`);\n  }\n\n  if (imports) {\n    out.push(\n      ...imports\n        .map((item) => `import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`)\n        .join('\\n'),\n    );\n  }\n\n  out.push(content);\n  return out.join('\\n\\n');\n}\n\nexport type DocumentContext =\n  | {\n      type: 'tag';\n      tag: TagObject | undefined;\n    }\n  | {\n      type: 'operation';\n    }\n  | {\n      type: 'file';\n    };\n\nfunction generatePage(\n  schemaId: string,\n  processed: ProcessedDocument,\n  pageProps: Omit<ApiPageProps, 'document'>,\n  options: PagesToTextOptions & {\n    title: string;\n    description?: string;\n  },\n  context: DocumentContext,\n): string {\n  const { frontmatter, includeDescription = false } = options;\n  const extend = frontmatter?.(options.title, options.description, context);\n  const page: ApiPageProps = {\n    ...pageProps,\n    document: schemaId,\n  };\n\n  let meta: InternalOpenAPIMeta | undefined;\n  if (page.operations?.length === 1) {\n    const operation = page.operations[0];\n\n    meta = {\n      method: operation.method.toUpperCase(),\n    };\n  } else if (page.webhooks?.length === 1) {\n    const webhook = page.webhooks[0];\n\n    meta = {\n      method: webhook.method.toUpperCase(),\n      webhook: true,\n    };\n  }\n\n  const data = toStaticData(page, processed.dereferenced);\n  const content: string[] = [];\n\n  if (options.description && includeDescription) content.push(options.description);\n  content.push(pageContent(page));\n\n  return generateDocument(\n    {\n      title: options.title,\n      description: !includeDescription ? options.description : undefined,\n      full: true,\n      ...extend,\n      _openapi: {\n        ...meta,\n        ...data,\n        ...(extend?._openapi as object | undefined),\n      },\n    },\n    content.join('\\n\\n'),\n    options,\n  );\n}\n\nfunction pageContent({\n  showTitle,\n  showDescription,\n  document,\n  webhooks,\n  operations,\n}: ApiPageProps): string {\n  const propStrs: string[] = [`document={${JSON.stringify(document)}}`];\n\n  // filter extra properties in props\n  if (webhooks) {\n    propStrs.push(\n      `webhooks={${JSON.stringify(\n        webhooks.map(\n          (item) =>\n            ({\n              name: item.name,\n              method: item.method,\n            }) satisfies WebhookItem,\n        ),\n      )}}`,\n    );\n  }\n  if (operations) {\n    propStrs.push(\n      `operations={${JSON.stringify(\n        operations.map(\n          (item) =>\n            ({\n              path: item.path,\n              method: item.method,\n            }) satisfies OperationItem,\n        ),\n      )}}`,\n    );\n  }\n  if (showTitle) {\n    propStrs.push(`showTitle={${JSON.stringify(showTitle)}}`);\n  }\n  if (showDescription) {\n    propStrs.push(`showDescription={${JSON.stringify(showDescription)}}`);\n  }\n\n  return `<APIPage ${propStrs.join(' ')} />`;\n}\n"],"mappings":"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"}
+{"version":3,"file":"to-text.js","names":[],"sources":["../../../src/utils/pages/to-text.ts"],"sourcesContent":["import type { ApiPageProps, OperationItem, WebhookItem } from '@/ui/api-page';\nimport type { ProcessedDocument } from '@/utils/process-document';\nimport type { TagObject } from '@/types';\nimport { dump } from 'js-yaml';\nimport { removeUndefined } from '@/utils/remove-undefined';\nimport type { OperationOutput, PageOutput, WebhookOutput } from '@/utils/pages/builder';\nimport type { InternalOpenAPIMeta } from '@/server/source-api';\nimport { toStaticData } from '@/utils/pages/to-static-data';\n\nexport interface PagesToTextOptions {\n  /**\n   * Additional imports of your MDX components.\n   */\n  imports?: {\n    names: string[];\n    from: string;\n  }[];\n\n  /**\n   * Customise frontmatter.\n   *\n   * A `full: true` property will be added by default.\n   */\n  frontmatter?: (\n    title: string,\n    description: string | undefined,\n    context: DocumentContext,\n  ) => Record<string, unknown>;\n\n  /**\n   * Add description to document body.\n   *\n   * We recommend but don't enable it by default because some OpenAPI schemas have invalid description that breaks MDX syntax.\n   *\n   * @defaultValue false\n   */\n  includeDescription?: boolean;\n\n  /**\n   * Add a comment to the top of generated files indicating they are auto-generated.\n   * - `true`: Adds a standardized comment\n   * - `false`: No comment is added\n   * - `string`: Adds the provided custom comment\n   *\n   * @defaultValue true\n   */\n  addGeneratedComment?: boolean | string;\n}\n\nexport function toText(\n  entry: PageOutput | OperationOutput | WebhookOutput,\n  processed: ProcessedDocument,\n  options: PagesToTextOptions = {},\n) {\n  switch (entry.type) {\n    case 'operation':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          operations: [entry.item],\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'operation',\n        },\n      );\n    case 'page':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          operations: entry.operations,\n          webhooks: entry.webhooks,\n          showTitle: true,\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        entry.tag\n          ? {\n              type: 'tag',\n              tag: entry.tag,\n            }\n          : {\n              type: 'file',\n            },\n      );\n    case 'webhook':\n      return generatePage(\n        entry.schemaId,\n        processed,\n        {\n          webhooks: [entry.item],\n        },\n        {\n          ...options,\n          ...entry.info,\n        },\n        {\n          type: 'operation',\n        },\n      );\n  }\n}\n\nexport function generateDocument(\n  frontmatter: unknown,\n  content: string,\n  options: PagesToTextOptions,\n): string {\n  const { addGeneratedComment = true, imports } = options;\n  const out: string[] = [];\n  const banner = dump(removeUndefined(frontmatter as object)).trimEnd();\n  if (banner.length > 0) out.push(`---\\n${banner}\\n---`);\n\n  if (addGeneratedComment) {\n    let commentContent =\n      'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';\n\n    if (typeof addGeneratedComment === 'string') {\n      commentContent = addGeneratedComment;\n    }\n\n    commentContent = commentContent.replaceAll('/', '\\\\/');\n    out.push(`{/* ${commentContent} */}`);\n  }\n\n  if (imports) {\n    out.push(\n      ...imports\n        .map((item) => `import { ${item.names.join(', ')} } from ${JSON.stringify(item.from)};`)\n        .join('\\n'),\n    );\n  }\n\n  out.push(content);\n  return out.join('\\n\\n');\n}\n\nexport type DocumentContext =\n  | {\n      type: 'tag';\n      tag: TagObject | undefined;\n    }\n  | {\n      type: 'operation';\n    }\n  | {\n      type: 'file';\n    };\n\nfunction generatePage(\n  schemaId: string,\n  processed: ProcessedDocument,\n  pageProps: Omit<ApiPageProps, 'document'>,\n  options: PagesToTextOptions & {\n    title: string;\n    description?: string;\n  },\n  context: DocumentContext,\n): string {\n  const { frontmatter, includeDescription = false } = options;\n  const extend = frontmatter?.(options.title, options.description, context);\n  const page: ApiPageProps = {\n    ...pageProps,\n    document: schemaId,\n  };\n\n  let meta: InternalOpenAPIMeta | undefined;\n  if (page.operations?.length === 1) {\n    const operation = page.operations[0];\n\n    meta = {\n      method: operation.method.toUpperCase(),\n    };\n  } else if (page.webhooks?.length === 1) {\n    const webhook = page.webhooks[0];\n\n    meta = {\n      method: webhook.method.toUpperCase(),\n      webhook: true,\n    };\n  }\n\n  const data = toStaticData(page, processed.dereferenced);\n  const content: string[] = [];\n\n  if (options.description && includeDescription) content.push(options.description);\n  content.push(pageContent(page));\n\n  return generateDocument(\n    {\n      title: options.title,\n      description: !includeDescription ? options.description : undefined,\n      full: true,\n      ...extend,\n      _openapi: {\n        ...meta,\n        ...data,\n        ...(extend?._openapi as object | undefined),\n      },\n    },\n    content.join('\\n\\n'),\n    options,\n  );\n}\n\nfunction pageContent({\n  showTitle,\n  showDescription,\n  document,\n  webhooks,\n  operations,\n}: ApiPageProps): string {\n  const propStrs: string[] = [`document={${JSON.stringify(document)}}`];\n\n  // filter extra properties in props\n  if (webhooks) {\n    propStrs.push(\n      `webhooks={${JSON.stringify(\n        webhooks.map(\n          (item) =>\n            ({\n              name: item.name,\n              method: item.method,\n            }) satisfies WebhookItem,\n        ),\n      )}}`,\n    );\n  }\n  if (operations) {\n    propStrs.push(\n      `operations={${JSON.stringify(\n        operations.map(\n          (item) =>\n            ({\n              path: item.path,\n              method: item.method,\n            }) satisfies OperationItem,\n        ),\n      )}}`,\n    );\n  }\n  if (showTitle) {\n    propStrs.push(`showTitle={${JSON.stringify(showTitle)}}`);\n  }\n  if (showDescription) {\n    propStrs.push(`showDescription={${JSON.stringify(showDescription)}}`);\n  }\n\n  return `<APIPage ${propStrs.join(' ')} />`;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "10.4.0",
+  "version": "10.5.0",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "Docs",
@@ -50,17 +50,17 @@
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.4",
     "@scalar/json-magic": "^0.12.4",
-    "@scalar/openapi-upgrader": "^0.2.1",
+    "@scalar/openapi-upgrader": "^0.2.2",
     "ajv": "^8.18.0",
     "class-variance-authority": "^0.7.1",
     "dereference-json-schema": "^0.2.2",
     "github-slugger": "^2.0.0",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "js-yaml": "^4.1.1",
-    "lucide-react": "^0.577.0",
+    "lucide-react": "^1.6.0",
     "next-themes": "^0.4.6",
     "openapi-sampler": "^1.7.2",
-    "react-hook-form": "^7.71.2",
+    "react-hook-form": "^7.72.0",
     "remark": "^15.0.1",
     "remark-rehype": "^11.1.2",
     "tailwind-merge": "^3.5.0",
@@ -68,7 +68,7 @@
     "@fumari/stf": "1.0.3"
   },
   "devDependencies": {
-    "@scalar/api-client-react": "^1.4.11",
+    "@scalar/api-client-react": "^1.4.14",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "25.5.0",
     "@types/openapi-sampler": "^1.0.3",
@@ -76,11 +76,11 @@
     "json-schema-typed": "^8.0.2",
     "shiki": "^4.0.2",
     "tailwindcss": "^4.2.2",
-    "tsdown": "0.21.4",
+    "tsdown": "0.21.5",
     "@fumadocs/tailwind": "0.0.3",
     "eslint-config-custom": "0.0.0",
-    "fumadocs-core": "16.7.0",
-    "fumadocs-ui": "16.7.0",
+    "fumadocs-core": "16.7.6",
+    "fumadocs-ui": "16.7.6",
     "tsconfig": "0.0.0"
   },
   "peerDependencies": {

package/dist/utils/pages/to-body.js

@@ -1,22 +0,0 @@
-//#region src/utils/pages/to-body.ts
-function toBody(entry) {
-	if (entry.type === "operation") return {
-		document: entry.schemaId,
-		operations: [entry.item]
-	};
-	if (entry.type === "webhook") return {
-		document: entry.schemaId,
-		webhooks: [entry.item]
-	};
-	return {
-		showTitle: true,
-		showDescription: true,
-		document: entry.schemaId,
-		operations: entry.operations,
-		webhooks: entry.webhooks
-	};
-}
-//#endregion
-export { toBody };
-
-//# sourceMappingURL=to-body.js.map

package/dist/utils/pages/to-body.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"to-body.js","names":[],"sources":["../../../src/utils/pages/to-body.ts"],"sourcesContent":["import type { ApiPageProps } from '@/ui/api-page';\nimport type { OutputEntry } from '@/utils/pages/builder';\n\nexport function toBody(entry: OutputEntry): ApiPageProps {\n  if (entry.type === 'operation')\n    return {\n      document: entry.schemaId,\n      operations: [entry.item],\n    };\n  if (entry.type === 'webhook')\n    return {\n      document: entry.schemaId,\n      webhooks: [entry.item],\n    };\n\n  return {\n    showTitle: true,\n    showDescription: true,\n    document: entry.schemaId,\n    operations: entry.operations,\n    webhooks: entry.webhooks,\n  };\n}\n"],"mappings":";AAGA,SAAgB,OAAO,OAAkC;AACvD,KAAI,MAAM,SAAS,YACjB,QAAO;EACL,UAAU,MAAM;EAChB,YAAY,CAAC,MAAM,KAAK;EACzB;AACH,KAAI,MAAM,SAAS,UACjB,QAAO;EACL,UAAU,MAAM;EAChB,UAAU,CAAC,MAAM,KAAK;EACvB;AAEH,QAAO;EACL,WAAW;EACX,iBAAiB;EACjB,UAAU,MAAM;EAChB,YAAY,MAAM;EAClB,UAAU,MAAM;EACjB"}