@chassis-ui/docs 0.5.0 → 0.6.0-next.0

package/src/libs/config.ts

@@ -0,0 +1,138 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { load } from 'js-yaml'
+import { z } from 'astro/zod'
+import {
+  configSchema,
+  removedConfigKeys,
+  renamedConfigKeys,
+  sidebarSchema,
+  type ChassisConfig,
+  type Sidebar
+} from './schema'
+
+export interface LoadConfigOptions<TSchema extends z.ZodType = typeof configSchema> {
+  /**
+   * Path of the config file. A relative path is resolved from `root`.
+   * @default 'config.yml'
+   */
+  file?: string
+  /**
+   * The site's root: the directory that holds `astro.config.ts`.
+   * @default process.cwd()
+   */
+  root?: string
+  /** `configSchema`, or an extension of it when the site has keys of its own. */
+  schema?: TSchema
+}
+
+function getValueAtPath(record: unknown, keyPath: string): unknown {
+  return keyPath.split('.').reduce<unknown>((value, part) => {
+    return value && typeof value === 'object' ? (value as Record<string, unknown>)[part] : undefined
+  }, record)
+}
+
+function formatIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => `  - ${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+    .join('\n')
+}
+
+// The schema is strict, so an old key would fail as "unrecognized key". These messages say
+// what to do about it.
+function findOutdatedKeys(raw: unknown): string[] {
+  const messages: string[] = []
+
+  for (const [oldKey, newKey] of Object.entries(renamedConfigKeys)) {
+    if (getValueAtPath(raw, oldKey) !== undefined) {
+      messages.push(`  - \`${oldKey}\` was renamed to \`${newKey}\`.`)
+    }
+  }
+
+  for (const [oldKey, reason] of Object.entries(removedConfigKeys)) {
+    if (getValueAtPath(raw, oldKey) !== undefined) {
+      messages.push(`  - \`${oldKey}\` was removed. ${reason}`)
+    }
+  }
+
+  return messages
+}
+
+function readYaml(file: string): unknown {
+  try {
+    return load(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`Failed to read \`${file}\`.`, { cause: error })
+  }
+}
+
+/**
+ * Reads and validates the site's `config.yml`.
+ *
+ * For code that runs while Astro loads its configuration, such as `astro.config.ts` and a
+ * site's own integrations. Pages and components read the config with `getConfig()` from
+ * `@chassis-ui/docs/site`.
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * const config = loadConfig({ root: import.meta.dirname, schema: siteConfigSchema })
+ * ```
+ */
+export function loadConfig<TSchema extends z.ZodType = typeof configSchema>(
+  options: LoadConfigOptions<TSchema> = {}
+): z.infer<TSchema> {
+  const { file = 'config.yml', root = process.cwd(), schema = configSchema } = options
+  const configPath = path.resolve(root, file)
+  const raw = readYaml(configPath)
+
+  const outdatedKeys = findOutdatedKeys(raw)
+
+  if (outdatedKeys.length > 0) {
+    throw new Error(
+      `\`${configPath}\` has keys from before @chassis-ui/docs 0.6.0:\n${outdatedKeys.join('\n')}`
+    )
+  }
+
+  const result = schema.safeParse(raw)
+
+  if (!result.success) {
+    throw new Error(`\`${configPath}\` is invalid:\n${formatIssues(result.error)}`)
+  }
+
+  return result.data as z.infer<TSchema>
+}
+
+export interface LoadDataOptions<TSchema extends z.ZodType> {
+  /** Path of the data file. A relative path is resolved from `root`. */
+  file: string
+  /** @default process.cwd() */
+  root?: string
+  schema: TSchema
+}
+
+/** Reads and validates a YAML data file. */
+export function loadData<TSchema extends z.ZodType>(
+  options: LoadDataOptions<TSchema>
+): z.infer<TSchema> {
+  const { file, root = process.cwd(), schema } = options
+  const dataPath = path.resolve(root, file)
+  const result = schema.safeParse(readYaml(dataPath))
+
+  if (!result.success) {
+    throw new Error(`\`${dataPath}\` is invalid:\n${formatIssues(result.error)}`)
+  }
+
+  return result.data as z.infer<TSchema>
+}
+
+/** Reads and validates the site's `data/sidebar.yml`. */
+export function loadSidebar(options: { file?: string; root?: string } = {}): Sidebar {
+  return loadData({
+    file: options.file ?? 'data/sidebar.yml',
+    root: options.root,
+    schema: sidebarSchema
+  })
+}
+
+export type { ChassisConfig, Sidebar }

package/src/libs/docs-path.ts

@@ -0,0 +1,12 @@
+/**
+ * URL path of a docs page.
+ *
+ * @param docsPath The `docsPath` of the site's `config.yml`, e.g. `"/css/docs"`.
+ * @param inputPath Path of the page inside the docs, e.g. `"/components/button/"`.
+ */
+export function joinDocsPath(docsPath: string, inputPath: string): string {
+  const base = docsPath.replace(/\/+$/, '')
+  const page = inputPath.replace(/^\/+/, '')
+
+  return page ? `${base}/${page}` : base
+}

package/src/libs/highlight.ts

@@ -14,32 +14,6 @@ const classTransformer: ShikiTransformer = {
   }
 }
 
-/**
- * Shiki transformer that wraps non-comment lines in a `<span class="line">`
- * element. Applied only to shell languages (bash, sh, powershell) where line
- * wrapping is needed for the copy-button to correctly extract individual commands.
- */
-const lineWrapperTransformer: ShikiTransformer = {
-  name: 'line-wrapper',
-  line(node) {
-    const hasOnlyComments = node.children.every(
-      (child) =>
-        child.type === 'element' &&
-        child.properties?.class &&
-        Array.isArray(child.properties.class) &&
-        child.properties.class.some((cls) => typeof cls === 'string' && cls.includes('comment'))
-    )
-
-    if (!hasOnlyComments) {
-      node.properties = node.properties || {}
-      const existing = node.properties.class ?? ''
-      const classes = typeof existing === 'string' ? existing.split(' ') : []
-      if (!classes.includes('line')) classes.push('line')
-      node.properties.class = classes.join(' ').trim()
-    }
-  }
-}
-
 /**
  * Replaces any remaining `shiki` / `shiki-themes` class strings in the
  * serialized HTML that the transformer may have missed (e.g. in inline styles
@@ -53,38 +27,24 @@ function replaceShikiClasses(html: string): string {
 }
 
 /**
- * Highlights a code string using Shiki with the GitHub light/dark dual theme.
- *
- * Inline styles are converted to CSS classes via `transformerStyleToClass` so
- * that a single `<style>` block can be emitted per page rather than repeating
- * styles on every token. The returned `css` string must be injected into the
- * page (e.g. inside a `<style>` tag) for the highlighted output to render correctly.
- *
- * For shell languages (`bash`, `sh`, `powershell`) each non-comment line is
- * additionally wrapped in `<span class="line">` to support per-line copy.
+ * Highlights a code string using Shiki with the GitHub light/dark dual theme. Shiki wraps
+ * each line in a `<span class="line">`.
  *
  * @param code - Source code to highlight.
  * @param lang - Shiki language identifier (e.g. `"html"`, `"ts"`, `"bash"`).
  * @param extraTransformers - Additional Shiki transformers to apply before the built-ins.
- * @returns An object with `html` (the highlighted markup) and `css` (the extracted styles).
+ * @returns An object with `html`, the highlighted markup.
  */
 export async function highlightCode(
   code: string,
   lang: string,
   extraTransformers: ShikiTransformer[] = []
 ): Promise<{ html: string }> {
-  const shouldWrapLines = ['bash', 'sh', 'powershell'].includes(lang)
-
-  const transformers: ShikiTransformer[] = [...extraTransformers, classTransformer]
-  if (shouldWrapLines) {
-    transformers.push(lineWrapperTransformer)
-  }
-
   const highlighted = await codeToHtml(code, {
     lang,
     themes: DOCS_SHIKI_THEMES,
     defaultColor: false,
-    transformers
+    transformers: [...extraTransformers, classTransformer]
   })
 
   return { html: replaceShikiClasses(highlighted) }

package/src/libs/paths.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Public paths of the package and the directories behind them. They match `exports` in
+// `package.json`.
+const publicDirectories: Record<string, string> = {
+  components: 'src/components',
+  js: 'src/js',
+  layouts: 'src/layouts',
+  scss: 'src/scss',
+  shortcodes: 'src/components/shortcodes'
+}
+
+/**
+ * Absolute path of the package on disk.
+ *
+ * Only correct in code that runs while Astro loads its configuration. Pages and components
+ * are bundled, so they use `getPackageFilePath()` from `@chassis-ui/docs/site`.
+ */
+export function getPackageRoot(): string {
+  return fileURLToPath(new URL('../../', import.meta.url))
+}
+
+/**
+ * Absolute path of a file of the package, named by its public path.
+ *
+ * @param file Path as it is imported, without the package name, e.g. `"js/color-modes.js"`
+ * or `"shortcodes/Code.astro"`.
+ * @param packageRoot Absolute path of the package.
+ */
+export function resolvePackageFilePath(file: string, packageRoot = getPackageRoot()): string {
+  const [directory, ...rest] = file.split('/')
+  const target = publicDirectories[directory]
+
+  if (!target) {
+    throw new Error(
+      `'${file}' is not a public path of @chassis-ui/docs. Expected a path that starts with one of: ${Object.keys(publicDirectories).join(', ')}.`
+    )
+  }
+
+  return path.join(packageRoot, target, ...rest)
+}
+
+// The repository root is the nearest ancestor with a `.git` entry or a pnpm workspace file.
+function getSearchDirectories(root: string): string[] {
+  const directories: string[] = []
+  let current = path.resolve(root)
+
+  while (true) {
+    directories.push(current)
+
+    const isRepositoryRoot =
+      fs.existsSync(path.join(current, '.git')) ||
+      fs.existsSync(path.join(current, 'pnpm-workspace.yaml'))
+    const parent = path.dirname(current)
+
+    if (isRepositoryRoot || parent === current) {
+      return directories
+    }
+
+    current = parent
+  }
+}
+
+/**
+ * Every `node_modules` directory between the site's root and the root of the repository,
+ * nearest first. For tools that resolve package names without Vite, such as the Sass API.
+ */
+export function getNodeModulesFsPaths(root = process.cwd()): string[] {
+  return getSearchDirectories(root)
+    .map((directory) => path.join(directory, 'node_modules'))
+    .filter((directory) => fs.existsSync(directory))
+}
+
+function findUp(root: string, candidates: string[], description: string): string {
+  const searched = getSearchDirectories(root)
+
+  for (const directory of searched) {
+    for (const candidate of candidates) {
+      const candidatePath = path.join(directory, candidate)
+
+      if (fs.existsSync(candidatePath)) {
+        return candidatePath
+      }
+    }
+  }
+
+  throw new Error(
+    `Could not find ${description}. Looked for ${candidates.map((c) => `'${c}'`).join(' or ')} in:\n${searched.map((d) => `  - ${d}`).join('\n')}`
+  )
+}
+
+export interface ChassisPathOptions {
+  /**
+   * The site's root. The search starts here and stops at the root of the repository.
+   * @default process.cwd()
+   */
+  root?: string
+  /**
+   * The directory to use, when it is not where the search would find it. A relative path is
+   * resolved from `root`.
+   */
+  dir?: string
+}
+
+function resolveDir({ root = process.cwd(), dir }: ChassisPathOptions): string | undefined {
+  return dir ? path.resolve(root, dir) : undefined
+}
+
+/**
+ * Directory of an installed package. Finds the package whether `node_modules` is in the
+ * site's root or hoisted to the root of the repository.
+ */
+export function getInstalledPackageFsPath(name: string, root = process.cwd()): string {
+  return findUp(root, [path.join('node_modules', name)], `the package '${name}'`)
+}
+
+/**
+ * The docs build of `@chassis-ui/tokens`. The folder moved from `dist/tokens/web/docs` to
+ * `dist/web/docs` between releases of the tokens package, and both are found.
+ */
+export function getChassisTokensFsPath(options: ChassisPathOptions = {}): string {
+  const tokens =
+    resolveDir(options) ?? getInstalledPackageFsPath('@chassis-ui/tokens', options.root)
+
+  return findUp(
+    tokens,
+    ['dist/web/docs/chassis', 'dist/tokens/web/docs/chassis'],
+    'the docs build of @chassis-ui/tokens'
+  )
+}
+
+/**
+ * The docs build of `chassis-assets`: in the `vendor/assets` submodule, or in `dist` for the
+ * site of `chassis-assets` itself.
+ */
+export function getChassisAssetsFsPath(options: ChassisPathOptions = {}): string {
+  return (
+    resolveDir(options) ??
+    findUp(
+      options.root ?? process.cwd(),
+      ['vendor/assets/dist/web/docs/chassis', 'dist/web/docs/chassis'],
+      'the docs build of chassis-assets'
+    )
+  )
+}
+
+/** The `dist` folder of `@chassis-ui/css`. */
+export function getChassisCSSFsPath(options: ChassisPathOptions = {}): string {
+  return (
+    resolveDir(options) ??
+    path.join(getInstalledPackageFsPath('@chassis-ui/css', options.root), 'dist')
+  )
+}
+
+/** The folder of `@chassis-ui/icons`. */
+export function getChassisIconsFsPath(options: ChassisPathOptions = {}): string {
+  return resolveDir(options) ?? getInstalledPackageFsPath('@chassis-ui/icons', options.root)
+}

package/src/libs/remark.ts

@@ -0,0 +1,184 @@
+import type { Root } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from 'mdast-util-mdx-jsx'
+import type { Plugin } from 'unified'
+import { visit } from 'unist-util-visit'
+import { joinDocsPath } from './docs-path'
+
+// [[config:foo]]
+// [[config:foo.bar]]
+const configRegExp = /\[\[config:(?<name>[\w.]+)\]\]/g
+// [[docsref:/foo]]
+// [[docsref:/foo/bar#baz]]
+const docsrefRegExp = /\[\[docsref:(?<path>[\w./#-]+)\]\]/g
+
+type Replacer = (_text: string) => string
+type MdxAttributes = (MdxJsxAttribute | MdxJsxExpressionAttribute)[]
+
+export interface RemarkCxConfigOptions {
+  /** The parsed `config.yml`. */
+  config: object
+}
+
+export interface RemarkCxDocsrefOptions {
+  /** The `docsPath` of the site's `config.yml`. */
+  docsPath: string
+  /** Called with each docs path that a page links to. */
+  onDocsPath?: (_path: string) => void
+}
+
+/** Replaces each `[[config:key]]` in `text` with the value of that key. */
+export function replaceConfigInText(text: string, config: object): string {
+  return text.replace(configRegExp, (_match, keyPath: string) => {
+    const value = keyPath.split('.').reduce<unknown>((values, part) => {
+      return values && typeof values === 'object'
+        ? (values as Record<string, unknown>)[part]
+        : undefined
+    }, config)
+
+    if (typeof value !== 'string' || !value) {
+      throw new Error(`Failed to find a valid configuration value for '${keyPath}'.`)
+    }
+
+    return value
+  })
+}
+
+/** Replaces each `[[docsref:/path]]` in `text` with the URL path of that docs page. */
+export function replaceDocsrefInText(text: string, options: RemarkCxDocsrefOptions): string {
+  return text.replace(docsrefRegExp, (_match, inputPath: string) => {
+    options.onDocsPath?.(inputPath)
+
+    return joinDocsPath(options.docsPath, inputPath)
+  })
+}
+
+function replaceInAttributes(attributes: MdxAttributes, replacer: Replacer) {
+  return attributes.map((attribute) => {
+    if (attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string') {
+      attribute.value = replacer(attribute.value)
+    }
+
+    return attribute
+  })
+}
+
+function replaceInFrontmatter(record: Record<string, unknown>, replacer: Replacer) {
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === 'string') {
+      record[key] = replacer(value)
+    } else if (Array.isArray(value)) {
+      record[key] = value.map((arrayValue) => {
+        return typeof arrayValue === 'string'
+          ? replacer(arrayValue)
+          : typeof arrayValue === 'object'
+            ? replaceInFrontmatter(arrayValue, replacer)
+            : arrayValue
+      })
+    }
+  }
+
+  return record
+}
+
+function containsFrontmatter(data: unknown): data is { frontmatter: Record<string, unknown> } {
+  return data != undefined && typeof data === 'object' && 'frontmatter' in data
+}
+
+/**
+ * A remark plugin that replaces config values in Markdown and MDX files. `[[config:foo]]`
+ * becomes the value of the `foo` key of `config.yml`, and `[[config:foo.bar]]` reads a nested
+ * key. It also works in frontmatter.
+ */
+export const remarkCxConfig: Plugin<[RemarkCxConfigOptions], Root> = function ({ config }) {
+  const replacer: Replacer = (text) => replaceConfigInText(text, config)
+
+  return function remarkCxConfigPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replacer)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      ['code', 'definition', 'image', 'inlineCode', 'link', 'mdxJsxFlowElement', 'text'],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replacer(node.value)
+            break
+          }
+          case 'image': {
+            if (node.alt) {
+              node.alt = replacer(node.alt)
+            }
+
+            node.url = replacer(node.url)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replacer(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement': {
+            node.attributes = replaceInAttributes(node.attributes, replacer)
+            break
+          }
+        }
+      }
+    )
+  }
+}
+
+/**
+ * A remark plugin that turns `[[docsref:/foo]]` into a link to the docs page `/foo`, under
+ * the `docsPath` of `config.yml`. It also works in frontmatter.
+ */
+export const remarkCxDocsref: Plugin<[RemarkCxDocsrefOptions], Root> = function (options) {
+  const replacer: Replacer = (text) => replaceDocsrefInText(text, options)
+
+  return function remarkCxDocsrefPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replacer)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      [
+        'code',
+        'definition',
+        'image',
+        'inlineCode',
+        'link',
+        'mdxJsxFlowElement',
+        'mdxJsxTextElement',
+        'text'
+      ],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replacer(node.value)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replacer(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement':
+          case 'mdxJsxTextElement': {
+            node.attributes = replaceInAttributes(node.attributes, replacer)
+            break
+          }
+        }
+      }
+    )
+  }
+}