@stainless-api/docs 0.1.0-beta.103 → 0.1.0-beta.105

package/styles/page.css

@@ -1,109 +1,165 @@
-.page,
-.page > header .header,
-.page > header .stl-secondary-nav-tabs {
-  max-width: var(--sl-page-max-width);
-  margin: 0 auto;
+:root {
+  --stl-page-max-width: 90rem;
 
-  @media (min-width: 50rem) {
-    padding-inline: var(--stl-ui-page-padding-inline);
+  /* 0.75rem at 25rem width (phone); 1.5rem at 72rem width (desktop) */
+  --_stl-page-min-padding-mobile-rem: 0.75;
+  --_stl-page-min-padding-desktop-rem: 1.5;
+  --_stl-page-min-padding-slope: (
+    (var(--_stl-page-min-padding-desktop-rem) - var(--_stl-page-min-padding-mobile-rem)) / (72 - 25)
+  );
+  --stl-page-min-padding: clamp(
+    var(--_stl-page-min-padding-mobile-rem) * 1rem,
+    var(--_stl-page-min-padding-slope) * (100vw - 25rem) + var(--_stl-page-min-padding-mobile-rem) * 1rem,
+    var(--_stl-page-min-padding-desktop-rem) * 1rem
+  );
+
+  --stl-content-max-width: 52rem;
+  --stl-content-padding: 2rem;
+  --stl-two-column-content-max-width: 80rem;
+
+  --stl-sidebar-width: 16.5rem;
+  --stl-nav-height: 3.5rem; /* has to be statically sized in order to correctly position the viewport-end grid area :( */
+  --stl-nav-gap: 0.5rem;
+
+  --stl-page-width: min(var(--stl-page-max-width), 100vw);
+  --vw: calc(var(--stl-page-width) / 100);
+}
+@media (min-width: 50rem) {
+  :root:has(.stl-secondary-nav-tabs) {
+    --stl-nav-height: 5.5rem;
+    header {
+      padding-top: 0.25rem;
+    }
   }
 }
 
+/* Grid layout */
+
 .page {
-  position: relative;
-  max-width: var(--sl-page-max-width);
+  display: grid;
 
-  .right-sidebar {
-    border-inline-start: unset;
-  }
+  /* TODO: verify that env-safe-area-inset is behaving as we expect */
+  --stl-viewport-width: calc(100vw - env(safe-area-inset-left, 0) - env(safe-area-inset-right, 0));
+  --stl-page-gutter-left: calc(
+    env(safe-area-inset-left, 0) +
+      max(var(--stl-page-min-padding), (var(--stl-viewport-width) - var(--stl-page-max-width)) / 2)
+  );
+  --stl-page-gutter-right: calc(
+    env(safe-area-inset-right, 0) +
+      max(var(--stl-page-min-padding), (var(--stl-viewport-width) - var(--stl-page-max-width)) / 2)
+  );
 
-  .mobile-preferences {
-    margin-top: 1rem;
-    display: flex;
-    justify-content: flex-end;
-  }
+  /* prettier-ignore */
+  grid:
+    /*  header + content have two identical columns because in mobile layout the menu trigger takes up the latter */
+    ' gutter-left                  header                   header          header   header  gutter-right                  chat' var(--stl-nav-height)                 /* nav */
+    ' gutter-left                  sidebar                  content         content  toc     gutter-right                  chat' calc(100dvh - var(--stl-nav-height))  /* viewport (above the fold) */
+    [viewport-end]
+    ' gutter-left                  .                        content         content  .       gutter-right                  .   ' auto                                  /* rest of page height */
+    / var(--stl-page-gutter-left)  var(--stl-sidebar-width) minmax(0, 1fr)  auto     auto    var(--stl-page-gutter-right)  auto;
 }
 
-:root {
-  --sl-mobile-toc-height: 4rem;
+.page > main,
+.page > .sidebar > .sidebar-pane,
+.page > .right-sidebar-panel nav {
+  padding-block-start: 1rem;
 }
 
-@media (min-width: 50rem) {
-  .page .sidebar-pane {
-    left: unset;
-  }
-  /* on desktop, adjust sidebar so that its _text content_ aligns with the page left edge.
-   * padding (visible on hover) bleeds out beyond the page left edge, covered by --stl-ui-page-padding-inline */
-  .sidebar-pane {
-    /* 12px comes from --stl-sidebar-item-padding-inline (which is unfortunately defined deeper than
-    this component). Please keep in sync. */
-    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + 12px));
-  }
+/* Sticky header and tabs */
 
-  .header,
-  .header {
-    padding-inline-start: 0;
-    padding-inline-end: 0;
-  }
+.page > header {
+  grid-area: header;
+  margin-left: calc(-1 * var(--stl-page-gutter-left));
+  margin-right: calc(-1 * var(--stl-page-gutter-right));
+  padding-left: var(--stl-page-gutter-left);
+  padding-right: var(--stl-page-gutter-right);
+}
 
-  mobile-starlight-toc nav {
-    inset-inline-start: calc(var(--sl-content-inline-start, 0) + var(--sl-sidebar-pad-x));
-  }
+header {
+  display: flex;
+  flex-direction: column;
+  border-bottom: 1px solid var(--stl-color-border-faint);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--stl-color-background);
 }
 
-.stl-content-breadcrumbs {
-  .stldocs-breadcrumbs {
-    padding-left: 0;
+@layer starlight.core {
+  header > .header {
+    all: revert-layer;
   }
 }
 
-.stl-page-nav-container {
+header > .header {
+  flex: 1;
   display: flex;
+  gap: var(--stl-nav-gap);
   align-items: center;
   justify-content: space-between;
-  gap: 1rem;
-  padding: 1rem 0 0 0;
-  flex-wrap: wrap;
 }
 
-.stl-page-nav-container {
+.header site-search > button {
+  @media (min-width: 50rem) {
+    margin-inline: 2rem;
+    flex: 1 1 12rem;
+  }
+}
+
+.header .right-group {
   display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 1rem;
-  padding: 1rem 0 0 0;
-  flex-wrap: wrap;
+  align-items: stretch;
 }
 
-.stldocs-root .stl-page-nav-container {
-  padding: 1rem 0 0 var(--stldocs-content-padding);
+/* Sticky sidebar and toc. Outer wrapper “sticks” to top of page, subgrid pushes child down below header */
+.page > .sidebar {
+  grid-area: sidebar;
+  /* sidebar should bleed to left edge of page in case people want to color it */
+  margin-left: calc(-1 * var(--stl-page-gutter-left));
+  padding-left: var(--stl-page-gutter-left);
 }
 
-[data-has-sidebar]:not([data-has-toc]) .sl-container {
-  max-width: 1428px;
+.page > .right-sidebar-panel {
+  grid-area: toc;
 }
 
-.stl-overview {
-  max-width: var(--sl-content-width);
+.page > .sidebar,
+.page > .right-sidebar-panel {
+  align-self: start;
+  grid-row-start: header-start;
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+  position: sticky;
+  top: 0;
+}
+.page > .sidebar > .sidebar-pane,
+.page > .right-sidebar-panel > starlight-toc {
+  grid-area: inherit;
+  grid-row-start: header-end;
+  overflow-y: auto;
+  overflow-x: clip;
 }
 
-@media (min-width: 50rem) {
-  :root[data-has-sidebar] {
-    --sl-content-inline-start: calc(var(--sl-sidebar-width) + 2rem);
-  }
+/* Page content */
 
-  .stldocs-root .stl-page-nav-container {
-    padding: 1rem 0 0 0;
-  }
+.page > main {
+  grid-area: content;
+  width: 100%;
+  max-width: min(var(--stl-content-max-width), 100%);
+  justify-self: center;
+  padding-inline: var(--stl-content-padding);
 }
 
-@media (min-width: 72rem) {
-  :root {
-    --sl-mobile-toc-height: 0rem;
-  }
+.stl-page-nav-container {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  flex-wrap: wrap;
 }
 
-.content-panel footer {
+.stl-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;
@@ -115,3 +171,94 @@
     }
   }
 }
+
+.mobile-preferences {
+  margin-top: 1rem;
+  display: flex;
+  justify-content: flex-end;
+}
+
+/* Two-column layouts go wider */
+.page > main:where(:has(.stldocs-method-double-pane)) {
+  max-width: min(var(--stl-two-column-content-max-width), 100%);
+  padding-inline-start: clamp(
+    var(--stl-content-padding),
+    var(--stl-page-gutter-right) - env(safe-area-inset-right, 0),
+    var(--stl-content-padding) * 2
+  );
+  padding-inline-end: 0;
+}
+
+/* Responsive page layout */
+
+/* On smaller screens, the main panel takes up the full width and the TOC is hidden */
+@media not (min-width: 72rem) {
+  .page > main {
+    /* right edge of content goes up to right gutter to align with header */
+    padding-inline-end: 0;
+    max-width: 100%;
+  }
+
+  .page > .right-sidebar-panel {
+    display: none;
+  }
+}
+
+/* On mobile screens, the sidebar and nav links collapse */
+@media not (min-width: 50rem) {
+  header {
+    padding-top: 0;
+    display: grid;
+    grid-template-columns: subgrid;
+  }
+
+  header > .header {
+    grid-column: span 2;
+  }
+
+  /* Sidebar moves to cover content area, hidden by default */
+  :root {
+    --stl-sidebar-width: 0px;
+  }
+  .page > .sidebar,
+  .page > .sidebar.hidden {
+    display: contents;
+  }
+  .page > .sidebar > .sidebar-pane {
+    visibility: hidden;
+    grid-area: content;
+    grid-row-end: viewport-end;
+    z-index: 9;
+    /* extend to right edge of page */
+    margin-inline-end: calc(-1 * var(--stl-page-gutter-right));
+    padding-inline-end: var(--stl-page-gutter-right);
+    border-inline-end: 0;
+  }
+  .page > .sidebar > starlight-menu-button[aria-expanded='true'] ~ .sidebar-pane {
+    visibility: visible;
+  }
+
+  /* left padding becomes the left gutter when there’s no sidebar */
+  .page > main {
+    padding-inline-start: 0;
+  }
+
+  /* Sidebar menu button moves to end of header; takes up space in layout (not absolutely positioned as in starlight) */
+  .sidebar starlight-menu-button {
+    grid-column: span 1 / content-end;
+    grid-row: header;
+    display: flex;
+    align-items: center;
+    position: sticky;
+    top: 0;
+    padding-left: var(--stl-nav-gap);
+    z-index: 11;
+  }
+  .sidebar starlight-menu-button button {
+    position: static;
+  }
+
+  .header .right-group {
+    display: none;
+  }
+}

package/styles/sidebar.css

@@ -1,23 +1,27 @@
-/* reset starlight styles */
-@layer starlight.core {
-  .sidebar .sidebar-pane .sidebar-content {
-    * {
-      all: revert-layer;
-      &::before,
-      &::after {
-        all: revert-layer;
-      }
-    }
-  }
-}
-
-.sidebar-pane {
+.page > .sidebar > .sidebar-pane {
+  padding-inline-end: 1rem;
   border-inline-end: 1px solid var(--stl-color-border-faint);
+  padding-block-end: calc(2rem + env(safe-area-inset-bottom));
+
+  /* make sure the sidebar doesn’t get clipped on the left by overflow */
+  margin-inline-start: calc(-1 * var(--stl-page-gutter-left));
+  padding-inline-start: var(--stl-page-gutter-left);
+
+  background-color: var(--stl-color-background);
+  /* work around chrome bug where the background-color isn’t getting painted in the overscroll? */
+  background-image: linear-gradient(to bottom, var(--stl-color-background), var(--stl-color-background));
+  background-attachment: fixed;
+
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
 }
 
-.sidebar-content .stl-mobile-only-sidebar-item-last {
-  margin-bottom: 2rem;
-  position: relative;
+@media (min-width: 50rem) {
+  .page > .sidebar :is(.stl-sdk-select, .stldocs-sidebar) {
+    /* align left edge of text with container */
+    margin-inline-start: calc(-1 * var(--stldocs-sidebar-item-padding-inline));
+  }
 }
 
 .stl-sidebar-header-links {
@@ -36,3 +40,9 @@
     display: none;
   }
 }
+
+/* No sidebar on splash pages */
+.page > .sidebar.hidden {
+  /* Note: on mobile, this will be overridden to display: contents; in order to show the mobile menu */
+  display: none;
+}

package/styles/sl-variables.css

@@ -1,19 +1,14 @@
 :root {
   --sl-color-bg-table-row: #ffffff0a;
   --sl-button-border-radius: 8px;
-  --sl-content-width: 52rem;
-  --sl-nav-pad-y: 0.5rem;
-  --sl-nav-height: 56px;
-  --sl-sidebar-width: 19rem;
   --sl-button-size: 32px;
   --sl-button-padding-x: 0.75rem;
   --sl-button-padding-y: 0.5rem;
   --sl-button-icon-offset: 0.2rem;
-  --sl-menu-button-size: var(--sl-button-size);
+
+  /* TODO: remove --sl-nav-height dependencies */
+  --sl-nav-height: 56px;
 
   --sl-nav-gap: 0.5rem;
   --sl-icon-color: var(--stl-color-foreground);
-  --sl-page-max-width: unset;
-
-  --sl-content-pad-x: 1rem;
 }

package/styles/stldocs-variables.css

@@ -1,6 +1,6 @@
 @import '@stainless-api/docs-ui/styles/variables.css';
 
 :root {
-  --stldocs-content-width: var(--sl-content-width);
-  --stldocs-content-padding: var(--sl-content-pad-x);
+  --stldocs-content-width: var(--stl-content-max-width);
+  --stldocs-content-padding-inline: 0;
 }

package/styles/toc.css

@@ -1,5 +1,11 @@
 .right-sidebar-panel {
   font-size: var(--stl-typography-scale-sm);
+  overflow-wrap: break-word;
+
+  nav {
+    min-width: 14ch;
+    max-width: calc(18 * var(--vw));
+  }
 
   nav > ul {
     padding-top: 0;
@@ -17,6 +23,7 @@
     color: var(--stl-color-foreground-reduced);
     position: relative;
     font-size: inherit;
+    text-decoration: none;
 
     &:hover {
       text-decoration: underline;
@@ -45,5 +52,6 @@
     line-height: 150%;
     text-decoration: none;
     font-weight: 400;
+    margin-bottom: 0.5em;
   }
 }

package/stl-docs/components/headers/SplashMobileMenuToggle.astro

@@ -1,65 +0,0 @@
----
-import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
-import Sidebar from 'virtual:starlight/components/Sidebar';
----
-
-<div class="stl-splash-mobile-menu-toggle">
-  <MobileMenuToggle />
-  <div id="starlight__sidebar" class="sidebar sidebar-pane">
-    <div class="sidebar-content sl-flex">
-      <Sidebar />
-    </div>
-  </div>
-</div>
-
-<style>
-  @layer starlight.core {
-    .sidebar-pane {
-      li,
-      li a,
-      li a[aria-current='page'] {
-        all: revert-layer;
-      }
-    }
-  }
-
-  :global([aria-expanded='true']) ~ .sidebar-pane {
-    --sl-sidebar-visibility: visible;
-  }
-  .sidebar-pane {
-    visibility: var(--sl-sidebar-visibility, hidden);
-    position: fixed;
-    z-index: var(--sl-z-index-menu);
-    inset-block: var(--sl-nav-height) 0;
-    inset-inline-start: 0;
-    width: 100%;
-    overflow-y: auto;
-    left: 0;
-
-    a {
-      font-size: var(--stl-typography-scale-sm);
-    }
-  }
-
-  .sidebar-content {
-    height: 100%;
-    min-height: max-content;
-    padding: 1rem var(--sl-sidebar-pad-x) 0;
-    flex-direction: column;
-    gap: 1rem;
-    background-color: var(--stl-color-background);
-  }
-
-  @media (min-width: 50rem) {
-    .stl-splash-mobile-menu-toggle {
-      display: none;
-    }
-  }
-</style>
-<style is:global>
-  .stl-splash-mobile-menu-toggle button {
-    position: relative;
-    top: unset;
-    inset-inline-end: unset;
-  }
-</style>