@scalar/workspace-store 0.40.2 → 0.40.4

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

@@ -1,94 +1,100 @@
-import { isHttpMethod } from "@scalar/helpers/http/is-http-method";
-import { objectKeys } from "@scalar/helpers/object/object-keys";
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-import { isDeprecatedOperation } from "../../navigation/helpers/traverse-paths.js";
-import { getTag } from "./get-tag.js";
-const createWebhookEntry = ({
-  ref,
-  method,
-  name,
-  title,
-  generateId,
-  parentTag,
-  webhook,
-  isDeprecated,
-  parentId
-}) => {
-  const id = generateId({
-    type: "webhook",
-    name,
-    method,
-    webhook,
-    parentTag,
-    parentId
-  });
-  const entry = {
-    id,
-    title,
-    name,
-    ref,
-    method,
-    type: "webhook",
-    isDeprecated
-  };
-  return entry;
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { objectKeys } from '@scalar/helpers/object/object-keys';
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { isDeprecatedOperation } from '../../navigation/helpers/traverse-paths.js';
+import { getTag } from './get-tag.js';
+/** Creates a traversed webhook entry from an OpenAPI webhook object.
+ *
+ * @param ref - JSON pointer reference to the webhook in the OpenAPI document
+ * @param method - HTTP method of the webhook
+ * @param name - Name of the webhook, defaults to 'Unknown'
+ * @param title - Title of the webhook, defaults to 'Unknown'
+ * @param entitiesMap - Map to store webhook IDs and titles for mobile header navigation
+ * @param getWebhookId - Function to generate unique IDs for webhooks
+ * @param tag - Optional tag object associated with the webhook
+ * @returns A traversed webhook entry with ID, title, name, method and reference
+ */
+const createWebhookEntry = ({ ref, method, name, title, generateId, parentTag, webhook, isDeprecated, parentId, }) => {
+    const id = generateId({
+        type: 'webhook',
+        name,
+        method,
+        webhook: webhook,
+        parentTag,
+        parentId: parentId,
+    });
+    const entry = {
+        id,
+        title,
+        name,
+        ref,
+        method: method,
+        type: 'webhook',
+        isDeprecated,
+    };
+    return entry;
 };
-const traverseWebhooks = ({
-  document,
-  tagsMap,
-  generateId,
-  untaggedWebhooksParentId,
-  documentId
-}) => {
-  const untagged = [];
-  Object.entries(document.webhooks ?? {}).forEach(([name, pathItemObject]) => {
-    const pathKeys = objectKeys(pathItemObject ?? {}).filter((key) => isHttpMethod(key));
-    pathKeys.forEach((method) => {
-      const _operation = pathItemObject?.[method];
-      const operation = getResolvedRef(_operation);
-      if (!operation) {
-        return;
-      }
-      if (operation["x-internal"] || operation["x-scalar-ignore"]) {
-        return;
-      }
-      const ref = `#/webhooks/${name}/${method}`;
-      if (operation.tags?.length) {
-        operation.tags.forEach((tagName) => {
-          const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
-          tagsMap.get(tagName)?.entries.push(
-            createWebhookEntry({
-              ref,
-              method,
-              name,
-              title: operation.summary ?? name,
-              webhook: operation,
-              generateId,
-              parentTag: { tag, id: tagId },
-              parentId: tagId,
-              isDeprecated: isDeprecatedOperation(operation)
-            })
-          );
+/** Traverses the webhooks in an OpenAPI document to build an array of webhook entries.
+ *
+ * This function processes each webhook in the document to:
+ * - Filter out internal webhooks (marked with x-internal) and webhooks to ignore (marked with x-scalar-ignore)
+ * - Group webhooks by their tags
+ * - Create webhook entries with unique references and IDs
+ * - Store webhook IDs and titles for mobile header navigation
+ *
+ * @param content - The OpenAPI document to traverse
+ * @param tagsMap - Map of tag names to arrays of traversed entries from operations
+ * @param tagsDict - Dictionary mapping tag names to their OpenAPI tag objects
+ * @param entitiesMap - Map to store webhook IDs and titles for mobile header navigation
+ * @param getWebhookId - Function to generate unique IDs for webhooks
+ * @returns Array of untagged webhook entries
+ */
+export const traverseWebhooks = ({ document, tagsMap, generateId, untaggedWebhooksParentId, documentId, }) => {
+    const untagged = [];
+    // Traverse webhooks
+    Object.entries(document.webhooks ?? {}).forEach(([name, pathItemObject]) => {
+        const pathKeys = objectKeys(pathItemObject ?? {}).filter((key) => isHttpMethod(key));
+        pathKeys.forEach((method) => {
+            const _operation = pathItemObject?.[method];
+            const operation = getResolvedRef(_operation);
+            if (!operation) {
+                return;
+            }
+            // Skip if the operation is internal or scalar-ignore
+            if (operation['x-internal'] || operation['x-scalar-ignore']) {
+                return;
+            }
+            const ref = `#/webhooks/${name}/${method}`;
+            if (operation.tags?.length) {
+                operation.tags.forEach((tagName) => {
+                    const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
+                    tagsMap.get(tagName)?.entries.push(createWebhookEntry({
+                        ref,
+                        method,
+                        name,
+                        title: operation.summary ?? name,
+                        webhook: operation,
+                        generateId: generateId,
+                        parentTag: { tag, id: tagId },
+                        parentId: tagId,
+                        isDeprecated: isDeprecatedOperation(operation),
+                    }));
+                });
+            }
+            // Add to untagged
+            else {
+                untagged.push(createWebhookEntry({
+                    ref,
+                    method,
+                    name,
+                    title: operation.summary ?? name,
+                    generateId,
+                    isDeprecated: isDeprecatedOperation(operation),
+                    webhook: operation,
+                    parentId: untaggedWebhooksParentId,
+                }));
+            }
         });
-      } else {
-        untagged.push(
-          createWebhookEntry({
-            ref,
-            method,
-            name,
-            title: operation.summary ?? name,
-            generateId,
-            isDeprecated: isDeprecatedOperation(operation),
-            webhook: operation,
-            parentId: untaggedWebhooksParentId
-          })
-        );
-      }
     });
-  });
-  return untagged;
-};
-export {
-  traverseWebhooks
+    return untagged;
 };
-//# sourceMappingURL=traverse-webhooks.js.map

package/dist/navigation/helpers/update-order-ids.js

@@ -1,54 +1,62 @@
-import { canHaveOrder, getOpenapiObject } from "../../navigation/helpers/get-openapi-object.js";
-import { getParentEntry } from "../../navigation/helpers/get-parent-entry.js";
-const updateOrderIds = ({ store, generateId, ...rest }) => {
-  rest.entries?.forEach((entry) => {
-    if (!canHaveOrder(entry.parent)) {
-      return;
-    }
-    const parentOpenAPIObject = getOpenapiObject({ store, entry: entry.parent });
-    if (!parentOpenAPIObject || !("x-scalar-order" in parentOpenAPIObject)) {
-      return;
-    }
-    const order = parentOpenAPIObject["x-scalar-order"];
-    const index = order?.indexOf(entry.id);
-    if (!Array.isArray(order) || typeof index !== "number" || index < 0) {
-      return;
-    }
-    if ("tag" in rest) {
-      const oldTagId = entry.id;
-      const newTagId = generateId({
-        type: "tag",
-        parentId: entry.parent.id,
-        tag: rest.tag
-      });
-      order[index] = newTagId;
-      if (oldTagId !== newTagId) {
-        const documentEntry = getParentEntry("document", entry);
-        const document = documentEntry ? store.workspace.documents[documentEntry.name] : null;
-        const renamedTagObj = document?.tags?.find((t) => t.name === rest.tag.name);
-        const childOrder = renamedTagObj?.["x-scalar-order"];
-        if (renamedTagObj && Array.isArray(childOrder)) {
-          const oldPrefix = `${oldTagId}/`;
-          const newPrefix = `${newTagId}/`;
-          renamedTagObj["x-scalar-order"] = childOrder.map(
-            (id) => id.startsWith(oldPrefix) ? newPrefix + id.slice(oldPrefix.length) : id
-          );
+import { canHaveOrder, getOpenapiObject } from '../../navigation/helpers/get-openapi-object.js';
+import { getParentEntry } from '../../navigation/helpers/get-parent-entry.js';
+/**
+ * Updates the order ID of an entry (operation or tag) in the sidebar.
+ * Used when changing path, method, or tag name so we do not lose the sidebar ordering.
+ *
+ * Accepts either operation/webhook entries or tag entries via a discriminated union,
+ * so the correct ID generation props are enforced at the call site.
+ */
+export const updateOrderIds = ({ store, generateId, ...rest }) => {
+    // Loop over the entries and replace the ID in the x-scalar-order with the new ID
+    rest.entries?.forEach((entry) => {
+        if (!canHaveOrder(entry.parent)) {
+            return;
         }
-      }
-      return;
-    }
-    const parentTag = entry.parent.type === "tag" && "name" in parentOpenAPIObject ? { tag: parentOpenAPIObject, id: entry.parent.id } : void 0;
-    order[index] = generateId({
-      type: "operation",
-      path: rest.path,
-      method: rest.method,
-      operation: rest.operation,
-      parentId: entry.parent.id,
-      parentTag
+        // Ensure we have an x-scalar-order property
+        const parentOpenAPIObject = getOpenapiObject({ store, entry: entry.parent });
+        if (!parentOpenAPIObject || !('x-scalar-order' in parentOpenAPIObject)) {
+            return;
+        }
+        const order = parentOpenAPIObject['x-scalar-order'];
+        const index = order?.indexOf(entry.id);
+        if (!Array.isArray(order) || typeof index !== 'number' || index < 0) {
+            return;
+        }
+        // Tag entries: generate a new tag ID using the updated tag object
+        if ('tag' in rest) {
+            const oldTagId = entry.id;
+            const newTagId = generateId({
+                type: 'tag',
+                parentId: entry.parent.id,
+                tag: rest.tag,
+            });
+            order[index] = newTagId;
+            // Ensure we update the children as well, so we don't lose the sidebar ordering when it rebuilds
+            if (oldTagId !== newTagId) {
+                const documentEntry = getParentEntry('document', entry);
+                const document = documentEntry ? store.workspace.documents[documentEntry.name] : null;
+                const renamedTagObj = document?.tags?.find((t) => t.name === rest.tag.name);
+                const childOrder = renamedTagObj?.['x-scalar-order'];
+                if (renamedTagObj && Array.isArray(childOrder)) {
+                    const oldPrefix = `${oldTagId}/`;
+                    const newPrefix = `${newTagId}/`;
+                    renamedTagObj['x-scalar-order'] = childOrder.map((id) => id.startsWith(oldPrefix) ? newPrefix + id.slice(oldPrefix.length) : id);
+                }
+            }
+            return;
+        }
+        // Operation/webhook entries: generate a new operation ID with the updated path and method
+        const parentTag = entry.parent.type === 'tag' && 'name' in parentOpenAPIObject
+            ? { tag: parentOpenAPIObject, id: entry.parent.id }
+            : undefined;
+        order[index] = generateId({
+            type: 'operation',
+            path: rest.path,
+            method: rest.method,
+            operation: rest.operation,
+            parentId: entry.parent.id,
+            parentTag,
+        });
     });
-  });
-};
-export {
-  updateOrderIds
 };
-//# sourceMappingURL=update-order-ids.js.map

package/dist/navigation/helpers/utils.js

@@ -1,25 +1,75 @@
-import { getHeadings } from "@scalar/code-highlight/markdown";
-import GithubSlugger from "github-slugger";
+import { getHeadings } from '@scalar/code-highlight/markdown';
+import GithubSlugger from 'github-slugger';
+/**
+ * Adds URL-friendly slugs to each heading in the array.
+ * Uses GithubSlugger to generate consistent slugs that match GitHub's heading anchor format.
+ *
+ * @param headings - Array of heading objects containing value and depth
+ * @param slugger - GithubSlugger instance for generating consistent slugs
+ * @returns Array of headings with added slug property
+ *
+ * @example
+ * const headings = [
+ *   { value: 'Getting Started', depth: 1 },
+ *   { value: 'Installation', depth: 2 }
+ * ]
+ * const slugger = new GithubSlugger()
+ * withSlugs(headings, slugger)
+ * // Returns:
+ * // [
+ * //   { value: 'Getting Started', depth: 1, slug: 'getting-started' },
+ * //   { value: 'Installation', depth: 2, slug: 'installation' }
+ * // ]
+ */
 const withSlugs = (headings, slugger) => headings.map((heading) => {
-  return {
-    ...heading,
-    slug: slugger.slug(heading.value)
-  };
+    return {
+        ...heading,
+        slug: slugger.slug(heading.value),
+    };
 });
-function getHeadingsFromMarkdown(input) {
-  const slugger = new GithubSlugger();
-  const headings = getHeadings(input);
-  return withSlugs(headings, slugger);
+/**
+ * Extracts all headings from a Markdown string and adds URL-friendly slugs to each heading.
+ * Uses GithubSlugger to generate consistent slugs that match GitHub's heading anchor format.
+ *
+ * @param input - The Markdown string to extract headings from
+ * @returns Array of heading objects containing value, depth, and slug
+ *
+ * @example
+ * const markdown = `
+ * # Getting Started
+ * ## Installation
+ * ### Requirements
+ * `
+ * const headings = getHeadingsFromMarkdown(markdown)
+ * // Returns:
+ * // [
+ * //   { value: 'Getting Started', depth: 1, slug: 'getting-started' },
+ * //   { value: 'Installation', depth: 2, slug: 'installation' },
+ * //   { value: 'Requirements', depth: 3, slug: 'requirements' }
+ * // ]
+ */
+export function getHeadingsFromMarkdown(input) {
+    const slugger = new GithubSlugger();
+    const headings = getHeadings(input);
+    return withSlugs(headings, slugger);
 }
-const getLowestHeadingLevel = (headings) => {
-  const lowestLevel = Math.min(...headings.map((heading) => heading.depth));
-  if (lowestLevel >= 1 && lowestLevel <= 6) {
-    return lowestLevel;
-  }
-  return 1;
+/**
+ * Returns the lowest heading level from a list of headings.
+ *
+ * @param headings - Array of heading objects containing depth property
+ * @returns The lowest heading level (1-6) or 1 if no valid headings found
+ *
+ * @example
+ * const headings = [
+ *   { value: 'Getting Started', depth: 1 },
+ *   { value: 'Installation', depth: 2 }
+ * ]
+ * getLowestHeadingLevel(headings) // Returns: 1
+ */
+export const getLowestHeadingLevel = (headings) => {
+    const lowestLevel = Math.min(...headings.map((heading) => heading.depth));
+    if (lowestLevel >= 1 && lowestLevel <= 6) {
+        return lowestLevel;
+    }
+    return 1;
 };
-export {
-  getHeadingsFromMarkdown,
-  getLowestHeadingLevel
-};
-//# sourceMappingURL=utils.js.map

package/dist/navigation/index.js

@@ -1,13 +1,5 @@
-import { getOpenapiObject } from "./helpers/get-openapi-object.js";
-import { getOperationEntries } from "./helpers/get-operation-entries.js";
-import { getParentEntry } from "./helpers/get-parent-entry.js";
-import { getTagEntries } from "./helpers/get-tag-entries.js";
-import { traverseDocument } from "./helpers/traverse-document.js";
-export {
-  traverseDocument as createNavigation,
-  getOpenapiObject,
-  getOperationEntries,
-  getParentEntry,
-  getTagEntries
-};
-//# sourceMappingURL=index.js.map
+export { getOpenapiObject } from './helpers/get-openapi-object.js';
+export { getOperationEntries } from './helpers/get-operation-entries.js';
+export { getParentEntry } from './helpers/get-parent-entry.js';
+export { getTagEntries } from './helpers/get-tag-entries.js';
+export { traverseDocument as createNavigation } from './helpers/traverse-document.js';

package/dist/navigation/types.js

@@ -1 +1 @@
-//# sourceMappingURL=types.js.map
+export {};