@chassis-ui/docs 0.1.10 → 0.3.0

package/src/libs/site.ts

@@ -0,0 +1,95 @@
+import os from 'os'
+
+/** Resolved host and port for the local Astro development server. */
+interface DevHost {
+  /** Hostname or IP address (e.g. `"localhost"` or a LAN IP when `--host` is passed). */
+  host: string
+  /** Port number the dev server is listening on. */
+  port: number
+}
+
+/**
+ * Minimum site configuration shape required by `getSiteUrl`.
+ * The consuming project's full config object satisfies this interface as long
+ * as it exposes a `baseURL` string.
+ */
+export interface SiteConfig {
+  /** Canonical base URL used as a fallback in production (e.g. `"https://chassis-ui.com/css/"`). */
+  baseURL: string
+}
+
+/**
+ * Resolves the host and port for the local Astro development server.
+ *
+ * Resolution order for port: `--port` CLI flag → `PORT` env var → `4321` (Astro default).
+ * When `--host` is passed, the first non-internal IPv4 network interface address
+ * is used as the host so the dev URL is reachable on the LAN.
+ */
+function getDevHost(): DevHost {
+  const hasHostFlag = process.argv.includes('--host')
+  let host = 'localhost'
+  let port = 4321
+
+  const portFlagIndex = process.argv.findIndex((arg) => arg === '--port')
+  if (portFlagIndex !== -1 && process.argv[portFlagIndex + 1]) {
+    const cliPort = parseInt(process.argv[portFlagIndex + 1], 10)
+    if (!isNaN(cliPort) && cliPort > 0 && cliPort < 65536) {
+      port = cliPort
+    }
+  }
+
+  if (process.env.PORT) {
+    const envPort = parseInt(process.env.PORT, 10)
+    if (!isNaN(envPort) && envPort > 0 && envPort < 65536) {
+      port = envPort
+    }
+  }
+
+  if (hasHostFlag) {
+    const interfaces = os.networkInterfaces()
+    for (const iface of Object.values(interfaces).flat()) {
+      if (iface?.family === 'IPv4' && !iface.internal) {
+        host = iface.address
+        break
+      }
+    }
+  }
+
+  return { host, port }
+}
+
+/**
+ * Determines the canonical site URL for the current environment.
+ *
+ * Resolution order:
+ * 1. `SITE_URL` env var — explicit override, takes precedence everywhere.
+ * 2. `NODE_ENV=development` — constructs a local `http://` URL from `getDevHost()`.
+ * 3. `VERCEL_ENV=production` — uses `config.baseURL` (the path-prefixed canonical
+ *    URL) rather than `VERCEL_PROJECT_PRODUCTION_URL` (the sub-project custom domain)
+ *    so sitemaps always point to the correct public URL.
+ * 4. `VERCEL_URL` present — Vercel preview/branch deployment; uses the auto-generated
+ *    `https://` preview URL.
+ * 5. Fallback — `config.baseURL` from the project's `config.yml`.
+ *
+ * @param config - Site configuration providing the `baseURL` fallback.
+ */
+export function getSiteUrl(config: SiteConfig): string {
+  if (process.env.SITE_URL) {
+    return process.env.SITE_URL
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    const { host, port } = getDevHost()
+    return `http://${host}:${port}`
+  }
+
+  if (process.env.VERCEL_ENV === 'production') {
+    return config.baseURL || `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+  }
+
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`
+  }
+
+  return config.baseURL
+}

package/src/libs/toc.ts

@@ -1,8 +1,28 @@
 import type { MarkdownHeading } from 'astro'
-// import { getConfig } from './config'
 
-// Generate a tree like structure from a list of headings.
-export function generateToc(allHeadings: MarkdownHeading[], config: any) {
+/**
+ * Minimum configuration shape required by `generateToc`.
+ * The consuming project's full config object satisfies this interface as long as
+ * it contains a `toc` section with `min` and `max` depth values.
+ */
+export interface TocConfig {
+  toc: {
+    /** Minimum heading depth to include (e.g. `2` to start at `<h2>`). */
+    min: number
+    /** Maximum heading depth to include (e.g. `4` to stop at `<h4>`). */
+    max: number
+  }
+}
+
+/**
+ * Generates a nested tree of TOC entries from a flat list of Markdown headings.
+ *
+ * Headings outside the depth range defined in `config.toc` are excluded. When
+ * a heading skips one or more levels (e.g. an `<h4>` follows an `<h2>` with no
+ * `<h3>` in between) it is attached to the deepest available parent rather than
+ * being silently dropped.
+ */
+export function generateToc(allHeadings: MarkdownHeading[], config: TocConfig): TocEntry[] {
   const headings = allHeadings.filter(
     (heading) => heading.depth >= config.toc.min && heading.depth <= config.toc.max
   )
@@ -29,14 +49,28 @@ export function generateToc(allHeadings: MarkdownHeading[], config: any) {
   return toc
 }
 
+/**
+ * Walks down the TOC tree to find the children array at the given relative
+ * `depth` below `entry`. If an intermediate level is missing (skipped heading),
+ * falls back to the deepest available children array so the heading is not lost.
+ */
 function getEntryChildrenAtDepth(entry: TocEntry, depth: number): TocEntry['children'] {
   if (!entry) {
     return []
   }
 
-  return depth === 1
-    ? entry.children
-    : getEntryChildrenAtDepth(entry.children[entry.children.length - 1], depth - 1)
+  if (depth === 1) {
+    return entry.children
+  }
+
+  const lastChild = entry.children[entry.children.length - 1]
+
+  if (!lastChild) {
+    // Heading skipped a level — attach to the current entry's children instead.
+    return entry.children
+  }
+
+  return getEntryChildrenAtDepth(lastChild, depth - 1)
 }
 
 export interface TocEntry extends MarkdownHeading {

package/src/libs/utils.ts

@@ -1,14 +1,20 @@
-import os from 'os'
 import { slug } from 'github-slugger'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { toString } from 'mdast-util-to-string'
 import { remark } from 'remark'
 import remarkHtml from 'remark-html'
 
+/** Returns `str` with its first character uppercased. */
 export function capitalizeFirstLetter(str: string) {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
+/**
+ * Generates an inclusive numeric sequence from `start` to `end` with the given `step`.
+ *
+ * @example getSequence(1, 5)      // [1, 2, 3, 4, 5]
+ * @example getSequence(0, 10, 2)  // [0, 2, 4, 6, 8, 10]
+ */
 export function getSequence(start: number, end: number, step = 1) {
   const sequence = []
 
@@ -19,107 +25,53 @@ export function getSequence(start: number, end: number, step = 1) {
   return sequence
 }
 
-// This function is used in the docs sidebar to generate partial slugs and properly order the sidebar entries and also
-// to generate docs frontmatter sections slugs.
-// Note: this should be refactored and removed, the sidebar ordering defined in `site/data/sidebar.yml` should not rely
-// on slugified custom titles that are expected to generate a string matching the actual file names on disk, this is
-// error prone. Instead, custom sidebar titles should be defined in the frontmatter of the MDX files when needed and
-// `site/data/sidebar.yml` should only reference the actual file names and slug extracted from the docs content
-// collection. Same goes for the docs frontmatter sections.
+/**
+ * Converts a string to a URL-safe slug, collapsing consecutive hyphens.
+ *
+ * Used by the docs sidebar to derive page slugs from sidebar entry titles and
+ * by `DocsLayout` to resolve frontmatter section slugs.
+ *
+ * @remarks
+ * **Known limitation:** the sidebar relies on slugified custom titles matching
+ * the actual filenames on disk, which is fragile. The long-term fix is to move
+ * slug generation into MDX frontmatter and have `sidebar.yml` reference file
+ * names directly. See the `DocsSidebar` component for related context.
+ */
 export function getSlug(str: string) {
   return slug(str).replace(/--+/g, '-')
 }
 
+/** Removes leading and trailing slashes from a URL path segment. */
 export function trimLeadingAndTrailingSlashes(str: string) {
   return str.replace(/^\/+|\/+$/g, '')
 }
 
+/**
+ * Strips Markdown formatting from a string, returning plain text.
+ * Useful for generating clean meta descriptions from Markdown content.
+ */
 export function stripMarkdown(str: string) {
   return toString(fromMarkdown(str))
 }
 
+/**
+ * Converts a Markdown string to an HTML string synchronously.
+ * Intended for short inline content such as page descriptions.
+ */
 export function processMarkdownToHtml(markdown: string): string {
-  // Use remark to process markdown to HTML
   const result = remark().use(remarkHtml).processSync(markdown)
   return result.toString()
 }
 
+/**
+ * Converts a string to title case (first letter of each word uppercased,
+ * remaining letters lowercased).
+ *
+ * @example titleCase('hello world') // 'Hello World'
+ */
 export function titleCase(str: string) {
   return str.replace(
     /\w\S*/g,
     (text) => text.charAt(0).toUpperCase() + text.substring(1).toLowerCase()
   )
 }
-
-/**
- * Gets the appropriate host and port for development server
- * @returns {object} Object with host and port properties
- */
-function getDevHost() {
-  const hasHostFlag = process.argv.includes('--host')
-  let host = 'localhost'
-  let port = 4321
-
-  // Check for --port command line argument (e.g., astro dev --port 4322)
-  const portFlagIndex = process.argv.findIndex((arg) => arg === '--port')
-  if (portFlagIndex !== -1 && process.argv[portFlagIndex + 1]) {
-    const cliPort = parseInt(process.argv[portFlagIndex + 1], 10)
-    if (!isNaN(cliPort) && cliPort > 0 && cliPort < 65536) {
-      port = cliPort
-    }
-  }
-
-  // Check for PORT environment variable (most common way to override port)
-  if (process.env.PORT) {
-    const envPort = parseInt(process.env.PORT, 10)
-    if (!isNaN(envPort) && envPort > 0 && envPort < 65536) {
-      port = envPort
-    }
-  }
-
-  // Determine host based on --host flag
-  if (hasHostFlag) {
-    const interfaces = os.networkInterfaces()
-    for (const iface of Object.values(interfaces).flat()) {
-      if (iface?.family === 'IPv4' && !iface.internal) {
-        host = iface.address
-        break
-      }
-    }
-  }
-
-  return { host, port }
-}
-
-/**
- * Determines the site URL based on environment and deployment context
- * @returns {string} The appropriate site URL for the current environment
- */
-export function getSiteUrl(config: any) {
-  // Check for explicit SITE_URL override first
-  if (process.env.SITE_URL) {
-    return process.env.SITE_URL
-  }
-
-  // Development: Local server with optional network access
-  if (process.env.NODE_ENV === 'development') {
-    const { host, port } = getDevHost()
-    return `http://${host}:${port}`
-  }
-
-  // Vercel Production: Prefer config.baseURL because it already has the correct
-  // path-prefixed chassis-ui.com URL (e.g. https://chassis-ui.com/tokens/).
-  // VERCEL_PROJECT_PRODUCTION_URL is the sub-project's own custom domain
-  // (e.g. tokens.chassis-ui.com) which is NOT the canonical URL we want in sitemaps.
-  if (process.env.VERCEL_ENV === 'production') {
-    return config.baseURL || `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
-  }
-
-  // Vercel Preview: Branch deployments and previews
-  if (process.env.VERCEL_URL) {
-    return `https://${process.env.VERCEL_URL}`
-  }
-
-  // Fallback: Use baseURL from config.yml
-  return config.baseURL
-}

package/src/libs/vite.ts

@@ -0,0 +1,45 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { Plugin } from 'vite'
+
+// Virtual module URL served by Vite's module graph at /@id/__x00__chassis-bundle.
+// Used to give the browser a single shared ESM instance of the chassis bundle in dev.
+const CHASSIS_BUNDLE_VIRTUAL_URL = '/@id/__x00__chassis-bundle'
+
+/**
+ * Vite plugin that resolves `@chassis-ui/css` to a virtual module in dev so
+ * both the `<script>` tag and any `import()` share one ESM instance.
+ *
+ * In build, `rollupOptions.external` + `paths` in the consuming `astro.config.ts`
+ * handles deduplication instead.
+ *
+ * @param getChassisCSSFsPath - Returns the absolute path to the compiled Chassis CSS dist folder.
+ */
+export function chassisBundlePlugin(getChassisCSSFsPath: () => string) {
+  return {
+    plugin: {
+      name: 'chassis-ui-css',
+      enforce: 'pre',
+      apply: 'serve',
+      resolveId(id: string) {
+        if (id === '@chassis-ui/css') return '\0@chassis-ui/css'
+        if (id === '/@chassis-bundle') return '\0chassis-bundle'
+      },
+      load(id: string) {
+        if (id === '\0@chassis-ui/css') return `export * from "/@chassis-bundle"`
+        if (id === '\0chassis-bundle') {
+          const bundlePath = path.join(getChassisCSSFsPath(), 'js/chassis.bundle.js')
+          const content = fs.readFileSync(bundlePath, 'utf-8')
+          // Strip sourceMappingURL — the map isn't resolvable from a virtual module URL.
+          return content.replace(/^\/\/# sourceMappingURL=.+$/m, '')
+        }
+      }
+    } satisfies Plugin,
+    // __CHASSIS_JS_SRC__ is a @chassis-ui/docs extension point: sets the URL for the
+    // chassis JS <script> tag in dev mode. Points at the virtual module so the browser
+    // gets one shared ESM instance instead of a second copy from public/.
+    define: {
+      'globalThis.__CHASSIS_JS_SRC__': JSON.stringify(CHASSIS_BUNDLE_VIRTUAL_URL)
+    }
+  }
+}

package/src/scss/_anchor.scss

@@ -1,21 +1,25 @@
-.anchor-link {
-  padding: 0 .175rem;
-  font-weight: 400;
-  color: rgba($link-main, .5);
-  text-decoration: none;
-  opacity: 0;
-  @include transition(color .15s ease-in-out, opacity .15s ease-in-out);
+@use "@chassis-ui/css/scss/config" as *;
+@use "@chassis-ui/css/scss/mixins" as *;
+@use "@chassis-ui/css/scss/functions" as *;
 
-  &::after {
-    content: "#";
-  }
-
-  &:focus,
-  &:hover,
-  :hover > &,
-  :target > & {
+@layer custom {
+  .anchor-link {
+    padding: 0 .175rem;
+    font-weight: 400;
     color: $link-main;
     text-decoration: none;
-    opacity: 1;
+    opacity: 0;
+    @include transition(color .15s ease-in-out, opacity .15s ease-in-out);
+
+    &::after {
+      content: "#";
+    }
+
+    &:focus,
+    &:hover,
+    :hover > &,
+    :target > & {
+      opacity: 1;
+    }
   }
 }

package/src/scss/_callouts.scss

@@ -1,40 +1,41 @@
+@use "./vars" as *;
+
 //
 // Callouts
 //
 
-.cxd-callout {
-  --#{$prefix}link-main-color-rgb: var(--cxd-callout-link);
-  --#{$prefix}code-color: var(--cxd-callout-code-color);
-
-  padding: 1.25rem;
-  margin-top: 1.25rem;
-  margin-bottom: 1.25rem;
-  color: var(--cxd-callout-color, inherit);
-  background-color: var(--cxd-callout-bg, var(--cx-gray-100));
-  border-left: .25rem solid var(--cxd-callout-border, var(--cx-gray-300));
+@layer custom {
+  .cxd-callout {
+    padding: 1.25rem;
+    margin-block-start: 1.25rem;
+    margin-block-end: 1.25rem;
+    color: var(--cxd-callout-color, inherit);
+    background-color: var(--cxd-callout-bg, var(--cx-neutral-bg-even));
+    border-inline-start: .25rem solid var(--cxd-callout-border, var(--cx-neutral-border-main));
 
-  h4 {
-    margin-bottom: .25rem;
-  }
+    h4 {
+      margin-block-end: .25rem;
+    }
 
-  > :last-child {
-    margin-bottom: 0;
-  }
+    > :last-child {
+      margin-block-end: 0;
+    }
 
-  + .cxd-callout {
-    margin-top: -.25rem;
-  }
+    + .cxd-callout {
+      margin-block-start: -.25rem;
+    }
 
-  .highlight {
-    background-color: rgba($black, .05);
+    .cxd-code {
+      background-color: rgba($black, .05);
+    }
   }
-}
 
-// Variations
-@each $variant in $cxd-callout-variants {
-  .cxd-callout-#{$variant} {
-    --cxd-callout-color: var(--cx-#{$variant}-fg-main);
-    --cxd-callout-bg: var(--cx-#{$variant}-bg-even);
-    --cxd-callout-border: var(--cx-#{$variant}-border-subtle);
+  // Variations
+  @each $variant in $cxd-callout-variants {
+    .cxd-callout-#{$variant} {
+      --cxd-callout-color: var(--cx-#{$variant}-fg-main);
+      --cxd-callout-bg: var(--cx-#{$variant}-bg-even);
+      --cxd-callout-border: var(--cx-#{$variant}-border-subtle);
+    }
   }
 }

package/src/scss/_content.scss

@@ -1,141 +1,110 @@
+@use "@chassis-ui/css/scss/config" as *;
+@use "@chassis-ui/css/scss/mixins" as *;
+
 //
 // Chassis - CSS docs content theming
 //
 
-.cxd-content {
-  padding-bottom: 2rem;
-  > h2,
-  > h3,
-  > h4 {
-    --cx-heading-color: var(--cx-fg-main);
-  }
-
-  // Offset content from fixed navbar when jumping to headings
-  > h2:not(:first-child) {
-    margin-top: 3rem;
-  }
-
-  > h3 {
-    margin-top: 2rem;
-  }
-
-  > ul li,
-  > ol li {
-    margin-bottom: .25rem;
+@layer custom {
+  .cxd-content {
+    padding-block-end: 2rem;
+    > h2,
+    > h3,
+    > h4 {
+      --cx-heading-color: var(--cx-fg-main);
+    }
 
-    // stylelint-disable selector-max-type, selector-max-compound-selectors
-    > p ~ ul {
-      margin-top: -.5rem;
-      margin-bottom: 1rem;
+    // Offset content from fixed navbar when jumping to headings
+    > h2:not(:first-child) {
+      margin-block-start: 3rem;
     }
-    // stylelint-enable selector-max-type, selector-max-compound-selectors
-  }
 
-  // Override Chassis - CSS defaults
-  > .table,
-  > .table-responsive .table {
-    // --cx-table-border-color: var(--cx-border-color);
+    > h3 {
+      margin-block-start: 2rem;
+    }
 
-    max-width: 100%;
-    margin-bottom: 1.5rem;
-    @include font-size(.875rem);
+    > ul li,
+    > ol li {
+      margin-block-end: .25rem;
 
-    @include media-breakpoint-down(large) {
-      &.table-bordered {
-        border: 0;
+      // stylelint-disable-next-line selector-max-type, selector-max-compound-selectors
+      > p ~ ul {
+        margin-block-start: -.5rem;
+        margin-block-end: 1rem;
       }
     }
 
-    thead {
-      border-bottom: 2px solid currentcolor;
+    > ol > li {
+      &:has(:where(h3, h4):first-child)::marker {
+        @include font-size(var(--cx-font-size-xlarge));
+        font-weight: var(--cx-font-weight-strong);
+      }
     }
 
-    tbody:not(:first-child) {
-      border-top: 2px solid currentcolor;
+    // Override Chassis - CSS defaults
+    > .table,
+    > .table-responsive .table {
+      max-width: 100%;
+      margin-block-end: 1.5rem;
+      th,
+      td:first-child > code { // stylelint-disable-line selector-max-compound-selectors
+        white-space: nowrap;
+      }
     }
 
-    th,
-    td {
-      &:first-child {
-        padding-left: 0;
-      }
+  }
 
-      &:not(:last-child) {
-        padding-right: 1.5rem;
-      }
+  a:has(code) {
+    text-decoration: none;
+    > code {
+      color: var(--cx-link-color);
     }
+  }
 
-    th {
-      color: var(--cx-fg-main);
+  .table-options {
+    td:nth-child(2) {
+      min-width: 160px;
     }
+  }
 
-    strong {
+  .table-options td:last-child,
+  .table-utilities td:last-child {
+    min-width: 280px;
+  }
+
+  .table-swatches {
+    th {
       color: var(--cx-fg-main);
     }
 
-    // Prevent breaking of code
-    th,
-    td:first-child > code { // stylelint-disable-line selector-max-compound-selectors
+    td code {
       white-space: nowrap;
     }
   }
-}
 
-.table-options {
-  td:nth-child(2) {
-    min-width: 160px;
+  .cxd-title {
+    --cx-heading-color: var(--cx-fg-main);
+    --cx-font-size: 3rem;
   }
-}
-
-.table-options td:last-child,
-.table-utilities td:last-child {
-  min-width: 280px;
-}
 
-.table-swatches {
-  th {
-    color: var(--cx-fg-main);
+  .cxd-subtitle {
+    @include map-font($font-context-lead, "blockquote");
+    @include font();
   }
 
-  td code {
-    white-space: nowrap;
+  .border-large-start {
+    @include media-breakpoint-up(large) {
+      border-inline-start: var(--cx-border-width) solid var(--cx-border-color);
+    }
   }
-}
 
-.cxd-title {
-  --cx-heading-color: var(--cx-fg-main);
-  --cx-font-size: 3rem;
-}
-
-.cxd-subtitle {
-  @include map-font($font-context-lead, "blockquote");
-  @include font();
-  // font-size: 1.2rem;
-  // line-height: 1.5em;
-  // font-family: var(--cx-font-family-display) !important;
-}
-
-.bi {
-  width: 1em;
-  height: 1em;
-  vertical-align: -.125em;
-  fill: currentcolor;
-}
+  .cxd-summary-link {
+    color: var(--cx-link-color);
 
-.border-large-start {
-  @include media-breakpoint-up(large) {
-    border-left: var(--cx-border-width) solid var(--cx-border-color);
+    &:hover,
+    details[open] > & {  // stylelint-disable-line selector-no-qualifying-type
+      color: var(--cx-hover-color);
+    }
   }
-}
-
-// stylelint-disable selector-no-qualifying-type
-.cxd-summary-link {
-  color: var(--cx-link-color);
 
-  &:hover,
-  details[open] > & {
-    color: var(--cx-hover-color);
-  }
 }
-// stylelint-enable selector-no-qualifying-type
-