@chassis-ui/docs 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @chassis-ui/docs
+
+Shared Astro components and layouts for Chassis documentation sites.
+
+## Overview
+
+This package provides reusable Astro components, layouts, and utilities specifically designed for building documentation websites within the Chassis UI ecosystem. It includes common documentation patterns, styling helpers, and content processing utilities.
+
+## Installation
+
+```bash
+npm install @chassis-ui/docs
+```
+
+or with pnpm:
+
+```bash
+pnpm add @chassis-ui/docs
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `@chassis-ui/css`: Chassis CSS framework
+- `@chassis-ui/icons`: Chassis icon library  
+- `@chassis-ui/tokens`: Chassis design tokens
+- `astro`: ^4.0.0 || ^5.0.0
+
+## Usage
+
+### Importing Components
+
+```typescript
+// Import layouts
+import Layout from '@chassis-ui/docs/layouts/Layout.astro'
+import DocsLayout from '@chassis-ui/docs/layouts/DocsLayout.astro'
+
+// Import components
+import CodeBlock from '@chassis-ui/docs/components/CodeBlock.astro'
+import Callout from '@chassis-ui/docs/components/Callout.astro'
+
+// Import utilities
+import { generateTOC } from '@chassis-ui/docs'
+import { processImage } from '@chassis-ui/docs'
+```
+
+### Available Exports
+
+This package exports:
+
+- **Layouts**: Pre-built Astro layouts for documentation pages
+- **Components**: Reusable documentation components (code blocks, callouts, navigation, etc.)
+- **Shortcodes**: MDX-compatible shortcode components
+- **Libraries**: Utility functions for content processing, TOC generation, and more
+- **Styles**: SCSS utilities and mixins
+- **Scripts**: Client-side JavaScript utilities
+
+### Directory Structure
+
+```
+src/
+├── components/     # Astro components
+│   └── shortcodes/ # MDX shortcode components
+├── layouts/        # Page layouts
+├── libs/           # Utility libraries
+├── js/             # Client-side scripts
+└── scss/           # Styling utilities
+```
+
+## Features
+
+- **Content Processing**: Utilities for processing markdown and MDX content
+- **Table of Contents**: Automatic TOC generation from headings
+- **Image Optimization**: Helper functions for responsive images
+- **Syntax Highlighting**: Code block components with syntax highlighting
+- **Navigation**: Responsive documentation navigation components
+- **Search Integration**: Ready-to-use search components
+- **Accessibility**: WCAG-compliant components with proper ARIA attributes
+
+## Development
+
+This package is part of the Chassis UI monorepo. For development instructions, see the main repository documentation.
+
+## License
+
+MIT © [Chassis UI](https://github.com/chassis-ui)
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines in the main repository.
+
+## Links
+
+- [Documentation](https://chassis-ui.com/docs)
+- [GitHub Repository](https://github.com/chassis-ui/website)
+- [Issue Tracker](https://github.com/chassis-ui/website/issues)
+- [Chassis UI Website](https://chassis-ui.com)

package/index.ts

@@ -0,0 +1,7 @@
+// Shared libraries for documentation sites
+export * from './src/libs/image'
+export * from './src/libs/layout'
+export * from './src/libs/rehype'
+export * from './src/libs/remark'
+export * from './src/libs/toc'
+export * from './src/libs/utils'

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@chassis-ui/docs",
+  "description": "Shared Astro components and layouts for Chassis documentation sites.",
+  "version": "0.1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chassis-ui/website.git",
+    "directory": "packages/docs"
+  },
+  "bugs": {
+    "url": "https://github.com/chassis-ui/website/issues"
+  },
+  "homepage": "https://chassis-ui.com",
+  "author": "Ozgur Gunes <o.gunes@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "chassis",
+    "documentation",
+    "components",
+    "layouts",
+    "design-system"
+  ],
+  "files": [
+    "src",
+    "index.ts",
+    "README.md"
+  ],
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./components/*": "./src/components/*",
+    "./shortcodes/*": "./src/components/shortcodes/*",
+    "./layouts/*": "./src/layouts/*",
+    "./libs/*": "./src/libs/*",
+    "./js/*": "./src/js/*",
+    "./scss/*": "./src/scss/*"
+  },
+  "peerDependencies": {
+    "@chassis-ui/css": "*",
+    "@chassis-ui/icons": "*",
+    "@chassis-ui/tokens": "*",
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@chassis-ui/css": "github:chassis-ui/css#app/docs",
+    "@chassis-ui/icons": "github:chassis-ui/icons#app/docs",
+    "@chassis-ui/tokens": "github:chassis-ui/tokens#app/docs",
+    "@docsearch/css": "^3.9.0",
+    "@docsearch/js": "^3.9.0",
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "astro": "^5.13.9",
+    "github-slugger": "^2.0.0",
+    "image-size": "^2.0.2",
+    "mdast-util-from-markdown": "^2.0.2",
+    "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.0.0",
+    "zod": "^4.1.11"
+  }
+}

package/src/components/DocsSidebar.astro

@@ -0,0 +1,89 @@
+---
+import { getData } from '@libs/data'
+import { getConfig } from '@libs/config'
+import { docsPages } from '@libs/content'
+import { getSlug } from '../libs/utils'
+
+const sidebar = getData('sidebar')
+---
+
+<nav class="cxd-links w-100" id="cxd-docs-nav" aria-label="Docs navigation">
+  <ul class="cxd-links-nav bulletless">
+    {
+      sidebar.map((group) => {
+        const groupSlug = getSlug(group.title)
+
+        if (group.pages) {
+          return (
+            <li
+              class:list={[
+                'cxd-links-group',
+                groupSlug === Astro.params.slug?.split('/')[0] ? 'active' : undefined
+              ]}
+            >
+              <strong class="cxd-links-heading">
+                {group.icon && (
+                  <svg
+                    class="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)
+                  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 'packages/websitedata/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>
+                  )
+                })}
+              </ul>
+            </li>
+          )
+        } else {
+          const active = Astro.params.slug === groupSlug
+
+          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>
+            </>
+          )
+        }
+      })
+    }
+  </ul>
+</nav>

package/src/components/NavDocsMenu.astro

@@ -0,0 +1,26 @@
+---
+import type { Layout } from '../libs/layout'
+
+interface Props {
+  layout: Layout
+}
+
+const { layout } = Astro.props
+---
+
+<a
+  class="nav-link dropdown-toggle"
+  href="/docs"
+  role="button"
+  data-cx-toggle="dropdown"
+  aria-expanded="false">Docs</a
+>
+<ul class="dropdown-menu">
+  <li><a class="dropdown-item" href="/css">CSS</a></li>
+  <li><a class="dropdown-item" href="/tokens">Tokens</a></li>
+  <li><a class="dropdown-item" href="/icons">Icons</a></li>
+  <li><a class="dropdown-item" href="/figma">Figma</a></li>
+  <li><a class="dropdown-item" href="/assets">Assets</a></li>
+  <li><hr class="dropdown-separator" /></li>
+  <li><a class="dropdown-item" href="/docs">Docs Index</a></li>
+</ul>

package/src/components/NavLink.astro

@@ -0,0 +1,24 @@
+---
+interface Props {
+  active?: boolean
+  class?: string
+  href: string
+  rel?: HTMLAnchorElement['rel']
+  target?: HTMLAnchorElement['target']
+  track?: boolean
+}
+
+const { active, class: className, track, ...props } = Astro.props
+
+const content = await Astro.slots.render('default')
+---
+
+<li class="nav-item col-6 col-large-auto">
+  <a
+    aria-current={active ? true : undefined}
+    class:list={['nav-link', className, { active }]}
+    {...props}
+  >
+    <slot />
+  </a>
+</li>

package/src/components/ResponsiveImage.astro

@@ -0,0 +1,31 @@
+---
+interface Props {
+  imgPath: string
+  alt: string
+  classes?: string
+  lazyload?: boolean
+  width?: number
+  height?: number
+}
+
+const { imgPath, alt, classes = '', lazyload = true, width, height } = Astro.props
+
+const classNames = ['image', classes].filter(Boolean).join(' ')
+
+const basePath = imgPath.split('/').slice(0, -1).join('/')
+const basename = imgPath.split('/').pop()?.split('.')[0] || ''
+const ext = imgPath.includes('.') ? `.${imgPath.split('.').pop()}` : ''
+
+const imgPath1x = `${basePath}/${basename}${ext}`
+const imgPath2x = `${basePath}/${basename}@2x${ext}`
+---
+
+<img
+  class={classNames}
+  srcset={`${imgPath1x}, ${imgPath2x} 2x`}
+  src={imgPath1x}
+  alt={alt}
+  loading={lazyload ? 'lazy' : undefined}
+  width={width}
+  height={height}
+/>

package/src/components/TableOfContents.astro

@@ -0,0 +1,31 @@
+---
+import type { MarkdownHeading } from 'astro'
+import { generateToc, type TocEntry } from '../libs/toc'
+
+interface Props {
+  headings?: MarkdownHeading[]
+  entries?: TocEntry[]
+  level?: number
+  config?: any
+}
+
+const { entries, headings, level, config } = Astro.props
+
+const toc = entries ? entries : generateToc(headings ?? [], config)
+let entryLevel = level ? level + 1 : 1
+---
+
+<ul>
+  {
+    toc.map(({ children, slug, text }) => {
+      return (
+        <li>
+          <a href={`#${slug}`} class={`level-${entryLevel}`}>
+            {text}
+          </a>
+          {children.length > 0 && <Astro.self entries={children} level={entryLevel} />}
+        </li>
+      )
+    })
+  }
+</ul>

package/src/components/ThemeToggler.astro

@@ -0,0 +1,70 @@
+---
+import type { Layout } from '../libs/layout'
+
+interface Props {
+  layout: Layout
+}
+
+const { layout } = Astro.props
+---
+
+<button
+  class=`nav-link dropdown-toggle`
+  id="cxd-theme"
+  type="button"
+  aria-expanded="false"
+  data-cx-toggle="dropdown"
+  {...layout !== 'examples' ? { 'data-cx-display': 'static' } : {}}
+  aria-label="Toggle theme (auto)"
+>
+  <svg class="icon theme-icon-active" aria-hidden="true"><use href="#circle-half-solid"></use></svg>
+  <span
+    class=`${layout === 'examples' ? 'visually-hidden' : 'd-large-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"
+>
+  <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>
+      Light
+      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+    </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
+      >
+      Dark
+      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+    </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
+      >
+      Auto
+      <svg class="icon ms-auto d-none" aria-hidden="true"><use href="#check-solid"></use></svg>
+    </button>
+  </li>
+</ul>

package/src/components/shortcodes/AddedIn.astro

@@ -0,0 +1,13 @@
+---
+/*
+ * Outputs badge to identify the first version something was added
+ */
+
+interface Props {
+  version: string
+}
+
+const { version } = Astro.props
+---
+
+<span class="badge large success smooth mb-medium rounded-medium">Added in v{version}</span>

package/src/components/shortcodes/Callout.astro

@@ -0,0 +1,37 @@
+---
+import { getCalloutByName, type CalloutName } from '@libs/content'
+import { render } from 'astro:content'
+import type { MarkdownInstance } from 'astro'
+
+interface Props {
+  /**
+   * The name of an existing callout to display located in `src/content/callouts`.
+   * This will override any content passed in via the default slot.
+   */
+  name?: CalloutName
+  /**
+   * The type of callout to display. One of `info`, `danger`, or `warning`.
+   * @default 'info'
+   */
+  type?: 'danger' | 'info' | 'warning'
+}
+
+const { name, type = 'info' } = Astro.props
+
+let Content: MarkdownInstance<{}>['Content'] | undefined
+
+if (name) {
+  const callout = await getCalloutByName(name)
+
+  if (!callout) {
+    throw new Error(`Could not find callout with name '${name}'.`)
+  }
+
+  const namedCallout = await render(callout)
+  Content = namedCallout.Content
+}
+---
+
+<div class={`cxd-callout cxd-callout-${type} context ${type}`}>
+  {Content ? <Content /> : <slot />}
+</div>

package/src/components/shortcodes/CxTable.astro

@@ -0,0 +1,16 @@
+---
+interface Props {
+  /**
+   * The CSS class to apply to the table.
+   * Note that the prop is not used in this component, but in a rehype plugin applying the classes to the table element
+   * directly on the HTML AST (HAST) generated by Astro.
+   * @default "table"
+   * @see src/libs/rehype.ts
+   */
+  class?: string
+}
+---
+
+<div class="table-responsive">
+  <slot />
+</div>

package/src/js/color-modes.js

@@ -0,0 +1,82 @@
+/*!
+ * Color mode toggler for Chassis's docs (https://chassis-ui.com/)
+ * Copyright 2011-2025 The Chassis Authors
+ * Licensed under the Creative Commons Attribution 3.0 Unported License.
+ */
+
+;(() => {
+  'use strict'
+
+  const getStoredTheme = () => localStorage.getItem('theme')
+  const setStoredTheme = (theme) => localStorage.setItem('theme', theme)
+
+  const getPreferredTheme = () => {
+    const storedTheme = getStoredTheme()
+    if (storedTheme) {
+      return storedTheme
+    }
+
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  }
+
+  const setTheme = (theme) => {
+    if (theme === 'auto') {
+      document.documentElement.setAttribute(
+        'data-cx-theme',
+        window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+      )
+    } else {
+      document.documentElement.setAttribute('data-cx-theme', theme)
+    }
+  }
+
+  setTheme(getPreferredTheme())
+
+  const showActiveTheme = (theme, focus = false) => {
+    const themeSwitcher = document.querySelector('#cxd-theme')
+
+    if (!themeSwitcher) {
+      return
+    }
+
+    const themeSwitcherText = document.querySelector('#cxd-theme-text')
+    const activeThemeIcon = document.querySelector('.theme-icon-active use')
+    const buttonToActive = document.querySelector(`[data-cx-theme-value="${theme}"]`)
+    const svgOfActiveButton = buttonToActive.querySelector('svg use').getAttribute('href')
+
+    document.querySelectorAll('[data-cx-theme-value]').forEach((element) => {
+      element.classList.remove('active')
+      element.setAttribute('aria-pressed', 'false')
+    })
+
+    buttonToActive.classList.add('active')
+    buttonToActive.setAttribute('aria-pressed', 'true')
+    activeThemeIcon.setAttribute('href', svgOfActiveButton)
+    const themeSwitcherLabel = `${themeSwitcherText.textContent} (${buttonToActive.dataset.cxThemeValue})`
+    themeSwitcher.setAttribute('aria-label', themeSwitcherLabel)
+
+    if (focus) {
+      themeSwitcher.focus()
+    }
+  }
+
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    const storedTheme = getStoredTheme()
+    if (storedTheme !== 'light' && storedTheme !== 'dark') {
+      setTheme(getPreferredTheme())
+    }
+  })
+
+  window.addEventListener('DOMContentLoaded', () => {
+    showActiveTheme(getPreferredTheme())
+
+    document.querySelectorAll('[data-cx-theme-value]').forEach((toggle) => {
+      toggle.addEventListener('click', () => {
+        const theme = toggle.getAttribute('data-cx-theme-value')
+        setStoredTheme(theme)
+        setTheme(theme)
+        showActiveTheme(theme, true)
+      })
+    })
+  })
+})()