@stainless-api/docs 0.1.0-beta.126 → 0.1.0-beta.127

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.127
+
+### Patch Changes
+
+- e0d595f: Fix snippet copy button click handler
+- 8752b4e: Fix getProsePages treating all pages as prose when API reference basePath is ""
+- Updated dependencies [871f3c0]
+- Updated dependencies [871f3c0]
+  - @stainless-api/docs-ui@0.1.0-beta.91
+  - @stainless-api/docs-search@0.1.0-beta.44
+
 ## 0.1.0-beta.126
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.126",
+  "version": "0.1.0-beta.127",
   "publishConfig": {
     "access": "public"
   },
@@ -43,12 +43,12 @@
   "dependencies": {
     "@astrojs/markdown-remark": "^7.1.0",
     "@astrojs/react": "^5.0.2",
-    "@markdoc/markdoc": "^0.5.6",
+    "@markdoc/markdoc": "^0.5.7",
     "@stainless-api/sdk": "0.5.0",
     "astro-expressive-code": "^0.41.7",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
-    "dotenv": "17.3.1",
+    "dotenv": "17.4.0",
     "lucide-react": "^0.577.0",
     "node-html-parser": "^7.1.0",
     "rehype-parse": "^9.0.1",
@@ -61,8 +61,8 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.3",
-    "@stainless-api/docs-search": "0.1.0-beta.43",
-    "@stainless-api/docs-ui": "0.1.0-beta.90",
+    "@stainless-api/docs-search": "0.1.0-beta.44",
+    "@stainless-api/docs-ui": "0.1.0-beta.91",
     "@stainless-api/ui-primitives": "0.1.0-beta.51"
   },
   "devDependencies": {
@@ -73,7 +73,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "tsx": "^4.21.0",
-    "typescript": "5.9.3",
+    "typescript": "6.0.2",
     "vite": "^7.3.1",
     "vitest": "^4.1.2",
     "zod": "^4.3.6",

package/plugin/components/RequestBuilder/index.tsx

@@ -22,7 +22,7 @@ export function RequestBuilder({
     if (!spec) throw new Error('Spec is required for RequestBuilder');
     params = spec && extractParams(spec, method);
   } catch (e) {
-    console.warn(e); // eslint-disable-line @eslint-react/purity
+    console.warn(e);
     return <div className={className}>{children}</div>;
   }
   /* eslint-enable */

package/plugin/globalJs/copy.ts

@@ -33,7 +33,7 @@ const preloadPlayground = (event: Event) => {
 };
 addEventListener('mouseover', preloadPlayground);
 addEventListener('click', (event) => {
-  if (!(event.target instanceof HTMLElement)) return;
+  if (!(event.target instanceof Element)) return;
   const copyButton = event.target.closest('[data-stldocs-snippet-copy]');
   if (!(copyButton instanceof HTMLElement)) return;
 

package/plugin/globalJs/navigation.ts

@@ -39,24 +39,22 @@ document.addEventListener(getPageLoadEvent(), () => {
 });
 
 document.addEventListener('click', (event) => {
-  const toggle = (event.target as HTMLElement).closest(
-    '[data-stldocs-property-toggle-expanded] > .stldocs-expand-toggle-content',
-  )?.parentElement;
+  const toggle =
+    event.target instanceof HTMLElement && event.target.closest('[data-stldocs-property-toggle-expanded]');
+  if (!toggle || !(toggle instanceof HTMLElement)) return;
 
-  if (!toggle) return;
-
-  const state = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
-  toggle.dataset.stldocsPropertyToggleExpanded = state ? 'false' : 'true';
+  // Toggle the “expanded” state of the toggle
+  const toggleIsExpanded = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
+  toggle.dataset.stldocsPropertyToggleExpanded = (!toggleIsExpanded).toString();
 
+  // Find the described “property group”
   const targetGroup = toggle.dataset.stldocsPropertyToggleTarget;
   if (!targetGroup) return;
-
   const target = document.querySelector(`[data-stldocs-property-group=${targetGroup}]`);
   if (!target) return;
 
-  target.querySelectorAll('details').forEach((details) => {
-    const el = details;
-    const initial = el.dataset.stldocsExpanderInitialState;
-    el.open = initial === 'true' ? true : !state;
+  // Expand or collapse all <details> elements within the target group
+  [...target.getElementsByTagName('details')].forEach((el) => {
+    el.open = el.dataset.stldocsExpanderInitialState === 'true' ? true : !toggleIsExpanded;
   });
 });

package/plugin/index.ts

@@ -30,7 +30,7 @@ import prebundleWorkers from 'vite-plugin-prebundle-workers';
 import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import { generateMissingRouteList, generateRouteList } from '@stainless-api/docs-ui/routing';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 
 export { generateAPILink } from './generateAPIReferenceLink';
@@ -357,13 +357,26 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
           collectedErrors = null;
         }
 
+        const specComposite = await resolveSpecs();
+
+        // TODO: (multi-spec) support multiple specs
+        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+
+        const basePrefixInOutput = path.posix.join(astroBase, pluginConfig.basePath).replace(/^\/+/, '');
+        const routeList = generateRouteList({ spec });
+        const apiReferencePages = [
+          // overview page
+          path.posix.join(basePrefixInOutput, 'index.html'),
+          // all route pages
+          ...routeList.map((r) => path.posix.join(basePrefixInOutput, r.slug, 'index.html')),
+        ];
+
         const manifest = {
           astroBase,
+          apiReferencePages,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
-        const specComposite = await resolveSpecs();
-
         await buildAlgoliaIndex({
           specComposite,
           logger,
@@ -375,9 +388,6 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         // in this file so Cloudflare can serve them with a 404 status. These pages display helpful information
         // about the missing method and provide links to SDKs where it is available.
 
-        // TODO: (multi-spec) support multiple specs
-        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
-
         const missingRoutes = generateMissingRouteList({
           spec,
           basePath: path.posix.join(astroBase, pluginConfig.basePath),

package/plugin/react/Routing.tsx

@@ -277,7 +277,7 @@ export function RenderSpec({
   const resource = getResourceFromSpec(path, spec);
 
   if (!resource || !parsed) {
-    console.warn(`Could not find resource or parsed path for '${path}'`); // eslint-disable-line @eslint-react/purity
+    console.warn(`Could not find resource or parsed path for '${path}'`);
     return null;
   }
 
@@ -329,7 +329,7 @@ export function RenderMethod({ path }: { path: string }) {
   const resource = getResourceFromSpec(path, spec);
 
   if (!resource || !parsed) {
-    console.warn(`Could not find resource or parsed path for '${path}'`); // eslint-disable-line @eslint-react/purity
+    console.warn(`Could not find resource or parsed path for '${path}'`);
     return null;
   }
 

package/shared/getProsePages.test.ts

@@ -0,0 +1,130 @@
+import type { Dirent } from 'fs';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { join } from 'path';
+
+vi.mock('fs/promises', () => ({
+  readdir: vi.fn(),
+  readFile: vi.fn(),
+}));
+
+import { readdir, readFile } from 'fs/promises';
+import { getProsePages } from './getProsePages';
+
+const mockedReaddir = vi.mocked(readdir);
+const mockedReadFile = vi.mocked(readFile);
+
+function fakeDirent(parentPath: string, name: string, isFile = true): Dirent {
+  return {
+    name,
+    parentPath,
+    path: parentPath,
+    isFile: () => isFile,
+    isDirectory: () => !isFile,
+    isBlockDevice: () => false,
+    isCharacterDevice: () => false,
+    isFIFO: () => false,
+    isSocket: () => false,
+    isSymbolicLink: () => false,
+  } as Dirent;
+}
+
+function stubManifest(apiReferencePages: string[]) {
+  mockedReadFile.mockResolvedValue(JSON.stringify({ astroBase: '/', apiReferencePages }));
+}
+
+function stubReaddir(dirents: Dirent[]) {
+  // readdir has many overloads; cast to match the withFileTypes variant
+  mockedReaddir.mockResolvedValue(dirents as unknown as Awaited<ReturnType<typeof readdir>>);
+}
+
+describe('getProsePages', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    // Default: no manifest
+    mockedReadFile.mockRejectedValue(new Error('ENOENT'));
+  });
+
+  it('does not return API reference pages as prose when basePath is ""', async () => {
+    stubManifest(['resources/users/index.html', 'resources/users/methods/create/index.html']);
+    stubReaddir([
+      fakeDirent('/out/guides', 'intro.html'),
+      fakeDirent('/out/resources/users', 'index.html'),
+      fakeDirent('/out/resources/users/methods/create', 'index.html'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    // resources/users/** are API reference pages, not prose
+    expect(result).not.toContainEqual(join('/out/resources/users', 'index.html'));
+    expect(result).not.toContainEqual(join('/out/resources/users/methods/create', 'index.html'));
+    expect(result).toContainEqual(join('/out/guides', 'intro.html'));
+  });
+
+  it('returns all HTML files when no manifest exists', async () => {
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('returns all HTML files when manifest has empty apiReferencePages', async () => {
+    stubManifest([]);
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('excludes files listed in the manifest', async () => {
+    stubManifest(['api/resources/users/index.html', 'api/resources/users/methods/create/index.html']);
+    stubReaddir([
+      fakeDirent('/out', 'index.html'),
+      fakeDirent('/out/guides', 'intro.html'),
+      fakeDirent('/out/api/resources/users', 'index.html'),
+      fakeDirent('/out/api/resources/users/methods/create', 'index.html'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
+  });
+
+  it('excludes non-HTML files', async () => {
+    stubReaddir([
+      fakeDirent('/out', 'index.html'),
+      fakeDirent('/out', 'style.css'),
+      fakeDirent('/out', 'app.js'),
+    ]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html')]);
+  });
+
+  it('excludes directories', async () => {
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out', 'guides', false)]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([join('/out', 'index.html')]);
+  });
+
+  it('returns empty when all HTML files are in the manifest', async () => {
+    stubManifest(['index.html', 'resources/users/index.html']);
+    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/resources/users', 'index.html')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([]);
+  });
+
+  it('returns empty when output has no HTML files', async () => {
+    stubReaddir([fakeDirent('/out', 'style.css')]);
+
+    const result = await getProsePages({ outputBasePath: '/out' });
+
+    expect(result).toEqual([]);
+  });
+});

package/shared/getProsePages.ts

@@ -1,6 +1,8 @@
-import { readdir } from 'fs/promises';
+import { readdir, readFile } from 'fs/promises';
 import { join, relative } from 'path';
 
+const MANIFEST_PATH = '_stainless/stl-manifest.json';
+
 /**
  * Get all prose pages after a build, by reading all HTML files from the
  * given output directory, and not from assets.
@@ -10,14 +12,11 @@ import { join, relative } from 'path';
  * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
  * previously in the [...slug] asset map entry would be lost (this is where starlight stores
  * its prose HTML files).
+ *
+ * API reference pages are excluded using the manifest written by the API
+ * reference plugin at build time, rather than guessing based on path prefix.
  */
-export async function getProsePages({
-  apiReferenceBasePath,
-  outputBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-  outputBasePath: string;
-}): Promise<string[]> {
+export async function getProsePages({ outputBasePath }: { outputBasePath: string }): Promise<string[]> {
   const allFiles = await readdir(outputBasePath, {
     recursive: true,
     withFileTypes: true,
@@ -27,15 +26,22 @@ export async function getProsePages({
     .filter((file) => file.isFile() && file.name.endsWith('.html'))
     .map((file) => join(file.parentPath, file.name));
 
-  if (!apiReferenceBasePath) return htmlFiles;
-  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
-  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
-  const pagesToRender = htmlFiles.filter((absPath) => {
+  const apiReferencePages = await readApiReferencePagesFromManifest(outputBasePath);
+  if (apiReferencePages.size === 0) return htmlFiles;
+
+  return htmlFiles.filter((absPath) => {
     const relPath = relative(outputBasePath, absPath);
-    // Filter out API reference pages
-    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
-    return true;
+    return !apiReferencePages.has(relPath);
   });
+}
 
-  return pagesToRender;
+async function readApiReferencePagesFromManifest(outputBasePath: string): Promise<Set<string>> {
+  try {
+    const raw = await readFile(join(outputBasePath, MANIFEST_PATH), 'utf-8');
+    const manifest = JSON.parse(raw) as { apiReferencePages?: string[] };
+    const pages = manifest.apiReferencePages ?? [];
+    return new Set(pages);
+  } catch {
+    return new Set();
+  }
 }

package/stl-docs/index.ts

@@ -303,17 +303,17 @@ export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration
     stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
     conditionalIntegration({
       condition: !config.experimental?.disableProseMarkdownRendering,
-      integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
+      integration: stainlessDocsMarkdownRenderer(),
       reason: 'disabled by experimental config "disableProseMarkdownRendering"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
+      integration: stainlessDocsAlgoliaProseIndexing(),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
+      integration: stainlessDocsVectorProseIndexing(normalizedConfig),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
   ];

package/stl-docs/proseDocSync.ts

@@ -304,10 +304,7 @@ async function syncProseDocuments(opts: {
 
 // ─── Astro integration ──────────────────────────────────────────────
 
-export function stainlessDocsVectorProseIndexing(
-  config: NormalizedStainlessDocsConfig,
-  apiReferenceBasePath: string | null,
-): AstroIntegration {
+export function stainlessDocsVectorProseIndexing(config: NormalizedStainlessDocsConfig): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -331,7 +328,7 @@ export function stainlessDocsVectorProseIndexing(
           return;
         }
 
-        const pages = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pages = await getProsePages({ outputBasePath });
         if (pages.length === 0) {
           logger.info('No prose pages found to index for vector search');
           return;

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -6,11 +6,7 @@ import { getSharedLogger } from '../../shared/getSharedLogger';
 import { bold } from '../../shared/terminalUtils';
 import { getProsePages } from '../../shared/getProsePages';
 
-export function stainlessDocsMarkdownRenderer({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
+export function stainlessDocsMarkdownRenderer(): AstroIntegration {
   return {
     name: 'stl-docs-md',
     hooks: {
@@ -23,7 +19,7 @@ export function stainlessDocsMarkdownRenderer({
       'astro:build:done': async ({ logger: localLogger, dir }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         const outputBasePath = dir.pathname;
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pagesToRender = await getProsePages({ outputBasePath });
 
         logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
 

package/stl-docs/proseSearchIndexing.ts

@@ -174,11 +174,7 @@ export function* indexHTML(
   }
 }
 
-export function stainlessDocsAlgoliaProseIndexing({
-  apiReferenceBasePath,
-}: {
-  apiReferenceBasePath: string | null;
-}): AstroIntegration {
+export function stainlessDocsAlgoliaProseIndexing(): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -197,7 +193,7 @@ export function stainlessDocsAlgoliaProseIndexing({
           return;
         }
 
-        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        const pagesToRender = await getProsePages({ outputBasePath });
         logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
 
         const objects = [];