@stainless-api/docs 0.1.0-beta.19 → 0.1.0-beta.20

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.20
+
+### Patch Changes
+
+- 9cdb24d: Update pagination components, fix search modal
+- Updated dependencies [9cdb24d]
+  - @stainless-api/docs-ui@0.1.0-beta.16
+  - @stainless-api/ui-primitives@0.1.0-beta.16
+
 ## 0.1.0-beta.19
 
 ### Patch Changes

package/components/variables.css

@@ -25,6 +25,7 @@
 
   --stldocs-color-bg: var(--sl-color-bg);
   --stldocs-color-bg-nav: var(--sl-color-bg-nav);
+  --stldocs-color-selected: var(--sl-color-gray-6);
   --stldocs-color-bg-ui: var(--sl-color-bg-ui);
 
   --stldocs-color-bg-inline-code: var(--sl-color-bg-inline-code);

package/locals.d.ts

@@ -0,0 +1,14 @@
+type SidebarEntry = App.Locals['starlightRoute']['sidebar'][number];
+
+/**
+ * Extending Astro’s `App.Locals` interface
+ */
+declare namespace App {
+  interface Locals {
+    _stlStarlightPage?: {
+      skipRenderingStarlightTitle?: boolean;
+      hasMarkdownRoute?: boolean;
+      fullSidebar?: SidebarEntry[];
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.20",
   "publishConfig": {
     "access": "public"
   },
@@ -50,8 +50,8 @@
     "remark-gfm": "^4.0.1",
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.5",
-    "@stainless-api/docs-ui": "0.1.0-beta.15",
-    "@stainless-api/ui-primitives": "0.1.0-beta.15"
+    "@stainless-api/ui-primitives": "0.1.0-beta.16",
+    "@stainless-api/docs-ui": "0.1.0-beta.16"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.5",
@@ -65,8 +65,8 @@
     "typescript": "5.9.3",
     "vite": "^6.3.6",
     "zod": "^4.0.0",
-    "@stainless/sdk-json": "^0.0.0",
-    "@stainless/eslint-config": "0.0.0"
+    "@stainless/eslint-config": "0.0.0",
+    "@stainless/sdk-json": "^0.0.0"
   },
   "scripts": {
     "vendor-deps": "pnpm tsx scripts/vendor_deps.ts",

package/plugin/components/search/SearchIsland.tsx

@@ -14,6 +14,7 @@ import {
   NavigationProvider,
   SearchProvider,
 } from '@stainless-api/docs-ui/src/contexts';
+import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
 import type { SearchSettings } from '@stainless-api/docs-ui/src/search/types';
 
 let $$highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null = null;
@@ -95,16 +96,18 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
 
   return (
     <DocsProvider spec={null} language={language}>
-      <NavigationProvider basePath="/" selectedPath={stainlessPath}>
-        <MarkdownProvider {...markdownRenderer}>
-          <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
-            <div className="stldocs-root">
-              <SearchModal id="stldocs-search" />
-              {SEARCH?.enableAISearch === true && <ChatModal id="stldocs-chat" />}
-            </div>
-          </SearchProvider>
-        </MarkdownProvider>
-      </NavigationProvider>
+      <ComponentProvider>
+        <NavigationProvider basePath="/" selectedPath={stainlessPath}>
+          <MarkdownProvider {...markdownRenderer}>
+            <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
+              <div className="stldocs-root">
+                <SearchModal id="stldocs-search" />
+                {SEARCH?.enableAISearch === true && <ChatModal id="stldocs-chat" />}
+              </div>
+            </SearchProvider>
+          </MarkdownProvider>
+        </NavigationProvider>
+      </ComponentProvider>
     </DocsProvider>
   );
 }

package/plugin/routes/Docs.astro

@@ -21,7 +21,6 @@ if (!route) {
 }
 
 // PageTitle override will skip rendering the default Starlight title
-// @ts-expect-error - _stlStarlightPage isn't typed yet
 Astro.locals._stlStarlightPage = {
   skipRenderingStarlightTitle: route.props.kind === 'readme' ? false : true,
 };
@@ -88,7 +87,7 @@ if (readme) {
 
           .stldocs-snippet-code:not(.stldocs-snippet-response .stldocs-snippet-code) {
             padding: 0 !important;
-            
+
             .astro-code {
               padding: 1rem;
             }

package/plugin/routes/Overview.astro

@@ -14,7 +14,6 @@ const metadata: SpecMetadata = languages
   .map<SpecMetadata[number]>((language) => [language, spec.metadata[language]!]);
 
 // PageTitle override will skip rendering the default Starlight title
-// @ts-expect-error - _stlStarlightPage isn't typed yet
 Astro.locals._stlStarlightPage = {
   hasMarkdownRoute: false,
 };

package/src/content.config.ts

@@ -0,0 +1,9 @@
+// Stub here so that `astro sync` generates the correct types for the `docs` content collection
+
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/stl-docs/components/PageTitle.astro

@@ -29,12 +29,9 @@ function sidebarHasEntry(sidebarEntry: StarlightRouteData['sidebar'], currentPat
   return false;
 }
 
-// @ts-expect-error - _stlStarlightPage isn't typed
-const skipRenderingStarlightTitle = (Astro.locals._stlStarlightPage?.skipRenderingStarlightTitle ??
-  false) as boolean;
+const skipRenderingStarlightTitle = Astro.locals._stlStarlightPage?.skipRenderingStarlightTitle ?? false;
 
-// @ts-expect-error - _stlStarlightPage isn't typed
-const hasMarkdownRoute = (Astro.locals._stlStarlightPage?.hasMarkdownRoute ?? true) as boolean;
+const hasMarkdownRoute = Astro.locals._stlStarlightPage?.hasMarkdownRoute ?? true;
 // ⬆️ hopefully this is temporary. But for now, we don't have a markdown representation of the API reference overview page
 
 const currentPath = Astro.url.pathname;

package/stl-docs/components/pagination/HomeLink.astro

@@ -0,0 +1,10 @@
+---
+import { base } from 'astro:config/client';
+import { HomeIcon } from 'lucide-react';
+import PaginationLinkQuiet from './PaginationLinkQuiet.astro';
+---
+
+<PaginationLinkQuiet href={base}>
+  <HomeIcon slot="icon" />
+  Home
+</PaginationLinkQuiet>

package/stl-docs/components/pagination/Pagination.astro

@@ -0,0 +1,173 @@
+---
+import HomeLink from './HomeLink.astro';
+import PaginationLinkEmphasized from './PaginationLinkEmphasized.astro';
+
+import { getPrevNextPage } from './util';
+import config from 'virtual:starlight/user-config';
+const { prev, next } = (await getPrevNextPage(Astro.locals.starlightRoute, config.pagination)) ?? {};
+---
+
+{
+  next || prev ? (
+    <div class="pagination-links print:hidden stl-ui-not-prose">
+      {/* Previous */}
+      {!prev && <HomeLink />}
+      {/* TODO: intelligently decide whether or not to emphasize the previous page - including user config option (page level?) */}
+      {/* {prev && next && (
+        <PaginationLinkQuiet href={prev.href}>
+          <ChevronLeftIcon slot="icon" />
+          Previous
+        </PaginationLinkQuiet>
+      )} */}
+      {prev && (
+        <PaginationLinkEmphasized href={prev.href} direction="prev">
+          <h2 slot="page-title">{prev.label}</h2>
+          {prev.description && <p slot="page-description">{prev.description}</p>}
+        </PaginationLinkEmphasized>
+      )}
+
+      {/* Next */}
+      {!next && <HomeLink />}
+      {next && (
+        <PaginationLinkEmphasized href={next.href} direction="next">
+          <h2 slot="page-title">{next.label}</h2>
+          {next.description && <p slot="page-description">{next.description}</p>}
+        </PaginationLinkEmphasized>
+      )}
+    </div>
+  ) : null
+}
+
+<style is:global>
+  @layer starlight.core {
+    .pagination-links,
+    .pagination-links a,
+    .pagination-links a:hover,
+    .pagination-links a[rel='next'],
+    .link-title {
+      all: revert-layer;
+    }
+  }
+
+  .pagination-links {
+    --stl-ui-pagination-padding: 8px;
+    --stl-ui-pagination-border-radius-inner: var(--stl-ui-layout-border-radius-sml);
+
+    padding: var(--stl-ui-pagination-padding);
+    background-color: var(--stl-ui-muted-background);
+    border: 1px solid var(--stl-ui-border);
+    border-radius: calc(var(--stl-ui-pagination-border-radius-inner) + var(--stl-ui-pagination-padding));
+
+    font-size: var(--stl-ui-type-scale-text-sm);
+    letter-spacing: normal;
+
+    display: flex;
+    gap: 8px;
+
+    margin-bottom: 2rem;
+
+    a {
+      border-radius: var(--stl-ui-pagination-border-radius-inner);
+    }
+  }
+
+  .pagination-links__link {
+    display: flex;
+    border-radius: var(--stl-ui-pagination-border-radius-inner);
+    padding: 8px 12px;
+    display: flex;
+    text-decoration: none;
+    align-items: center;
+  }
+
+  .pagination-links__link--emphasized {
+    background-color: var(--stl-ui-background);
+    border: 1px solid var(--stl-ui-border);
+    flex: 1 1 50%;
+    gap: 12px;
+  }
+
+  .pagination-links__link--quiet {
+    flex: 0 1 auto;
+  }
+
+  .pagination-links__button {
+    display: flex;
+    align-items: center;
+    padding: 8px 14px;
+    font-weight: 500;
+    line-height: 1;
+
+    svg {
+      width: 16px;
+      height: 16px;
+      margin-block: -4px;
+      margin-inline-start: -6px;
+      margin-inline-end: 6px;
+    }
+
+    &.pagination-links__link--quiet {
+      padding-inline: 22px;
+    }
+  }
+
+  .pagination-links__link__divider {
+    border: 0;
+    border-inline-start: 1px solid var(--stl-ui-border);
+    align-self: stretch;
+  }
+
+  .pagination-links__page-description {
+    padding-block: 4px;
+    padding-inline-start: 8px;
+    padding-inline-end: 2px;
+    line-height: 1.5;
+    flex: 1 1 50%;
+    width: 0;
+
+    h2,
+    p {
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    h2 {
+      font-size: inherit;
+      font-weight: 500;
+    }
+    p {
+      font-size: var(--stl-ui-type-scale-text-xs);
+      color: var(--stl-ui-foreground-muted);
+    }
+  }
+
+  .pagination-links__link--quiet:hover {
+    background-color: rgb(from var(--stl-ui-foreground) r g b / 0.05);
+  }
+  .pagination-links__link--emphasized:hover {
+    border-color: var(--stl-ui-border-emphasis);
+    .pagination-links__page-description h2 {
+      text-decoration: underline;
+    }
+  }
+
+  /* “next” link runs the opposite direction of the “previous” link */
+  .pagination-links__link:last-child {
+    flex-direction: row-reverse;
+
+    &.pagination-links__button,
+    .pagination-links__button {
+      flex-direction: row-reverse;
+      svg {
+        margin-inline-start: 6px;
+        margin-inline-end: -6px;
+      }
+    }
+
+    .pagination-links__page-description {
+      padding-inline-start: 2px;
+      padding-inline-end: 8px;
+      text-align: right;
+    }
+  }
+</style>

package/stl-docs/components/pagination/PaginationLinkEmphasized.astro

@@ -0,0 +1,22 @@
+---
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+const { href, direction } = Astro.props;
+export interface Props {
+  href: string;
+  direction: 'prev' | 'next';
+}
+---
+
+<a href={href} class="pagination-links__link pagination-links__link--emphasized">
+  <div class="pagination-links__button">
+    {{ prev: <ChevronLeftIcon />, next: <ChevronRightIcon /> }[direction]}
+    <span>{{ prev: 'Previous', next: 'Next' }[direction]}</span>
+  </div>
+
+  <hr class="pagination-links__link__divider" />
+
+  <article class="pagination-links__page-description">
+    <slot name="page-title" />
+    <slot name="page-description" />
+  </article>
+</a>

package/stl-docs/components/pagination/PaginationLinkQuiet.astro

@@ -0,0 +1,13 @@
+---
+const { href } = Astro.props;
+export interface Props {
+  href: string;
+}
+---
+
+<a href={href} class="pagination-links__link pagination-links__button pagination-links__link--quiet">
+  <slot name="icon" />
+  <span>
+    <slot />
+  </span>
+</a>

package/stl-docs/components/pagination/util.ts

@@ -0,0 +1,71 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { getCollection } from 'astro:content';
+
+export type SidebarEntry = StarlightRouteData['sidebar'][number];
+export type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+export type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+
+export const flattenSidebar = (sidebar: SidebarEntry[]): SidebarLink[] =>
+  sidebar.flatMap((e) => (e.type === 'group' ? flattenSidebar(e.entries) : e));
+
+function findParentOfSidebarEntry(sidebar: SidebarEntry[], targetEntry: SidebarEntry): SidebarGroup | null {
+  for (const entry of sidebar) {
+    if (entry.type === 'group') {
+      if (entry.entries.includes(targetEntry)) {
+        return entry;
+      }
+      const foundInChild = findParentOfSidebarEntry(entry.entries, targetEntry);
+      if (foundInChild) {
+        return foundInChild;
+      }
+    }
+  }
+  return null;
+}
+
+export async function getPrevNextPage(page: StarlightRouteData, paginationEnabled: boolean) {
+  // TODO: respect user `next` / `prev` config from frontmatter the way starlight does
+
+  if (!paginationEnabled) return null;
+
+  const docsContent = await getCollection('docs');
+  const findSidebarLinkInContent = (link: SidebarLink) =>
+    docsContent.find((doc) => {
+      if (doc.id === 'index' && link.href === '/') return true;
+      return doc.id === link.href.replace(/^\//, '').replace(/\/$/, '');
+    });
+
+  const currentSidebar = page.sidebar;
+
+  const paginationSequence: (SidebarLink & { description?: string })[] = flattenSidebar(currentSidebar)
+    // Remove injected stl-mobile-only-sidebar-item links - TODO: better solution for this
+    .filter((link) => !(link.attrs.class ?? '').trim().split(/\s+/).includes('stl-mobile-only-sidebar-item'))
+    // Remove data-stldocs-method links from pagination sequence
+    .filter((link) => !link.attrs['data-stldocs-method'])
+    // Map data-stldocs-overview=readme links so that their name is not just “Overview”
+    .map((link) => {
+      if (link.attrs['data-stldocs-overview'] && link.label === 'Overview') {
+        const parent = findParentOfSidebarEntry(currentSidebar, link);
+        if (parent) return { ...link, label: parent.label };
+      }
+      return link;
+    })
+    .map((link) => {
+      const contentEntry = findSidebarLinkInContent(link);
+      if (contentEntry) return { ...link, description: contentEntry.data.description };
+      return link;
+    });
+
+  const currentIndex = paginationSequence.findIndex((e) => e.isCurrent);
+  if (currentIndex === -1) return null;
+
+  const prevIndex = currentIndex > 0 ? currentIndex - 1 : null;
+  const nextIndex = currentIndex < paginationSequence.length - 1 ? currentIndex + 1 : null;
+  const prevSidebarEntry = prevIndex !== null ? (paginationSequence[prevIndex] ?? null) : null;
+  const nextSidebarEntry = nextIndex !== null ? (paginationSequence[nextIndex] ?? null) : null;
+
+  return {
+    prev: prevSidebarEntry,
+    next: nextSidebarEntry,
+  };
+}

package/stl-docs/index.ts

@@ -54,6 +54,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
     ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
     TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
     PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.astro'),
   };
 
   const plugins: StarlightPlugin[] = [

package/stl-docs/tabsMiddleware.ts

@@ -186,5 +186,6 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   matchingGroup?.entries.unshift(...mobileLinks);
 
+  (context.locals._stlStarlightPage ??= {}).fullSidebar = context.locals.starlightRoute.sidebar;
   context.locals.starlightRoute.sidebar = matchingGroup.entries;
 });

package/styles/links.css

@@ -10,40 +10,3 @@
   border: 1px solid var(--sl-color-accent-high);
   background-color: var(--sl-color-accent-low);
 }
-
-.pagination-links {
-  margin-bottom: 2rem;
-
-  > a {
-    border-radius: var(--sl-button-border-radius);
-    border: 1px solid transparent;
-    box-shadow: none;
-    max-width: 90%;
-    text-decoration: none;
-
-    svg {
-      margin-top: 0;
-      transform: translateY(6px);
-    }
-  }
-
-  > a:hover {
-    transition: 0.3s;
-    border: 1px solid var(--sl-color-accent-high);
-    background-color: var(--sl-color-accent-low);
-    box-shadow: none;
-  }
-
-  /* if only one pagination direction */
-  > a:first-child:nth-last-child(1) {
-    max-width: 45%;
-  }
-
-  > a[rel='next'] {
-    margin-left: auto;
-  }
-
-  > a[rel='prev'] {
-    margin-right: auto;
-  }
-}

package/styles/page.css

@@ -91,3 +91,16 @@
     --sl-mobile-toc-height: 0rem;
   }
 }
+
+.content-panel footer {
+  /* Don’t render empty footer meta, which results in extra margin getting applied on behalf of the flex gap.
+   * Instead, move its margin to its parent. */
+  margin-top: 3rem;
+  .meta {
+    margin-top: 0;
+    &:empty,
+    &:not(:has(> *)) {
+      display: none;
+    }
+  }
+}