@stainless-api/docs 0.1.0-beta.12 → 0.1.0-beta.120

package/styles/page.css

@@ -1,78 +1,256 @@
-.page {
-  position: relative;
-  max-width: var(--sl-page-max-width);
-  margin: 0 auto;
+:root {
+  --stl-page-max-width: 90rem;
 
-  .sidebar-pane {
-    left: auto;
-  }
+  /* 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);
 
-  > header {
-    .stl-secondary-nav-tabs,
-    .header {
-      max-width: var(--sl-page-max-width);
-      margin: 0 auto;
+  scroll-padding-top: calc(var(--stl-nav-height) + 1rem);
+}
+@media (min-width: 50rem) {
+  :root:has(.stl-secondary-nav-tabs) {
+    --stl-nav-height: 5.5rem;
+    header {
+      padding-top: 0.25rem;
     }
   }
+}
 
-  .right-sidebar {
-    border-inline-start: unset;
-  }
+/* Grid layout */
 
-  .mobile-preferences {
-    margin-top: 1rem;
-  }
+.page {
+  display: grid;
+
+  /* TODO: verify that env-safe-area-inset is behaving as we expect */
+  --stl-viewport-width: calc(
+    100vw - env(safe-area-inset-left, 0px) - env(safe-area-inset-right, 0px) -
+      var(--stl-chat-panel-width, 0px)
+  );
+  --stl-page-gutter-left: calc(
+    env(safe-area-inset-left, 0px) +
+      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, 0px) +
+      max(var(--stl-page-min-padding), (var(--stl-viewport-width) - var(--stl-page-max-width)) / 2)
+  );
+
+  /* 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;
 }
 
-@media (min-width: 50rem) {
-  .page {
-    padding-left: var(--sl-sidebar-pad-x);
-    padding-right: var(--sl-sidebar-pad-x);
-
-    > header {
-      .header,
-      .stl-secondary-nav-tabs {
-        padding: 0 1.5rem;
-      }
-    }
+.page > main,
+.page > .sidebar > .sidebar-pane,
+.page > .right-sidebar-panel nav {
+  padding-block-start: 1rem;
+}
 
-    > header {
-      .stl-secondary-nav-tabs {
-        padding-left: 0.55rem;
-      }
-    }
-  }
+/* 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));
-  }
-  .sidebar-content {
-    padding-left: 0;
+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);
+}
+
+@layer starlight.core {
+  header > .header {
+    all: revert-layer;
   }
 }
 
-.stl-content-breadcrumbs {
-  .stldocs-breadcrumbs {
-    padding-left: 0;
+header > .header {
+  flex: 1;
+  display: flex;
+  gap: var(--stl-nav-gap);
+  align-items: center;
+  justify-content: space-between;
+}
+
+.header site-search > button {
+  @media (min-width: 50rem) {
+    margin-inline: 2rem;
+    flex: 1 1 12rem;
   }
 }
 
+.header .right-group {
+  display: flex;
+  align-items: stretch;
+}
+
+/* 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);
+}
+
+.page > .right-sidebar-panel {
+  grid-area: toc;
+}
+
+.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;
+}
+
+/* Page content */
+
+.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);
+}
+
 .stl-page-nav-container {
   display: flex;
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
-  padding: 1rem 0 0 1rem;
   flex-wrap: wrap;
 }
-@media (min-width: 50em) {
-  :root[data-has-sidebar] {
-    --sl-content-inline-start: calc(var(--sl-sidebar-width) + 1rem);
+
+.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, 0px),
+    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/sdk_select.css

@@ -1,10 +1,13 @@
-.stldocs-root {
-  .stldocs-dropdown-menu.stl-sdk-select-dropdown-menu {
-    min-width: 200px;
-  }
-}
 .stl-sdk-select {
+  .stl-ui-dropdown {
+    width: 100%;
+
+    .stl-ui-dropdown__button {
+      width: 100%;
+      justify-content: space-between;
+    }
+  }
   .stldocs-icon.http path {
-    fill: var(--stldocs-color-text);
+    fill: var(--stl-color-foreground);
   }
 }

package/styles/search.css

@@ -15,45 +15,41 @@ site-search {
     padding: 0;
     width: var(--sl-button-size);
     justify-content: center;
-    background-color: var(--sl-color-bg-ui);
-    border: 1px solid var(--sl-color-hairline);
+    background-color: var(--stl-color-ui-background);
+    border: 1px solid var(--stl-color-border);
     border-radius: var(--sl-button-border-radius);
     height: var(--sl-button-size);
 
     &:hover {
-      border-color: var(--sl-color-hairline-shade);
+      background: var(--stl-color-ui-background-hover);
     }
 
     span {
-      font-size: var(--sl-text-sm);
-      color: var(--sl-color-text-secondary);
+      font-size: var(--stl-typography-scale-sm);
+      color: var(--stl-color-foreground-reduced);
       line-height: 150%;
       padding-left: var(--sl-button-icon-offset);
       padding-right: var(--sl-button-icon-offset);
     }
 
     > svg {
-      width: var(--sl-text-sm);
-      height: var(--sl-text-sm);
-    }
-
-    &.stldocs-button {
-      padding: 0;
+      width: var(--stl-typography-scale-sm);
+      height: var(--stl-typography-scale-sm);
     }
   }
 
   button > kbd {
     border-radius: 0.25rem;
-    font-size: var(--sl-text-2xs);
+    font-size: var(--stl-typography-scale-xs);
     gap: 0.25em;
     padding-inline: 0.375rem;
-    background-color: var(--sl-color-gray-6);
+    background-color: var(--stl-color-muted-background);
     margin-right: -0.3rem;
   }
 
   kbd {
     font-family: var(--__sl-font);
-    color: var(--sl-color-text);
+    color: var(--stl-color-foreground-reduced);
   }
 }
 
@@ -61,16 +57,10 @@ site-search {
   site-search {
     > button {
       border-radius: var(--sl-button-border-radius);
-      padding-inline-start: var(--sl-button-padding-x);
-      padding-inline-end: var(--sl-button-padding-x);
       width: 100%;
       max-width: 30rem;
       justify-content: start;
-
-      &.stldocs-button {
-        padding-inline-start: var(--sl-button-padding-x);
-        padding-inline-end: var(--sl-button-padding-x);
-      }
+      padding: var(--sl-button-padding-y) var(--sl-button-padding-x);
 
       > :last-child {
         margin-inline-start: auto;

package/styles/sidebar.css

@@ -1,219 +1,27 @@
-/* reset starlight styles */
-@layer starlight.core {
-  .sidebar .sidebar-pane .sidebar-content {
-    * {
-      all: revert-layer;
-      &::before,
-      &::after {
-        all: revert-layer;
-      }
-    }
-  }
-}
-
-.sidebar {
-  --stl-sidebar-item-padding-inline: 12px;
-  --stl-sidebar-item-padding-block: 6px;
-  --stl-sidebar-indent: 12px;
-  font-size: var(--stl-ui-type-scale-text-sm);
-}
-
-.sidebar-pane {
-  border-inline-end: 1px solid var(--sl-color-hairline-light);
-}
-
-.sidebar-content {
-  ul,
-  summary {
-    list-style-type: none;
-  }
-
-  /* collapsible sections */
-  details > summary {
-    display: flex;
-    align-items: center;
-    font-weight: 500;
-
-    .caret {
-      margin-left: auto;
-      margin-right: -4px;
-      opacity: 0.65;
-      transition:
-        opacity 0.1s ease-out,
-        transform 0.1s ease-out;
-    }
-  }
-  details[open] > summary .caret {
-    opacity: 1;
-    transform: rotate(90deg);
-  }
-
-  /* list items */
-  summary,
-  li {
-    margin: 0;
-    border-radius: 8px;
-  }
-  summary,
-  li a {
-    cursor: pointer;
-    padding: var(--stl-sidebar-item-padding-block) var(--stl-sidebar-item-padding-inline);
-    &:hover,
-    &[aria-current='page'] {
-      color: var(--stl-ui-foreground);
-    }
-  }
-  li a {
-    color: var(--stl-ui-foreground-secondary);
-    font-weight: 400;
-    display: flex;
-    text-decoration: none;
-    span {
-      font-weight: inherit;
-    }
-
-    &:hover {
-      text-decoration: underline;
-      text-decoration-color: var(--stl-ui-foreground-secondary);
-    }
-    &[aria-current='page'] {
-      font-weight: 500;
-    }
-  }
-  li:has(> a:is(:hover, [aria-current='page'])),
-  summary:hover {
-    background-color: var(--stl-ui-muted-background);
-  }
-
-  /* nested list items have flat left edge */
-  ul ul :is(summary, li) {
-    border-start-start-radius: 0;
-    border-end-start-radius: 0;
-  }
-  ul {
-    padding: 0;
-  }
-  ul ul li {
-    border-inline-start: 1px solid var(--stl-ui-border-muted);
-    margin-inline-start: var(--stl-sidebar-indent);
-    &:has(> a[aria-current='page']) {
-      border-inline-start: 2px solid var(--stl-ui-foreground-accent);
-      & > a {
-        margin-left: -1px;
-      }
-    }
-  }
-
-  /* Method & resource icons */
-
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    --stl-ui-sidebar-icon-size-outer: 18px;
-    --stl-ui-sidebar-icon-margin: 8px;
-  }
-  a[data-stldocs-method] {
-    --stl-ui-sidebar-icon-size-inner: 16px;
-    --stl-ui-sidebar-icon-color-inverse: var(--stl-ui-swatch-gray-white);
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-color: var(--stl-ui-swatch-green-base);
-      --stl-ui-sidebar-icon-color-faint: var(--stl-ui-swatch-green-faint);
-      --stl-ui-sidebar-icon-color-muted: var(--stl-ui-swatch-green-muted);
-    }
-    &[data-stldocs-method='post'] {
-      --stl-ui-sidebar-icon-color: var(--stl-ui-swatch-blue-base);
-      --stl-ui-sidebar-icon-color-faint: var(--stl-ui-swatch-blue-faint);
-      --stl-ui-sidebar-icon-color-muted: var(--stl-ui-swatch-blue-muted);
-    }
-    &[data-stldocs-method='patch'],
-    &[data-stldocs-method='put'] {
-      --stl-ui-sidebar-icon-color: var(--stl-ui-swatch-orange-base);
-      --stl-ui-sidebar-icon-color-faint: var(--stl-ui-swatch-orange-faint);
-      --stl-ui-sidebar-icon-color-muted: var(--stl-ui-swatch-orange-muted);
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-color: var(--stl-ui-swatch-red-base);
-      --stl-ui-sidebar-icon-color-faint: var(--stl-ui-swatch-red-faint);
-      --stl-ui-sidebar-icon-color-muted: var(--stl-ui-swatch-red-muted);
-    }
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 7 7 17"/><path d="M17 17H7V7"/></svg>');
-    }
-    &[data-stldocs-method='post'],
-    &[data-stldocs-method='put'],
-    &[data-stldocs-method='patch'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 7h10v10"/><path d="M7 17 17 7"/></svg>');
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>');
-    }
-  }
-
-  a[data-stldocs-resource] {
-    /* not yet implemented in markup */
-    --stl-ui-sidebar-icon-color: var(--stl-ui-foreground-muted);
-    --stl-ui-sidebar-icon-color-faint: var(--stl-ui-muted-background);
-    --stl-ui-sidebar-icon-color-inverse: var(--stl-ui-inverse-foreground);
-    --stl-ui-sidebar-icon-size-inner: 14px;
-    --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1"/><path d="M16 21h1a2 2 0 0 0 2-2v-5c0-1.1.9-2 2-2a2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1"/></svg>');
-  }
+.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));
 
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    display: flex;
-    gap: var(--stl-ui-sidebar-icon-margin);
-    align-items: center;
-    position: relative;
+  /* 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);
 
-    &::before,
-    &::after {
-      content: '';
-      width: var(--stl-ui-sidebar-icon-size-outer);
-      height: var(--stl-ui-sidebar-icon-size-outer);
-      display: block;
-    }
-    &::before {
-      border-radius: 4px;
-      background-color: var(--stl-ui-sidebar-icon-color-faint);
-      flex: 0 0 auto;
-    }
-    /* yuck (we can clean this up once we are changing sidebar markup) */
-    &::after {
-      background-color: var(--stl-ui-sidebar-icon-color);
-      mask-image: var(--stl-ui-sidebar-icon-url);
-      mask-size: var(--stl-ui-sidebar-icon-size-inner) var(--stl-ui-sidebar-icon-size-inner);
-      mask-repeat: no-repeat;
-      mask-position: center;
-      position: absolute;
-      left: var(--stl-sidebar-item-padding-inline);
-      top: 50%;
-      transform: translateY(-50%);
-    }
+  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;
 
-    &:hover {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color-muted);
-      }
-    }
-    &[aria-current='page'] {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color);
-      }
-      &::after {
-        background-color: var(--stl-ui-sidebar-icon-color-inverse);
-      }
-    }
-  }
-}
-
-.sidebar-content .stl-mobile-only-sidebar-item-last {
-  margin-bottom: 2rem;
-  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
 }
 
-.stl-sdk-select .dropdown-toggle {
-  width: 100%;
+@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 {
@@ -232,3 +40,12 @@
     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;
+}
+:root:has(.page > .sidebar.hidden) {
+  --stl-sidebar-width: 0px;
+}

package/styles/{variables.css → sl-variables.css}

@@ -1,18 +1,14 @@
 :root {
   --sl-color-bg-table-row: #ffffff0a;
   --sl-button-border-radius: 8px;
-  --sl-text-body-sm: 0.86rem;
-  --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(--sl-color-text);
-  --sl-page-max-width: unset;
+  --sl-icon-color: var(--stl-color-foreground);
 }

package/styles/stldocs-variables.css

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