@chassis-ui/docs 0.5.1 → 0.6.0

package/src/layouts/BaseLayout.astro

@@ -5,9 +5,9 @@
  * Main layout wrapper for all pages with configurable HTML attributes and layout modes.
  */
 
-import type { CollectionEntry } from 'astro:content'
-import { getConfig } from '@libs/config'
 import type { Layout, LayoutOverridesHTMLAttributes } from '../libs/layout'
+import type { DocsFrontmatter } from '../libs/schema'
+import { getConfig } from '../site'
 import Head from './head/Head.astro'
 import Header from './header/Header.astro'
 import Scripts from './footer/Scripts.astro'
@@ -42,11 +42,11 @@ type Props = {
 // The following props are automatically set by Astro (if defined) based on the markdown frontmatter when rendering a
 // markdown page. They can be accessed through the `Astro.props.frontmatter` object but note that they won't be set when
 // not rendering a markdown page.
-type MarkdownProps = { frontmatter?: Partial<CollectionEntry<'docs'>['data']> }
+type MarkdownProps = { frontmatter?: DocsFrontmatter }
 
-// This type is used to define the shape of the `extra_js` frontmatter property which allows adding extra JavaScript
+// This type is used to define the shape of the `extraJs` frontmatter property which allows adding extra JavaScript
 // files to a page by passing an array of objects containing the `src` and `async` properties.
-type ExtraJS = NonNullable<CollectionEntry<'docs'>['data']['extra_js']>[number]
+type ExtraJS = NonNullable<DocsFrontmatter['extraJs']>[number]
 
 const { frontmatter, layout, overrides, robots } = Astro.props
 
@@ -96,10 +96,8 @@ const mainProps = overrides?.main ?? {}
     </Scripts>
 
     {
-      frontmatter?.extra_js &&
-        frontmatter.extra_js.map((js: ExtraJS) => (
-          <script is:inline async={js.async} src={js.src} />
-        ))
+      frontmatter?.extraJs &&
+        frontmatter.extraJs.map((js: ExtraJS) => <script is:inline async={js.async} src={js.src} />)
     }
 
     {

package/src/layouts/DocsLayout.astro

@@ -6,13 +6,10 @@
  */
 
 import type { MarkdownHeading } from 'astro'
-import type { CollectionEntry } from 'astro:content'
-import { getConfig } from '@libs/config'
-import { docsPages } from '@libs/content'
-import { getChassisDocsPath } from '@libs/path'
 import type { LayoutOverridesHTMLAttributes } from '../libs/layout'
-import { getSiteFileUrl } from '../libs/source'
+import type { DocsFrontmatter } from '../libs/schema'
 import { getSlug, processMarkdownToHtml } from '../libs/utils'
+import { getConfig, getDocsPages, getDocsPath, getSiteFileUrl } from '../site'
 import BaseLayout from './BaseLayout.astro'
 import DocsSidebar from '../components/DocsSidebar.astro'
 import TableOfContents from '../components/TableOfContents.astro'
@@ -20,11 +17,11 @@ import Icon from '../components/shortcodes/Icon.astro'
 
 interface Props {
   /** Frontmatter data from the docs collection */
-  frontmatter: CollectionEntry<'docs'>['data']
+  frontmatter: DocsFrontmatter
   /** Markdown headings for table of contents */
   headings?: MarkdownHeading[]
   /** Document ID from the docs collection */
-  id: CollectionEntry<'docs'>['id']
+  id: string
   /**
    * Path of the page's source file from the site's root. Looked up from the docs collection
    * by `id` when omitted.
@@ -36,7 +33,8 @@ const { frontmatter, headings, id } = Astro.props
 
 // "View on GitHub" links to the page's own source file. The old link, which assumed the
 // file sat at `<id>.mdx` in the repository root, is kept only when no file path is known.
-const filePath = Astro.props.filePath ?? docsPages.find((page) => page.id === id)?.filePath
+const filePath =
+  Astro.props.filePath ?? (await getDocsPages()).find((page) => page.id === id)?.filePath
 const githubUrl = filePath ? getSiteFileUrl(filePath) : `${getConfig().repo}/blob/${id}.mdx`
 
 type DocSection = NonNullable<typeof frontmatter.sections>[number]
@@ -86,11 +84,11 @@ if (frontmatter.toc) {
           <div class="md:d-flex md:flex-row-reverse justify-content-between align-items-start">
             <div class="mb-md md:mb-0 d-flex text-nowrap">
               {
-                // This is needed because we want to show the badge if show_badge isn't present or is set to false
+                // This is needed because we want to show the badge if showBadge isn't present or is set to false
                 frontmatter.added &&
-                  ((frontmatter.added.show_badge !== undefined &&
-                    frontmatter.added.show_badge === true) ||
-                    frontmatter.added.show_badge === undefined) && (
+                  ((frontmatter.added.showBadge !== undefined &&
+                    frontmatter.added.showBadge === true) ||
+                    frontmatter.added.showBadge === undefined) && (
                     <span class="badge success smooth rounded-md me-xs">
                       Added in v{frontmatter.added.version}
                     </span>
@@ -153,7 +151,7 @@ if (frontmatter.toc) {
                 <div class="md:col-6">
                   <a
                     class="d-block text-decoration-none"
-                    href={getChassisDocsPath(
+                    href={getDocsPath(
                       `${parentDirectory ? parentDirectory + '/' : ''}${section.slug ? section.slug : getSlug(section.title)}/`
                     )}
                   >

package/src/layouts/RedirectLayout.astro

@@ -5,7 +5,7 @@
  * Minimal layout for redirect pages with meta refresh.
  */
 
-import { getConfig } from '@libs/config'
+import { getConfig } from '../site'
 
 interface Props {
   /** Destination path for the redirect */

package/src/layouts/head/Analytics.astro

@@ -2,16 +2,18 @@
 /**
  * Analytics
  *
- * Analytics script tags for Fathom and Google Analytics.
+ * Google Analytics script tags. Rendered in production builds, when `analytics.googleId` is
+ * set in `config.yml`.
  */
 
-import { getConfig } from '@libs/config'
+import { getConfig } from '../../site'
+
 const isProd = import.meta.env.PROD
-const googleId = getConfig().analytics.google_id
+const { googleId } = getConfig().analytics
 ---
 
 {
-  isProd && (
+  isProd && googleId && (
     <>
       <script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleId}`} />
       <script

package/src/layouts/head/Head.astro

@@ -5,13 +5,13 @@
  * HTML head section with meta tags, stylesheets, and SEO configuration.
  */
 
-import { getConfig } from '@libs/config'
+import { getConfig } from '../../site'
 import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
 import Favicons from './Favicons.astro'
 import Social from './Social.astro'
 import Analytics from './Analytics.astro'
-import '@scss/docs.scss'
+import 'virtual:chassis-docs/styles'
 
 interface Props {
   /** Page description for meta tags */

package/src/layouts/head/Social.astro

@@ -5,11 +5,9 @@
  * Social media meta tags (Open Graph, Twitter Cards).
  */
 
-import path from 'node:path'
-import { getConfig } from '@libs/config'
-import { getDocsPublicFsPath } from '@libs/path'
 import { getRemoteImageSize, getStaticImageSize } from '../../libs/image'
 import type { Layout } from '../../libs/layout'
+import { getConfig, getPublicFsPath } from '../../site'
 
 interface Props {
   /** Page description */
@@ -28,12 +26,13 @@ const socialImageUrl = new URL(thumbnail, Astro.site)
 const isRemoteThumbnail = /^https?:\/\//i.test(thumbnail)
 const socialImageSize = isRemoteThumbnail
   ? await getRemoteImageSize(thumbnail)
-  : await getStaticImageSize(path.join(getDocsPublicFsPath(), thumbnail))
+  : await getStaticImageSize(getPublicFsPath(thumbnail))
+const { xUsername } = getConfig()
 ---
 
 <meta name="twitter:card" content="summary_lg_image" />
-<meta name="twitter:site" content=`@${getConfig().x_username}` />
-<meta name="twitter:creator" content=`@${getConfig().x_username}` />
+{xUsername && <meta name="twitter:site" content={`@${xUsername}`} />}
+{xUsername && <meta name="twitter:creator" content={`@${xUsername}`} />}
 <meta name="twitter:title" content={title} />
 <meta name="twitter:description" content={description} />
 <meta name="twitter:image" content={socialImageUrl} />

package/src/layouts/header/Navigation.astro

@@ -5,8 +5,8 @@
  * Main site navigation bar with menu items and theme toggler.
  */
 
-import { getConfig } from '@libs/config'
 import type { Layout } from '../../libs/layout'
+import { getConfig } from '../../site'
 import NavLink from '../../components/NavLink.astro'
 import ThemeToggler from '../../components/ThemeToggler.astro'
 import SearchTrigger from './SearchTrigger.astro'
@@ -19,6 +19,7 @@ interface Props {
 }
 
 const { layout } = Astro.props
+const { figmaHandle, githubOrg } = getConfig()
 const { pathname } = Astro.url
 const isActive = (path: string) => {
   if (path === '/') {
@@ -106,24 +107,32 @@ const isActive = (path: string) => {
         <hr class="lg:d-none m-0" />
 
         <ul class="navbar-nav flex-row flex-wrap lg:ms-auto align-items-center">
-          <NavLink
-            class="px-0 lg:px-xs"
-            href={`https://figma.com/@${getConfig().figma_handle}`}
-            target="_blank"
-            rel="noopener"
-          >
-            <Icon name="figma-brand" title="Figma" />
-            <small class="lg:d-none ms-xs">Figma Community</small>
-          </NavLink>
-          <NavLink
-            class="px-0 lg:px-xs"
-            href={`https://github.com/${getConfig().github_org}`}
-            target="_blank"
-            rel="noopener"
-          >
-            <Icon name="github-brand" title="GitHub" />
-            <small class="lg:d-none ms-xs">GitHub</small>
-          </NavLink>
+          {
+            figmaHandle && (
+              <NavLink
+                class="px-0 lg:px-xs"
+                href={`https://figma.com/@${figmaHandle}`}
+                target="_blank"
+                rel="noopener"
+              >
+                <Icon name="figma-brand" title="Figma" />
+                <small class="lg:d-none ms-xs">Figma Community</small>
+              </NavLink>
+            )
+          }
+          {
+            githubOrg && (
+              <NavLink
+                class="px-0 lg:px-xs"
+                href={`https://github.com/${githubOrg}`}
+                target="_blank"
+                rel="noopener"
+              >
+                <Icon name="github-brand" title="GitHub" />
+                <small class="lg:d-none ms-xs">GitHub</small>
+              </NavLink>
+            )
+          }
           <li class="nav-item col-12 lg:col-auto">
             <div class="vr d-none lg:d-flex h-100 lg:mx-2xs"></div>
             <hr class="lg:d-none" />

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