@chassis-ui/docs 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Shared Astro layouts, components, and utilities for Chassis documentation sites.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.3.0](https://img.shields.io/badge/Version-0.3.0-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
 
 ## Overview
 
@@ -53,15 +53,15 @@ import { generateTOC, processImage } from '@chassis-ui/docs'
 
 ## Exports
 
-| Subpath | Contents |
-| --- | --- |
-| `@chassis-ui/docs` | Library functions: `chassis`, `image`, `layout`, `rehype`, `toc`, `utils` |
-| `@chassis-ui/docs/layouts/*` | `BaseLayout`, `DocsLayout`, `RedirectLayout`, `SingleLayout` |
+| Subpath                         | Contents                                                                                      |
+| ------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@chassis-ui/docs`              | Library functions: `chassis`, `image`, `layout`, `rehype`, `toc`, `utils`                     |
+| `@chassis-ui/docs/layouts/*`    | `BaseLayout`, `DocsLayout`, `RedirectLayout`, `SingleLayout`                                  |
 | `@chassis-ui/docs/components/*` | `DocsSidebar`, `FeatureCard`, `NavLink`, `ResponsiveImage`, `TableOfContents`, `ThemeToggler` |
-| `@chassis-ui/docs/shortcodes/*` | MDX shortcode components |
-| `@chassis-ui/docs/libs/*` | Direct access to individual library modules |
-| `@chassis-ui/docs/js/*` | Client-side scripts |
-| `@chassis-ui/docs/scss/*` | SCSS utilities and partials |
+| `@chassis-ui/docs/shortcodes/*` | MDX shortcode components                                                                      |
+| `@chassis-ui/docs/libs/*`       | Direct access to individual library modules                                                   |
+| `@chassis-ui/docs/js/*`         | Client-side scripts                                                                           |
+| `@chassis-ui/docs/scss/*`       | SCSS utilities and partials                                                                   |
 
 ### Source Layout
 
@@ -78,14 +78,14 @@ src/
 
 This package is part of the Chassis Design System's multi-repository architecture:
 
-| Project | Description |
-| --- | --- |
+| Project                                                  | Description                                                    |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
 | [chassis-website](https://github.com/chassis-ui/website) | **Main website and home of `@chassis-ui/docs` (this package)** |
-| [chassis-css](https://github.com/chassis-ui/css) | CSS framework and component library |
-| [chassis-tokens](https://github.com/chassis-ui/tokens) | Design token generation and management |
-| [chassis-icons](https://github.com/chassis-ui/icons) | Icon library and build toolkit |
-| [chassis-assets](https://github.com/chassis-ui/assets) | Multi-platform asset management |
-| [chassis-figma](https://github.com/chassis-ui/figma) | Figma component documentation |
+| [chassis-css](https://github.com/chassis-ui/css)         | CSS framework and component library                            |
+| [chassis-tokens](https://github.com/chassis-ui/tokens)   | Design token generation and management                         |
+| [chassis-icons](https://github.com/chassis-ui/icons)     | Icon library and build toolkit                                 |
+| [chassis-assets](https://github.com/chassis-ui/assets)   | Multi-platform asset management                                |
+| [chassis-figma](https://github.com/chassis-ui/figma)     | Figma component documentation                                  |
 
 All documentation sites in the ecosystem share this package for consistent layouts, components, and styling.
 

package/index.ts

@@ -1,7 +1,12 @@
 // Shared libraries for documentation sites
-export * from './src/libs/chassis'
+export * from './src/libs/highlight'
 export * from './src/libs/image'
 export * from './src/libs/layout'
+export * from './src/libs/markdown'
+export * from './src/libs/placeholder'
 export * from './src/libs/rehype'
+export * from './src/libs/shortcodes'
+export * from './src/libs/site'
 export * from './src/libs/toc'
 export * from './src/libs/utils'
+export * from './src/libs/vite'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -40,24 +40,36 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "astro": "astro"
+  },
   "peerDependencies": {
-    "astro": "^5.0.0"
+    "@astrojs/markdown-remark": "^7.0.0",
+    "@chassis-ui/css": ">=0.3.1",
+    "@pagefind/component-ui": "^1.0.0",
+    "@shikijs/transformers": "^4.3.1",
+    "astro": "^7.0.0",
+    "htmlparser2": "^10.1.0",
+    "rehype-autolink-headings": "^7.0.0",
+    "sass": "1.99.0",
+    "shiki": "^4.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@pagefind/component-ui": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@docsearch/css": "^4.6.2",
-    "@docsearch/js": "^4.6.2",
     "@types/hast": "^3.0.4",
-    "@types/mdast": "^4.0.4",
-    "astro": "^6.1.9",
+    "astro": "^7.0.6",
     "github-slugger": "^2.0.0",
     "image-size": "^2.0.2",
     "mdast-util-from-markdown": "^2.0.3",
-    "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-string": "^4.0.0",
     "remark": "^15.0.1",
     "remark-html": "^16.0.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "zod": "^4.3.6"
+    "vite": "^8.1.3"
   }
 }

package/src/components/DocsSidebar.astro

@@ -5,16 +5,17 @@
  * Navigation sidebar for documentation pages with hierarchical menu structure.
  */
 
-import { getData } from '@libs/data'
+import { getData, type SidebarItem, type SidebarSubItem } from '@libs/data'
 import { getConfig } from '@libs/config'
 import { docsPages } from '@libs/content'
 import { getSlug } from '../libs/utils'
+import Icon from './shortcodes/Icon.astro'
 
 const sidebar = getData('sidebar')
 ---
 
 <nav class="cxd-links w-100" id="cxd-docs-nav" aria-label="Docs navigation">
-  <ul class="cxd-links-nav bulletless">
+  <menu class="p-0 m-0">
     {
       sidebar.map((group) => {
         const groupSlug = getSlug(group.title)
@@ -29,19 +30,60 @@ const sidebar = getData('sidebar')
             >
               <strong class="cxd-links-heading">
                 {group.icon && (
-                  <svg
-                    class="icon"
+                  <Icon
+                    name={group.icon}
                     style={group.icon_color && `color: var(--cx-${group.icon_color});`}
-                    aria-hidden="true"
-                  >
-                    <use xlink:href={`#${group.icon}`} />
-                  </svg>
+                  />
                 )}
                 {group.title}
               </strong>
-              <ul>
-                {group.pages?.map((page) => {
-                  const docSlug = getSlug(page.title)
+              <ul class="nav flex-column cxd-links-nav">
+                {group.pages?.map((item: SidebarItem) => {
+                  // Handle sub-groups
+                  if (item.group && item.pages) {
+                    return (
+                      <>
+                        <li class="cxd-links-subgroup">{item.group}</li>
+                        {item.pages.map((page: SidebarSubItem) => {
+                          const docSlug = getSlug(page.title)
+                          const unversionedPageSlug = `${groupSlug}/${docSlug}`
+
+                          const url = `${getConfig().docsPath}/${unversionedPageSlug}`
+                          const active = Astro.params.slug === unversionedPageSlug
+
+                          const generatedPage = docsPages.find(
+                            (page) => page.id === unversionedPageSlug
+                          )
+
+                          // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
+                          if (!generatedPage) {
+                            throw new Error(
+                              `The page '${page.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
+                            )
+                          }
+
+                          return (
+                            <li>
+                              <a
+                                href={url}
+                                class:list={['cxd-links-link', { active }]}
+                                aria-current={active ? 'page' : undefined}
+                              >
+                                {page.title}
+                              </a>
+                            </li>
+                          )
+                        })}
+                      </>
+                    )
+                  }
+
+                  // Handle regular pages
+                  if (!item.title) {
+                    return null
+                  }
+
+                  const docSlug = getSlug(item.title)
                   const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
                   const url = `${getConfig().docsPath}/${unversionedPageSlug}`
@@ -52,7 +94,7 @@ const sidebar = getData('sidebar')
                   // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
                   if (!generatedPage) {
                     throw new Error(
-                      `The page '${page.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
+                      `The page '${item.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
                     )
                   }
 
@@ -63,7 +105,7 @@ const sidebar = getData('sidebar')
                         class:list={['cxd-links-link', { active }]}
                         aria-current={active ? 'page' : undefined}
                       >
-                        {page.title}
+                        {item.title}
                       </a>
                     </li>
                   )
@@ -77,19 +119,17 @@ const sidebar = getData('sidebar')
           return (
             <>
               <li class="cxd-links-span-all mt-2xsmall mb-medium mx-large border-top" />
-              <li class="cxd-links-span-all">
-                <a
-                  href={`${getConfig().docsPath}/${groupSlug}/`}
-                  class:list={['cxd-links-link', { active }]}
-                  aria-current={active ? 'page' : undefined}
-                >
-                  {group.title}
-                </a>
-              </li>
+              <a
+                href={`${getConfig().docsPath}/${groupSlug}/`}
+                class:list={['cxd-links-link cxd-links-span-all', { active }]}
+                aria-current={active ? 'page' : undefined}
+              >
+                {group.title}
+              </a>
             </>
           )
         }
       })
     }
-  </ul>
+  </menu>
 </nav>

package/src/components/FeatureCard.astro

@@ -9,6 +9,8 @@
  * @slot default - Optional additional content (images, code blocks, etc.)
  */
 
+import Icon from './shortcodes/Icon.astro'
+
 interface Props {
   /** Icon ID from the SVG sprite (e.g., "cx-folder-tree") */
   icon?: string
@@ -45,9 +47,7 @@ const headerClasses = [
     {
       icon && (
         <div class="feature-thumb">
-          <svg class="icon feature-icon icon-3xlarge medium:icon-4xlarge" aria-hidden="true">
-            <use href={`#${icon}`} />
-          </svg>
+          <Icon name={icon} class="feature-icon icon-3xlarge medium:icon-4xlarge" sprite="" />
         </div>
       )
     }

package/src/components/TableOfContents.astro

@@ -3,25 +3,26 @@
  * Table of Contents
  *
  * Generate and render a hierarchical table of contents from headings.
+ * Can be called recursively to render nested children.
  */
 
 import type { MarkdownHeading } from 'astro'
-import { generateToc, type TocEntry } from '../libs/toc'
+import { generateToc, type TocConfig, type TocEntry } from '../libs/toc'
 
 interface Props {
-  /** Markdown headings to generate TOC from */
+  /** Markdown headings to generate TOC from. Required when `entries` is not provided. */
   headings?: MarkdownHeading[]
-  /** Pre-generated TOC entries */
+  /** Pre-generated TOC entries. When provided, `headings` is ignored. */
   entries?: TocEntry[]
-  /** Current nesting level */
+  /** Current nesting level. Set automatically during recursive rendering. */
   level?: number
-  /** TOC generation configuration */
-  config?: any
+  /** TOC depth configuration. Required when `entries` is not provided. */
+  config?: TocConfig
 }
 
 const { entries, headings, level, config } = Astro.props
 
-const toc = entries ? entries : generateToc(headings ?? [], config)
+const toc = entries ? entries : generateToc(headings ?? [], config!)
 let entryLevel = level ? level + 1 : 1
 ---
 

package/src/components/ThemeToggler.astro

@@ -6,6 +6,7 @@
  */
 
 import type { Layout } from '../libs/layout'
+import Icon from './shortcodes/Icon.astro'
 
 interface Props {
   /** Current layout context */
@@ -16,62 +17,40 @@ const { layout } = Astro.props
 ---
 
 <button
-  class=`nav-link dropdown-toggle`
+  class="nav-link gap-2xsmall px-0 large:px-small"
   id="cxd-theme"
   type="button"
   aria-expanded="false"
-  data-cx-toggle="dropdown"
-  {...layout !== 'examples' ? { 'data-cx-display': 'static' } : {}}
+  data-cx-toggle="menu"
   aria-label="Toggle theme (auto)"
+  data-cx-placement="bottom-end"
 >
-  <svg class="icon theme-icon-active" aria-hidden="true"><use href="#circle-half-solid"></use></svg>
+  <Icon name="circle-half-solid" class="theme-icon-active" />
   <span
     class=`${layout === 'examples' ? 'visually-hidden' : 'large:d-none ms-xsmall'}`
     id="cxd-theme-text">Toggle theme</span
   >
 </button>
-<ul
-  class=`dropdown-menu dropdown-menu-end${layout === 'examples' ? ' shadow' : ''}`
-  aria-labelledby="cxd-theme-text"
->
+<ul class="menu" role="menu" aria-label="Theme options">
   <li>
-    <button
-      type="button"
-      class="dropdown-item d-flex align-items-center"
-      data-cx-theme-value="light"
-      aria-pressed="false"
-    >
-      <svg class="icon icon-reset me-xsmall" aria-hidden="true"><use href="#sun-solid"></use></svg>
+    <button type="button" class="menu-item" data-cx-theme-value="light">
+      <Icon name="sun-solid" class="menu-item-icon" />
       Light
-      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+      <Icon name="check-solid" class="menu-item-check" />
     </button>
   </li>
   <li>
-    <button
-      type="button"
-      class="dropdown-item d-flex align-items-center"
-      data-cx-theme-value="dark"
-      aria-pressed="false"
-    >
-      <svg class="icon icon-reset me-xsmall" aria-hidden="true"
-        ><use href="#moon-stars-solid"></use></svg
-      >
+    <button type="button" class="menu-item" data-cx-theme-value="dark">
+      <Icon name="moon-stars-solid" class="menu-item-icon" />
       Dark
-      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+      <Icon name="check-solid" class="menu-item-check" />
     </button>
   </li>
   <li>
-    <button
-      type="button"
-      class="dropdown-item d-flex align-items-center active"
-      data-cx-theme-value="auto"
-      aria-pressed="true"
-    >
-      <svg class="icon icon-reset me-xsmall" aria-hidden="true"
-        ><use href="#circle-half-solid"></use></svg
-      >
+    <button type="button" class="menu-item" data-cx-theme-value="auto">
+      <Icon name="circle-half-solid" class="menu-item-icon" />
       Auto
-      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+      <Icon name="check-solid" class="menu-item-check" />
     </button>
   </li>
 </ul>

package/src/components/shortcodes/Blockquote.astro

@@ -7,7 +7,7 @@
 
 interface Props {
   /** Attribution text or HTML for the quote */
-  attr?: String
+  attr?: string
 }
 
 const { attr } = Astro.props

package/src/components/shortcodes/CSSOnly.astro

@@ -1,9 +1,13 @@
 ---
-/*
- * Outputs badge to identify features that are only available in CSS and not in Figma
+/**
+ * CSS Only
+ *
+ * Badge indicating a feature is available in CSS but has no equivalent
+ * Figma component. Renders with a tooltip that can be customized.
  */
 
 interface Props {
+  /** Tooltip text shown on hover. */
   tooltip?: string
 }
 

package/src/components/shortcodes/Callout.astro

@@ -20,9 +20,13 @@ interface Props {
    * @default 'info'
    */
   type?: 'danger' | 'info' | 'warning'
+  /**
+   * The CSS class(es) to be added to the callout wrapping `div` element.
+   */
+  class?: string
 }
 
-const { name, type = 'info' } = Astro.props
+const { name, type = 'info', class: className } = Astro.props
 
 let Content: MarkdownInstance<{}>['Content'] | undefined
 
@@ -38,6 +42,6 @@ if (name) {
 }
 ---
 
-<div class={`cxd-callout cxd-callout-${type} context ${type}`}>
+<div class:list={[`cxd-callout cxd-callout-${type} context ${type}`, className]}>
   {Content ? <Content /> : <slot />}
 </div>