@scalar/api-client 2.38.3 → 2.39.0

package/dist/v2/features/modal/helpers/resolve-route-parameters.js

@@ -0,0 +1,92 @@
+import { getOperationEntries } from "@scalar/workspace-store/navigation";
+import { isHttpMethod } from "@scalar/helpers/http/is-http-method";
+//#region src/v2/features/modal/helpers/resolve-route-parameters.ts
+/** Type guard to check if an entry is an example. */
+var isExample = (entry) => entry.type === "example";
+/**
+* Gets the document from the workspace store.
+* Returns undefined if the document slug is not provided or the document does not exist.
+*/
+var getDocument = (ctx) => ctx.store.workspace.documents[ctx.documentSlug ?? ""];
+/**
+* Resolves the document slug from a raw input value.
+*
+* When "default" is specified and no document exists with that slug,
+* we fall back to the active document or the first available document.
+* This ensures a valid document is selected even when the caller does not know which documents exist.
+*/
+var resolveDocumentSlug = (store, slug) => {
+	if (slug !== "default" || store.workspace.documents[slug] !== void 0) return slug;
+	return store.workspace["x-scalar-active-document"] || Object.keys(store.workspace.documents)[0];
+};
+/**
+* Resolves the path from a raw input value.
+*
+* When "default" is specified, returns the first available path in the document.
+* This is useful for initial navigation when no specific path is requested.
+*/
+var resolvePath = (ctx, path) => {
+	const document = getDocument(ctx);
+	if (!document) return;
+	if (path === "default") return Object.keys(document.paths ?? {})[0];
+	return path;
+};
+/**
+* Resolves the HTTP method from a raw input value.
+*
+* When "default" is specified, returns the first valid HTTP method for the given path.
+* This ensures we select a real method rather than metadata keys like "parameters" or "summary".
+*/
+var resolveMethod = (ctx, path, method) => {
+	const document = getDocument(ctx);
+	if (!document || !path) return;
+	if (method === "default") return Object.keys(document.paths?.[path] ?? {}).find(isHttpMethod);
+	return isHttpMethod(method) ? method : void 0;
+};
+/**
+* Resolves the example name from a raw input value.
+*
+* When "default" is specified, returns the first available example name.
+* Falls back to "default" when no examples exist, which signals to use the default request body.
+*/
+var resolveExampleName = (ctx, operation, exampleKey) => {
+	if (!getDocument(ctx) || operation?.type !== "operation") return "default";
+	const examples = operation.children?.filter(isExample) ?? [];
+	const matchingExample = examples.find((child) => child.name === exampleKey);
+	if (matchingExample) return matchingExample.name;
+	if (exampleKey === "default") return examples[0]?.name ?? "default";
+	return "default";
+};
+/**
+* Resolves all route parameters from raw input values to their actual values.
+*
+* This function handles "default" placeholders by looking up actual values from the workspace store.
+* It ensures the modal can be opened even when the caller does not know specific paths, methods, or examples.
+*/
+var resolveRouteParameters = (store, params) => {
+	const documentSlug = resolveDocumentSlug(store, params.documentSlug);
+	const ctx = {
+		store,
+		documentSlug
+	};
+	const path = resolvePath(ctx, params.path);
+	const method = resolveMethod(ctx, path, params.method);
+	const traversedDocument = getDocument(ctx)?.["x-scalar-navigation"];
+	if (!traversedDocument) return {
+		documentSlug,
+		path,
+		method,
+		example: "default"
+	};
+	const operation = getOperationEntries(traversedDocument).get(`${path}|${method}`)?.find((entry) => entry.type === "operation");
+	return {
+		documentSlug,
+		path,
+		method,
+		example: resolveExampleName(ctx, operation, params.example)
+	};
+};
+//#endregion
+export { resolveRouteParameters };
+
+//# sourceMappingURL=resolve-route-parameters.js.map

package/dist/v2/features/modal/helpers/resolve-route-parameters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-route-parameters.js","names":[],"sources":["../../../../../src/v2/features/modal/helpers/resolve-route-parameters.ts"],"sourcesContent":["import type { HttpMethod } from '@scalar/helpers/http/http-methods'\nimport { isHttpMethod } from '@scalar/helpers/http/is-http-method'\nimport type { WorkspaceStore } from '@scalar/workspace-store/client'\nimport { getOperationEntries } from '@scalar/workspace-store/navigation'\nimport type { TraversedEntry, TraversedExample } from '@scalar/workspace-store/schemas/navigation'\n\n/** Payload for routing and opening the API client modal. */\nexport type RoutePayload = {\n  path: string\n  method: HttpMethod\n  example?: string\n  documentSlug?: string\n}\n\n/** Raw input values that may contain \"default\" placeholders. */\nexport type DefaultEntities = Record<keyof RoutePayload, string>\n\n/** Context for resolving route parameters from the workspace store. */\ntype ResolverContext = {\n  store: WorkspaceStore\n  documentSlug: string | undefined\n}\n\n/** Type guard to check if an entry is an example. */\nconst isExample = (entry: TraversedEntry): entry is TraversedExample => entry.type === 'example'\n\n/**\n * Gets the document from the workspace store.\n * Returns undefined if the document slug is not provided or the document does not exist.\n */\nconst getDocument = (ctx: ResolverContext) => ctx.store.workspace.documents[ctx.documentSlug ?? '']\n\n/**\n * Resolves the document slug from a raw input value.\n *\n * When \"default\" is specified and no document exists with that slug,\n * we fall back to the active document or the first available document.\n * This ensures a valid document is selected even when the caller does not know which documents exist.\n */\nexport const resolveDocumentSlug = (store: WorkspaceStore, slug: string | undefined): string | undefined => {\n  const hasMatchingDocument = slug !== 'default' || store.workspace.documents[slug] !== undefined\n\n  if (hasMatchingDocument) {\n    return slug\n  }\n\n  // Fall back to active document, then first available document\n  return store.workspace['x-scalar-active-document'] || Object.keys(store.workspace.documents)[0]\n}\n\n/**\n * Resolves the path from a raw input value.\n *\n * When \"default\" is specified, returns the first available path in the document.\n * This is useful for initial navigation when no specific path is requested.\n */\nexport const resolvePath = (ctx: ResolverContext, path: string | undefined): string | undefined => {\n  const document = getDocument(ctx)\n\n  if (!document) {\n    return undefined\n  }\n\n  if (path === 'default') {\n    return Object.keys(document.paths ?? {})[0]\n  }\n\n  return path\n}\n\n/**\n * Resolves the HTTP method from a raw input value.\n *\n * When \"default\" is specified, returns the first valid HTTP method for the given path.\n * This ensures we select a real method rather than metadata keys like \"parameters\" or \"summary\".\n */\nexport const resolveMethod = (\n  ctx: ResolverContext,\n  path: string | undefined,\n  method: string | undefined,\n): HttpMethod | undefined => {\n  const document = getDocument(ctx)\n\n  if (!document || !path) {\n    return undefined\n  }\n\n  if (method === 'default') {\n    const pathMethods = Object.keys(document.paths?.[path] ?? {})\n    return pathMethods.find(isHttpMethod)\n  }\n\n  return isHttpMethod(method) ? method : undefined\n}\n\n/**\n * Resolves the example name from a raw input value.\n *\n * When \"default\" is specified, returns the first available example name.\n * Falls back to \"default\" when no examples exist, which signals to use the default request body.\n */\nexport const resolveExampleName = (\n  ctx: ResolverContext,\n  operation: TraversedEntry | undefined,\n  exampleKey: string | undefined,\n): string => {\n  const document = getDocument(ctx)\n\n  if (!document || operation?.type !== 'operation') {\n    return 'default'\n  }\n\n  const examples = operation.children?.filter(isExample) ?? []\n  const matchingExample = examples.find((child) => child.name === exampleKey)\n\n  if (matchingExample) {\n    return matchingExample.name\n  }\n\n  if (exampleKey === 'default') {\n    return examples[0]?.name ?? 'default'\n  }\n\n  return 'default'\n}\n\n/**\n * Resolves all route parameters from raw input values to their actual values.\n *\n * This function handles \"default\" placeholders by looking up actual values from the workspace store.\n * It ensures the modal can be opened even when the caller does not know specific paths, methods, or examples.\n */\nexport const resolveRouteParameters = (store: WorkspaceStore, params: DefaultEntities): Partial<RoutePayload> => {\n  const documentSlug = resolveDocumentSlug(store, params.documentSlug)\n  const ctx: ResolverContext = { store, documentSlug }\n\n  const path = resolvePath(ctx, params.path)\n  const method = resolveMethod(ctx, path, params.method)\n\n  const traversedDocument = getDocument(ctx)?.['x-scalar-navigation']\n\n  if (!traversedDocument) {\n    return { documentSlug, path, method, example: 'default' }\n  }\n\n  const operations = getOperationEntries(traversedDocument)\n  const operation = operations.get(`${path}|${method}`)?.find((entry) => entry.type === 'operation')\n  const example = resolveExampleName(ctx, operation, params.example)\n\n  return { documentSlug, path, method, example }\n}\n"],"mappings":";;;;AAwBA,IAAM,aAAa,UAAqD,MAAM,SAAS;;;;;AAMvF,IAAM,eAAe,QAAyB,IAAI,MAAM,UAAU,UAAU,IAAI,gBAAgB;;;;;;;;AAShG,IAAa,uBAAuB,OAAuB,SAAiD;AAG1G,KAF4B,SAAS,aAAa,MAAM,UAAU,UAAU,UAAU,KAAA,EAGpF,QAAO;AAIT,QAAO,MAAM,UAAU,+BAA+B,OAAO,KAAK,MAAM,UAAU,UAAU,CAAC;;;;;;;;AAS/F,IAAa,eAAe,KAAsB,SAAiD;CACjG,MAAM,WAAW,YAAY,IAAI;AAEjC,KAAI,CAAC,SACH;AAGF,KAAI,SAAS,UACX,QAAO,OAAO,KAAK,SAAS,SAAS,EAAE,CAAC,CAAC;AAG3C,QAAO;;;;;;;;AAST,IAAa,iBACX,KACA,MACA,WAC2B;CAC3B,MAAM,WAAW,YAAY,IAAI;AAEjC,KAAI,CAAC,YAAY,CAAC,KAChB;AAGF,KAAI,WAAW,UAEb,QADoB,OAAO,KAAK,SAAS,QAAQ,SAAS,EAAE,CAAC,CAC1C,KAAK,aAAa;AAGvC,QAAO,aAAa,OAAO,GAAG,SAAS,KAAA;;;;;;;;AASzC,IAAa,sBACX,KACA,WACA,eACW;AAGX,KAAI,CAFa,YAAY,IAAI,IAEhB,WAAW,SAAS,YACnC,QAAO;CAGT,MAAM,WAAW,UAAU,UAAU,OAAO,UAAU,IAAI,EAAE;CAC5D,MAAM,kBAAkB,SAAS,MAAM,UAAU,MAAM,SAAS,WAAW;AAE3E,KAAI,gBACF,QAAO,gBAAgB;AAGzB,KAAI,eAAe,UACjB,QAAO,SAAS,IAAI,QAAQ;AAG9B,QAAO;;;;;;;;AAST,IAAa,0BAA0B,OAAuB,WAAmD;CAC/G,MAAM,eAAe,oBAAoB,OAAO,OAAO,aAAa;CACpE,MAAM,MAAuB;EAAE;EAAO;EAAc;CAEpD,MAAM,OAAO,YAAY,KAAK,OAAO,KAAK;CAC1C,MAAM,SAAS,cAAc,KAAK,MAAM,OAAO,OAAO;CAEtD,MAAM,oBAAoB,YAAY,IAAI,GAAG;AAE7C,KAAI,CAAC,kBACH,QAAO;EAAE;EAAc;EAAM;EAAQ,SAAS;EAAW;CAI3D,MAAM,YADa,oBAAoB,kBAAkB,CAC5B,IAAI,GAAG,KAAK,GAAG,SAAS,EAAE,MAAM,UAAU,MAAM,SAAS,YAAY;AAGlG,QAAO;EAAE;EAAc;EAAM;EAAQ,SAFrB,mBAAmB,KAAK,WAAW,OAAO,QAAQ;EAEpB"}

package/dist/v2/features/modal/helpers/restore-workspace-state.js

@@ -0,0 +1,51 @@
+import { unpackProxyObject } from "@scalar/workspace-store/helpers/unpack-proxy";
+//#region src/v2/features/modal/helpers/restore-workspace-state.ts
+/**
+* Restores the state of a workspace document by reverting its state
+* to the specified import, while preserving certain live properties
+* such as servers, security schemes, and selected server.
+*/
+var restoreWorkspaceState = ({ workspaceStore, workspaceState, name }) => {
+	if (!workspaceStore) return {
+		ok: false,
+		error: "Workspace store is not available"
+	};
+	const currentDocument = unpackProxyObject(workspaceStore.workspace.documents[name]);
+	if (!currentDocument) return {
+		ok: false,
+		error: "Current document not found in workspace store"
+	};
+	const importingDocument = workspaceState.documents[name];
+	if (!importingDocument) return {
+		ok: false,
+		error: "Importing document not found in workspace state"
+	};
+	const persistedProperties = {
+		selectedServer: currentDocument["x-scalar-selected-server"],
+		securitySchemes: currentDocument.components?.securitySchemes,
+		servers: currentDocument.servers
+	};
+	workspaceStore.loadWorkspace({
+		meta: {},
+		documents: { [name]: importingDocument },
+		intermediateDocuments: {},
+		originalDocuments: {},
+		overrides: {},
+		history: {},
+		auth: {}
+	});
+	const newDocument = unpackProxyObject(workspaceStore.workspace.documents[name]);
+	if (!newDocument) return {
+		ok: false,
+		error: "New document not found in workspace store"
+	};
+	newDocument["x-scalar-selected-server"] = persistedProperties.selectedServer;
+	newDocument.servers = persistedProperties.servers;
+	newDocument.components ??= {};
+	newDocument.components.securitySchemes = persistedProperties.securitySchemes;
+	return { ok: true };
+};
+//#endregion
+export { restoreWorkspaceState };
+
+//# sourceMappingURL=restore-workspace-state.js.map

package/dist/v2/features/modal/helpers/restore-workspace-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-workspace-state.js","names":[],"sources":["../../../../../src/v2/features/modal/helpers/restore-workspace-state.ts"],"sourcesContent":["import type { WorkspaceStore } from '@scalar/workspace-store/client'\nimport { unpackProxyObject } from '@scalar/workspace-store/helpers/unpack-proxy'\nimport type { InMemoryWorkspace } from '@scalar/workspace-store/schemas/inmemory-workspace'\n\n/**\n * Restores the state of a workspace document by reverting its state\n * to the specified import, while preserving certain live properties\n * such as servers, security schemes, and selected server.\n */\nexport const restoreWorkspaceState = ({\n  workspaceStore,\n  workspaceState,\n  name,\n}: {\n  workspaceStore: WorkspaceStore | null\n  workspaceState: InMemoryWorkspace\n  name: string\n}): { ok: true } | { ok: false; error: string } => {\n  if (!workspaceStore) {\n    return { ok: false, error: 'Workspace store is not available' }\n  }\n\n  const currentDocument = unpackProxyObject(workspaceStore.workspace.documents[name])\n  if (!currentDocument) {\n    return { ok: false, error: 'Current document not found in workspace store' }\n  }\n\n  const importingDocument = workspaceState.documents[name]\n  if (!importingDocument) {\n    return { ok: false, error: 'Importing document not found in workspace state' }\n  }\n\n  // Preserve some of the document properties we want to keep\n  const persistedProperties = {\n    selectedServer: currentDocument['x-scalar-selected-server'],\n    securitySchemes: currentDocument.components?.securitySchemes,\n    servers: currentDocument.servers,\n  }\n\n  // We only revert the active state of the document itself\n  workspaceStore.loadWorkspace({\n    meta: {},\n    documents: {\n      [name]: importingDocument,\n    },\n    intermediateDocuments: {},\n    originalDocuments: {},\n    overrides: {},\n    history: {},\n    auth: {},\n  })\n\n  const newDocument = unpackProxyObject(workspaceStore.workspace.documents[name])\n  if (!newDocument) {\n    return { ok: false, error: 'New document not found in workspace store' }\n  }\n\n  // Now restore the persisted properties\n  // ------------------------------------------------------------\n  // Server selection\n  newDocument['x-scalar-selected-server'] = persistedProperties.selectedServer\n  newDocument.servers = persistedProperties.servers\n\n  // ------------------------------------------------------------\n  // Security schemes\n  newDocument.components ??= {}\n  newDocument.components.securitySchemes = persistedProperties.securitySchemes\n\n  return { ok: true }\n}\n"],"mappings":";;;;;;;AASA,IAAa,yBAAyB,EACpC,gBACA,gBACA,WAKiD;AACjD,KAAI,CAAC,eACH,QAAO;EAAE,IAAI;EAAO,OAAO;EAAoC;CAGjE,MAAM,kBAAkB,kBAAkB,eAAe,UAAU,UAAU,MAAM;AACnF,KAAI,CAAC,gBACH,QAAO;EAAE,IAAI;EAAO,OAAO;EAAiD;CAG9E,MAAM,oBAAoB,eAAe,UAAU;AACnD,KAAI,CAAC,kBACH,QAAO;EAAE,IAAI;EAAO,OAAO;EAAmD;CAIhF,MAAM,sBAAsB;EAC1B,gBAAgB,gBAAgB;EAChC,iBAAiB,gBAAgB,YAAY;EAC7C,SAAS,gBAAgB;EAC1B;AAGD,gBAAe,cAAc;EAC3B,MAAM,EAAE;EACR,WAAW,GACR,OAAO,mBACT;EACD,uBAAuB,EAAE;EACzB,mBAAmB,EAAE;EACrB,WAAW,EAAE;EACb,SAAS,EAAE;EACX,MAAM,EAAE;EACT,CAAC;CAEF,MAAM,cAAc,kBAAkB,eAAe,UAAU,UAAU,MAAM;AAC/E,KAAI,CAAC,YACH,QAAO;EAAE,IAAI;EAAO,OAAO;EAA6C;AAM1E,aAAY,8BAA8B,oBAAoB;AAC9D,aAAY,UAAU,oBAAoB;AAI1C,aAAY,eAAe,EAAE;AAC7B,aAAY,WAAW,kBAAkB,oBAAoB;AAE7D,QAAO,EAAE,IAAI,MAAM"}

package/dist/v2/features/modal/hooks/use-modal-sidebar.d.ts

@@ -3,7 +3,7 @@ import { createSidebarState } from '@scalar/sidebar';
 import type { WorkspaceStore } from '@scalar/workspace-store/client';
 import type { TraversedEntry } from '@scalar/workspace-store/schemas/navigation';
 import { type ComputedRef } from 'vue';
-import type { RoutePayload } from '@/v2/features/modal/helpers/resolve-route-parameters';
+import type { RoutePayload } from '../../../../v2/features/modal/helpers/resolve-route-parameters.js';
 export type UseModalSidebarReturn = {
     handleSelectItem: (id: string) => void;
     state: ReturnType<typeof createSidebarState<TraversedEntry>>;

package/dist/v2/features/modal/hooks/use-modal-sidebar.js

@@ -0,0 +1,142 @@
+import { generateLocationId } from "../../../helpers/generate-location-id.js";
+import { computed, toValue, watch } from "vue";
+import { createSidebarState, generateReverseIndex, getChildEntry } from "@scalar/sidebar";
+import { getParentEntry } from "@scalar/workspace-store/navigation";
+//#region src/v2/features/modal/hooks/use-modal-sidebar.ts
+/**
+* useSidebarState - Custom hook to manage the sidebar state and navigation logic in the Scalar API client
+*
+* This composable manages the sidebar structure, synchronizes selection state
+* with the current route, and provides a handler for selecting sidebar items.
+*
+* Example usage:
+*
+* const { handleSelectItem, sidebarState } = useSidebarState({
+*   workspaceStore,
+*   workspaceSlug,
+*   documentSlug,
+*   path,
+*   method,
+*   exampleName,
+* })
+*/
+var useModalSidebar = ({ workspaceStore, documentSlug, path, method, exampleName, route }) => {
+	const entries = computed(() => workspaceStore?.workspace.documents[toValue(documentSlug) ?? ""]?.["x-scalar-navigation"]?.children ?? []);
+	const state = createSidebarState(entries);
+	/**
+	* Computed index for fast lookup of sidebar nodes by their unique API location.
+	*
+	* - Only indexes nodes of type 'operation', or 'example'.
+	* - The lookup key is a serialized array of: [operationPath, operationMethod, exampleName?].
+	* - Supports precise resolution of sidebar entries given an API "location".
+	*/
+	const locationIndex = computed(() => generateReverseIndex({
+		items: entries.value,
+		nestedKey: "children",
+		filter: (node) => node.type === "operation" || node.type === "example",
+		getId: (node) => {
+			const operation = getParentEntry("operation", node);
+			return generateLocationId({
+				document: toValue(documentSlug) ?? "",
+				path: operation?.path,
+				method: operation?.method,
+				example: node.type === "example" ? node.name : void 0
+			});
+		}
+	}));
+	/**
+	* Looks up a sidebar entry by its unique API location.
+	* - First tries to find an entry matching all provided properties (including example).
+	* - If not found, falls back to matching only the operation (ignores example field).
+	* This allows resolving either examples, operations, or documents as appropriate.
+	*
+	* @param location - Object specifying the document name, path, method, and optional example name.
+	* @returns The matching sidebar entry, or undefined if none found.
+	*
+	* Example:
+	*   const entry = getEntryByLocation({
+	*     document: 'pets',
+	*     path: '/pets',
+	*     method: 'get',
+	*     example: 'default',
+	*   })
+	*/
+	const getEntryByLocation = (location) => {
+		const entryWithExample = locationIndex.value.get(generateLocationId({
+			document: location.document,
+			path: location.path,
+			method: location.method,
+			example: location.example
+		}));
+		if (entryWithExample) return entryWithExample;
+		return locationIndex.value.get(generateLocationId({
+			document: location.document,
+			path: location.path,
+			method: location.method
+		}));
+	};
+	/**
+	* Handles item selection from the sidebar and routes navigation accordingly.
+	*
+	* Example:
+	*   handleSelectItem('id-of-entry')
+	*/
+	const handleSelectItem = (id) => {
+		const entry = state.getEntryById(id);
+		if (!entry) {
+			console.warn(`Could not find sidebar entry with id ${id} to select`);
+			return;
+		}
+		if (entry.type === "operation" || entry.type === "example") {
+			if (state.isSelected(id)) {
+				state.setExpanded(id, !state.isExpanded(id));
+				return;
+			}
+			const operation = getParentEntry("operation", entry);
+			const example = getChildEntry("example", entry);
+			if (example) {
+				state.setSelected(example.id);
+				state.setExpanded(example.id, true);
+			} else state.setSelected(id);
+			if (!operation) return;
+			return route({
+				documentSlug: toValue(documentSlug),
+				path: operation.path,
+				method: operation.method,
+				example: example?.name ?? "default"
+			});
+		}
+		state.setExpanded(id, !state.isExpanded(id));
+	};
+	/** Keep the sidebar state in sync with the modal parameters */
+	watch([
+		documentSlug,
+		path,
+		method,
+		exampleName
+	], ([newDocument, newPath, newMethod, newExample]) => {
+		if (!newDocument) {
+			state.setSelected(null);
+			return;
+		}
+		const entry = getEntryByLocation({
+			document: newDocument,
+			path: newPath,
+			method: newMethod,
+			example: newExample
+		});
+		if (entry) {
+			state.setSelected(entry.id);
+			state.setExpanded(entry.id, true);
+		}
+	}, { immediate: true });
+	return {
+		handleSelectItem,
+		state,
+		getEntryByLocation
+	};
+};
+//#endregion
+export { useModalSidebar };
+
+//# sourceMappingURL=use-modal-sidebar.js.map

package/dist/v2/features/modal/hooks/use-modal-sidebar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-modal-sidebar.js","names":[],"sources":["../../../../../src/v2/features/modal/hooks/use-modal-sidebar.ts"],"sourcesContent":["import type { HttpMethod } from '@scalar/helpers/http/http-methods'\nimport { createSidebarState, generateReverseIndex, getChildEntry } from '@scalar/sidebar'\nimport type { WorkspaceStore } from '@scalar/workspace-store/client'\nimport { getParentEntry } from '@scalar/workspace-store/navigation'\nimport type { TraversedEntry } from '@scalar/workspace-store/schemas/navigation'\nimport { type ComputedRef, computed, toValue, watch } from 'vue'\n\nimport type { RoutePayload } from '@/v2/features/modal/helpers/resolve-route-parameters'\nimport { generateLocationId } from '@/v2/helpers/generate-location-id'\n\nexport type UseModalSidebarReturn = {\n  handleSelectItem: (id: string) => void\n  state: ReturnType<typeof createSidebarState<TraversedEntry>>\n  getEntryByLocation: (location: {\n    document: string\n    path?: string\n    method?: HttpMethod\n    example?: string\n  }) => TraversedEntry | undefined\n}\n\n/**\n * useSidebarState - Custom hook to manage the sidebar state and navigation logic in the Scalar API client\n *\n * This composable manages the sidebar structure, synchronizes selection state\n * with the current route, and provides a handler for selecting sidebar items.\n *\n * Example usage:\n *\n * const { handleSelectItem, sidebarState } = useSidebarState({\n *   workspaceStore,\n *   workspaceSlug,\n *   documentSlug,\n *   path,\n *   method,\n *   exampleName,\n * })\n */\nexport const useModalSidebar = ({\n  workspaceStore,\n  documentSlug,\n  path,\n  method,\n  exampleName,\n  route,\n}: {\n  workspaceStore: WorkspaceStore | null\n  documentSlug: ComputedRef<string | undefined>\n  path: ComputedRef<string | undefined>\n  method: ComputedRef<HttpMethod | undefined>\n  exampleName: ComputedRef<string | undefined>\n  route: (payload: RoutePayload) => void\n}): UseModalSidebarReturn => {\n  const entries = computed(\n    () => workspaceStore?.workspace.documents[toValue(documentSlug) ?? '']?.['x-scalar-navigation']?.children ?? [],\n  )\n  const state = createSidebarState(entries)\n\n  /**\n   * Computed index for fast lookup of sidebar nodes by their unique API location.\n   *\n   * - Only indexes nodes of type 'operation', or 'example'.\n   * - The lookup key is a serialized array of: [operationPath, operationMethod, exampleName?].\n   * - Supports precise resolution of sidebar entries given an API \"location\".\n   */\n  const locationIndex = computed(() =>\n    generateReverseIndex({\n      items: entries.value,\n      nestedKey: 'children',\n      filter: (node) => node.type === 'operation' || node.type === 'example',\n      getId: (node) => {\n        const operation = getParentEntry('operation', node)\n        return generateLocationId({\n          document: toValue(documentSlug) ?? '',\n          path: operation?.path,\n          method: operation?.method,\n          example: node.type === 'example' ? node.name : undefined,\n        })\n      },\n    }),\n  )\n\n  /**\n   * Looks up a sidebar entry by its unique API location.\n   * - First tries to find an entry matching all provided properties (including example).\n   * - If not found, falls back to matching only the operation (ignores example field).\n   * This allows resolving either examples, operations, or documents as appropriate.\n   *\n   * @param location - Object specifying the document name, path, method, and optional example name.\n   * @returns The matching sidebar entry, or undefined if none found.\n   *\n   * Example:\n   *   const entry = getEntryByLocation({\n   *     document: 'pets',\n   *     path: '/pets',\n   *     method: 'get',\n   *     example: 'default',\n   *   })\n   */\n  const getEntryByLocation: UseModalSidebarReturn['getEntryByLocation'] = (location) => {\n    // Try to find an entry with the most-specific location (including example)\n    const entryWithExample = locationIndex.value.get(\n      generateLocationId({\n        document: location.document,\n        path: location.path,\n        method: location.method,\n        example: location.example,\n      }),\n    )\n\n    if (entryWithExample) {\n      return entryWithExample\n    }\n\n    // Fallback to the operation (ignoring example) if an example wasn't found or specified\n    return locationIndex.value.get(\n      generateLocationId({\n        document: location.document,\n        path: location.path,\n        method: location.method,\n      }),\n    )\n  }\n\n  /**\n   * Handles item selection from the sidebar and routes navigation accordingly.\n   *\n   * Example:\n   *   handleSelectItem('id-of-entry')\n   */\n  const handleSelectItem = (id: string) => {\n    const entry = state.getEntryById(id)\n\n    if (!entry) {\n      console.warn(`Could not find sidebar entry with id ${id} to select`)\n      return\n    }\n\n    // Navigate to the example page\n    if (entry.type === 'operation' || entry.type === 'example') {\n      // If we are already in the operation, just toggle expansion\n      if (state.isSelected(id)) {\n        state.setExpanded(id, !state.isExpanded(id))\n        return\n      }\n\n      const operation = getParentEntry('operation', entry)\n      const example = getChildEntry('example', entry)\n\n      if (example) {\n        state.setSelected(example.id)\n        state.setExpanded(example.id, true)\n      } else {\n        state.setSelected(id)\n      }\n\n      if (!operation) {\n        return\n      }\n\n      return route({\n        documentSlug: toValue(documentSlug),\n        path: operation.path,\n        method: operation.method,\n        example: example?.name ?? 'default',\n      })\n    }\n\n    state.setExpanded(id, !state.isExpanded(id))\n    return\n  }\n\n  /** Keep the sidebar state in sync with the modal parameters */\n  watch(\n    [documentSlug, path, method, exampleName],\n    ([newDocument, newPath, newMethod, newExample]) => {\n      if (!newDocument) {\n        // Reset selection if no document is selected\n        state.setSelected(null)\n        return\n      }\n\n      const entry = getEntryByLocation({\n        document: newDocument,\n        path: newPath,\n        method: newMethod,\n        example: newExample,\n      })\n\n      if (entry) {\n        state.setSelected(entry.id)\n        state.setExpanded(entry.id, true)\n      }\n    },\n    {\n      immediate: true,\n    },\n  )\n\n  return {\n    handleSelectItem,\n    state,\n    getEntryByLocation,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsCA,IAAa,mBAAmB,EAC9B,gBACA,cACA,MACA,QACA,aACA,YAQ2B;CAC3B,MAAM,UAAU,eACR,gBAAgB,UAAU,UAAU,QAAQ,aAAa,IAAI,MAAM,wBAAwB,YAAY,EAAE,CAChH;CACD,MAAM,QAAQ,mBAAmB,QAAQ;;;;;;;;CASzC,MAAM,gBAAgB,eACpB,qBAAqB;EACnB,OAAO,QAAQ;EACf,WAAW;EACX,SAAS,SAAS,KAAK,SAAS,eAAe,KAAK,SAAS;EAC7D,QAAQ,SAAS;GACf,MAAM,YAAY,eAAe,aAAa,KAAK;AACnD,UAAO,mBAAmB;IACxB,UAAU,QAAQ,aAAa,IAAI;IACnC,MAAM,WAAW;IACjB,QAAQ,WAAW;IACnB,SAAS,KAAK,SAAS,YAAY,KAAK,OAAO,KAAA;IAChD,CAAC;;EAEL,CAAC,CACH;;;;;;;;;;;;;;;;;;CAmBD,MAAM,sBAAmE,aAAa;EAEpF,MAAM,mBAAmB,cAAc,MAAM,IAC3C,mBAAmB;GACjB,UAAU,SAAS;GACnB,MAAM,SAAS;GACf,QAAQ,SAAS;GACjB,SAAS,SAAS;GACnB,CAAC,CACH;AAED,MAAI,iBACF,QAAO;AAIT,SAAO,cAAc,MAAM,IACzB,mBAAmB;GACjB,UAAU,SAAS;GACnB,MAAM,SAAS;GACf,QAAQ,SAAS;GAClB,CAAC,CACH;;;;;;;;CASH,MAAM,oBAAoB,OAAe;EACvC,MAAM,QAAQ,MAAM,aAAa,GAAG;AAEpC,MAAI,CAAC,OAAO;AACV,WAAQ,KAAK,wCAAwC,GAAG,YAAY;AACpE;;AAIF,MAAI,MAAM,SAAS,eAAe,MAAM,SAAS,WAAW;AAE1D,OAAI,MAAM,WAAW,GAAG,EAAE;AACxB,UAAM,YAAY,IAAI,CAAC,MAAM,WAAW,GAAG,CAAC;AAC5C;;GAGF,MAAM,YAAY,eAAe,aAAa,MAAM;GACpD,MAAM,UAAU,cAAc,WAAW,MAAM;AAE/C,OAAI,SAAS;AACX,UAAM,YAAY,QAAQ,GAAG;AAC7B,UAAM,YAAY,QAAQ,IAAI,KAAK;SAEnC,OAAM,YAAY,GAAG;AAGvB,OAAI,CAAC,UACH;AAGF,UAAO,MAAM;IACX,cAAc,QAAQ,aAAa;IACnC,MAAM,UAAU;IAChB,QAAQ,UAAU;IAClB,SAAS,SAAS,QAAQ;IAC3B,CAAC;;AAGJ,QAAM,YAAY,IAAI,CAAC,MAAM,WAAW,GAAG,CAAC;;;AAK9C,OACE;EAAC;EAAc;EAAM;EAAQ;EAAY,GACxC,CAAC,aAAa,SAAS,WAAW,gBAAgB;AACjD,MAAI,CAAC,aAAa;AAEhB,SAAM,YAAY,KAAK;AACvB;;EAGF,MAAM,QAAQ,mBAAmB;GAC/B,UAAU;GACV,MAAM;GACN,QAAQ;GACR,SAAS;GACV,CAAC;AAEF,MAAI,OAAO;AACT,SAAM,YAAY,MAAM,GAAG;AAC3B,SAAM,YAAY,MAAM,IAAI,KAAK;;IAGrC,EACE,WAAW,MACZ,CACF;AAED,QAAO;EACL;EACA;EACA;EACD"}

package/dist/v2/features/modal/index.d.ts

@@ -1,4 +1,4 @@
-export { type ApiClientModal, createApiClientModal } from './helpers/create-api-client-modal';
-export { mapHiddenClientsConfig } from './helpers/map-hidden-clients-config';
-export { initializeModalEvents } from './modal-events';
+export { type ApiClientModal, createApiClientModal } from './helpers/create-api-client-modal.js';
+export { mapHiddenClientsConfig } from './helpers/map-hidden-clients-config.js';
+export { initializeModalEvents } from './modal-events.js';
 //# sourceMappingURL=index.d.ts.map