@stainless-api/docs 0.1.0-beta.1 → 0.1.0-beta.100

package/stl-docs/components/nav-tabs/NavTabs.astro

@@ -7,80 +7,98 @@ import clsx from 'clsx';
 const navLinks = buildNavLinks(Astro.locals.starlightRoute);
 ---
 
-<div id="nav-links-container">
-  <ul class="nav-links" id="nav-links-list">
-    <li class="mobile-menu-item" data-mobile-only>
-      <NavDropdown />
-    </li>
-    {
-      navLinks.map((item) => (
-        <li data-desktop-only>
-          <Button
-            href={item.link}
-            className={clsx('nav-link')}
-            variant={item.active ? 'accent-muted' : 'ghost'}
-          >
-            <span>{item.label}</span>
-          </Button>
-        </li>
-      ))
-    }
-  </ul>
-  <!-- The test container is used to measure the width of the nav links and see if they fit -->
-  <!-- TODO: probably want to clean this up bc it's duplicated code -->
-  <ul class="nav-links" id="nav-links-test-container">
-    {
-      navLinks.map((item) => (
-        <li>
-          <Button href={item.link} className={clsx('nav-link')} variant={item.active ? 'accent' : 'ghost'}>
-            <span>{item.label}</span>
-          </Button>
-        </li>
-      ))
-    }
-  </ul>
+<div id="nav-links-container" class="nav-links-container">
+  <div class="desktop-nav-links-container">
+    <ul class="nav-links" id="nav-links-list">
+      {
+        navLinks.map((item) => (
+          <li data-desktop-only>
+            <Button
+              href={item.link}
+              className={clsx('nav-link')}
+              variant={item.active ? 'accent-muted' : 'ghost'}
+            >
+              <span>{item.label}</span>
+            </Button>
+          </li>
+        ))
+      }
+    </ul>
+  </div>
+  <div class="mobile-nav-dropdown" data-mobile-only>
+    <NavDropdown />
+  </div>
 </div>
 
 <script>
   import { getPageLoadEvent } from '../../../plugin/helpers/getPageLoadEvent';
 
-  function getRequiredWidth() {
-    const navLinksTestContainer = document.getElementById('nav-links-test-container');
-    if (!navLinksTestContainer) return 1000000; // fallback to a large number
+  // We need to measure the nav links to see if they fit. We create an offscreen hidden clone for measurement.
+  function createOffscreenClone(element: HTMLElement): HTMLElement {
+    const clone = element.cloneNode(true) as HTMLElement;
+    clone.removeAttribute('id');
+    clone.id = 'cloned-nav-links-measurement';
+    clone.style.position = 'absolute';
+    clone.style.visibility = 'hidden';
+    clone.style.top = '0';
+    clone.style.left = '0';
+    clone.style.width = 'auto';
+    clone.style.whiteSpace = 'nowrap';
+    clone.style.pointerEvents = 'none';
+    clone.style.zIndex = '-9999';
+
+    clone.querySelectorAll('[data-desktop-only], [data-mobile-only]').forEach((el) => {
+      el.removeAttribute('data-desktop-only');
+    });
 
-    const rw = navLinksTestContainer.scrollWidth;
-    navLinksTestContainer.remove();
-    return rw;
+    document.body.appendChild(clone);
+    return clone;
   }
 
   function initNavbar() {
-    const masterContainer = document.getElementById('nav-links-container');
-    if (!masterContainer) return;
+    const navLinksContainer = document.getElementById('nav-links-container');
+    if (!navLinksContainer) {
+      console.error(`NavTabs: #nav-links-container not found`);
+      return;
+    }
 
-    const navLinksContainer = document.getElementById('nav-links-list');
-    if (!navLinksContainer) return;
+    const navLinksList = document.getElementById('nav-links-list');
+    if (!navLinksList) {
+      console.error(`NavTabs: #nav-links-list not found`);
+      return;
+    }
+
+    const measurementClone = createOffscreenClone(navLinksList);
+    const requiredWidth = measurementClone.clientWidth;
 
-    const requiredWidth = getRequiredWidth();
+    let currentMode: 'desktop' | 'mobile' | null = null;
 
     function checkIfFits() {
-      if (!masterContainer) return;
       if (!navLinksContainer) return;
-      const availableWidth = masterContainer.clientWidth;
-      const canFit = availableWidth >= requiredWidth;
+
+      // 16px buffer helps it feel less crowded before switching modes
+      const bufferSpace = 16;
+      const availableWidth = navLinksContainer.clientWidth;
+      const canFit = availableWidth - bufferSpace >= requiredWidth;
 
       const mode = canFit ? 'desktop' : 'mobile';
 
-      localStorage.setItem('stl-nav-links-mode', mode);
+      // Only update if mode actually changed
+      if (mode === currentMode) return;
+
+      currentMode = mode;
 
-      document.documentElement.classList.remove('stl-nav-links-mode-desktop');
-      document.documentElement.classList.remove('stl-nav-links-mode-mobile');
+      localStorage.setItem('stl-nav-links-mode', mode);
 
+      document.documentElement.classList.remove('stl-nav-links-mode-desktop', 'stl-nav-links-mode-mobile');
       document.documentElement.classList.add('stl-nav-links-mode-' + mode);
     }
 
-    window.addEventListener('resize', () => {
+    const resizeObserver = new ResizeObserver(() => {
       checkIfFits();
     });
+
+    resizeObserver.observe(navLinksContainer);
     checkIfFits();
   }
 
@@ -109,55 +127,35 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
 </style>
 
 <style>
-  /* :root {
-    --menu-font-size: calc(var(--sl-text-body));
-  } */
+  .nav-links-container {
+    flex-grow: 1;
+    margin-left: 1rem;
+    margin-right: 1rem;
+  }
 
-  #nav-links-container {
-    visibility: hidden;
+  .desktop-nav-links-container {
     display: flex;
     flex-grow: 1;
     justify-content: flex-start;
     overflow: hidden;
-    margin-left: 1rem;
-    margin-right: 1rem;
   }
 
   .nav-links {
     display: flex;
     list-style: none;
-    gap: 0;
+    gap: 4px;
     padding: 0;
     margin: 0;
     white-space: nowrap;
     overflow: hidden;
   }
 
-  #nav-links-test-container {
-    position: absolute;
-    top: 0;
-    left: 0;
-    visibility: hidden;
-  }
-
-  .nav-links li {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-
-  .nav-link {
-    text-decoration: none;
-    flex: 1;
-
-    &.stl-ui-button--ghost:hover {
-      color: var(--sl-color-text-accent);
-      background-color: transparent;
-    }
+  .mobile-nav-dropdown {
+    flex-grow: 1;
   }
 
   @media (min-width: 50rem) {
-    #nav-links-container {
+    .desktop-nav-links-container {
       display: flex;
       visibility: visible;
     }

package/stl-docs/components/nav-tabs/SecondaryNavTabs.astro

@@ -34,13 +34,7 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
       align-items: center;
       padding: 0;
       list-style: none;
-      overflow-x: auto;
       margin-bottom: -1px;
-      gap: 0.29rem;
-    }
-
-    .stl-active-secondary-link:hover {
-      background-color: transparent;
     }
 
     li {
@@ -48,7 +42,21 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
       border-bottom: 2px solid transparent;
 
       &.active {
-        border-color: var(--sl-color-text-accent);
+        border-color: var(--stl-color-accent-border-strong);
+      }
+
+      .stl-ui-button {
+        /* match sidebar. TODO: hoist sidebar variables to use those instead of hardcoding? */
+        border-width: 0;
+        padding: 8px 12px;
+        margin-inline: -12px;
+      }
+      /* cover for button’s negative margin */
+      &:not(:first-child) {
+        margin-inline-start: 12px;
+      }
+      &:not(:last-child) {
+        margin-inline-end: 12px;
       }
     }
   }
@@ -56,7 +64,6 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
   @media (min-width: 50rem) {
     .stl-secondary-nav-tabs {
       display: block;
-      padding-left: 0.55rem;
     }
   }
 </style>

package/stl-docs/components/nav-tabs/buildNavLinks.ts

@@ -1,9 +1,10 @@
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import { TABS } from 'virtual:stl-stl-starlight-virtual-module';
+import { TABS } from 'virtual:stl-docs-virtual-module';
+import type { StarlightRouteWithStlDocs } from '../../tabsMiddleware';
 
 export function buildNavLinks(starlightRoute: StarlightRouteData) {
-  // TODO: specify the type of Astro.locals.starlightRoute._stlStarlight
-  const activeTabIndex = starlightRoute._stlStarlight?.activeTabIndex;
+  const routeData: StarlightRouteWithStlDocs = starlightRoute;
+  const activeTabIndex = routeData?._stlDocs?.activeTabIndex;
 
   const navLinks = TABS.map((item, index) => ({
     ...item,

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,175 @@
+---
+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-color-faint-background);
+    border: 1px solid var(--stl-color-border);
+    border-radius: calc(var(--stl-ui-pagination-border-radius-inner) + var(--stl-ui-pagination-padding));
+
+    font-size: var(--stl-typography-scale-sm);
+    letter-spacing: normal;
+
+    display: flex;
+    gap: 8px;
+
+    margin-bottom: 2rem;
+    color: inherit; /* stl-ui-not-prose sets color: initial */
+
+    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;
+    color: inherit;
+  }
+
+  .pagination-links__link--emphasized {
+    background-color: var(--stl-color-background);
+    border: 1px solid var(--stl-color-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-color-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-typography-scale-xs);
+      color: var(--stl-color-foreground-muted);
+    }
+  }
+  .pagination-links__link--quiet:hover {
+    background-color: var(--stl-color-background-hover);
+  }
+  .pagination-links__link--emphasized:hover {
+    border-color: var(--stl-color-border-strong);
+    .pagination-links__page-description h2 {
+      text-decoration: underline;
+      text-decoration-color: var(--stl-color-foreground-reduced);
+    }
+  }
+
+  /* “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/components/scripts.ts

@@ -0,0 +1 @@
+export * from '@stainless-api/ui-primitives/scripts';

package/stl-docs/components/sidebars/BaseSidebar.astro

@@ -0,0 +1,87 @@
+---
+import HeaderLinks from '../headers/HeaderLinks.astro';
+import { SidebarWithComponents } from './SidebarWithComponents';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+import { convertAstroSidebarToStl } from './convertAstroSidebarToStl';
+import { StlSidebarEntry, StlSidebarGroup, StlSidebarLink } from '@stainless-api/docs-ui/components';
+import { LINK_GROUP_TITLES_TO_OVERVIEW_PAGES } from 'virtual:stl-docs-virtual-module';
+
+const { sidebar } = Astro.locals.starlightRoute;
+
+let stlSidebar = convertAstroSidebarToStl(sidebar);
+
+function extractOverviewPage(entry: StlSidebarGroup): {
+  overviewLink: StlSidebarLink | null;
+  remainingEntries: StlSidebarEntry[];
+} {
+  let overviewLink: StlSidebarLink | null = null;
+
+  const withoutOverview = entry.entries.filter((e) => {
+    if (e.type !== 'link') {
+      return true;
+    }
+    const overviewAttr = e.attrs?.['data-stldocs-overview'];
+    if (!overviewAttr) {
+      return true;
+    }
+    overviewLink = e;
+    return false;
+  });
+
+  return {
+    overviewLink,
+    remainingEntries: withoutOverview,
+  };
+}
+
+function linkGroupTitleToOverviewPages(sidebar: StlSidebarEntry[]): StlSidebarEntry[] {
+  return sidebar.map((entry) => {
+    if (entry.type === 'group') {
+      const { overviewLink, remainingEntries } = extractOverviewPage(entry);
+
+      // group only contained an overview link
+      if (overviewLink && remainingEntries.length === 0) {
+        return {
+          ...overviewLink,
+          label: entry.label, // keep the group label
+        };
+      }
+
+      // set the group target to the overview link target
+
+      let target = entry.target;
+      let isCurrent = entry.isCurrent;
+      let collapsed = entry.collapsed;
+      if (overviewLink) {
+        target = overviewLink.target;
+        isCurrent = overviewLink.isCurrent;
+        if (isCurrent) {
+          collapsed = false;
+        }
+      }
+
+      return {
+        ...entry,
+        entries: linkGroupTitleToOverviewPages(remainingEntries),
+        target,
+        isCurrent,
+        collapsed,
+      };
+    } else {
+      return entry;
+    }
+  });
+}
+
+if (LINK_GROUP_TITLES_TO_OVERVIEW_PAGES === true) {
+  stlSidebar = linkGroupTitleToOverviewPages(stlSidebar);
+}
+---
+
+<div class="stl-sidebar-header-links">
+  <HeaderLinks />
+</div>
+<slot name="sdk-select" />
+<SidebarPersister>
+  <SidebarWithComponents entries={stlSidebar} withStarlightRestoration />
+</SidebarPersister>

package/stl-docs/components/sidebars/SDKSelectSidebar.astro

@@ -0,0 +1,8 @@
+---
+import BaseSidebar from './BaseSidebar.astro';
+import SDKSelect from '../../../plugin/components/SDKSelect.astro';
+---
+
+<BaseSidebar>
+  <SDKSelect slot="sdk-select" />
+</BaseSidebar>

package/stl-docs/components/sidebars/SidebarWithComponents.tsx

@@ -0,0 +1,10 @@
+import { StlSidebar, StlSidebarProps } from '@stainless-api/docs-ui/components';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+
+export function SidebarWithComponents(props: StlSidebarProps) {
+  return (
+    <ComponentProvider>
+      <StlSidebar {...props} />
+    </ComponentProvider>
+  );
+}