@powerduck/tree 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 powerduck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,556 @@
+# @powerduck/tree
+
+Extensible tree component for API navigation, schema exploration, and documentation. Built on a generic core with adapters for OpenAPI, JSON Schema, and custom data sources.
+
+[Website](https://www.powerduck.com) · [Documentation](https://www.powerduck.com/docs/tree) · [GitHub](https://github.com/powerducklab/tree) · [npm](https://www.npmjs.com/package/@powerduck/tree)
+
+## Features
+
+- **Generic core** — `TreeNode<TMetadata>` works with any data source
+- **OpenAPI adapter** — tag-based navigation with OAS 3.2 native parent nesting, `x-tagGroups`, `x-order`, `x-displayName`, `x-internal`
+- **JSON Schema adapter** — deep expansion of nested properties, arrays, combinators with `jsonPath` metadata for editor line jumping
+- **Doc adapter** — Stripe-style documentation tree with operation count badges, parameters, request body, and responses
+- **React component** — search, expand/collapse toggle (Material Design unfold icons), keyboard navigation, method badges, custom render props, `searchRowExtra` for inline toolbar extensions
+- **Drag and drop** — reorder within the same parent **and cross-level move into folders**, with three-zone drop detection, `canDrag`/`canDrop` predicates, `dragGroupKey` isolation, `onReorder`/`onMove` callbacks, and circular reference prevention
+- **Context menu** — right-click or the more (…) button for per-node actions, with custom item definitions, icons, separators, danger styling, and two-step confirm for destructive actions
+- **Imperative locate** — `locateNode(predicate)` finds a node, expands all ancestors, selects it, and scrolls into view (ideal for "jump to API" features)
+- **JSON Patch integration** — `onPatch` callback emits RFC 6902 operations for reorder/move/delete, compatible with [`@powerduck/conf-patch`](https://www.npmjs.com/package/@powerduck/conf-patch) for applying to the original document
+- **High-quality icons** — powered by [react-icons](https://react-icons.github.io/react-icons/) (Lucide + Material Design icon sets)
+- **CSS variable theming** — compatible with powerduck `tokens.css`, light/dark mode
+- **Zero hard dependencies** — core and adapters have no runtime dependencies; React layer requires `react`, `react-dom`, and `react-icons`
+
+## Installation
+
+```bash
+npm install @powerduck/tree
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom react-icons
+```
+
+### CSS Import
+
+Import the component styles in your app entry point:
+
+```ts
+import "@powerduck/tree/react/index.css";
+```
+
+## Quick Start
+
+### API Debug Tree
+
+```tsx
+import { useMemo } from "react";
+import { buildOpenApiTree } from "@powerduck/tree";
+import { Tree } from "@powerduck/tree/react";
+
+function ApiNav({ document }) {
+  const { root } = useMemo(() => buildOpenApiTree(document), [document]);
+
+  return (
+    <div style={{ width: 320, height: "100%" }}>
+      <Tree
+        nodes={root.children ?? []}
+        onSelect={(node) => console.log(node.metadata?.method, node.metadata?.path)}
+        searchable
+        showExpandAll
+        defaultExpandDepth={2}
+      />
+    </div>
+  );
+}
+```
+
+### Schema Navigation Tree
+
+```tsx
+import { useMemo } from "react";
+import { buildSchemaTree } from "@powerduck/tree";
+import { Tree } from "@powerduck/tree/react";
+
+function SchemaNav({ schema, editorRef }) {
+  const { root } = useMemo(() => buildSchemaTree(schema), [schema]);
+
+  const handleSelect = (node) => {
+    const jsonPath = node.metadata?.jsonPath;
+    if (jsonPath) {
+      editorRef.current?.revealLine(jsonPath);
+    }
+  };
+
+  return (
+    <Tree
+      nodes={root.children ?? []}
+      onSelect={handleSelect}
+      searchable
+      defaultExpandDepth={3}
+    />
+  );
+}
+```
+
+### Custom Data Source
+
+```tsx
+import { Tree } from "@powerduck/tree/react";
+import type { TreeNode } from "@powerduck/tree/core";
+
+interface FileMeta {
+  type: "folder" | "file";
+  size?: number;
+}
+
+const files: TreeNode<FileMeta>[] = [
+  {
+    id: "src",
+    name: "src",
+    metadata: { type: "folder" },
+    children: [
+      { id: "src/index.ts", name: "index.ts", metadata: { type: "file", size: 512 } },
+    ],
+  },
+];
+
+function FileTree() {
+  return <Tree nodes={files} searchable defaultExpandDepth={1} />;
+}
+```
+
+## Drag and Drop
+
+Enable drag and drop with the `draggable` prop. Nodes can be reordered within the same parent **or moved into a different parent** (cross-level) by dragging the grip handle.
+
+### Reordering (same level)
+
+```tsx
+import { useState } from "react";
+import { Tree } from "@powerduck/tree/react";
+import type { ReorderResult } from "@powerduck/tree/core";
+
+function SortableTree({ initialNodes }) {
+  const [nodes, setNodes] = useState(initialNodes);
+
+  const handleReorder = (result: ReorderResult) => {
+    console.log(`Moved "${result.moved.name}" from index ${result.fromIndex} to ${result.toIndex}`);
+    setNodes(result.nodes);
+  };
+
+  return (
+    <Tree
+      nodes={nodes}
+      draggable
+      onReorder={handleReorder}
+    />
+  );
+}
+```
+
+### Cross-level move (drag into folder)
+
+When dragging over a branch node, the middle 50% of the row highlights the node as a drop target (folder). Dropping there moves the node to become a child of that folder.
+
+```tsx
+import { useState } from "react";
+import { Tree } from "@powerduck/tree/react";
+import type { TreeNode } from "@powerduck/tree/core";
+
+function MoveableTree({ initialNodes }) {
+  const [nodes, setNodes] = useState(initialNodes);
+
+  const handleMove = (newNodes: TreeNode[], movedNode, targetParentId) => {
+    console.log(`Moved "${movedNode.name}" into folder "${targetParentId}"`);
+    setNodes(newNodes);
+  };
+
+  return (
+    <Tree
+      nodes={nodes}
+      draggable
+      onReorder={(result) => setNodes(result.nodes)}
+      onMove={handleMove}
+    />
+  );
+}
+```
+
+Drop zones on a branch node:
+- **Top 25%** — insert before (reorder)
+- **Middle 50%** — move into this folder (cross-level)
+- **Bottom 25%** — insert after (reorder)
+
+Circular references are automatically prevented: a node cannot be dropped into its own descendant.
+
+### Control which nodes can be dragged
+
+```tsx
+<Tree
+  nodes={nodes}
+  draggable
+  canDrag={(node) => node.metadata?.type !== "folder"}
+  onReorder={handleReorder}
+/>
+```
+
+### Control where nodes can be dropped
+
+```tsx
+<Tree
+  nodes={nodes}
+  draggable
+  canDrop={(dragged, target, position) => {
+    /* position is "before" | "after" | "child" */
+    return position !== "child" || target.metadata?.type === "folder";
+  }}
+  onReorder={handleReorder}
+  onMove={(nodes) => setNodes(nodes)}
+/>
+```
+
+## Imperative Handle
+
+Access tree methods via `ref`:
+
+```tsx
+import { useRef } from "react";
+import { Tree } from "@powerduck/tree/react";
+import type { TreeHandle } from "@powerduck/tree/react";
+
+function TreeWithLocate() {
+  const treeRef = useRef<TreeHandle>(null);
+
+  const locateByOperationId = (operationId: string) => {
+    const found = treeRef.current?.locateNode((node) =>
+      node.metadata?.operationId === operationId
+    );
+    /* found is the matched TreeNode, or undefined if not found */
+  };
+
+  return (
+    <>
+      <button onClick={() => locateByOperationId("getPet")}>Locate getPet</button>
+      <Tree ref={treeRef} nodes={nodes} />
+    </>
+  );
+}
+```
+
+### Handle methods
+
+| Method | Description |
+| --- | --- |
+| `expandAll()` | Expand all nodes |
+| `collapseAll()` | Collapse all nodes |
+| `expandToDepth(depth)` | Expand nodes to a specific depth |
+| `getExpandedIds()` | Get currently expanded node IDs |
+| `getSelectedNode()` | Get the currently selected node |
+| `scrollToNode(id)` | Scroll a node into view by ID |
+| `locateNode(predicate)` | Find a node by predicate, expand ancestors, select, and scroll into view |
+
+## Context Menu
+
+Enable per-node actions via right-click or the more (…) button that appears on row hover. Define menu items with the `contextMenuItems` prop.
+
+```tsx
+import { LuCopy, LuTrash2 } from "react-icons/lu";
+import { Tree } from "@powerduck/tree/react";
+import type { ContextMenuItem } from "@powerduck/tree/react";
+
+function ApiTree({ nodes }) {
+  const buildMenu = (node): ContextMenuItem[] => [
+    {
+      label: "Copy operationId",
+      icon: <LuCopy size={14} />,
+      onClick: (n) => navigator.clipboard.writeText(n.metadata?.operationId ?? ""),
+    },
+    { separator: true, label: "", onClick: () => undefined },
+    {
+      label: "Delete",
+      icon: <LuTrash2 size={14} />,
+      danger: true,
+      onClick: (n) => console.log("Delete", n.id),
+    },
+  ];
+
+  return <Tree nodes={nodes} contextMenuItems={buildMenu} />;
+}
+```
+
+### ContextMenuItem properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `string` | Display text |
+| `icon` | `ReactNode` | Optional icon before label |
+| `onClick` | `(node) => void` | Click handler |
+| `disabled` | `boolean` | Disable the item |
+| `danger` | `boolean` | Red text for destructive actions |
+| `separator` | `boolean` | Render a horizontal line above this item |
+
+## JSON Patch & conf-patch Integration
+
+When nodes carry a `jsonPath` in their metadata, the tree emits RFC 6902 JSON Patch operations via the `onPatch` callback. Apply these to the original document with [`@powerduck/conf-patch`](https://www.npmjs.com/package/@powerduck/conf-patch).
+
+```tsx
+import { patchContent } from "@powerduck/conf-patch/core";
+import { Tree } from "@powerduck/tree/react";
+import type { JsonPatchOp } from "@powerduck/tree/react";
+
+function EditableTree({ initialDocument, format }) {
+  const [document, setDocument] = useState(initialDocument);
+
+  const handlePatch = (ops: JsonPatchOp[]) => {
+    /* Apply patch operations to the document string. */
+    const updated = patchContent(document, ops, format);
+    setDocument(updated);
+  };
+
+  return (
+    <Tree
+      nodes={nodes}
+      draggable
+      onReorder={(result) => setNodes(result.nodes)}
+      onPatch={handlePatch}
+    />
+  );
+}
+```
+
+Patch operations are currently emitted for **reorder** (array `move`). Nodes must have `metadata.jsonPath` as an array of path segments for patch generation.
+
+## API Reference
+
+### Core
+
+#### `TreeNode<TMetadata>`
+
+```ts
+interface TreeNode<TMetadata = unknown> {
+  id: string;
+  name: string;
+  order?: number;
+  children?: TreeNode<TMetadata>[];
+  metadata?: TMetadata;
+}
+```
+
+#### Tree Utilities
+
+| Function | Description |
+|----------|-------------|
+| `findNode(nodes, id)` | Find a node by ID |
+| `findPath(nodes, id)` | Find full path from root to node |
+| `getLeaves(nodes)` | Get all leaf nodes |
+| `countNodes(nodes)` | Count all nodes |
+| `getMaxDepth(nodes)` | Get maximum tree depth |
+| `sortNodes(nodes)` | Sort by order, then name |
+| `sortTree(nodes)` | Recursively sort all levels |
+| `filterTree(nodes, { query })` | Filter by search query |
+| `getExpandableIds(nodes, { maxDepth })` | Get IDs to expand |
+| `getBranchIds(nodes)` | Get all branch node IDs |
+| `flattenTree(nodes)` | Flatten to pre-order list with depth |
+| `updateNode(nodes, id, updater)` | Immutable node update |
+| `removeNode(nodes, id)` | Immutable node removal |
+| `insertChild(nodes, parentId, child)` | Immutable child insertion |
+
+### OpenAPI Adapter
+
+#### `buildOpenApiTree(document, options?)`
+
+```ts
+interface OpenApiTreeOptions {
+  showInternal?: boolean;      // default false
+  showComponents?: boolean;    // default true
+  showWebhooks?: boolean;      // default true
+  defaultExpandDepth?: number; // default 2
+}
+```
+
+**Navigation strategy (priority order):**
+1. OAS 3.2 native `parent`-nested tags
+2. `x-tagGroups` (with powerduck nested `groups` extension)
+3. Flat tag grouping (fallback)
+
+**Supported extensions:**
+- `x-order` — sort tags and operations
+- `x-displayName` — human-friendly tag label
+- `x-internal` / `x-scalar-ignore` — hide operations
+- `x-tagGroups` — group tags into navigation folders
+
+### JSON Schema Adapter
+
+#### `buildSchemaTree(schema, options?)`
+
+```ts
+interface SchemaTreeOptions {
+  maxDepth?: number;          // default 8
+  showDeprecated?: boolean;   // default true
+  expandCombinators?: boolean; // default true
+  showArrayItems?: boolean;   // default true
+}
+```
+
+#### `findSchemaNodeByPath(root, jsonPath)`
+
+Find a schema tree node by its JSON path.
+
+#### `formatSchemaType(metadata)`
+
+Format a schema type label for display (e.g. `"string (email)"`, `"string | null"`).
+
+### Doc Adapter
+
+#### `buildDocTree(document, options?)`
+
+```ts
+interface DocTreeOptions {
+  showInternal?: boolean;         // default false
+  showComponents?: boolean;       // default true
+  showWebhooks?: boolean;         // default true
+  expandOperationDetails?: boolean; // default true
+}
+```
+
+Builds a Stripe-style documentation tree where each operation expands to show parameters, request body, and responses.
+
+### React Component
+
+#### `<Tree />` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nodes` | `TreeNode[]` | required | Root nodes to render |
+| `onSelect` | `(node) => void` | — | Called when a leaf node is clicked |
+| `onExpandedChange` | `(ids) => void` | — | Called when expanded nodes change |
+| `defaultExpandedIds` | `string[]` | — | Initially expanded node IDs |
+| `defaultExpandDepth` | `number` | `1` | Default expansion depth |
+| `searchable` | `boolean` | `false` | Show search input |
+| `searchPlaceholder` | `string` | `"Search..."` | Search input placeholder |
+| `searchRowExtra` | `ReactNode` | — | Extra content inside the search row (between input and action buttons) |
+| `showExpandAll` | `boolean` | `false` | Show expand/collapse all toggle button (single toggle, Material Design unfold icons) |
+| `showRefresh` | `boolean` | `false` | Show refresh button |
+| `onRefresh` | `() => void` | — | Called when refresh button is clicked |
+| `toolbar` | `ReactNode` | — | Custom toolbar content rendered above the tree |
+| `renderNode` | `(ctx, defaultNode) => ReactNode` | — | Fully custom node renderer |
+| `renderIcon` | `(ctx) => ReactNode` | — | Custom icon renderer |
+| `renderLabel` | `(ctx) => ReactNode` | — | Custom label renderer |
+| `renderSuffix` | `(ctx) => ReactNode` | — | Custom suffix (badges, count, etc.) |
+| `className` | `string` | — | Additional CSS class |
+| `style` | `CSSProperties` | — | Inline styles |
+| `size` | `"xs" \| "sm" \| "md"` | `"sm"` | Size variant |
+| `showIndentGuides` | `boolean` | `true` | Show indent guide lines |
+| `maxHeight` | `number \| string` | — | Max height before scrolling |
+| `draggable` | `boolean` | `false` | Enable drag and drop reordering |
+| `dragGroupKey` | `string` | — | Metadata key for drag isolation (nodes with different group values cannot intermix) |
+| `onReorder` | `(result: ReorderResult) => void` | — | Called when a node is reordered within the same parent |
+| `onMove` | `(nodes, movedNode, targetParentId) => void` | — | Called when a node is moved to a different parent |
+| `canDrag` | `(node) => boolean` | — | Predicate to control which nodes can be dragged |
+| `canDrop` | `(dragged, target, position) => boolean` | — | Predicate to control allowed drop targets |
+| `contextMenuItems` | `(node) => ContextMenuItem[]` | — | Right-click / more-button context menu items |
+| `onPatch` | `(ops, context) => void` | — | Called with RFC 6902 JSON Patch ops on reorder (for conf-patch integration) |
+
+#### Tree Handle (via ref)
+
+```ts
+interface TreeHandle {
+  expandAll: () => void;
+  collapseAll: () => void;
+  expandToDepth: (depth: number) => void;
+  getExpandedIds: () => string[];
+  getSelectedNode: () => TreeNode | undefined;
+  scrollToNode: (id: string) => void;
+}
+```
+
+## Architecture
+
+```
+@powerduck/tree
+├── core/           Generic tree types and utilities (zero dependencies)
+├── adapters/       Data source adapters
+│   ├── openapi.ts    OpenAPI document → navigation tree
+│   ├── json-schema.ts JSON Schema → deep exploration tree
+│   └── doc.ts        OpenAPI → Stripe-style documentation tree
+├── react/          React Tree component
+│   ├── Tree.tsx       Main component
+│   ├── Tree.module.css Styles (CSS variables)
+│   ├── hooks/         useTreeSearch, useTreeExpansion
+│   └── libs/          Types and utilities
+└── index.ts          Main entry (core + adapters)
+```
+
+### Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@powerduck/tree` | Core types, utilities, and all adapters |
+| `@powerduck/tree/react` | React Tree component and hooks |
+| `@powerduck/tree/adapters` | OpenAPI, JSON Schema, and Doc adapters |
+| `@powerduck/tree/core` | Core types and utilities only |
+
+## Theming
+
+The component uses CSS variables that align with powerduck's `tokens.css`. Override them in your application:
+
+```css
+:root {
+  --color-surface: #ffffff;
+  --color-text-primary: #26282b;
+  --color-accent: #f28c28;
+  /* ... see tokens.css for full list */
+}
+
+:root[data-theme="dark"] {
+  --color-surface: #1f2125;
+  --color-text-primary: #edf0f3;
+  /* ... */
+}
+```
+
+## OAS 3.2 Nested Tags
+
+OAS 3.2 supports native tag nesting via the `parent` field:
+
+```yaml
+tags:
+  - name: Account
+  - name: Users
+    parent: Account
+  - name: Admin
+    parent: Account
+  - name: Roles
+    parent: Admin
+```
+
+The adapter automatically detects and resolves nested tags, with circular reference detection and unknown parent warnings.
+
+## x-tagGroups with Nested Folders
+
+The powerduck extension supports nested groups via the `groups` field:
+
+```yaml
+x-tagGroups:
+  - name: Account
+    tags: [Users]
+    groups:
+      - name: Admin
+        tags: [Roles, Permissions]
+```
+
+Redoc and Scalar safely ignore the unknown `groups` field.
+
+## Development
+
+```bash
+npm install
+npm run build      # Build with tsup
+npm run test       # Run tests with vitest
+npm run typecheck  # Type check with tsc
+```
+
+## License
+
+MIT

package/dist/adapters/index.cjs

@@ -0,0 +1 @@
+"use strict";var e,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,r=Object.prototype.hasOwnProperty,a={};function s(e){return[...e].sort((e,t)=>{const n=e.order??Number.MAX_SAFE_INTEGER,o=t.order??Number.MAX_SAFE_INTEGER;if(n!==o)return n-o;return e.name.localeCompare(t.name,"en-US",{numeric:!0,sensitivity:"base"})||e.id.localeCompare(t.id)})}((e,n)=>{for(var o in n)t(e,o,{get:n[o],enumerable:!0})})(a,{buildDocTree:()=>z,buildOpenApiTree:()=>y,buildSchemaTree:()=>v,findSchemaNodeByPath:()=>N,formatSchemaType:()=>C}),module.exports=(e=a,((e,a,s,i)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let c of o(a))r.call(e,c)||c===s||t(e,c,{get:()=>a[c],enumerable:!(i=n(a,c))||i.enumerable});return e})(t({},"__esModule",{value:!0}),e));var i=["get","put","post","delete","options","head","patch","trace"],c={showInternal:!1,showComponents:!0,showWebhooks:!0,defaultExpandDepth:2};function d(e){return"object"!=typeof e||null===e||Array.isArray(e)?null:e}function p(e){return"string"==typeof e&&e.trim().length>0?e.trim():void 0}function u(e){return"boolean"==typeof e?e:void 0}function m(e){return Array.isArray(e)?e:void 0}function f(e,t){return!t&&(!0===u(e["x-scalar-ignore"])||!0===u(e["x-internal"]))}function h(e){return"number"==typeof(t=e["x-order"])&&Number.isFinite(t)?t:void 0;var t}function l(e){return p(e["x-displayName"])}function g(e,t,n,o){const r=new Map;for(const t of e)r.set(t.name,t);const a=new Map;for(const t of e){if(!t.parent){a.set(t.name,null);continue}if(!r.has(t.parent)){o.push(`Tag "${t.name}" references unknown parent "${t.parent}", treating as root.`),a.set(t.name,null);continue}const e=[t.name];let n=t.parent,s=!1;for(;n;){if(e.includes(n)){s=!0,o.push(`Circular tag reference detected: ${e.join(" -> ")} -> ${n}. Breaking cycle.`);break}e.push(n),n=r.get(n)?.parent}a.set(t.name,s?null:t.parent)}const i=new Map;for(const e of t){if(f(e.raw,n.showInternal))continue;const t=e.tags.length>0?e.tags:["Other"];for(const n of t){const t=i.get(n)??[];t.push(e),i.set(n,t)}}const c=new Map;for(const t of e){const e=a.get(t.name)??null??"__root__",n=c.get(e)??[];n.push(t),c.set(e,n)}const d=e=>s((c.get(e)??[]).map(e=>{const t=(e=>{const t=(i.get(e.name)??[]).map(t=>({id:`op:${e.name}:${t.id}`,name:t.name,order:h(t.raw),metadata:{method:t.method,path:t.path,operationId:t.operationId,deprecated:t.deprecated,summary:t.summary,pointer:t.pointer,source:"oas32-parent",kind:"operation"}}));return{id:`tag:${e.name}`,name:e.displayName,order:e.order,children:s(t),metadata:{source:"oas32-parent",kind:"tag"}}})(e),n=d(e.name);return n.length>0&&(t.children=s([...t.children??[],...n])),t})),p=d("__root__"),u=i.get("Other")??[];if(u.length>0){const e=u.map(e=>({id:`op:Other:${e.id}`,name:e.name,order:h(e.raw),metadata:{method:e.method,path:e.path,operationId:e.operationId,deprecated:e.deprecated,summary:e.summary,pointer:e.pointer,source:"fallback",kind:"operation"}}));p.push({id:"tag:Other",name:"Other",order:Number.MAX_SAFE_INTEGER,children:s(e),metadata:{source:"fallback",kind:"tag"}})}return s(p)}function y(e,t={}){const n={...c,...t},o=[],r=d(e);if(!r)return{root:{id:"root",name:"OpenAPI",children:[],metadata:{kind:"root"}},warnings:["Document is null or not an object."]};const a=function(e){const t=d(e.paths);if(!t)return[];const n=[];for(const[e,o]of Object.entries(t)){const t=d(o);if(t)for(const o of i){const r=t[o];if(null==r)continue;const a=d(r);if(!a)continue;const s=p(a.operationId),i=p(a.summary),c=m(a.tags)?.filter(e=>"string"==typeof e).map(e=>e.trim()).filter(e=>e.length>0)??[],f=i??s??`${o.toUpperCase()} ${e}`,h=s??`${o}:${e}`,l=`/paths/${encodeURIComponent(e)}/${o}`;n.push({id:h,path:e,method:o,name:f,summary:i,operationId:s,deprecated:!0===u(a.deprecated),tags:c,pointer:l,raw:a})}}return n}(r),y=function(e){const t=m(e.tags);if(!t)return[];const n=[];for(const e of t){const t=d(e),o=p(t?.name);o&&t&&n.push({name:o,displayName:l(t)??o,description:p(t.description),parent:p(t.parent),order:h(t),raw:t})}return n}(r);let $;if(function(e){return e.some(e=>void 0!==e.parent)}(y))$=g(y,a,n,o);else{const e=function(e){const t=m(e["x-tagGroups"]);if(!t)return[];const n=(e,t)=>{const o=d(e),r=p(o?.name),a=m(o?.tags)?.filter(e=>"string"==typeof e).map(e=>e.trim()).filter(e=>e.length>0)??[];if(!r)return null;const s=m(o?.groups)?.map((e,t)=>n(e,t)).filter(e=>null!==e)??[];return{name:r,tags:a,groups:s.length>0?s:void 0,order:h(o??{})??t}};return t.map((e,t)=>n(e,t)).filter(e=>null!==e)}(r);$=e.length>0?function(e,t,n,o){const r=new Map;for(const e of t)r.set(e.name,e.displayName);const a=new Map;for(const e of n)if(!f(e.raw,o.showInternal))for(const t of e.tags){const n=a.get(t)??[];n.push(e),a.set(t,n)}const i=e=>(a.get(e)??[]).map(t=>({id:`op:${e}:${t.id}`,name:t.name,order:h(t.raw),metadata:{method:t.method,path:t.path,operationId:t.operationId,deprecated:t.deprecated,summary:t.summary,pointer:t.pointer,source:"tag-group",kind:"operation"}})),c=e=>({id:`tag:${e}`,name:r.get(e)??e,children:s(i(e)),metadata:{source:"tag-group",kind:"tag"}}),d=e=>{const t=[];for(const n of e.tags){const e=a.get(n);e?.length&&t.push(c(n))}for(const n of e.groups??[])t.push(d(n));return{id:`tag-group:${e.name}`,name:e.name,order:e.order,children:s(t),metadata:{source:"tag-group",kind:"tag-group"}}};return s(e.map(d))}(e,y,a,n):function(e,t,n){const o=new Map,r=new Map;for(let t=0;t<e.length;t+=1){const n=e[t];r.set(n.name,n.order??t)}for(const e of t){if(f(e.raw,n.showInternal))continue;const t=e.tags.length>0?e.tags:["Other"];for(const n of t){const t=o.get(n)??[];t.push(e),o.set(n,t)}}const a=new Map;for(const t of e)a.set(t.name,t.displayName);const i=[];for(const[e,t]of o){const n=t.map(t=>({id:`op:${e}:${t.id}`,name:t.name,order:h(t.raw),metadata:{method:t.method,path:t.path,operationId:t.operationId,deprecated:t.deprecated,summary:t.summary,pointer:t.pointer,source:"tag",kind:"operation"}}));i.push({id:`tag:${e}`,name:a.get(e)??e,order:"Other"===e?Number.MAX_SAFE_INTEGER:r.get(e),children:s(n),metadata:{source:"tag",kind:"tag"}})}return s(i)}(y,a,n)}const k=function(e,t){if(!t.showWebhooks)return;const n=d(e.webhooks);if(!n)return;const o=[];for(const[e,r]of Object.entries(n)){const n=d(r);if(n)for(const r of i){const a=d(n[r]);if(!a||f(a,t.showInternal))continue;const s=p(a.operationId),i=p(a.summary),c=i??s??`${r.toUpperCase()} ${e}`;o.push({id:`webhook:${e}:${r}`,name:c,order:h(a),metadata:{method:r,path:e,operationId:s,deprecated:!0===u(a.deprecated),summary:i,pointer:`/webhooks/${encodeURIComponent(e)}/${r}`,source:"tag",kind:"webhook"}})}}return 0!==o.length?{id:"section:webhooks",name:"Webhooks",order:Number.MAX_SAFE_INTEGER-2,children:s(o),metadata:{source:"section",kind:"section",section:"webhooks"}}:void 0}(r,n),w=function(e,t){if(!t.showComponents)return;const n=d(e.components),o=d(n?.schemas);if(!o)return;const r=[];for(const[e,n]of Object.entries(o)){const o=d(n);o&&!f(o,t.showInternal)&&r.push({id:`schema:${e}`,name:e,order:h(o),metadata:{pointer:`/components/schemas/${encodeURIComponent(e)}`,source:"tag",kind:"schema"}})}return 0!==r.length?{id:"section:components",name:"Components",order:Number.MAX_SAFE_INTEGER-1,children:s(r),metadata:{source:"section",kind:"section",section:"components"}}:void 0}(r,n);return{root:{id:"root",name:"OpenAPI",children:s([{id:"section:apis",name:"APIs",children:$,metadata:{kind:"section",source:"section",section:"apis"},order:0},...k?[k]:[],...w?[w]:[]]),metadata:{kind:"root"}},warnings:o}}var $={openapi:0,info:1,servers:2,paths:3,webhooks:4,components:5,security:6,tags:7,externalDocs:8,jsonSchemaDialect:9},k={maxDepth:8,showDeprecated:!0,expandCombinators:!0,showArrayItems:!0},w=new Set(["string","number","integer","boolean","null"]);function b(e){return"object"!=typeof e||null===e||Array.isArray(e)?null:e}function I(e){return"string"==typeof e&&e.trim().length>0?e.trim():void 0}function A(e){return"boolean"==typeof e?e:void 0}function O(e){return Array.isArray(e)?e:void 0}function j(e){return e?Array.isArray(e)?e.join(" | "):e:"any"}function _(e,t,n,o,r,a){const i=function(e){const t=e.type;return"string"==typeof t||Array.isArray(t)&&t.every(e=>"string"==typeof e)?t:void 0}(t),c=I(t.format),d=I(t.description),p=!0===A(t.deprecated),u=function(e){if(!e)return"unknown";switch(Array.isArray(e)?e[0]:e){case"object":return"object";case"array":return"array";case"string":return"string";case"number":return"number";case"integer":return"integer";case"boolean":return"boolean";case"null":return"null";default:return"unknown"}}(i),m={jsonPath:n,type:i,format:c,required:a,deprecated:p,description:d,kind:u},f=I(t.$ref);if(f){if(r.refStack.has(f))return r.warnings.push(`Circular $ref detected at ${n.join(".")}: ${f}. Breaking recursion.`),{id:n.join(".")||"root",name:e,metadata:{...m,kind:"ref",isLeaf:!0}};r.refStack.add(f)}let h,l=function(e){return!!e&&(Array.isArray(e)?e.every(e=>w.has(e)):w.has(e))}(i);if(o>=r.options.maxDepth)return f&&r.refStack.delete(f),{id:n.join(".")||"root",name:e,metadata:{...m,isLeaf:!0}};const g=b(t.properties);if(g){const e=O(t.required)??[],a=new Set(e.filter(e=>"string"==typeof e)),i=[];for(const[e,t]of Object.entries(g)){const s=b(t);s&&((r.options.showDeprecated||!0!==A(s.deprecated))&&i.push(_(e,s,[...n,"properties",e],o+1,r,a.has(e))))}h=[...h??[],...s(i)],l=!1}if(r.options.showArrayItems&&"array"===i){const e=b(t.items);if(e){h=[...h??[],_("items",e,[...n,"items"],o+1,r,!1)],l=!1}else m.hasItems=!1}if(r.options.expandCombinators){const e=[{key:"allOf",kind:"allOf"},{key:"anyOf",kind:"anyOf"},{key:"oneOf",kind:"oneOf"}];for(const{key:a,kind:i}of e){const e=O(t[a]);if(!e?.length)continue;const c=e.map((e,t)=>{const s=b(e);return s?_(`[${t}]`,s,[...n,a,String(t)],o+1,r,!1):{id:`${n.join(".")}.${a}[${t}]`,name:`[${t}]`,metadata:{jsonPath:[...n,a,String(t)],kind:"unknown",isLeaf:!0}}});h=[...h??[],{id:`${n.join(".")}.${a}`,name:a,children:s(c),metadata:{jsonPath:[...n,a],kind:i}}],l=!1}}const y=O(t.enum);return y?.length&&!h?.length&&(m.kind="enum",l=!0),f&&r.refStack.delete(f),{id:n.join(".")||"root",name:e,order:$[e],metadata:{...m,isLeaf:l},children:h}}function v(e,t={}){const n={...k,...t},o=[],r=b(e);if(!r)return{root:{id:"root",name:"Schema",metadata:{jsonPath:[],kind:"root",isLeaf:!0}},warnings:["Schema is null or not an object."]};return{root:_("root",r,[],0,{options:n,warnings:o,refStack:new Set},!0),warnings:o}}function N(e,t){if(0===t.length)return e;const n=t.join("."),o=[e];for(;o.length>0;){const e=o.shift();if(!e)continue;const t=e.metadata?.jsonPath?.join(".");if(t===n)return e;for(const t of e.children??[])o.push(t)}}function C(e){return"enum"===e.kind?"enum":"ref"===e.kind?"$ref":e.format?`${j(e.type)} (${e.format})`:j(e.type)}var E=["get","put","post","delete","options","head","patch","trace"],M={showInternal:!1,showComponents:!1,showWebhooks:!0,expandOperationDetails:!0};function S(e){return"object"!=typeof e||null===e||Array.isArray(e)?null:e}function R(e){return"string"==typeof e&&e.trim().length>0?e.trim():void 0}function x(e){return"boolean"==typeof e?e:void 0}function T(e){return Array.isArray(e)?e:void 0}function U(e,t){return!t&&(!0===x(e["x-scalar-ignore"])||!0===x(e["x-internal"]))}function P(e){const t=e["x-order"];return"number"==typeof t&&Number.isFinite(t)?t:void 0}function D(e){return R(e["x-displayName"])}function G(e,t){const n=[],o=T(e.parameters);if(o?.length){const e=function(e,t){const n=[];for(const o of e){const e=S(o);if(!e)continue;const r=R(e.name),a=R(e.in);if(!r||!a)continue;const s=`${a}:${r}`;n.push({id:`${t}/parameters/${encodeURIComponent(s)}`,name:r,metadata:{paramIn:a,required:!0===x(e.required),description:R(e.description),pointer:`${t}/parameters`,kind:"parameter"}})}return s(n)}(o,t);e.length>0&&n.push({id:`${t}/parameters`,name:"Parameters",children:e,metadata:{pointer:`${t}/parameters`,kind:"parameters"}})}const r=S(e.requestBody);if(r){const e=S(r.content),o=[];if(e)for(const[n]of Object.entries(e))o.push({id:`${t}/requestBody/content/${encodeURIComponent(n)}`,name:n,metadata:{contentType:n,pointer:`${t}/requestBody/content/${encodeURIComponent(n)}`,kind:"content"}});n.push({id:`${t}/requestBody`,name:"Request Body",metadata:{description:R(r.description),required:!0===x(r.required),pointer:`${t}/requestBody`,kind:"request-body"},children:o.length>0?o:void 0})}const a=S(e.responses);if(a){const e=function(e,t){const n=[];for(const[o,r]of Object.entries(e)){const e=S(r);if(!e)continue;const a=R(e.description),s=S(e.content),i=[];if(s)for(const[e]of Object.entries(s))i.push({id:`${t}/responses/${encodeURIComponent(o)}/content/${encodeURIComponent(e)}`,name:e,metadata:{contentType:e,pointer:`${t}/responses/${encodeURIComponent(o)}/content/${encodeURIComponent(e)}`,kind:"content"}});n.push({id:`${t}/responses/${encodeURIComponent(o)}`,name:o,metadata:{statusCode:o,description:a,pointer:`${t}/responses/${encodeURIComponent(o)}`,kind:"response"},children:i.length>0?i:void 0})}return s(n)}(a,t);e.length>0&&n.push({id:`${t}/responses`,name:"Responses",children:e,metadata:{pointer:`${t}/responses`,kind:"responses"}})}return n}function q(e,t,n,o){const r=t.expandOperationDetails?G(e.raw,e.pointer):void 0;return{id:`op:${o}:${e.id}`,name:e.name,order:P(e.raw),metadata:{method:e.method,path:e.path,operationId:e.operationId,deprecated:e.deprecated,summary:e.summary,description:e.description,pointer:e.pointer,source:n,kind:"operation"},children:r&&r.length>0?r:void 0}}function F(e,t,n,o){const r=new Map;for(const t of e)r.set(t.name,t);const a=new Map;for(const t of e){if(!t.parent){a.set(t.name,null);continue}if(!r.has(t.parent)){o.push(`Tag "${t.name}" references unknown parent "${t.parent}", treating as root.`),a.set(t.name,null);continue}const e=[t.name];let n=t.parent,s=!1;for(;n;){if(e.includes(n)){s=!0,o.push(`Circular tag reference detected: ${e.join(" -> ")} -> ${n}. Breaking cycle.`);break}e.push(n),n=r.get(n)?.parent}a.set(t.name,s?null:t.parent)}const i=new Map;for(const e of t){if(U(e.raw,n.showInternal))continue;const t=e.tags.length>0?e.tags:["Other"];for(const n of t){const t=i.get(n)??[];t.push(e),i.set(n,t)}}const c=new Map;for(const t of e){const e=a.get(t.name)??null??"__root__",n=c.get(e)??[];n.push(t),c.set(e,n)}const d=e=>s((c.get(e)??[]).map(e=>{const t=(e=>{const t=(i.get(e.name)??[]).map(t=>q(t,n,"oas32-parent",e.name));return{id:`tag:${e.name}`,name:e.displayName,order:e.order,children:s(t),metadata:{description:e.description,source:"oas32-parent",kind:"tag"}}})(e),o=d(e.name);return o.length>0&&(t.children=s([...t.children??[],...o])),t})),p=d("__root__"),u=i.get("Other")??[];if(u.length>0){const e=u.map(e=>q(e,n,"fallback","Other"));p.push({id:"tag:Other",name:"Other",order:Number.MAX_SAFE_INTEGER,children:s(e),metadata:{source:"fallback",kind:"tag"}})}return s(p)}function B(e){if(!Array.isArray(e))return[];const t=[];for(const n of e){const e=S(n);if(!e||"string"!=typeof e.name)continue;const o={name:e.name};Array.isArray(e.tags)&&(o.tags=e.tags.filter(e=>"string"==typeof e)),Array.isArray(e.groups)&&(o.groups=B(e.groups)),t.push(o)}return t}function X(e,t,n,o,r,a=0){const i=[];if(e.tags)for(const a of e.tags){const e=t.get(a);if(!e||0===e.length)continue;const c=e.map(e=>q(e,r,"tag-group",a));i.push({id:`tag:${a}`,name:n.get(a)??a,order:o.get(a),children:s(c),metadata:{source:"tag-group",kind:"tag"}})}if(e.groups)for(const s of e.groups)i.push(X(s,t,n,o,r,a+1));return{id:`tag-group:${e.name}`,name:e.name,order:1e3*a,children:s(i),metadata:{source:"tag-group",kind:"tag-group"}}}function L(e,t,n,o){const r=new Map,a=new Map,i=new Map;for(let e=0;e<t.length;e+=1)a.set(t[e].name,e),i.set(t[e].name,t[e].displayName);for(const e of n){if(U(e.raw,o.showInternal))continue;const t=e.tags.length>0?e.tags:["Other"];for(const n of t){const t=r.get(n)??[];t.push(e),r.set(n,t)}}const c=B(e["x-tagGroups"]).map(e=>X(e,r,i,a,o)),d=r.get("Other");if(d&&d.length>0){const e=d.map(e=>q(e,o,"fallback","Other"));c.push({id:"tag:Other",name:"Other",order:Number.MAX_SAFE_INTEGER,children:s(e),metadata:{source:"fallback",kind:"tag"}})}return s(c)}function W(e){return e.map(e=>{const t=e.children?W(e.children):void 0,n="operation"===e.metadata?.kind?1:0,o=t?.reduce((e,t)=>e+(t.metadata?.operationCount??0),0)??0;return{...e,children:t,metadata:{...e.metadata,operationCount:n+o}}})}function z(e,t={}){const n={...M,...t},o=[],r=S(e);if(!r)return{root:{id:"root",name:"API Documentation",children:[],metadata:{kind:"root"}},warnings:["Document is null or not an object."]};const a=function(e){const t=S(e.paths);if(!t)return[];const n=[];for(const[e,o]of Object.entries(t)){const t=S(o);if(t)for(const o of E){const r=S(t[o]);if(!r)continue;const a=R(r.operationId),s=R(r.summary),i=R(r.description),c=T(r.tags)?.filter(e=>"string"==typeof e).map(e=>e.trim()).filter(e=>e.length>0)??[],d=s??a??`${o.toUpperCase()} ${e}`,p=a??`${o}:${e}`,u=`/paths/${encodeURIComponent(e)}/${o}`;n.push({id:p,path:e,method:o,name:d,summary:s,description:i,operationId:a,deprecated:!0===x(r.deprecated),tags:c,pointer:u,raw:r})}}return n}(r),i=function(e){const t=T(e.tags);if(!t)return[];const n=[];for(const e of t){const t=S(e),o=R(t?.name);o&&t&&n.push({name:o,displayName:D(t)??o,description:R(t.description),parent:R(t.parent),order:P(t)})}return n}(r);let c;c=function(e){return e.some(e=>void 0!==e.parent)}(i)?F(i,a,n,o):function(e){return Array.isArray(e["x-tagGroups"])&&e["x-tagGroups"].length>0}(r)?L(r,i,a,n):function(e,t,n){const o=new Map,r=new Map;for(let t=0;t<e.length;t+=1)r.set(e[t].name,t);for(const e of t){if(U(e.raw,n.showInternal))continue;const t=e.tags.length>0?e.tags:["Other"];for(const n of t){const t=o.get(n)??[];t.push(e),o.set(n,t)}}const a=new Map;for(const t of e)a.set(t.name,t.displayName);const i=[];for(const[e,t]of o){const o=t.map(t=>q(t,n,"tag",e));i.push({id:`tag:${e}`,name:a.get(e)??e,order:"Other"===e?Number.MAX_SAFE_INTEGER:r.get(e),children:s(o),metadata:{source:"tag",kind:"tag"}})}return s(i)}(i,a,n);const d=function(e,t){if(!t.showComponents)return;const n=S(e.components),o=S(n?.schemas);if(!o)return;const r=[];for(const[e,n]of Object.entries(o)){const o=S(n);o&&!U(o,t.showInternal)&&r.push({id:`schema:${e}`,name:e,order:P(o),metadata:{description:R(o.description),pointer:`/components/schemas/${encodeURIComponent(e)}`,source:"tag",kind:"schema"}})}return 0!==r.length?{id:"section:components",name:"Components",order:Number.MAX_SAFE_INTEGER-1,children:s(r),metadata:{source:"tag",kind:"component"}}:void 0}(r,n);return{root:{id:"root",name:"API Documentation",children:s(W([...c,...d?[d]:[]])),metadata:{kind:"root"}},warnings:o}}