@chassis-ui/docs 0.2.0 → 0.3.0

package/src/layouts/head/Analytics.astro

@@ -6,18 +6,24 @@
  */
 
 import { getConfig } from '@libs/config'
+const isProd = import.meta.env.PROD
 const googleId = getConfig().analytics.google_id
 ---
 
-<!-- Google tag (gtag.js) -->
-<script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleId}`}></script>
-<script
-  is:inline
-  set:html={`
+{
+  isProd && (
+    <>
+      <script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleId}`} />
+      <script
+        is:inline
+        set:html={`
   window.dataLayer = window.dataLayer || [];
   function gtag(){dataLayer.push(arguments);}
   gtag('js', new Date());
 
   gtag('config', '${googleId}');
 `}
-/>
+      />
+    </>
+  )
+}

package/src/layouts/head/Favicons.astro

@@ -4,8 +4,6 @@
  *
  * Favicon and app icon link tags for various platforms.
  */
-
-// <meta name="theme-color" content="#00A4CC" />
 ---
 
 <link rel="apple-touch-icon" href={'/static/images/apple-touch-icon.png'} sizes="180x180" />

package/src/layouts/head/Head.astro

@@ -16,8 +16,6 @@ import '@scss/docs.scss'
 interface Props {
   /** Page description for meta tags */
   description: string
-  /** Text direction (for RTL languages) */
-  direction?: 'rtl'
   /** Current layout context */
   layout: Layout
   /** Robots meta tag value */
@@ -28,7 +26,7 @@ interface Props {
   title: string
 }
 
-const { description, direction, layout, robots, thumbnail, title } = Astro.props
+const { description, layout, robots, thumbnail, title } = Astro.props
 
 const canonicalUrl = new URL(Astro.url.pathname, Astro.site)
 
@@ -45,19 +43,16 @@ const pageTitle = isHome
 
 <meta name="author" content={getConfig().authors} />
 <meta name="generator" content={Astro.generator} />
-<meta name="docsearch:language" content="en" />
 
 <link rel="canonical" href={canonicalUrl} />
 
-<link rel="preconnect" href={`https://${getConfig().algolia.app_id}-dsn.algolia.net`} crossorigin />
-
 <title>{pageTitle}</title>
 
 {robots && <meta name="robots" content={robots} />}
 
 <script src="../../js/color-modes.js"></script>
 
-<Stylesheet direction={direction} layout={layout} />
+<Stylesheet />
 <slot name="styles" />
 <Favicons />
 <Social description={description} layout={layout} thumbnail={thumbnail} title={title} />

package/src/layouts/head/Stylesheet.astro

@@ -5,18 +5,25 @@
  * Stylesheet link tags for external CSS resources.
  */
 
-import { getChassisCssProps } from '../../libs/chassis'
-import type { Layout } from '../../libs/layout'
+import type { HTMLAttributes } from 'astro/types'
 
-interface Props {
-  /** Text direction (for RTL languages) */
-  direction?: 'rtl'
-  /** Current layout context */
-  layout: Layout
-}
+function getChassisCssProps() {
+  let cxCssLinkHref = '/static/css/chassis'
+
+  if (import.meta.env.PROD) {
+    cxCssLinkHref = `${cxCssLinkHref}.min`
+  }
+
+  cxCssLinkHref = `${cxCssLinkHref}.css`
 
-const { direction } = Astro.props
+  const cxCssLinkProps: HTMLAttributes<'link'> = {
+    href: cxCssLinkHref,
+    rel: 'stylesheet'
+  }
+
+  return cxCssLinkProps
+}
 ---
 
-<link {...getChassisCssProps(direction)} />
-<link rel="stylesheet" href={`/static/icons/chassis-icons.min.css`} />
+<link {...getChassisCssProps()} />
+<link rel="stylesheet" href={`/static/icons/chassis-icons.css`} />

package/src/layouts/header/Header.astro

@@ -5,23 +5,20 @@
  * Site header with navigation and page title.
  */
 
-import type { CollectionEntry } from 'astro:content'
 import type { Layout } from '../../libs/layout'
 import Skippy from './Skippy.astro'
 import Navigation from './Navigation.astro'
 
 interface Props {
-  /** Version when the feature was added */
-  addedIn?: CollectionEntry<'docs'>['data']['added']
   /** Current layout context */
   layout: Layout
   /** Page title */
   title: string
 }
 
-const { layout, title } = Astro.props
+const { layout } = Astro.props
 ---
 
 <Skippy layout={layout} />
 
-<Navigation layout={layout} title={title} />
+<Navigation layout={layout} />

package/src/layouts/header/Navigation.astro

@@ -9,12 +9,13 @@ import { getConfig } from '@libs/config'
 import type { Layout } from '../../libs/layout'
 import NavLink from '../../components/NavLink.astro'
 import ThemeToggler from '../../components/ThemeToggler.astro'
+import SearchTrigger from './SearchTrigger.astro'
+import SearchDialog from './SearchDialog.astro'
+import Icon from '../../components/shortcodes/Icon.astro'
 
 interface Props {
   /** Current layout context */
   layout: Layout
-  /** Page title for the navbar */
-  title: string
 }
 
 const { layout } = Astro.props
@@ -31,22 +32,20 @@ const isActive = (path: string) => {
 }
 ---
 
-<header class="navbar large:navbar-expand cxd-navbar sticky-top">
-  <nav class="container 2xlarge" aria-label="Main navigation">
+<header class="navbar translucent large:navbar-expand cxd-navbar sticky-top">
+  <nav class="container 2xlarge" aria-label="Site navigation">
     {
       layout === 'docs' && (
         <div class="cxd-navbar-toggle">
           <button
-            class="navbar-toggler p-xsmall2"
+            class="button icon-only navbar-toggler"
             type="button"
-            data-cx-toggle="offcanvas"
+            data-cx-toggle="drawer"
             data-cx-target="#cxdSidebar"
             aria-controls="cxdSidebar"
             aria-label="Toggle docs navigation"
           >
-            <svg class="icon icon-large" aria-hidden="true">
-              <use href="#bars-solid" />
-            </svg>
+            <Icon name="bars-solid" class="icon-large" />
             <span class="d-none large:d-inline fs-6 pe-2xsmall">Browse</span>
           </button>
         </div>
@@ -54,44 +53,42 @@ const isActive = (path: string) => {
     }
     {layout !== 'docs' && <div class="large:d-none" style="width: 4.25rem;" />}
 
-    <a class="navbar-brand large:me-medium" href="/" aria-label="Chassis">
+    <a class="navbar-brand m-0 py-small large:me-medium" href="/" aria-label="Chassis">
       <img src="/static/images/site-logo.svg" alt="Chassis UI" width="123" height="32" />
     </a>
 
     <div class="d-flex">
-      <div class="cxd-search" id="docsearch"></div>
+      <div class="cxd-search"><SearchTrigger placeholder="Search docs…" /></div>
 
       <button
-        class="navbar-toggler d-flex large:d-none order-3 p-xsmall"
+        class="button icon-only navbar-toggler"
         type="button"
-        data-cx-toggle="offcanvas"
+        data-cx-toggle="drawer"
         data-cx-target="#cxdNavbar"
         aria-controls="cxdNavbar"
         aria-label="Toggle navigation"
       >
-        <svg class="icon" aria-hidden="true"><use xlink:href="#ellipsis-h-solid"></use></svg>
+        <Icon name="ellipsis-h-solid" />
       </button>
     </div>
 
-    <div
-      class="offcanvas large:offcanvas offcanvas-end flex-grow-1"
-      role="dialog"
-      tabindex="-1"
+    <dialog
+      class="max-large:drawer drawer-end flex-grow-1"
       id="cxdNavbar"
       aria-labelledby="cxdNavbarOffcanvasLabel"
     >
-      <div class="offcanvas-header px-large pb-0">
-        <h5 class="offcanvas-title text-white" id="cxdNavbarOffcanvasLabel">Chassis</h5>
+      <div class="drawer-header">
+        <h2 class="drawer-title" id="cxdNavbarOffcanvasLabel">Chassis</h2>
         <button
           type="button"
           class="close-button close-button-white"
-          data-cx-dismiss="offcanvas"
+          data-cx-dismiss="drawer"
           aria-label="Close"
           data-cx-target="#cxdNavbar"></button>
       </div>
 
-      <div class="offcanvas-body p-large pt-0 large:p-0">
-        <hr class="large:d-none" />
+      <hr class="large:d-none m-0" />
+      <div class="drawer-body large:p-0">
         <ul class="navbar-nav flex-row flex-wrap cxd-navbar-nav mx-0 large:mx-medium">
           <NavLink active={isActive('/tokens')} href="/tokens">Tokens</NavLink>
           <NavLink active={isActive('/figma')} href="/figma">Figma</NavLink>
@@ -99,43 +96,44 @@ const isActive = (path: string) => {
           <NavLink active={isActive('/assets')} href="/assets">Assets</NavLink>
           <NavLink active={isActive('/icons')} href="/icons">Icons</NavLink>
           <li class="nav-item col-12 large:col-auto large:d-flex">
-            <div class="vr d-none large:d-flex my-auto large:mx-2"></div>
+            <div class="vr d-none large:d-flex my-auto large:mx-small"></div>
             <hr class="large:d-none" />
           </li>
           <NavLink active={isActive('/examples')} href="/examples">Examples</NavLink>
         </ul>
 
-        <hr class="large:d-none" />
+        <hr class="large:d-none m-0" />
 
-        <ul class="navbar-nav flex-row flex-wrap medium:ms-auto align-items-center">
+        <ul class="navbar-nav flex-row flex-wrap large:ms-auto align-items-center">
           <NavLink
-            class="nav-link px-0 large:px-2"
+            class="px-0 large:px-small"
             href={getConfig().github_org}
             target="_blank"
             rel="noopener"
           >
-            <svg class="icon"><title>GitHub</title><use href="#github-brand"></use></svg>
+            <Icon name="github-brand" title="GitHub" />
             <small class="large:d-none ms-xsmall">GitHub</small>
           </NavLink>
           <NavLink
-            class="nav-link px-0 large:px-2"
+            class="px-0 large:px-small"
             href={`https://x.com/${getConfig().x}`}
             target="_blank"
             rel="noopener"
           >
-            <svg class="icon"><title>X</title><use href="#x-twitter-brand"></use></svg>
+            <Icon name="x-twitter-brand" title="X" />
             <small class="large:d-none ms-xsmall">X</small>
           </NavLink>
           <li class="nav-item col-12 large:col-auto">
-            <div class="vr d-none large:d-flex h-100 large:mx-2"></div>
+            <div class="vr d-none large:d-flex h-100 large:mx-2xsmall"></div>
             <hr class="large:d-none" />
           </li>
 
-          <li class="nav-item dropdown">
+          <li class="nav-item">
             <ThemeToggler layout={layout} />
           </li>
         </ul>
       </div>
-    </div>
+    </dialog>
   </nav>
 </header>
+<SearchDialog placeholder="Search docs…" />

package/src/layouts/header/SearchDialog.astro

@@ -0,0 +1,74 @@
+---
+/**
+ * Search Dialog
+ *
+ * Modal dialog containing the Pagefind search input and results. Opened by
+ * `SearchTrigger` or the ⌘K / Ctrl+K / "/" keyboard shortcuts defined in
+ * `src/js/search.js`. Uses native `<dialog>` with `showModal()`.
+ */
+
+import Icon from '../../components/shortcodes/Icon.astro'
+
+interface Props {
+  /** HTML `id` of the dialog element. Must match the `target` in `SearchTrigger`. */
+  id?: string
+  /** Placeholder text for the search input and the visually-hidden label. */
+  placeholder?: string
+}
+
+const { id = 'cxdSearchDialog', placeholder = 'Search docs…' } = Astro.props
+---
+
+<dialog
+  class="modal dialog large cxd-search-dialog scrollable"
+  id={id}
+  aria-labelledby={`${id}-label`}
+>
+  <search class="modal-header cxd-search-form">
+    <label class="visually-hidden" id={`${id}-label`} for={`${id}-input`}>
+      {placeholder}
+    </label>
+    <cxd-search-input>
+      <div class="form-input">
+        <div class="input-help">
+          <Icon name="search-solid" />
+        </div>
+        <input
+          id={`${id}-input`}
+          type="search"
+          class="ghost-input cxd-search-input"
+          placeholder={placeholder}
+          autocomplete="off"
+          spellcheck="false"
+          enterkeyhint="search"
+        />
+      </div>
+    </cxd-search-input>
+    <button
+      type="button"
+      class="close-button"
+      aria-label="Close"
+      data-cx-dismiss="dialog"
+      data-cx-target={`#${id}`}>×</button
+    >
+  </search>
+
+  <div class="modal-body cxd-search-body">
+    <cxd-search-results></cxd-search-results>
+  </div>
+  <div class="modal-footer cxd-search-footer">
+    <ul class="list horizontal cxd-search-shortcuts-list">
+      <li class="list-item">
+        <kbd class="cxd-search-shortcut-key font-2xsmall">⮐</kbd>
+        <span class="cxd-search-shortcut-label">to select</span>
+      </li><li class="list-item">
+        <kbd class="cxd-search-shortcut-key font-small">↑</kbd>
+        <kbd class="cxd-search-shortcut-key font-small">↓</kbd>
+        <span class="cxd-search-shortcut-label">to navigate</span>
+      </li><li class="list-item">
+        <kbd class="cxd-search-shortcut-key font-xsmall">ESC</kbd>
+        <span class="cxd-search-shortcut-label">to close</span>
+      </li>
+    </ul>
+  </div>
+</dialog>

package/src/layouts/header/SearchTrigger.astro

@@ -0,0 +1,41 @@
+---
+/**
+ * Search Trigger
+ *
+ * Button that opens the `SearchDialog`. Displays a platform-aware keyboard
+ * shortcut hint (⌘K on Mac, Ctrl K elsewhere) that `search.js` fills in after
+ * detecting the platform — rendered hidden until then so non-JS visitors never
+ * see a misleading hint.
+ */
+
+import Icon from '../../components/shortcodes/Icon.astro'
+
+interface Props {
+  /** Additional CSS classes to apply to the trigger button. */
+  class?: string
+  /** Accessible label and visible placeholder text inside the trigger. */
+  placeholder?: string
+  /** CSS selector for the dialog to open. Must match `SearchDialog`'s `id`. */
+  target?: string
+}
+
+const { class: className, placeholder = 'Search docs…', target = '#cxdSearchDialog' } = Astro.props
+---
+
+<button
+  type="button"
+  class:list={['cxd-search-trigger', className]}
+  data-cx-toggle="dialog"
+  data-cx-target={target}
+  aria-haspopup="dialog"
+  aria-label={placeholder}
+>
+  <Icon name="search-solid" size={16} />
+  <span class="cxd-search-trigger-label">{placeholder}</span>
+  {
+    /* Shortcut hint is empty + hidden until search.js detects the platform and
+      fills in either ⌘K (Mac) or Ctrl K (other). Without JS the shortcut
+      itself doesn't work, so showing nothing is more honest than guessing. */
+  }
+  <span class="cxd-search-trigger-shortcut" hidden></span>
+</button>

package/src/libs/highlight.ts

@@ -0,0 +1,91 @@
+import { codeToHtml, type ShikiTransformer } from 'shiki'
+import { DOCS_SHIKI_THEMES } from './markdown'
+
+/**
+ * Shiki transformer that renames the `shiki` CSS class on `<pre>` elements to
+ * `astro-code` so that Astro's built-in syntax highlighting styles apply.
+ */
+const classTransformer: ShikiTransformer = {
+  name: 'class-name-transformer',
+  pre(node) {
+    if (typeof node.properties.class === 'string') {
+      node.properties.class = node.properties.class.replace(/shiki/g, 'astro-code')
+    }
+  }
+}
+
+/**
+ * Shiki transformer that wraps non-comment lines in a `<span class="line">`
+ * element. Applied only to shell languages (bash, sh, powershell) where line
+ * wrapping is needed for the copy-button to correctly extract individual commands.
+ */
+const lineWrapperTransformer: ShikiTransformer = {
+  name: 'line-wrapper',
+  line(node) {
+    const hasOnlyComments = node.children.every(
+      (child) =>
+        child.type === 'element' &&
+        child.properties?.class &&
+        Array.isArray(child.properties.class) &&
+        child.properties.class.some((cls) => typeof cls === 'string' && cls.includes('comment'))
+    )
+
+    if (!hasOnlyComments) {
+      node.properties = node.properties || {}
+      const existing = node.properties.class ?? ''
+      const classes = typeof existing === 'string' ? existing.split(' ') : []
+      if (!classes.includes('line')) classes.push('line')
+      node.properties.class = classes.join(' ').trim()
+    }
+  }
+}
+
+/**
+ * Replaces any remaining `shiki` / `shiki-themes` class strings in the
+ * serialized HTML that the transformer may have missed (e.g. in inline styles
+ * converted by `transformerStyleToClass`).
+ */
+function replaceShikiClasses(html: string): string {
+  return html
+    .replace(/class=(["'])shiki(\s+)/g, 'class=$1astro-code$2')
+    .replace(/class=(["'])shiki(["'])/g, 'class=$1astro-code$2')
+    .replace(/shiki-themes/g, 'astro-code-themes')
+}
+
+/**
+ * Highlights a code string using Shiki with the GitHub light/dark dual theme.
+ *
+ * Inline styles are converted to CSS classes via `transformerStyleToClass` so
+ * that a single `<style>` block can be emitted per page rather than repeating
+ * styles on every token. The returned `css` string must be injected into the
+ * page (e.g. inside a `<style>` tag) for the highlighted output to render correctly.
+ *
+ * For shell languages (`bash`, `sh`, `powershell`) each non-comment line is
+ * additionally wrapped in `<span class="line">` to support per-line copy.
+ *
+ * @param code - Source code to highlight.
+ * @param lang - Shiki language identifier (e.g. `"html"`, `"ts"`, `"bash"`).
+ * @param extraTransformers - Additional Shiki transformers to apply before the built-ins.
+ * @returns An object with `html` (the highlighted markup) and `css` (the extracted styles).
+ */
+export async function highlightCode(
+  code: string,
+  lang: string,
+  extraTransformers: ShikiTransformer[] = []
+): Promise<{ html: string }> {
+  const shouldWrapLines = ['bash', 'sh', 'powershell'].includes(lang)
+
+  const transformers: ShikiTransformer[] = [...extraTransformers, classTransformer]
+  if (shouldWrapLines) {
+    transformers.push(lineWrapperTransformer)
+  }
+
+  const highlighted = await codeToHtml(code, {
+    lang,
+    themes: DOCS_SHIKI_THEMES,
+    defaultColor: false,
+    transformers
+  })
+
+  return { html: replaceShikiClasses(highlighted) }
+}

package/src/libs/icon.ts

@@ -0,0 +1,75 @@
+import * as htmlparser2 from 'htmlparser2'
+
+const iconRegex = /<Icon\s+([^>]+)\/>/g
+
+interface IconOptions {
+  name: string
+  class?: string
+  size: number
+  font: boolean
+  sprite: string
+  title?: string
+}
+
+/**
+ * Replaces `<Icon />` elements described using the `<Icon />` Astro component in HTML markup with the
+ * expected HTML content.
+ *
+ * This is needed because the `<Example />` shortcode renders its `code` prop as raw HTML via `set:html`
+ * rather than as MDX, so nested Astro components (like `<Icon />`, similar to `<Placeholder />`) are never
+ * actually invoked — they need to be expanded to their rendered markup ahead of time.
+ * @see src/components/shortcodes/Icon.astro
+ */
+export function replaceIconsInHtml(html: string) {
+  return html.replace(iconRegex, (match) => {
+    const document = htmlparser2.parseDocument(match, { xmlMode: true })
+    const iconElement = document.firstChild
+
+    if (
+      document.children.length > 1 ||
+      !iconElement ||
+      iconElement.type !== htmlparser2.ElementType.Tag ||
+      iconElement.name !== 'Icon'
+    ) {
+      throw new Error('Invalid icon element.')
+    }
+
+    return renderIconToString(getOptionsWithDefaults(iconElement.attribs))
+  })
+}
+
+function getOptionsWithDefaults(attribs: Record<string, string>): IconOptions {
+  if (!attribs.name) {
+    throw new Error('Icon element is missing the required "name" attribute.')
+  }
+
+  return {
+    name: attribs.name,
+    class: attribs.class,
+    size: attribs.size ? Number(attribs.size.replace(/[{}]/g, '')) : 24,
+    font: attribs.font !== undefined && attribs.font !== '{false}',
+    sprite: attribs.sprite || '/static/icons/chassis-icons.svg',
+    title: attribs.title
+  }
+}
+
+function renderIconToString({ name, class: className, size, font, sprite, title }: IconOptions) {
+  const classes = ['icon', font ? `cx-${name}` : undefined, className].filter(Boolean).join(' ')
+  const ariaHidden = title ? '' : ' aria-hidden="true"'
+
+  if (font) {
+    const ariaLabel = title ? ` aria-label="${escapeHtml(title)}"` : ''
+    return `<span class="${classes}"${ariaHidden}${ariaLabel}></span>`
+  }
+
+  const titleTag = title ? `<title>${escapeHtml(title)}</title>` : ''
+  return `<svg class="${classes}" width="${size}" height="${size}"${ariaHidden}>${titleTag}<use href="${sprite}#${name}"></use></svg>`
+}
+
+function escapeHtml(value: string) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/libs/image.ts

@@ -1,9 +1,20 @@
 import { promises as fs } from 'node:fs'
 import sizeOf from 'image-size'
 
+/**
+ * Reads an image file from disk and returns its pixel dimensions.
+ *
+ * Intended for build-time use only (e.g. generating `<meta og:image:width/height>`
+ * tags). Do not call at runtime in a server or edge context where filesystem
+ * access is unavailable.
+ *
+ * @param imagePath - Absolute path to the image file.
+ * @returns An object with `width` and `height` in pixels.
+ * @throws If the file cannot be read or its dimensions cannot be determined.
+ */
 export async function getStaticImageSize(imagePath: string) {
   const buffer = await fs.readFile(imagePath)
-  const size = await sizeOf(new Uint8Array(buffer))
+  const size = sizeOf(new Uint8Array(buffer))
 
   if (!size?.height || !size?.width) {
     throw new Error(`Failed to get size of static image at '${imagePath}'.`)

package/src/libs/layout.ts

@@ -1,7 +1,25 @@
 import type { HTMLAttributes, HTMLTag } from 'astro/types'
 
+/**
+ * Identifies which top-level layout a page is using. Passed down through
+ * layouts and components to conditionally render layout-specific UI (e.g.
+ * sidebar toggle, TOC, search).
+ *
+ * `undefined` means a plain page with no special layout context.
+ */
 export type Layout = 'docs' | 'icons' | 'examples' | 'single' | 'blog' | undefined
 
+/**
+ * Extends Astro's standard HTML element attributes with an open-ended set of
+ * `data-*` attributes so that arbitrary data attributes can be passed as
+ * override props without TypeScript errors.
+ *
+ * @example
+ * const bodyProps: LayoutOverridesHTMLAttributes<'body'> = {
+ *   class: 'docs-body',
+ *   'data-cx-spy': 'scroll',
+ * }
+ */
 export type LayoutOverridesHTMLAttributes<TTag extends HTMLTag> = HTMLAttributes<TTag> & {
   [key in `data-${string}`]: string //eslint-disable-line no-unused-vars
 }