@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.130

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,177 @@
+---
+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);
+    --stl-ui-pagination-border-radius-outer: calc(
+      var(--stl-ui-pagination-border-radius-inner) + var(--stl-ui-pagination-padding)
+    );
+
+    padding: var(--stl-ui-pagination-padding);
+    background-color: var(--stl-color-faint-background);
+    border: 1px solid var(--stl-color-border);
+    border-radius: var(--stl-ui-pagination-border-radius-outer);
+
+    font-size: var(--stl-typography-scale-sm);
+    letter-spacing: normal;
+
+    display: flex;
+    gap: 8px;
+
+    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;
+type 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;
+type 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];
+type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+
+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

@@ -1,10 +1,88 @@
 ---
-import Default from '@astrojs/starlight/components/Sidebar.astro';
 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;
+    }
+  });
+}
+
+// Since Terraform only renders the top level resource, we don't need to link group titles to overview pages.
+if (LINK_GROUP_TITLES_TO_OVERVIEW_PAGES === true && Astro.locals.language !== 'terraform') {
+  stlSidebar = linkGroupTitleToOverviewPages(stlSidebar);
+}
 ---
 
 <div class="stl-sidebar-header-links">
   <HeaderLinks />
 </div>
 <slot name="sdk-select" />
-<Default><slot /></Default>
+<SidebarPersister>
+  <SidebarWithComponents entries={stlSidebar} withStarlightRestoration />
+</SidebarPersister>

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>
+  );
+}

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

@@ -0,0 +1,62 @@
+import { StlSidebarEntry } from '@stainless-api/docs-ui/components';
+import { SidebarEntry } from '../pagination/util';
+import { ReactNode } from 'react';
+import { Badge, getHttpMethod } from '@stainless-api/ui-primitives';
+import { FunctionIcon } from '@stainless-api/ui-primitives/icons';
+import { BracesIcon } from 'lucide-react';
+
+function getIcon(entry: SidebarEntry): ReactNode | undefined {
+  if (entry.type !== 'link') {
+    return undefined;
+  }
+  const methodAttr = entry.attrs['data-stldocs-method'];
+  const httpMethod = getHttpMethod(methodAttr);
+  if (httpMethod) {
+    return <Badge.HTTP method={httpMethod} iconOnly size="sm" />;
+  }
+
+  // special handling for the webhooks resource overview page
+  if (entry.attrs['data-stldocs-overview'] === 'webhooks') {
+    return (
+      <Badge size="sm" icon={<BracesIcon />} intent="info">
+        {''}
+      </Badge>
+    );
+  }
+
+  // Support empty string as method to show generic "Function" badge
+  else if (methodAttr === '') {
+    return (
+      <Badge size="sm" icon={<FunctionIcon />} intent="info">
+        {''}
+      </Badge>
+    );
+  }
+  return undefined;
+}
+
+export function convertAstroSidebarToStl(entries: SidebarEntry[]): StlSidebarEntry[] {
+  return entries.map((entry): StlSidebarEntry => {
+    if (entry.type === 'link') {
+      const icon = getIcon(entry);
+      return {
+        type: 'link',
+        attrs: entry.attrs,
+        label: entry.label,
+        target: {
+          type: 'href',
+          href: entry.href,
+        },
+        isCurrent: entry.isCurrent,
+        icon,
+      };
+    } else {
+      return {
+        type: 'group',
+        label: entry.label,
+        collapsed: entry.collapsed,
+        entries: convertAstroSidebarToStl(entry.entries),
+      };
+    }
+  });
+}

package/stl-docs/disableCalloutSyntax.ts

@@ -0,0 +1,36 @@
+import type { AstroIntegration } from 'astro';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+
+const disableCalloutSyntaxAstroIntegration = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'astro:config:setup': ({ config: astroConfig }) => {
+      // Remove starlight callout syntax in favor of our own callout component
+      // updateConfig always deeply merges arrays so we need to mutate remarkPlugins directly
+      // in order to remove plugins that starlight added
+      astroConfig.markdown.remarkPlugins = astroConfig.markdown.remarkPlugins.filter((plugin, i, arr) => {
+        if (typeof plugin !== 'function') return true;
+        // remove:
+        // 1. remarkDirective plugin
+        if (plugin.name === 'remarkDirective') return false;
+        // 2. directly followed by remarkAsides plugin (inner function named 'attacher')
+        if (plugin.name === 'attacher') {
+          const prev = arr[i - 1];
+          if (typeof prev === 'function' && prev.name === 'remarkDirective') return false;
+        }
+        // 3. remarkDirectivesRestoration plugin
+        if (plugin.name === 'remarkDirectivesRestoration') return false;
+        return true;
+      });
+    },
+  },
+} satisfies AstroIntegration;
+
+export const disableCalloutSyntaxStarlightPlugin = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'config:setup': ({ addIntegration }) => {
+      addIntegration(disableCalloutSyntaxAstroIntegration);
+    },
+  },
+} satisfies StarlightPlugin;

package/stl-docs/fonts.ts

@@ -0,0 +1,186 @@
+import type { AstroConfig } from 'astro';
+import type { Defined } from './loadStlDocsConfig';
+import { fontProviders } from 'astro/config';
+import type { FontPreloadFilter } from 'astro:assets';
+
+type AstroFontConfigEntry = Defined<AstroConfig['fonts']>[number];
+
+// Apply Omit to each member of the union while preserving union structure
+type PreloadFilter = { preload?: FontPreloadFilter };
+export type StlDocsFontConfigEntry = (AstroFontConfigEntry extends infer T
+  ? T extends unknown
+    ? Omit<T, 'cssVariable'>
+    : never
+  : never) &
+  PreloadFilter;
+
+export type StlDocsFontConfig = {
+  primary?: StlDocsFontConfigEntry;
+  heading?: StlDocsFontConfigEntry;
+  mono?: StlDocsFontConfigEntry;
+  additional?: (AstroFontConfigEntry & PreloadFilter)[];
+};
+const latinFeatureSettings = "'ss01' on, 'ss03' on, 'ss04' on, 'ss06' on, 'ss08' on";
+/* prettier-ignore */
+const latinUnicodeRange: readonly string[] = ['U+0000-00FF', 'U+0131', 'U+0152-0153', 'U+02BB-02BC', 'U+02C6', 'U+02DA', 'U+02DC', 'U+0304', 'U+0308', 'U+0329', 'U+2000-206F', 'U+20AC', 'U+2122', 'U+2191', 'U+2193', 'U+2212', 'U+2215', 'U+FEFF', 'U+FFFD'];
+// /* prettier-ignore */
+// const latinExtUnicodeRange: readonly string[] = ['U+0100-02BA', 'U+02BD-02C5', 'U+02C7-02CC', 'U+02CE-02D7', 'U+02DD-02FF', 'U+0304', 'U+0308', 'U+0329', 'U+1D00-1DBF', 'U+1E00-1E9F', 'U+1EF2-1EFF', 'U+2020', 'U+20A0-20AB', 'U+20AD-20C0', 'U+2113', 'U+2C60-2C7F', 'U+A720-A7FF'];
+
+export function getFontRoles(fonts: StlDocsFontConfig | undefined) {
+  if (!fonts) {
+    return {};
+  }
+  const fontConfigs: {
+    primary?: { cssVariable: string; preload?: FontPreloadFilter };
+    heading?: { cssVariable: string; preload?: FontPreloadFilter };
+    mono?: { cssVariable: string; preload?: FontPreloadFilter };
+    additional?: { cssVariable: string; preload?: FontPreloadFilter }[];
+  } = {};
+  if (fonts.primary) {
+    fontConfigs['primary'] = {
+      cssVariable: '--stl-typography-font' as const,
+      preload: fonts.primary.preload ?? [{ style: 'normal' }],
+    };
+  }
+  if (fonts.heading) {
+    fontConfigs['heading'] = {
+      cssVariable: '--stl-typography-font-heading' as const,
+      preload: fonts.heading.preload ?? [{ style: 'normal' }],
+    };
+  }
+  if (fonts.mono) {
+    fontConfigs['mono'] = {
+      cssVariable: '--stl-typography-font-mono' as const,
+      preload: fonts.mono.preload ?? [{ style: 'normal' }],
+    };
+  }
+  if (fonts.additional) {
+    fontConfigs['additional'] = fonts.additional.map((font) => ({
+      cssVariable: font.cssVariable,
+      preload: font.preload ?? [{ style: 'normal' }],
+    }));
+  }
+  return fontConfigs;
+}
+
+export function normalizeFonts(fonts: StlDocsFontConfig | undefined): StlDocsFontConfig {
+  const defaultPrimary: StlDocsFontConfigEntry = {
+    provider: fontProviders.local(),
+    name: 'Geist',
+    display: 'swap',
+    preload: [
+      {
+        weight: '100 900',
+        style: 'normal',
+      },
+    ],
+    options: {
+      variants: [
+        {
+          weight: '100 900',
+          style: 'normal',
+          src: [new URL('../assets/fonts/geist/geist-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+          featureSettings: latinFeatureSettings,
+        },
+        {
+          weight: '100 900',
+          style: 'italic',
+          src: [new URL('../assets/fonts/geist/geist-italic-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+          featureSettings: latinFeatureSettings,
+        },
+        // {
+        //   weight: '100 900',
+        //   style: 'normal',
+        //   src: [new URL('../assets/fonts/geist/geist-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        //   featureSettings: latinFeatureSettings,
+        // },
+        // {
+        //   weight: '100 900',
+        //   style: 'italic',
+        //   src: [new URL('../assets/fonts/geist/geist-italic-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        //   featureSettings: latinFeatureSettings,
+        // },
+      ],
+    },
+  };
+  const defaultMono: StlDocsFontConfigEntry = {
+    provider: fontProviders.local(),
+    name: 'Geist Mono',
+    display: 'swap',
+    preload: [
+      {
+        weight: '100 900',
+        style: 'normal',
+      },
+    ],
+    options: {
+      variants: [
+        {
+          weight: '100 900',
+          style: 'normal',
+          src: [new URL('../assets/fonts/geist/geist-mono-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+        },
+        {
+          weight: '100 900',
+          style: 'italic',
+          src: [new URL('../assets/fonts/geist/geist-mono-italic-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+        },
+        // {
+        //   weight: '100 900',
+        //   style: 'normal',
+        //   src: [new URL('../assets/fonts/geist/geist-mono-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        // },
+        // {
+        //   weight: '100 900',
+        //   style: 'italic',
+        //   src: [new URL('../assets/fonts/geist/geist-mono-italic-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        // },
+      ],
+    },
+  };
+
+  return {
+    primary: fonts?.primary ?? defaultPrimary,
+    heading: fonts?.heading ?? undefined,
+    mono: fonts?.mono ?? defaultMono,
+    additional: fonts?.additional ?? [],
+  };
+}
+
+// Normalize fonts for the Astro config
+export function flattenFonts(fonts: StlDocsFontConfig | undefined): AstroFontConfigEntry[] {
+  if (!fonts) {
+    return [];
+  }
+  const fontConfigs: AstroFontConfigEntry[] = [];
+  if (fonts.primary) {
+    fontConfigs.push({
+      ...fonts.primary,
+      cssVariable: '--stl-typography-font' as const,
+    } as AstroFontConfigEntry);
+  }
+  if (fonts.heading) {
+    fontConfigs.push({
+      ...fonts.heading,
+      cssVariable: '--stl-typography-font-heading' as const,
+    } as AstroFontConfigEntry);
+  }
+  if (fonts.mono) {
+    fontConfigs.push({
+      ...fonts.mono,
+      cssVariable: '--stl-typography-font-mono' as const,
+    } as AstroFontConfigEntry);
+  }
+  if (fonts.additional) {
+    fontConfigs.push(...fonts.additional.map((font) => font as AstroFontConfigEntry));
+  }
+  return fontConfigs;
+}