@chassis-ui/docs 0.2.0 → 0.3.0

package/src/components/shortcodes/ResizableExample.astro

@@ -0,0 +1,126 @@
+---
+import { replacePlaceholdersInHtml } from '../../libs/placeholder'
+import { replaceIconsInHtml } from '../../libs/icon'
+import Code from './Code.astro'
+import Icon from './Icon.astro'
+
+interface Props {
+  /**
+   * Defines if extra JS snippet should be added to StackBlitz or not.
+   * @default false
+   */
+  addStackblitzJs?: boolean
+  /**
+   * The example code.
+   */
+  code: string | string[]
+  /**
+   * Custom markup to display in the source code section, different from the preview code.
+   * If provided, this will be used instead of the `code` prop for the source display.
+   */
+  customMarkup?: string | string[]
+  /**
+   * The CSS class(es) to be added to the resizable container.
+   */
+  class?: string
+  /**
+   * Alias for class prop.
+   */
+  containerClass?: string
+  /**
+   * The preview wrapping `div` element ID.
+   */
+  id?: string
+  /**
+   * Initial width of the resizable container.
+   * @default '100%'
+   */
+  initialWidth?: string
+  /**
+   * Minimum width of the resizable container.
+   * @default '200px'
+   */
+  minWidth?: string
+  /**
+   * Whether to show the code markup below.
+   * @default true
+   */
+  showMarkup?: boolean
+  /**
+   * If true, displays line numbers in the code block.
+   * @default false
+   */
+  lineNumbers?: boolean
+}
+
+const {
+  code,
+  class: className,
+  customMarkup,
+  containerClass,
+  id,
+  initialWidth = '100%',
+  minWidth = '200px',
+  showMarkup = true,
+  lineNumbers = false
+} = Astro.props
+
+let markup = Array.isArray(code) ? code.join('\n') : code
+markup = replacePlaceholdersInHtml(markup)
+markup = replaceIconsInHtml(markup)
+
+// The resizable container needs `overflow: hidden` for the CSS `resize` handle
+// to work, which clips popovers like menus/dropdowns when they open. Render them
+// with a fixed positioning strategy in the live preview only so they can spill
+// outside the container. The displayed markup below is left untouched.
+const previewMarkup = markup.replace(
+  /data-cx-toggle="(menu|dropdown)"(?![^>]*\bdata-cx-strategy=)/g,
+  'data-cx-toggle="$1" data-cx-strategy="fixed"'
+)
+
+let sourceMarkup = customMarkup
+  ? Array.isArray(customMarkup)
+    ? customMarkup.join('\n')
+    : customMarkup
+  : markup
+
+const simplifiedMarkup = sourceMarkup
+  .replace(
+    /<svg.*class="cxd-placeholder-img(?:-large)?(?: *?cxd-placeholder-img-large)? ?(.*?)".*?<\/svg>/g,
+    (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
+  )
+  .replace(
+    /<img.*class="cxd-placeholder-img(?:-large)?(?: *?cxd-placeholder-img-large)? ?(.*?)".*?>/g,
+    (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
+  )
+  .replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
+  .replace(/href="\/static\/icons\/chassis-icons\.svg#/g, 'href="#')
+---
+
+<div class="cxd-example-snippet cxd-code-snippet" data-pagefind-ignore>
+  <div id={id} class:list={['cxd-example m-0 border-0 context', className]}>
+    <div class="cxd-mode">
+      <button
+        type="button"
+        class="button-mode"
+        title="Toggle color mode"
+        aria-label="Toggle color mode"
+        data-cx-toggle="tooltip"
+        onclick="toggleTheme(this)"
+      >
+        <Icon name="swatchbook-solid" />
+      </button>
+    </div>
+    <div
+      class:list={['cxd-resizable-container', containerClass]}
+      style={`width: ${initialWidth}; min-width: ${minWidth};`}
+    >
+      <Fragment set:html={previewMarkup} />
+    </div>
+  </div>
+  {
+    showMarkup && (
+      <Code code={simplifiedMarkup} lang="html" nestedInExample={true} lineNumbers={lineNumbers} />
+    )
+  }
+</div>

package/src/components/shortcodes/ScssDocs.astro

@@ -0,0 +1,108 @@
+---
+import fs from 'node:fs'
+import path from 'node:path'
+import * as sass from 'sass'
+import Code from './Code.astro'
+
+// Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
+// comments in the docs. When compile={true}, the snippet is compiled via the Sass
+// JS API so @include mixin output is shown as real CSS. Default is raw SCSS.
+
+interface Props {
+  /**
+   * Reference name used to find the content to display within the content of the `file` prop.
+   */
+  name: string
+  /**
+   * File path that contains the content to display relative to the root of the repository.
+   */
+  file: string
+  /**
+   * When true, compiles the SCSS snippet via the Sass JS API and displays
+   * the resulting CSS output (useful when the block contains @include mixin calls).
+   * Defaults to false — raw SCSS is shown as-is.
+   */
+  compile?: boolean
+}
+
+const { name, file, compile = false } = Astro.props
+
+if (!name || !file) {
+  throw new Error(
+    `Missing required parameter(s) for the '<ScssDocs />' component, expected both 'name' and 'file' but got 'name: ${name}' and 'file: ${file}'.`
+  )
+}
+
+let content: string
+let lang: string = 'scss'
+
+try {
+  const fileContent = fs.readFileSync(file, 'utf8')
+
+  const matches = fileContent.match(
+    new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
+  )
+
+  if (!matches || !matches[1]) {
+    throw new Error(
+      `Failed to find the content named '${name}', make sure that '// scss-docs-start ${name}' and '// scss-docs-end ${name}' are defined.`
+    )
+  }
+
+  const rawContent = matches[1]
+
+  if (compile) {
+    // Derive the SCSS load path from the file argument (e.g. "scss/_foo.scss" → "scss/")
+    const scssLoadPath = path.resolve(process.cwd(), file.split('/')[0])
+
+    const scssInput = [
+      '@use "config" as *;',
+      '@use "functions" as *;',
+      '@use "tokens" as *;',
+      '@use "maps" as *;',
+      '@use "mixins" as *;',
+      '',
+      '.__cxd_docs_sentinel__ {',
+      rawContent,
+      '}'
+    ].join('\n')
+
+    const result = await sass.compileStringAsync(scssInput, {
+      loadPaths: [scssLoadPath, path.resolve(process.cwd(), 'scss/vendor')],
+      // Match the same deprecation silencing used in astro.config.ts / vite scss options
+      silenceDeprecations: ['import', 'global-builtin', 'color-functions', 'if-function'] as any
+    })
+
+    // Extract the body between the sentinel braces.
+    // Greedy [\s\S]* ensures we capture multi-property output including mixin expansions.
+    const sentinelMatch = result.css.match(/\.__cxd_docs_sentinel__\s*\{([\s\S]*)\}/)
+    content = sentinelMatch ? sentinelMatch[1] : result.css
+    // Apply the same cx- prefix to CSS custom properties as the build's css:prefix step does.
+    content = content.replace(/\.__cxd_docs_sentinel__\s*/g, '')
+    content = content.replace(/--(?!cx-|cxd-|pf-|shell-|shiki-)([a-zA-Z][a-zA-Z0-9-]*)/g, '--cx-$1')
+  } else {
+    // Raw SCSS mode — Sass variable declarations, shown as-is.
+    content = rawContent.replaceAll(' !default', '')
+  }
+
+  // Normalise indentation by removing the common leading-space prefix.
+  const lines = content.split('\n')
+  const spaceCounts = lines
+    .filter((line) => line.trim().length > 0)
+    .map((line) => (line.match(/^ */) || [''])[0].length)
+  const minSpaces = spaceCounts.length ? Math.min(...spaceCounts) : 0
+  content = lines
+    .map((line) => line.slice(minSpaces))
+    .join('\n')
+    .trim()
+} catch (error) {
+  throw new Error(
+    `Failed to find the content to render in the '<ScssDocs />' component at '${file}'.`,
+    {
+      cause: error
+    }
+  )
+}
+---
+
+<Code containerClass="cxd-example-snippet cxd-file-ref" code={content} lang={lang} file={file} />

package/src/components/shortcodes/ScssDocsSimple.astro

@@ -0,0 +1,66 @@
+---
+import fs from 'node:fs'
+import Code from './Code.astro'
+
+// Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
+// comments in the docs.
+
+interface Props {
+  /**
+   * Reference name used to find the content to display within the content of the `file` prop.
+   */
+  name: string
+  /**
+   * File path that contains the content to display relative to the root of the repository.
+   */
+  file: string
+}
+
+const { name, file } = Astro.props
+
+let lang: string = 'scss'
+
+if (!name || !file) {
+  throw new Error(
+    `Missing required parameter(s) for the '<ScssDocs />' component, expected both 'name' and 'file' but got 'name: ${name}' and 'file: ${file}'.`
+  )
+}
+
+let content: string
+
+try {
+  const fileContent = fs.readFileSync(file, 'utf8')
+
+  const matches = fileContent.match(
+    new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
+  )
+
+  if (!matches || !matches[1]) {
+    throw new Error(
+      `Failed to find the content named '${name}', make sure that '// scss-docs-start ${name}' and '// scss-docs-end ${name}' are defined.`
+    )
+  }
+
+  content = matches[1].replaceAll(' !default', '')
+
+  // Fix the identation by removing extra spaces at the beginning of each line
+  const lines = content.split('\n')
+  const spaceCounts = lines
+    .filter((line) => line.trim().length > 0)
+    .map((line) => (line.match(/^ */) || [''])[0].length)
+  const minSpaces = spaceCounts.length ? Math.min(...spaceCounts) : 0
+  content = lines
+    .map((line) => line.slice(minSpaces))
+    .join('\n')
+    .trimEnd()
+} catch (error) {
+  throw new Error(
+    `Failed to find the content to render in the '<ScssDocs />' component at '${file}'.`,
+    {
+      cause: error
+    }
+  )
+}
+---
+
+<Code containerClass="cxd-example-snippet cxd-file-ref" code={content} lang={lang} file={file} />

package/src/js/color-modes.js

@@ -7,7 +7,7 @@
 ;(() => {
   'use strict'
 
-  const getStoredTheme = () => localStorage.getItem('theme')
+  const getStoredTheme = () => localStorage.getItem('theme') || 'auto'
   const setStoredTheme = (theme) => localStorage.setItem('theme', theme)
 
   const getPreferredTheme = () => {
@@ -45,11 +45,11 @@
     const svgOfActiveButton = buttonToActive.querySelector('svg use').getAttribute('href')
 
     document.querySelectorAll('[data-cx-theme-value]').forEach((element) => {
-      element.classList.remove('active')
+      element.classList.remove('selected')
       element.setAttribute('aria-pressed', 'false')
     })
 
-    buttonToActive.classList.add('active')
+    buttonToActive.classList.add('selected')
     buttonToActive.setAttribute('aria-pressed', 'true')
     activeThemeIcon.setAttribute('href', svgOfActiveButton)
     const themeSwitcherLabel = `${themeSwitcherText.textContent} (${buttonToActive.dataset.cxThemeValue})`

package/src/js/example-mode.js

@@ -0,0 +1,75 @@
+import { Tooltip } from '@chassis-ui/css'
+
+// Helper to detect the user's preferred theme
+function getPreferredTheme() {
+  // First check localStorage
+  const storedTheme = localStorage.getItem('theme')
+  if (storedTheme && storedTheme !== 'auto') {
+    return storedTheme
+  }
+
+  // Then check system preference
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+// Direct theme toggle function that's globally accessible
+function toggleTheme(button) {
+  const example = button.closest('.cxd-example-snippet').querySelector('.cxd-example')
+  if (!example) return
+
+  // Get current theme - try from element, then use detection logic if not set
+  let currentTheme = example.getAttribute('data-cx-theme')
+  if (!currentTheme) {
+    // If element doesn't have theme set, use preferred theme
+    currentTheme = getPreferredTheme()
+  }
+
+  // Toggle to the opposite
+  const newTheme = currentTheme === 'dark' ? 'light' : 'dark'
+
+  // Get system preferred theme
+  const preferredTheme = getPreferredTheme()
+
+  // If the new theme matches the preferred system theme, remove the attribute
+  // to let it naturally follow system preference
+  if (newTheme === preferredTheme) {
+    example.removeAttribute('data-cx-theme')
+  } else {
+    // Otherwise, explicitly set the theme
+    example.setAttribute('data-cx-theme', newTheme)
+  }
+
+  // Update the icon to match the theme
+  const iconUse = button.querySelector('use')
+  if (iconUse) {
+    const iconHref = newTheme === 'dark' ? 'sun-solid' : 'moon-solid'
+    iconUse.setAttribute('href', `/static/icons/chassis-icons.svg#${iconHref}`)
+  }
+}
+
+// Expose globally for inline onclick="toggleTheme(this)" handlers in Example.astro
+window.toggleTheme = toggleTheme
+
+// Initialize theme icons for all buttons based on current theme
+document.addEventListener('DOMContentLoaded', () => {
+  const preferredTheme = getPreferredTheme()
+
+  document.querySelectorAll('.button-mode').forEach((button) => {
+    // Initialize tooltip
+    Tooltip.getOrCreateInstance(button)
+
+    // Set initial icon based on theme
+    const iconUse = button.querySelector('use')
+    if (iconUse) {
+      const example = button.closest('.cxd-example-snippet')?.querySelector('.cxd-example')
+      const currentTheme = example?.getAttribute('data-cx-theme') || preferredTheme
+      const iconHref = currentTheme === 'dark' ? 'sun-solid' : 'moon-solid'
+      iconUse.setAttribute('href', `/static/icons/chassis-icons.svg#${iconHref}`)
+    }
+
+    // Add event listener if not already set through onclick
+    if (!button.hasAttribute('onclick')) {
+      button.addEventListener('click', () => toggleTheme(button))
+    }
+  })
+})