@chassis-ui/docs 0.1.0

package/src/js/icon-loader.js

@@ -0,0 +1,220 @@
+/**
+ * Chassis Icons SVG Sprite Loader
+ *
+ * Efficiently loads and caches the chassis-icons.svg sprite using localStorage.
+ * This reduces page size by avoiding inline SVG and enables browser caching.
+ *
+ * Features:
+ * - localStorage caching with version control
+ * - Automatic fallback on cache miss or corruption
+ * - Network request deduplication
+ * - Small footprint and fast execution
+ */
+
+;(function () {
+  'use strict'
+
+  // Configuration
+  const CACHE_KEY = 'chassis-icons-sprite'
+  const VERSION_KEY = 'chassis-icons-version'
+  const CURRENT_VERSION = '1.0.0' // Update when icons change
+  const SVG_URL = '/static/icons/chassis-icons.svg' // Icons SVG sprite path
+
+  // State management
+  let loadPromise = null
+
+  /**
+   * Get SVG sprite from localStorage cache
+   * @returns {string|null} Cached SVG content or null if not found/invalid
+   */
+  function getCachedSprite() {
+    try {
+      const cachedVersion = localStorage.getItem(VERSION_KEY)
+      const cachedSprite = localStorage.getItem(CACHE_KEY)
+
+      if (cachedVersion === CURRENT_VERSION && cachedSprite) {
+        return cachedSprite
+      }
+    } catch (error) {
+      console.warn('Failed to read icon cache:', error)
+    }
+
+    return null
+  }
+
+  /**
+   * Store SVG sprite in localStorage cache
+   * @param {string} spriteContent - SVG content to cache
+   */
+  function setCachedSprite(spriteContent) {
+    try {
+      localStorage.setItem(VERSION_KEY, CURRENT_VERSION)
+      localStorage.setItem(CACHE_KEY, spriteContent)
+    } catch (error) {
+      console.warn('Failed to cache icon sprite:', error)
+      // Handle localStorage quota exceeded or other errors
+      // Clear old cache and try again
+      try {
+        localStorage.removeItem(CACHE_KEY)
+        localStorage.removeItem(VERSION_KEY)
+        localStorage.setItem(VERSION_KEY, CURRENT_VERSION)
+        localStorage.setItem(CACHE_KEY, spriteContent)
+      } catch (retryError) {
+        console.warn('Failed to cache icon sprite after retry:', retryError)
+      }
+    }
+  }
+
+  /**
+   * Fetch SVG sprite from network
+   * @returns {Promise<string>} Promise resolving to SVG content
+   */
+  async function fetchSprite() {
+    const response = await fetch(SVG_URL)
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch icon sprite: ${response.status} ${response.statusText}`)
+    }
+
+    const spriteContent = await response.text()
+
+    // Basic validation - ensure it's actually SVG content
+    if (!spriteContent.includes('<svg') || !spriteContent.includes('</svg>')) {
+      throw new Error('Invalid SVG content received')
+    }
+
+    return spriteContent
+  }
+
+  /**
+   * Inject SVG sprite into the DOM
+   * @param {string} spriteContent - SVG content to inject
+   */
+  function injectSprite(spriteContent) {
+    // Remove any existing sprite container
+    const existingContainer = document.getElementById('chassis-icons-sprite')
+    if (existingContainer) {
+      existingContainer.remove()
+    }
+
+    // Create hidden container for the sprite
+    const container = document.createElement('div')
+    container.id = 'chassis-icons-sprite'
+    container.style.display = 'none'
+    container.setAttribute('aria-hidden', 'true')
+    container.innerHTML = spriteContent
+
+    // Insert at the beginning of body
+    document.body.insertBefore(container, document.body.firstChild)
+  }
+
+  /**
+   * Load and inject the icon sprite
+   * @returns {Promise<void>} Promise that resolves when sprite is loaded
+   */
+  function loadIconSprite() {
+    // Return existing promise if already loading
+    if (loadPromise) {
+      return loadPromise
+    }
+
+    // Check cache first
+    const cachedSprite = getCachedSprite()
+    if (cachedSprite) {
+      injectSprite(cachedSprite)
+      return Promise.resolve()
+    }
+
+    // Fetch from network
+    loadPromise = fetchSprite()
+      .then((spriteContent) => {
+        // Cache the content
+        setCachedSprite(spriteContent)
+
+        // Inject into DOM
+        injectSprite(spriteContent)
+      })
+      .catch((error) => {
+        console.error('Failed to load icon sprite:', error)
+        // Don't throw - let the page continue to work without icons
+      })
+      .finally(() => {
+        loadPromise = null
+      })
+
+    return loadPromise
+  }
+
+  /**
+   * Initialize icon loading
+   * Runs immediately if DOM is ready, or waits for DOMContentLoaded
+   */
+  function init() {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', loadIconSprite)
+    } else {
+      loadIconSprite()
+    }
+  }
+
+  // Public API for manual cache management
+  window.ChassisIcons = {
+    /**
+     * Manually reload the icon sprite (bypasses cache)
+     * @returns {Promise<void>}
+     */
+    reload: async function () {
+      try {
+        // Clear cache
+        localStorage.removeItem(CACHE_KEY)
+        localStorage.removeItem(VERSION_KEY)
+
+        // Force reload
+        loadPromise = null
+        await loadIconSprite()
+      } catch (error) {
+        console.error('Failed to reload icon sprite:', error)
+      }
+    },
+
+    /**
+     * Clear the icon cache
+     */
+    clearCache: function () {
+      try {
+        localStorage.removeItem(CACHE_KEY)
+        localStorage.removeItem(VERSION_KEY)
+      } catch (error) {
+        console.warn('Failed to clear icon cache:', error)
+      }
+    },
+
+    /**
+     * Get cache information
+     * @returns {object} Cache status and size info
+     */
+    getCacheInfo: function () {
+      try {
+        const version = localStorage.getItem(VERSION_KEY)
+        const sprite = localStorage.getItem(CACHE_KEY)
+        return {
+          version: version,
+          cached: !!sprite,
+          size: sprite ? sprite.length : 0,
+          currentVersion: CURRENT_VERSION
+        }
+      } catch (error) {
+        return {
+          version: null,
+          cached: false,
+          size: 0,
+          currentVersion: CURRENT_VERSION,
+          error: error.message
+        }
+      }
+    }
+  }
+
+  // Initialize
+  init()
+})()

package/src/js/search.js

@@ -0,0 +1,58 @@
+// NOTICE!! DO NOT USE ANY OF THIS JAVASCRIPT
+// IT'S ALL JUST JUNK FOR OUR DOCS!
+// ++++++++++++++++++++++++++++++++++++++++++
+
+/*!
+ * JavaScript for Chassis's docs (https://chassis-ui.com/)
+ * Copyright 2024-2025 The Chassis Authors
+ * Licensed under the Creative Commons Attribution 3.0 Unported License.
+ * For details, see https://creativecommons.org/licenses/by/3.0/.
+ */
+
+import docsearch from '@docsearch/js'
+;(() => {
+  // These values will be replaced by Astro's Vite plugin
+  const CONFIG = {
+    apiKey: '__API_KEY__',
+    indexName: '__INDEX_NAME__',
+    appId: '__APP_ID__'
+  }
+
+  const searchElement = document.getElementById('docsearch')
+
+  if (!searchElement) {
+    return
+  }
+
+  const siteDocsVersion = searchElement.getAttribute('data-cxd-docs-version')
+
+  docsearch({
+    apiKey: CONFIG.apiKey,
+    indexName: CONFIG.indexName,
+    appId: CONFIG.appId,
+    container: searchElement,
+    searchParameters: {
+      facetFilters: [`version:${siteDocsVersion}`]
+    },
+    transformItems(items) {
+      return items.map((item) => {
+        const liveUrl = 'https://chassis-ui.com/'
+
+        item.url = window.location.origin.startsWith(liveUrl)
+          ? // On production, return the result as is
+            item.url
+          : // On development or Netlify, replace `item.url` with a trailing slash,
+            // so that the result link is relative to the server root
+            item.url.replace(liveUrl, '/')
+
+        // Prevent jumping to first header
+        if (item.anchor === 'content') {
+          item.url = item.url.replace(/#content$/, '')
+          item.anchor = null
+        }
+
+        return item
+      })
+    }
+  })
+})()

package/src/js/sidebar.js

@@ -0,0 +1,30 @@
+// NOTICE!! DO NOT USE ANY OF THIS JAVASCRIPT
+// IT'S ALL JUST JUNK FOR OUR DOCS!
+// ++++++++++++++++++++++++++++++++++++++++++
+
+/*
+ * JavaScript for Chassis's docs (https://chassis-ui.com/)
+ * Copyright 2011-2025 The Chassis Authors
+ * Licensed under the Creative Commons Attribution 3.0 Unported License.
+ * For details, see https://creativecommons.org/licenses/by/3.0/.
+ */
+
+;(() => {
+  // Scroll the active sidebar link into view
+  const sidenav = document.querySelector('.cxd-sidebar')
+  const sidenavActiveLink = document.querySelector('.cxd-links-nav .active')
+
+  if (!sidenav || !sidenavActiveLink) {
+    return
+  }
+
+  const sidenavHeight = sidenav.clientHeight
+  const sidenavActiveLinkTop = sidenavActiveLink.offsetTop
+  const sidenavActiveLinkHeight = sidenavActiveLink.clientHeight
+  const viewportTop = sidenavActiveLinkTop
+  const viewportBottom = viewportTop - sidenavHeight + sidenavActiveLinkHeight
+
+  if (sidenav.scrollTop > viewportTop || sidenav.scrollTop < viewportBottom) {
+    sidenav.scrollTop = viewportTop - sidenavHeight / 2 + sidenavActiveLinkHeight / 2
+  }
+})()

package/src/js/theme-color.js

@@ -0,0 +1,126 @@
+// Dynamic theme color based on scroll position
+;(() => {
+  'use strict'
+
+  // Configuration
+  const CONFIG = {
+    scrollThreshold: 100,
+    defaultColor: '#00A4CC'
+  }
+
+  // DOM elements
+  const elements = {
+    themeColorMeta: document.querySelector('meta[name="theme-color"]'),
+    header: document.querySelector('header'),
+    footer: document.querySelector('.cxd-footer')
+  }
+
+  // Early return if required elements are missing
+  if (!elements.themeColorMeta || !elements.header || !elements.footer) {
+    return
+  }
+
+  /**
+   * Extracts RGB values from a CSS color string
+   * @param {string} color - CSS color string (rgb/rgba)
+   * @returns {Object|null} RGB object or null if invalid
+   */
+  function extractRGB(color) {
+    const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*[\d.]+)?\)/)
+    return match
+      ? {
+          r: parseInt(match[1], 10),
+          g: parseInt(match[2], 10),
+          b: parseInt(match[3], 10)
+        }
+      : null
+  }
+
+  /**
+   * Converts RGB values to hex color string
+   * @param {number} r - Red value (0-255)
+   * @param {number} g - Green value (0-255)
+   * @param {number} b - Blue value (0-255)
+   * @returns {string} Hex color string
+   */
+  function rgbToHex(r, g, b) {
+    return '#' + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1).toUpperCase()
+  }
+
+  /**
+   * Gets the computed background color of an element as hex
+   * @param {HTMLElement} element - DOM element
+   * @returns {string} Hex color string or default color
+   */
+  function getElementBackgroundColor(element) {
+    const bgColor = getComputedStyle(element).backgroundColor
+    const rgb = extractRGB(bgColor)
+    return rgb ? rgbToHex(rgb.r, rgb.g, rgb.b) : CONFIG.defaultColor
+  }
+
+  /**
+   * Determines the current scroll position context
+   * @returns {string} 'top', 'bottom', or 'middle'
+   */
+  function getScrollContext() {
+    const scrollTop = window.pageYOffset || document.documentElement.scrollTop
+    const windowHeight = window.innerHeight
+    const documentHeight = document.documentElement.scrollHeight
+
+    if (scrollTop < CONFIG.scrollThreshold) {
+      return 'top'
+    }
+
+    if (scrollTop + windowHeight >= documentHeight - CONFIG.scrollThreshold) {
+      return 'bottom'
+    }
+
+    return 'middle'
+  }
+
+  /**
+   * Updates the theme color meta tag based on scroll position
+   */
+  function updateThemeColor() {
+    const context = getScrollContext()
+    let color = CONFIG.defaultColor
+
+    switch (context) {
+      case 'top':
+        color = getElementBackgroundColor(elements.header)
+        break
+      case 'bottom':
+        color = getElementBackgroundColor(elements.footer)
+        break
+      case 'middle':
+      default:
+        color = CONFIG.defaultColor
+        break
+    }
+
+    elements.themeColorMeta.setAttribute('content', color)
+  }
+
+  // Throttle function for performance optimization
+  function throttle(func, limit) {
+    let inThrottle
+    return function () {
+      const args = arguments
+      const context = this
+      if (!inThrottle) {
+        func.apply(context, args)
+        inThrottle = true
+        setTimeout(() => (inThrottle = false), limit)
+      }
+    }
+  }
+
+  // Event listeners with throttling for better performance
+  const throttledUpdate = throttle(updateThemeColor, 16) // ~60fps
+
+  window.addEventListener('scroll', throttledUpdate, { passive: true })
+  window.addEventListener('resize', throttledUpdate, { passive: true })
+
+  // Initial update
+  updateThemeColor()
+})()

package/src/layouts/BaseLayout.astro

@@ -0,0 +1,94 @@
+---
+import type { CollectionEntry } from 'astro:content'
+import { getConfig } from '@libs/config'
+import type { Layout, LayoutOverridesHTMLAttributes } from '../libs/layout'
+import Head from './head/Head.astro'
+import Header from './header/Header.astro'
+import Scripts from './footer/Scripts.astro'
+import Footer from './footer/Footer.astro'
+import { stripMarkdown } from '../libs/utils'
+
+// The following props can be directly passed to the base layout component from any page or layout extending it,
+// e.g. <BaseLayout layout="docs" robots="noindex" />.
+type Props = {
+  // A specific layout to use for the current page used to determine if some components should be rendered or not.
+  // Available layouts are defined in `src/libs/layout.ts`.
+  layout?: Layout
+  // An object containing HTML attributes that can be overridden for some HTML elements used in the base layout keyed by
+  // HTML element names.
+  overrides?: {
+    body?: LayoutOverridesHTMLAttributes<'body'>
+    // Note that main can also be overridden by the Astro slot named "main" and that the slot will take precedence over
+    // any override.
+    main?: LayoutOverridesHTMLAttributes<'main'>
+  }
+  // A string containing the robots meta tag content. If not set, the tag will not be rendered.
+  robots?: string
+  // An override for the page title. If not defined, the title will either be the content of the `title` frontmatter
+  // property when rendering a markdown page or default back to the one defined in the `config.yml` file.
+  title?: string
+} & MarkdownProps
+
+// The following props are automatically set by Astro (if defined) based on the markdown frontmatter when rendering a
+// markdown page. They can be accessed through the `Astro.props.frontmatter` object but note that they won't be set when
+// not rendering a markdown page.
+type MarkdownProps = { frontmatter?: Partial<CollectionEntry<'docs' | 'blog'>['data']> }
+
+const { frontmatter, layout, overrides, robots } = Astro.props
+
+const title = Astro.props.title ?? frontmatter?.title ?? getConfig().title
+const description = frontmatter?.description
+  ? stripMarkdown(frontmatter.description)
+  : getConfig().description
+const thumbnail = frontmatter?.thumbnail
+  ? `img/${frontmatter.thumbnail}`
+  : 'logo/chassis-logo-default.svg'
+
+const bodyProps = overrides?.body ?? {}
+const mainProps = overrides?.main ?? {}
+---
+
+<!doctype html>
+<html lang="en" data-cx-theme="auto">
+  <head>
+    <Head
+      description={description}
+      layout={layout}
+      robots={robots}
+      thumbnail={thumbnail}
+      title={title}
+    />
+  </head>
+  <body {...bodyProps}>
+    <Header layout={layout} title={title} />
+
+    {
+      Astro.slots.has('main') ? (
+        <slot name="main" />
+      ) : (
+        <main {...mainProps}>
+          <slot />
+        </main>
+      )
+    }
+
+    <Footer />
+
+    <Scripts layout={layout}>
+      <slot name="scripts" slot="scripts" />
+    </Scripts>
+
+    {
+      frontmatter?.extra_js &&
+        frontmatter.extra_js.map((js) => <script is:inline async={js.async} src={js.src} />)
+    }
+
+    {
+      (layout === 'docs' || layout === 'icons') && (
+        <div class="position-fixed" aria-hidden="true">
+          <input type="text" tabindex="-1" />
+        </div>
+      )
+    }
+  </body>
+</html>

package/src/layouts/DocsLayout.astro

@@ -0,0 +1,147 @@
+---
+import type { MarkdownHeading } from 'astro'
+import type { CollectionEntry } from 'astro:content'
+import { getConfig } from '@libs/config'
+import { getChassisDocsPath } from '@libs/path'
+import type { LayoutOverridesHTMLAttributes } from '../libs/layout'
+import { getSlug, processMarkdownToHtml } from '../libs/utils'
+import BaseLayout from './BaseLayout.astro'
+import DocsSidebar from '../components/DocsSidebar.astro'
+import TableOfContents from '../components/TableOfContents.astro'
+
+interface Props {
+  frontmatter: CollectionEntry<'docs'>['data']
+  headings?: MarkdownHeading[]
+  id: CollectionEntry<'docs'>['id']
+}
+
+const { frontmatter, headings, id } = Astro.props
+
+// Extract the directory/section from the ID (format: "directory/filename.mdx")
+const parentDirectory = id.includes('/') ? id.split('/')[0] : ''
+
+const bodyProps: LayoutOverridesHTMLAttributes<'body'> = {}
+
+if (frontmatter.toc) {
+  bodyProps['data-cx-spy'] = 'scroll'
+  bodyProps['data-cx-target'] = '#TableOfContents'
+}
+---
+
+<BaseLayout {...Astro.props} layout="docs" overrides={{ body: bodyProps }}>
+  <div slot="main" class="container-fluid cxd-gutter cxd-layout">
+    <aside class="cxd-sidebar">
+      <div
+        class="offcanvas-large offcanvas-start"
+        tabindex="-1"
+        id="cxdSidebar"
+        aria-labelledby="cxdSidebarOffcanvasLabel"
+      >
+        <div class="offcanvas-header border-bottom">
+          <h5 class="offcanvas-title" id="cxdSidebarOffcanvasLabel">Browse docs</h5>
+          <button
+            type="button"
+            class="close-button"
+            data-cx-dismiss="offcanvas"
+            aria-label="Close"
+            data-cx-target="#cxdSidebar"></button>
+        </div>
+
+        <div class="offcanvas-body">
+          <DocsSidebar />
+        </div>
+      </div>
+    </aside>
+
+    <main class="cxd-main">
+      <div class="cxd-intro">
+        <div
+          class="d-medium-flex flex-medium-row-reverse justify-content-between align-items-start"
+        >
+          <div class="mb-medium mb-medium-0 d-flex text-nowrap">
+            {
+              // This is needed because we want to show the badge if show_badge isn't present or is set to false
+              frontmatter.added &&
+                ((frontmatter.added.show_badge !== undefined &&
+                  frontmatter.added.show_badge === true) ||
+                  frontmatter.added.show_badge === undefined) && (
+                  <span class="badge success smooth rounded-medium me-xsmall">
+                    Added in v{frontmatter.added.version}
+                  </span>
+                )
+            }
+            <a
+              class="button default small"
+              href={`${getConfig().repo}/blob/${id}.mdx`}
+              title="View and edit this file on GitHub"
+              target="_blank"
+              rel="noopener"
+            >
+              View on GitHub
+            </a>
+          </div>
+          <h1 class="cxd-title mb-0" id="content">{frontmatter.title}</h1>
+        </div>
+        <div class="cxd-subtitle">
+          {
+            frontmatter.description && (
+              <Fragment set:html={processMarkdownToHtml(frontmatter.description)} />
+            )
+          }
+        </div>
+      </div>
+
+      {
+        frontmatter.toc && headings && (
+          <div class="cxd-toc">
+            <button
+              class="button default mb-large text-decoration-none cxd-toc-toggle d-medium-none"
+              type="button"
+              data-cx-toggle="collapse"
+              data-cx-target="#tocContents"
+              aria-expanded="false"
+              aria-controls="tocContents"
+            >
+              On this page
+              <svg class="icon icon-small" aria-hidden="true">
+                <use xlink:href="#chevron-sort-solid" />
+              </svg>
+            </button>
+            <strong class="d-none d-medium-block h6 my-xsmall">On this page</strong>
+            <hr class="d-none d-medium-block my-xsmall" />
+            <div class="collapse cxd-toc-collapse" id="tocContents">
+              <nav id="TableOfContents">
+                <TableOfContents headings={headings} config={getConfig()} />
+              </nav>
+            </div>
+          </div>
+        )
+      }
+
+      <div class="cxd-content">
+        {
+          frontmatter.sections && (
+            <div class="row g-xlarge">
+              {frontmatter.sections.map((section) => (
+                <div class="col-medium-6">
+                  <a
+                    class="d-block text-decoration-none"
+                    href={getChassisDocsPath(
+                      `${parentDirectory ? parentDirectory + '/' : ''}${getSlug(section.title)}/`
+                    )}
+                  >
+                    <strong class="d-block h5 mb-2xsmall">{section.title}</strong>
+                    <span class="fg-subtle">{section.description}</span>
+                  </a>
+                </div>
+              ))}
+            </div>
+          )
+        }
+
+        <slot />
+      </div>
+    </main>
+  </div>
+  <slot name="scripts" slot="scripts" />
+</BaseLayout>

package/src/layouts/IconsLayout.astro

@@ -0,0 +1,19 @@
+---
+import type { LayoutOverridesHTMLAttributes } from '../libs/layout'
+import BaseLayout from './BaseLayout.astro'
+
+const bodyProps: LayoutOverridesHTMLAttributes<'body'> = {}
+
+bodyProps['id'] = 'icons-body'
+bodyProps['data-cx-spy'] = 'scroll'
+bodyProps['data-cx-target'] = '#icons-nav'
+---
+
+<BaseLayout {...Astro.props} layout="icons" overrides={{ body: bodyProps }}>
+  <div
+    slot="main"
+    class="container-2xlarge px-medium px-medium-4xlarge cxd-gutter icon-docs icon-reset pt-medium-large pb-medium-large"
+  >
+    <slot />
+  </div>
+</BaseLayout>