@chassis-ui/docs 0.2.0 → 0.3.0

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)
+      }
+    }
+  }
+}

package/src/libs/site.ts

@@ -0,0 +1,95 @@
+import os from 'os'
+
+/** Resolved host and port for the local Astro development server. */
+interface DevHost {
+  /** Hostname or IP address (e.g. `"localhost"` or a LAN IP when `--host` is passed). */
+  host: string
+  /** Port number the dev server is listening on. */
+  port: number
+}
+
+/**
+ * Minimum site configuration shape required by `getSiteUrl`.
+ * The consuming project's full config object satisfies this interface as long
+ * as it exposes a `baseURL` string.
+ */
+export interface SiteConfig {
+  /** Canonical base URL used as a fallback in production (e.g. `"https://chassis-ui.com/css/"`). */
+  baseURL: string
+}
+
+/**
+ * Resolves the host and port for the local Astro development server.
+ *
+ * Resolution order for port: `--port` CLI flag → `PORT` env var → `4321` (Astro default).
+ * When `--host` is passed, the first non-internal IPv4 network interface address
+ * is used as the host so the dev URL is reachable on the LAN.
+ */
+function getDevHost(): DevHost {
+  const hasHostFlag = process.argv.includes('--host')
+  let host = 'localhost'
+  let port = 4321
+
+  const portFlagIndex = process.argv.findIndex((arg) => arg === '--port')
+  if (portFlagIndex !== -1 && process.argv[portFlagIndex + 1]) {
+    const cliPort = parseInt(process.argv[portFlagIndex + 1], 10)
+    if (!isNaN(cliPort) && cliPort > 0 && cliPort < 65536) {
+      port = cliPort
+    }
+  }
+
+  if (process.env.PORT) {
+    const envPort = parseInt(process.env.PORT, 10)
+    if (!isNaN(envPort) && envPort > 0 && envPort < 65536) {
+      port = envPort
+    }
+  }
+
+  if (hasHostFlag) {
+    const interfaces = os.networkInterfaces()
+    for (const iface of Object.values(interfaces).flat()) {
+      if (iface?.family === 'IPv4' && !iface.internal) {
+        host = iface.address
+        break
+      }
+    }
+  }
+
+  return { host, port }
+}
+
+/**
+ * Determines the canonical site URL for the current environment.
+ *
+ * Resolution order:
+ * 1. `SITE_URL` env var — explicit override, takes precedence everywhere.
+ * 2. `NODE_ENV=development` — constructs a local `http://` URL from `getDevHost()`.
+ * 3. `VERCEL_ENV=production` — uses `config.baseURL` (the path-prefixed canonical
+ *    URL) rather than `VERCEL_PROJECT_PRODUCTION_URL` (the sub-project custom domain)
+ *    so sitemaps always point to the correct public URL.
+ * 4. `VERCEL_URL` present — Vercel preview/branch deployment; uses the auto-generated
+ *    `https://` preview URL.
+ * 5. Fallback — `config.baseURL` from the project's `config.yml`.
+ *
+ * @param config - Site configuration providing the `baseURL` fallback.
+ */
+export function getSiteUrl(config: SiteConfig): string {
+  if (process.env.SITE_URL) {
+    return process.env.SITE_URL
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    const { host, port } = getDevHost()
+    return `http://${host}:${port}`
+  }
+
+  if (process.env.VERCEL_ENV === 'production') {
+    return config.baseURL || `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+  }
+
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`
+  }
+
+  return config.baseURL
+}

package/src/libs/toc.ts

@@ -1,8 +1,28 @@
 import type { MarkdownHeading } from 'astro'
-// import { getConfig } from './config'
 
-// Generate a tree like structure from a list of headings.
-export function generateToc(allHeadings: MarkdownHeading[], config: any) {
+/**
+ * Minimum configuration shape required by `generateToc`.
+ * The consuming project's full config object satisfies this interface as long as
+ * it contains a `toc` section with `min` and `max` depth values.
+ */
+export interface TocConfig {
+  toc: {
+    /** Minimum heading depth to include (e.g. `2` to start at `<h2>`). */
+    min: number
+    /** Maximum heading depth to include (e.g. `4` to stop at `<h4>`). */
+    max: number
+  }
+}
+
+/**
+ * Generates a nested tree of TOC entries from a flat list of Markdown headings.
+ *
+ * Headings outside the depth range defined in `config.toc` are excluded. When
+ * a heading skips one or more levels (e.g. an `<h4>` follows an `<h2>` with no
+ * `<h3>` in between) it is attached to the deepest available parent rather than
+ * being silently dropped.
+ */
+export function generateToc(allHeadings: MarkdownHeading[], config: TocConfig): TocEntry[] {
   const headings = allHeadings.filter(
     (heading) => heading.depth >= config.toc.min && heading.depth <= config.toc.max
   )
@@ -29,14 +49,28 @@ export function generateToc(allHeadings: MarkdownHeading[], config: any) {
   return toc
 }
 
+/**
+ * Walks down the TOC tree to find the children array at the given relative
+ * `depth` below `entry`. If an intermediate level is missing (skipped heading),
+ * falls back to the deepest available children array so the heading is not lost.
+ */
 function getEntryChildrenAtDepth(entry: TocEntry, depth: number): TocEntry['children'] {
   if (!entry) {
     return []
   }
 
-  return depth === 1
-    ? entry.children
-    : getEntryChildrenAtDepth(entry.children[entry.children.length - 1], depth - 1)
+  if (depth === 1) {
+    return entry.children
+  }
+
+  const lastChild = entry.children[entry.children.length - 1]
+
+  if (!lastChild) {
+    // Heading skipped a level — attach to the current entry's children instead.
+    return entry.children
+  }
+
+  return getEntryChildrenAtDepth(lastChild, depth - 1)
 }
 
 export interface TocEntry extends MarkdownHeading {