@chassis-ui/docs 0.1.10 → 0.3.0

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
 }

package/src/libs/markdown.ts

@@ -0,0 +1,128 @@
+import type { AstroUserConfig } from 'astro'
+import type { Element, Text } from 'hast'
+import type { ShikiTransformer } from 'shiki'
+import { rehypeHeadingIds, unified } from '@astrojs/markdown-remark'
+import type { UnifiedProcessorOptions } from '@astrojs/markdown-remark'
+import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+import { rehypeCxTable } from './rehype'
+
+type MarkdownConfig = NonNullable<AstroUserConfig['markdown']>
+
+/**
+ * Shiki theme pair used for both programmatic highlighting (`highlightCode`) and
+ * the Astro markdown pipeline (`getDocsMarkdownConfig`). Defined once here to
+ * keep both in sync.
+ */
+export const DOCS_SHIKI_THEMES = {
+  light: 'github-light' as const,
+  dark: 'github-dark' as const
+}
+
+/**
+ * Shiki transformer that exposes the current language as a `data-language`
+ * attribute on `<pre>` elements. The `Code` component reads this attribute when
+ * rendering inline markdown code blocks so it can display the correct language
+ * label without requiring an explicit `lang` prop.
+ */
+const addLanguageAttributeTransformer: ShikiTransformer = {
+  name: 'add-language-attribute',
+  pre(node) {
+    const lang = this.options.lang
+    if (lang) {
+      node.properties['dataLanguage'] = lang
+    }
+  }
+}
+
+/**
+ * Options accepted by `getDocsMarkdownConfig`.
+ */
+export interface DocsMarkdownConfigOptions {
+  /**
+   * Heading depth range used to determine which headings receive an autolink
+   * anchor. Typically sourced from the project's `config.yml` `anchors` section.
+   *
+   * @example { min: 2, max: 4 } // anchors h2–h4
+   */
+  anchors: {
+    min: number
+    max: number
+  }
+  /** Additional project-specific rehype plugins, appended after the base set. */
+  rehypePlugins?: UnifiedProcessorOptions['rehypePlugins']
+  /** Additional project-specific remark plugins, appended after the base set. */
+  remarkPlugins?: UnifiedProcessorOptions['remarkPlugins']
+  /**
+   * Passed directly to `remark-rehype`. Shallow-merged so individual handler
+   * overrides don't discard base handlers.
+   */
+  remarkRehype?: UnifiedProcessorOptions['remarkRehype']
+}
+
+/**
+ * Returns the shared Astro markdown configuration for Chassis docs sites.
+ *
+ * Includes the following base rehype plugins (in order):
+ * - `rehypeHeadingIds` — adds `id` attributes to all headings.
+ * - `rehypeAutolinkHeadings` — appends anchor links to headings in the
+ *   `anchors.min`–`anchors.max` depth range.
+ * - `rehypeCxTable` — applies CSS classes to `<CxTable>`-wrapped tables.
+ * - _(any `options.rehypePlugins`)_
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * import { getDocsMarkdownConfig } from '@chassis-ui/docs'
+ * import { getConfig } from './src/libs/config'
+ *
+ * export default defineConfig({
+ *   markdown: getDocsMarkdownConfig({
+ *     anchors: getConfig().anchors,
+ *     rehypePlugins: [myExtraPlugin],
+ *     remarkPlugins: [remarkCxConfig, remarkDefinitionList],
+ *     remarkRehype: { handlers: defListHastHandlers }
+ *   })
+ * })
+ * ```
+ */
+export function getDocsMarkdownConfig(options: DocsMarkdownConfigOptions): MarkdownConfig {
+  const headingsRangeRegex = new RegExp(`^h[${options.anchors.min}-${options.anchors.max}]$`)
+
+  return {
+    processor: unified({
+      smartypants: false,
+      rehypePlugins: [
+        rehypeHeadingIds,
+        [
+          rehypeAutolinkHeadings,
+          {
+            behavior: 'append',
+            content: [{ type: 'text', value: ' ' }],
+            properties: (element: Element) => ({
+              class: 'anchor-link',
+              ariaLabel: `Link to this section: ${(element.children[0] as Text).value}`
+            }),
+            test: (element: Element) => element.tagName.match(headingsRangeRegex)
+          }
+        ],
+        rehypeCxTable,
+        ...(options.rehypePlugins ?? [])
+      ],
+      remarkPlugins: options.remarkPlugins ?? [],
+      ...(options.remarkRehype && {
+        remarkRehype: options.remarkRehype
+      })
+    }),
+    syntaxHighlight: 'shiki',
+    shikiConfig: {
+      themes: DOCS_SHIKI_THEMES,
+      defaultColor: false,
+      transformers: [
+        transformerNotationDiff(),
+        transformerNotationHighlight(),
+        addLanguageAttributeTransformer
+      ]
+    }
+  }
+}

package/src/libs/placeholder.ts

@@ -0,0 +1,250 @@
+import type { HTMLAttributes } from 'astro/types'
+import * as htmlparser2 from 'htmlparser2'
+
+const placeholderRegex = /<Placeholder\s+([^>]+)\/>/g
+
+/**
+ * Generates all the placeholder attributes and options required to render a placeholder.
+ * @see src/components/shortcodes/Placeholder.astro
+ */
+export function getPlaceholder(userOptions: Partial<PlaceholderOptions>): Placeholder {
+  const options = getOptionsWithDefaults(userOptions)
+  const { class: className, height, markup, text, title, width } = options
+
+  const showText = text !== false
+  const showTitle = title !== false
+
+  const placeholderClassList = ['cxd-placeholder-image', className].join(' ')
+  const placeholderRole = showTitle || showText ? 'img' : undefined
+  const placeholderAriaHidden = !showText && !showTitle ? 'true' : undefined
+
+  const placeholderLabel =
+    showText || showTitle
+      ? `${showTitle ? title : ''}${showTitle && showText ? ': ' : ''}${showText ? text : ''}`
+      : undefined
+
+  const optionsWithVisibilities = { ...options, showText, showTitle }
+
+  if (markup === 'img') {
+    return {
+      type: 'img',
+      options: optionsWithVisibilities,
+      props: {
+        alt: placeholderLabel,
+        class: placeholderClassList,
+        height,
+        src: getPlaceholderSrc(showTitle, showText, options),
+        width
+      }
+    }
+  }
+
+  return {
+    type: 'svg',
+    options: optionsWithVisibilities,
+    props: {
+      'aria-hidden': placeholderAriaHidden,
+      'aria-label': placeholderLabel,
+      class: placeholderClassList,
+      height,
+      preserveAspectRatio: 'xMidYMid slice',
+      role: placeholderRole,
+      width,
+      xmlns: 'http://www.w3.org/2000/svg'
+    }
+  }
+}
+
+/**
+ * Replaces placeholders described using the `<Placeholder />` component in HTML markup with the expected HTML content.
+ * This is useful to render examples that have a pretty large set of constraints:
+ *
+ *  - The provided HTML code is not valid MDX (e.g. unclosed void elements like <img>) but can contain the
+ *      `<Placeholder />` Astro component. This means that we cannot use an Astro slot for example that requires valid
+ *      MDX.
+ *  - The provided HTML code cannot be parsed in a forgiving way with XML mode enabled (to not lose the structure due
+ *      to self-closing MDX or Astro components) and serialized back to a string while closing all known void elements
+ *      in order to render it as MDX using `@mdx-js/mdx` & `astro/jsx-runtime`. This works perfectly (tested) but the
+ *      DOM needs to contains the exact same HTML markup (even indentation) provided to the example as it is used on the
+ *      client to send the example to StackBlitz with the same indentation as the original example.
+ *
+ * If you are not sure if you need to use this function, you probably don't.
+ */
+export function replacePlaceholdersInHtml(html: string) {
+  return html.replace(placeholderRegex, (match) => {
+    const document = htmlparser2.parseDocument(match, { xmlMode: true })
+    const placeholderElement = document.firstChild
+
+    if (
+      document.children.length > 1 ||
+      !placeholderElement ||
+      placeholderElement.type !== htmlparser2.ElementType.Tag ||
+      placeholderElement.name !== 'Placeholder'
+    ) {
+      throw new Error('Invalid placeholder element.')
+    }
+
+    const placeholder = getPlaceholder(sanitizeHtmlAttributesFromMdx(placeholderElement.attribs))
+
+    return renderPlaceholderToString(placeholder)
+  })
+}
+
+function renderPlaceholderToString(placeholder: Placeholder) {
+  let placeholderStr = `<${placeholder.type}`
+
+  for (const [key, value] of Object.entries(placeholder.props)) {
+    if (value === undefined) {
+      continue
+    }
+
+    placeholderStr = `${placeholderStr} ${key}="${value}"`
+  }
+
+  if (placeholder.type === 'img') {
+    return `${placeholderStr} />`
+  }
+
+  placeholderStr = `${placeholderStr}>`
+
+  if (placeholder.options.showTitle) {
+    placeholderStr = `${placeholderStr}<title>${placeholder.options.title}</title>`
+  }
+
+  placeholderStr = `${placeholderStr}<rect width="100%" height="100%" fill="${placeholder.options.background}" />`
+
+  if (placeholder.options.showText) {
+    placeholderStr = `${placeholderStr}<text x="50%" y="50%" fill="${placeholder.options.color}" dy=".3em">${placeholder.options.text}</text>`
+  }
+
+  return `${placeholderStr}</${placeholder.type}>`
+}
+
+function getOptionsWithDefaults(options: Partial<PlaceholderOptions>) {
+  const optionsWithDefaults = Object.assign(
+    {},
+    {
+      background: 'var(--cx-neutral-bg-evident)',
+      color: 'var(--cx-neutral-fg-subtle)',
+      // width: '100%',
+      // height: '180',
+      markup: 'svg',
+      title: 'Placeholder'
+    },
+    options
+  )
+
+  if (optionsWithDefaults.text === undefined) {
+    optionsWithDefaults.text = `${optionsWithDefaults.width}x${optionsWithDefaults.height}`
+  }
+
+  return optionsWithDefaults as PlaceholderOptions
+}
+
+function getPlaceholderSrc(
+  showTitle: boolean,
+  showText: boolean,
+  { background, color, text, title }: PlaceholderOptions
+) {
+  // Sanitize the background and text colors by removing the leading hash if any.
+  const bgColor = background.replace(/^#/, '')
+  const textColor = color.replace(/^#/, '')
+
+  // Build the raw SVG string first
+  let svg = `<svg style='font-size: 1.125rem; font-family:system-ui; -webkit-user-select: none; -moz-user-select: none; user-select: none; text-anchor: middle;' width='200' height='200' xmlns='http://www.w3.org/2000/svg'>`
+
+  if (showTitle) {
+    svg += `<title>${title}</title>`
+  }
+
+  svg += `<rect width='100%' height='100%' fill='#${bgColor}'></rect>`
+
+  if (showText) {
+    svg += `<text x='50%' y='50%' fill='#${textColor}' dy='.3em'>${text}</text>`
+  }
+
+  svg += `</svg>`
+
+  const encodedSvg = encodeURIComponent(svg)
+
+  return `data:image/svg+xml,${encodedSvg}`
+}
+
+function sanitizeHtmlAttributesFromMdx(attributes: Record<string, unknown>) {
+  const sanitizedAttributes: typeof attributes = {}
+
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined) {
+      continue
+    } else if (value === '{false}') {
+      sanitizedAttributes[key] = false
+    } else if (value === '{true}') {
+      sanitizedAttributes[key] = true
+    } else {
+      sanitizedAttributes[key] = value
+    }
+  }
+
+  return sanitizedAttributes
+}
+
+export interface PlaceholderOptions {
+  /**
+   * The SVG background color.
+   * @default "#868f96"
+   */
+  background: string
+  /**
+   * CSS classes to append to `cxd-placeholder-img` for the `svg` or `img` elements.
+   */
+  class?: string
+  /**
+   * The text color (foreground).
+   * @default "#dee2e6"
+   */
+  color: string
+  /**
+   * The placeholder height.
+   * @default "180"
+   */
+  height: string
+  /**
+   * If it should render `svg` or `img` tags.
+   * @default "svg"
+   */
+  markup: 'img' | 'svg'
+  /**
+   * The text to show in the image. You can explicitely pass the `false` boolean value (and not the string "false") to
+   * hide the text.
+   * @default "${width}x${height}"
+   */
+  text: string | false
+  /**
+   * Used in the SVG `title` tag. You can explicitely pass the `false` boolean value (and not the string "false") to
+   * hide the title.
+   * @default "Placeholder"
+   */
+  title: string | false
+  /**
+   * The placeholder width.
+   * @default "100%"
+   */
+  width: string
+}
+
+interface PlaceholderVisibilities {
+  showText: boolean
+  showTitle: boolean
+}
+
+type Placeholder =
+  | {
+      type: 'img'
+      options: PlaceholderOptions & PlaceholderVisibilities
+      props: HTMLAttributes<'img'>
+    }
+  | {
+      type: 'svg'
+      options: PlaceholderOptions & PlaceholderVisibilities
+      props: HTMLAttributes<'svg'>
+    }

package/src/libs/rehype.ts

@@ -41,20 +41,3 @@ export const rehypeCxTable: Plugin<[], Root> = function () {
     })
   }
 }
-
-/**
- * Rehype plugin to strip `is:raw` attributes from code elements.
- *
- * The `@astrojs/markdown-remark` rehype-prism plugin adds `is:raw` as an Astro
- * directive, but it leaks into the final HTML output because rehype processes
- * it as a plain attribute rather than an Astro compiler directive.
- */
-export const rehypeStripIsRaw: Plugin<[], Root> = function () {
-  return function rehypeStripIsRawPlugin(tree) {
-    visit(tree, 'element', (node) => {
-      if (node.properties && 'is:raw' in node.properties) {
-        delete node.properties['is:raw']
-      }
-    })
-  }
-}

package/src/libs/shortcodes.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { AstroIntegration } from 'astro'
+
+interface MdxjsEsmNode {
+  type: 'mdxjsEsm'
+  value: string
+  data: { estree: object }
+}
+
+function buildImportsNode(imports: string[]): MdxjsEsmNode {
+  const body = imports.map((filePath) => {
+    const name = path.parse(filePath).name.replaceAll(/[^\w\d]/g, '')
+    return {
+      type: 'ImportDeclaration',
+      specifiers: [{ type: 'ImportDefaultSpecifier', local: { type: 'Identifier', name } }],
+      source: { type: 'Literal', value: filePath, raw: JSON.stringify(filePath) }
+    }
+  })
+
+  return {
+    type: 'mdxjsEsm',
+    value: '',
+    data: { estree: { type: 'Program', sourceType: 'module', body } }
+  }
+}
+
+export interface ChassisAutoImportOptions {
+  /** Absolute path to the docs site root (e.g. `getDocsFsPath()`). Used for the
+   *  site-local shortcodes directory and the type definitions output path. */
+  docsPath: string
+  /** Absolute path to the directory containing `node_modules`. Defaults to
+   *  `docsPath` when omitted — override when `node_modules` lives at the repo root. */
+  modulesPath?: string
+}
+
+function scanComponents({ docsPath, modulesPath = docsPath }: ChassisAutoImportOptions) {
+  const dirs = [
+    path.join(modulesPath, 'node_modules/@chassis-ui/docs/src/components/shortcodes'),
+    path.join(docsPath, 'src/components/shortcodes')
+  ]
+
+  const components: string[] = []
+  const definitions: string[] = []
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue
+      components.push(`${dir}/${entry.name}`)
+      if (entry.name.endsWith('.astro')) {
+        const importPath = dir.includes('@chassis-ui/docs')
+          ? `@chassis-ui/docs/shortcodes`
+          : `@shortcodes`
+        definitions.push(
+          `export const ${entry.name.replace('.astro', '')}: typeof import('${importPath}/${entry.name}').default`
+        )
+      }
+    }
+  }
+
+  return { components, definitions }
+}
+
+/**
+ * Astro integration that writes the auto-import type definitions file, and a
+ * remark plugin factory for injecting shortcode imports into every MDX file.
+ *
+ * Replaces `astro-auto-import`, which triggers a deprecation warning in Astro 7.
+ *
+ * @example
+ * ```ts
+ * // astro.ts
+ * const { integration, plugin } = chassisAutoImport({ docsPath: getDocsFsPath(), modulesPath: process.cwd() })
+ *
+ * // astro.config.ts
+ * markdown: getDocsMarkdownConfig({ remarkPlugins: [plugin()] })
+ * integrations: [integration()]
+ * ```
+ */
+export function chassisAutoImport(options: ChassisAutoImportOptions): {
+  /** Astro integration that writes `src/types/auto-import.d.ts`. */
+  integration: () => AstroIntegration
+  /** Factory for the remark plugin that injects imports into every `.mdx` file. */
+  plugin: () => ReturnType<typeof createAutoImportPlugin>
+} {
+  const { components, definitions } = scanComponents(options)
+  const typeDefinitionsPath = path.join(options.docsPath, 'src/types/auto-import.d.ts')
+
+  return {
+    integration: () => ({
+      name: 'chassis-auto-import',
+      hooks: {
+        'astro:config:setup': () => {
+          fs.writeFileSync(
+            typeDefinitionsPath,
+            `/**
+ * DO NOT EDIT THIS FILE MANUALLY.
+ *
+ * This file is automatically generated by the Chassis Astro Integration.
+ * It contains the type definitions for the components that are auto imported in all pages.
+ */
+export declare global {
+  ${definitions.join('\n  ')}
+}
+`
+          )
+        }
+      }
+    }),
+    plugin: () => createAutoImportPlugin(components)
+  }
+}
+
+/**
+ * Returns a remark plugin that prepends import statements for the given component
+ * paths into every `.mdx` file.
+ */
+export function createAutoImportPlugin(imports: string[]) {
+  const importsNode = buildImportsNode(imports)
+
+  return function remarkAutoImport() {
+    return function (tree: any, vfile: any) {
+      if (!vfile.basename?.endsWith('.md')) {
+        tree.children.unshift(importsNode)
+      }
+    }
+  }
+}