@stainless-api/docs 0.1.0-beta.0

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

@@ -0,0 +1,62 @@
+---
+import { Button } from '@stainless-api/ui-primitives';
+import { buildNavLinks } from './buildNavLinks';
+import clsx from 'clsx';
+
+const navLinks = buildNavLinks(Astro.locals.starlightRoute);
+---
+
+<div class="stl-secondary-nav-tabs">
+  <ul>
+    {
+      navLinks.map((item) => (
+        <li class:list={[item.active && 'active']}>
+          <Button
+            href={item.link}
+            variant="ghost"
+            className={clsx(item.active && 'stl-active-secondary-link')}
+          >
+            <Button.Label>{item.label}</Button.Label>
+          </Button>
+        </li>
+      ))
+    }
+  </ul>
+</div>
+
+<style>
+  .stl-secondary-nav-tabs {
+    display: none;
+    width: 100%;
+
+    ul {
+      display: flex;
+      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 {
+      padding-bottom: 1px;
+      border-bottom: 2px solid transparent;
+
+      &.active {
+        border-color: var(--sl-color-text-accent);
+      }
+    }
+  }
+
+  @media (min-width: 50rem) {
+    .stl-secondary-nav-tabs {
+      display: block;
+      padding-left: 0.55rem;
+    }
+  }
+</style>

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

@@ -0,0 +1,14 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { TABS } from 'virtual:stl-stl-starlight-virtual-module';
+
+export function buildNavLinks(starlightRoute: StarlightRouteData) {
+  // TODO: specify the type of Astro.locals.starlightRoute._stlStarlight
+  const activeTabIndex = starlightRoute._stlStarlight?.activeTabIndex;
+
+  const navLinks = TABS.map((item, index) => ({
+    ...item,
+    active: index === activeTabIndex,
+  })).filter((item) => !item.hidden);
+
+  return navLinks;
+}

package/stl-docs/index.ts

@@ -0,0 +1,174 @@
+import starlight from '@astrojs/starlight';
+import react from '@astrojs/react';
+import { stainlessStarlight } from '../plugin';
+
+import type { AstroIntegration } from 'astro';
+
+import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
+import { join } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import {
+  parseStlDocsConfig,
+  type Defined,
+  type NormalizedStainlessDocsConfig,
+  type StainlessDocsUserConfig,
+  type StarlightConfigDefined,
+  type StarlightSidebarConfig,
+} from './loadStlDocsConfig';
+import { buildVirtualModuleString } from '../shared/virtualModule';
+
+import geistPath from '../plugin/assets/fonts/geist/geist-latin.woff2?url';
+
+export * from '../plugin';
+
+function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig) {
+  // We transform our tabs into a Starlight sidebar
+  // This gives them all the built-in features of Starlight (eg. auto-generated entries by directory)
+  // In our middleware, we pull the appropriate group for the current tab and remove the others
+  let sidebar: Defined<StarlightSidebarConfig> = [];
+
+  if (config.splitTabsEnabled) {
+    config.tabs.forEach((tab, index) => {
+      // force unwrap bc we know we have a sidebar
+      sidebar.push({
+        label: index.toString(),
+        items: tab.sidebar ?? [],
+      });
+    });
+  } else if (config.sidebar) {
+    sidebar = config.sidebar;
+  }
+
+  type ComponentOverrides = StarlightConfigDefined['components'];
+  const componentOverrides: ComponentOverrides = {
+    Search: '@stainless-api/docs/Search',
+    Sidebar: '@stainless-api/docs/Sidebar',
+    Header: '@stainless-api/docs/Header',
+    ThemeSelect: '@stainless-api/docs/ThemeSelect',
+    ContentPanel: '@stainless-api/docs/ContentPanel',
+  };
+
+  // TODO: re-add once we figure out what to do with the client router
+  // if (config.enableClientRouter) {
+  //   // logger.info(`Client router is enabled`);
+  //   componentOverrides.Head = '@stainless-api/docs/head';
+  // } else {
+  //   // logger.info(`Client router is disabled`);
+  // }
+
+  return starlight({
+    ...config.starlightPassThrough,
+    sidebar,
+    components: {
+      ...componentOverrides,
+      ...config.starlightCompat.components,
+    },
+    head: [
+      ...config.head,
+      {
+        tag: 'script',
+        content: `
+        function setupNavLinksInitial(){
+          let mode = localStorage.getItem("stl-nav-links-mode");
+          // initial guess
+          if(mode === null){
+            mode = window.innerWidth < 1000 ? "mobile" : "desktop";
+          }
+          document.documentElement.classList.add("stl-nav-links-mode-" + mode)
+        }
+        setupNavLinksInitial();
+      `,
+      },
+      // TODO: for users who are overriding the font stack in their own styles, how can we know that
+      // and preload their font instead of ours?
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'preload',
+          as: 'font',
+          type: 'font/woff2',
+          crossorigin: 'anonymous',
+          href: geistPath,
+        },
+      },
+    ],
+    routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
+    customCss: ['@stainless-api/docs/theme', ...config.customCss],
+    plugins: [stainlessStarlight(config.apiReference), ...config.starlightCompat.plugins],
+  });
+}
+
+function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
+  const virtualId = `virtual:stl-stl-starlight-virtual-module`;
+  // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
+  const resolvedId = `\0${virtualId}`;
+  let redirects: NormalizedRedirectConfig | null = null;
+
+  return {
+    name: 'stl-docs-integration',
+    hooks: {
+      'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
+        // // we only handle redirects for builds
+        // // in dev, Astro handles them for us
+        if (command === 'build' && astroConfig.redirects) {
+          redirects = normalizeRedirects(astroConfig.redirects);
+        }
+
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: 'stl-docs-vite',
+                resolveId(id) {
+                  if (id === virtualId) {
+                    return resolvedId;
+                  }
+                },
+                load(id) {
+                  if (id === resolvedId) {
+                    return buildVirtualModuleString({
+                      TABS: config.tabs,
+                      SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+                      HEADER_LINKS: config.header.links,
+                      HEADER_LAYOUT: config.header.layout,
+                      ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+                    });
+                  }
+                },
+              },
+            ],
+          },
+          build: {
+            ...astroConfig.build,
+            redirects: false,
+          },
+        });
+      },
+      'astro:build:done': ({ dir }) => {
+        if (redirects !== null) {
+          const stainlessDir = join(dir.pathname, '_stainless');
+          mkdirSync(stainlessDir);
+          const outputPath = join(stainlessDir, 'redirects.json');
+          writeFileSync(outputPath, JSON.stringify(redirects, null, 2), {
+            encoding: 'utf-8',
+          });
+        }
+      },
+    },
+  };
+}
+
+export function stainlessDocs(config: StainlessDocsUserConfig) {
+  const normalizedConfigResult = parseStlDocsConfig(config);
+  if (normalizedConfigResult.result === 'error') {
+    // TODO: would be good to use the astro logger somehow
+    console.error(normalizedConfigResult.message);
+    process.exit(1);
+  }
+  const normalizedConfig = normalizedConfigResult.config;
+  return [
+    react(),
+    stainlessDocsStarlightIntegration(normalizedConfig),
+    stainlessDocsIntegration(normalizedConfig),
+  ];
+}

package/stl-docs/loadStlDocsConfig.ts

@@ -0,0 +1,160 @@
+import type { StainlessStarlightUserConfig } from '../plugin/loadPluginConfig';
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import type { ButtonVariant } from '@stainless-api/ui-primitives';
+import type { AnchorHTMLAttributes } from 'react';
+import type starlight from '@astrojs/starlight';
+
+type StarlightConfig = Parameters<typeof starlight>[0];
+
+type SidebarEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
+
+export type Defined<T> = T extends undefined ? never : T;
+
+export type StarlightConfigDefined = Defined<StarlightUserConfig>;
+
+export type StarlightSidebarConfig = StarlightConfig['sidebar'];
+
+type PassThroughStarlightConfigOptions = Pick<
+  StarlightConfigDefined,
+  | 'title'
+  | 'logo'
+  | 'description'
+  | 'tagline'
+  | 'head'
+  | 'defaultLocale'
+  | 'customCss'
+  | 'tableOfContents'
+  | 'titleDelimiter'
+  | 'disable404Route'
+  | 'editLink'
+  | 'favicon'
+  | 'locales'
+  | 'lastUpdated'
+  | 'pagination'
+  | 'sidebar'
+>;
+
+type ExperimentalStarlightCompatibilityConfig = Pick<
+  StarlightConfigDefined,
+  'components' | 'routeMiddleware' | 'plugins'
+>;
+
+type Tabs = {
+  label: string;
+  link: string;
+  sidebar?: SidebarEntry[];
+  /**
+   * Whether to hide the tab in the tab bar.
+   * Defaults to `false`.
+   */
+  hidden?: boolean;
+}[];
+
+export type HeaderLink = {
+  label: string;
+  link: string;
+  variant?: ButtonVariant;
+  attrs?: AnchorHTMLAttributes<HTMLAnchorElement>;
+};
+
+export type StainlessDocsUserConfig = {
+  apiReference: StainlessStarlightUserConfig;
+  tabs?: Tabs;
+  header?: {
+    layout?: HeaderLayout;
+    links?: HeaderLink[];
+  };
+  experimental?: {
+    starlightCompat?: ExperimentalStarlightCompatibilityConfig;
+    enableClientRouter?: boolean;
+  };
+} & PassThroughStarlightConfigOptions;
+
+type HeaderLayout = 'default' | 'stacked';
+
+function areSplitTabsEnabled(config: StainlessDocsUserConfig) {
+  if (config.sidebar) {
+    return false;
+  }
+  if (config.tabs?.length === 0) {
+    return false;
+  }
+
+  const hasTabsWithSidebar = config.tabs?.some((tab) => tab.sidebar !== undefined);
+  if (hasTabsWithSidebar) {
+    return true;
+  }
+
+  return false;
+}
+
+function normalizeRouteMiddleware(userConfig: StainlessDocsUserConfig) {
+  const entry = userConfig.experimental?.starlightCompat?.routeMiddleware;
+  if (entry === undefined) {
+    return [];
+  }
+  if (typeof entry === 'string') {
+    return [entry];
+  }
+  return entry;
+}
+
+function normalizeConfig(userConfig: StainlessDocsUserConfig) {
+  const splitTabsEnabled = areSplitTabsEnabled(userConfig);
+
+  const configWithDefaults = {
+    splitTabsEnabled,
+    tabs: userConfig.tabs ?? [],
+    head: userConfig.head ?? [],
+    defaultLocale: userConfig.defaultLocale,
+    customCss: userConfig.customCss ?? [],
+    header: {
+      layout: userConfig.header?.layout ?? 'default',
+      links: userConfig.header?.links ?? [],
+    },
+    starlightPassThrough: {
+      tableOfContents: userConfig.tableOfContents,
+      titleDelimiter: userConfig.titleDelimiter,
+      title: userConfig.title,
+      description: userConfig.description,
+      tagline: userConfig.tagline,
+      logo: userConfig.logo,
+    },
+    starlightCompat: {
+      components: userConfig.experimental?.starlightCompat?.components ?? {},
+      plugins: userConfig.experimental?.starlightCompat?.plugins ?? [],
+      routeMiddleware: normalizeRouteMiddleware(userConfig),
+    },
+    enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
+    apiReference: userConfig.apiReference,
+    sidebar: userConfig.sidebar,
+  };
+
+  return configWithDefaults;
+}
+
+export type NormalizedStainlessDocsConfig = ReturnType<typeof normalizeConfig>;
+
+/*
+ The goal of the code in this file is to take a user's config and normalize it. 
+ Specifically: we want a single complete config format used throughout the internals of the plugin.
+
+ We've tried to avoid any config values being optional/undefined. To accomplish this:
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
+ - We prefer empty arrays over undefined/null
+*/
+export function parseStlDocsConfig(userConfig: StainlessDocsUserConfig) {
+  try {
+    const config = normalizeConfig(userConfig);
+    return {
+      result: 'success' as const,
+      config,
+    };
+  } catch (error) {
+    return {
+      result: 'error' as const,
+      message: error instanceof Error ? error.message : 'An unknown error occurred',
+    };
+  }
+}

package/stl-docs/redirects.ts

@@ -0,0 +1,33 @@
+import type { RedirectConfig } from 'astro';
+
+// astro redirect keys can be strings or objects, if they're strings, 301 is assumed
+// this type/function normalizes them to the complete object form
+export type NormalizedRedirectConfig = Record<string, { destination: string; status: number }>;
+
+export function normalizeRedirects(redirects: Record<string, RedirectConfig> | null) {
+  if (!redirects) {
+    return null;
+  }
+
+  if (Object.keys(redirects).length === 0) {
+    return null;
+  }
+
+  const output: NormalizedRedirectConfig = {};
+  for (const [source, redirect] of Object.entries(redirects)) {
+    let destination: string;
+    let status: number;
+    if (typeof redirect === 'string') {
+      destination = redirect;
+      status = 301; // astro default
+    } else {
+      destination = redirect.destination;
+      status = redirect.status;
+    }
+    output[source] = {
+      destination,
+      status,
+    };
+  }
+  return output;
+}

package/stl-docs/tabsMiddleware.ts

@@ -0,0 +1,183 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-stl-starlight-virtual-module';
+import clsx from 'clsx';
+
+// this fn is loaded in the plugin via addRouteMiddleware
+
+type SidebarEntry = StarlightRouteData['sidebar'][number];
+
+function recursiveGetLinks(entry: SidebarEntry[]) {
+  const links = new Set<string>();
+
+  for (const e of entry) {
+    if (e.type === 'link') {
+      let href = e.href;
+
+      if (href.endsWith('/') && href !== '/') {
+        href = href.slice(0, -1);
+      }
+
+      links.add(href);
+    }
+
+    if (e.type === 'group') {
+      recursiveGetLinks(e.entries).forEach((link) => links.add(link));
+    }
+  }
+  return links;
+}
+
+function getLinksByTab(sidebarEntries: SidebarEntry[]) {
+  const linksByTab = new Map<string, string>();
+
+  for (const entry of sidebarEntries) {
+    if (entry.type === 'group') {
+      const linksForTab = recursiveGetLinks(entry.entries);
+      for (const link of linksForTab) {
+        linksByTab.set(link, entry.label);
+      }
+    }
+  }
+
+  // we have to manually add the hrefs from the tab links to the linksByTab map
+  TABS.forEach((tab, index) => {
+    const indexStr = String(index);
+    linksByTab.set(tab.link, indexStr);
+  });
+
+  return linksByTab;
+}
+
+function getTabIndexForSlug(
+  linksByTab: Map<string, string>,
+  slug: string,
+): {
+  index: number;
+  match: 'exact' | 'prefix';
+} | null {
+  // ↓ exact match eg. slug = "/blog" and there is a link containing "/blog"
+  let tab = linksByTab.get(slug);
+  if (typeof tab === 'string') {
+    return {
+      match: 'exact',
+      index: Number(tab),
+    };
+  }
+
+  // ↓ matching prefix, eg. slug = "/blog/posts/intro" and there is a link containing "/blog"
+
+  // All links in order of longest to shortest
+  // This way our matches will be the most specific possible
+  const linksArr = Array.from(linksByTab.keys()).sort((a, b) => b.length - a.length);
+
+  for (const link of linksArr) {
+    if (slug.startsWith(link)) {
+      const tab = linksByTab.get(link)!; // force unwrap bc we know its in the map
+      return {
+        match: 'prefix',
+        index: Number(tab),
+      };
+    }
+  }
+  return null;
+}
+
+function getNonSplitLinksByTab() {
+  const linksByTab = new Map<string, string>();
+
+  for (let i = 0; i < TABS.length; i++) {
+    const tab = TABS[i];
+    linksByTab.set(tab.link, String(i));
+  }
+
+  return linksByTab;
+}
+
+export const onRequest = defineRouteMiddleware(async (context) => {
+  // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
+  // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
+
+  const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
+
+  /*
+    In the index of our starlight plugin, we transform our "tabs" into a plain old Starlight sidebar.
+    Eg: tabs = [
+      {
+        label: "API Reference",
+        link: "/api",
+        items: [],
+      },
+      {
+        label: "Guides",
+        link: "/guides",
+        items: [],
+      },
+    ];
+    becomes a Starlight sidebar with the items for each tab in groups "0" and "1" (corresponding to the idx of the tab)
+    we do this bc Starlight has many advanced features (eg. auto-generated entries by directory) that we want to reuse
+
+    Once we get to middleware, our basic job is:
+    - find the appropriate tab given the current slug
+    - replace the sidebar with just the items for that tab
+  */
+
+  const linksByTab = SPLIT_TABS_ENABLED
+    ? getLinksByTab(context.locals.starlightRoute.sidebar)
+    : getNonSplitLinksByTab();
+
+  const activeTabIndex = getTabIndexForSlug(linksByTab, slug);
+
+  if (activeTabIndex === null) {
+    return;
+  }
+
+  // handling a very rare case where a page has no sidebar and we match a prefix
+  // a good example case is a splash page at a route like "/splash"
+  // if "/splash" isn't a nav link or an entry in a sidebar BUT there is a nav link for "/", it would be a prefix match
+  // in that case, we'd be highlighting the nav item for "/" which isn't the expected behavior
+  // so we just return early and there is no active tab index
+  if (activeTabIndex.match === 'prefix' && !context.locals.starlightRoute.hasSidebar) {
+    return;
+  }
+
+  // We store the active tab index so we can use it in our nav tabs component
+  context.locals.starlightRoute._stlStarlight = {
+    activeTabIndex: activeTabIndex.index,
+  };
+
+  // if split tabs are not enabled, we don't need to do anything else
+  // we can leave the sidebar as-is
+  if (!SPLIT_TABS_ENABLED) {
+    return;
+  }
+
+  const matchingGroup = context.locals.starlightRoute.sidebar.find((group) => {
+    return group.label === String(activeTabIndex.index);
+  });
+
+  if (!matchingGroup || matchingGroup.type !== 'group') {
+    return;
+  }
+
+  const hasEntries = matchingGroup.entries && matchingGroup.entries.length > 0;
+
+  const mobileLinks: SidebarEntry[] = TABS.map((tab, index) => ({
+    type: 'link' as const,
+    label: tab.label,
+    href: tab.link,
+    badge: undefined,
+    isCurrent: tab.link === slug,
+    attrs: {
+      class: clsx(
+        'stl-mobile-only-sidebar-item',
+        hasEntries && index === TABS.length - 1 && 'stl-mobile-only-sidebar-item-last',
+      ),
+    },
+  }));
+
+  matchingGroup?.entries.unshift(...mobileLinks);
+
+  context.locals.starlightRoute.sidebar = matchingGroup.entries;
+});