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

package/src/integration.ts

@@ -0,0 +1,271 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { AstroIntegration, AstroUserConfig, ViteUserConfig } from 'astro'
+import type { z } from 'astro/zod'
+import { loadConfig, loadSidebar } from './libs/config'
+import { joinDocsPath } from './libs/docs-path'
+import { getDocsMarkdownConfig, type DocsMarkdownConfigOptions } from './libs/markdown'
+import { getInstalledPackageFsPath, getPackageRoot } from './libs/paths'
+import { remarkCxConfig, remarkCxDocsref } from './libs/remark'
+import { configSchema, type ChassisConfig, type Sidebar } from './libs/schema'
+import { chassisAutoImport, type ChassisAutoImportOptions } from './libs/shortcodes'
+import { getSiteUrl } from './libs/site'
+
+export interface ChassisDocsOptions<TSchema extends z.ZodType = typeof configSchema> {
+  /**
+   * The config, for a site that has loaded it with `loadConfig()` to use it in
+   * `astro.config.ts`. `configFile` is then only watched, and `configSchema` is not used.
+   */
+  config?: ChassisConfig
+  /**
+   * Path of the config file, from the site's root.
+   * @default 'config.yml'
+   */
+  configFile?: string
+  /**
+   * Schema of the config file: `configSchema` from `@chassis-ui/docs/schema`, or an
+   * extension of it when the site has keys of its own.
+   */
+  configSchema?: TSchema
+  /**
+   * Path of the sidebar data file, from the site's root. `false` for a site that does not
+   * render `<DocsSidebar>`.
+   * @default 'data/sidebar.yml' when the file exists
+   */
+  sidebarFile?: string | false
+  /**
+   * Stylesheets that every page loads, from the site's root. A site's stylesheet is expected
+   * to `@use "@chassis-ui/docs/scss/main"`.
+   * @default ['src/scss/docs.scss'] when the file exists, the package's styles otherwise
+   */
+  styles?: string[]
+  /** Which shortcodes are imported into every MDX file. */
+  shortcodes?: Pick<ChassisAutoImportOptions, 'dir' | 'include' | 'exclude'>
+  /** Plugins of the site. They run after the plugins of the package. */
+  markdown?: Pick<DocsMarkdownConfigOptions, 'rehypePlugins' | 'remarkPlugins' | 'remarkRehype'>
+  /**
+   * What happens when a `[[docsref:]]` link points to a page that was not built.
+   * @default 'error'
+   */
+  brokenDocsrefs?: 'error' | 'warn' | 'ignore'
+}
+
+type VitePlugin = Extract<NonNullable<ViteUserConfig['plugins']>[number], { name: string }>
+
+const virtualPrefix = 'virtual:chassis-docs/'
+const resolvedPrefix = '\0' + virtualPrefix
+
+function virtualModules(modules: Record<string, string>): VitePlugin {
+  return {
+    name: 'chassis-docs:virtual',
+    resolveId(id) {
+      if (id.startsWith(virtualPrefix) && id.slice(virtualPrefix.length) in modules) {
+        return '\0' + id
+      }
+    },
+    load(id) {
+      if (id.startsWith(resolvedPrefix)) {
+        return modules[id.slice(resolvedPrefix.length)]
+      }
+    }
+  }
+}
+
+// The declarations of `virtual.d.ts`, for a site.
+const virtualTypes = `declare module 'virtual:chassis-docs/config' {
+  const config: import('@chassis-ui/docs/schema').ChassisConfig
+  export default config
+}
+
+declare module 'virtual:chassis-docs/sidebar' {
+  const sidebar: import('@chassis-ui/docs/schema').Sidebar
+  export default sidebar
+}
+
+declare module 'virtual:chassis-docs/paths' {
+  export const root: string
+  export const publicDir: string
+  export const sourceDir: string
+  export const packageRoot: string
+}
+
+declare module 'virtual:chassis-docs/styles' {}
+`
+
+// The folder of `@chassis-ui/css` with its default `_chassis-tokens.scss`, when the site has
+// the package installed.
+function getDefaultTokensLoadPath(root: string): string | undefined {
+  try {
+    return path.join(getInstalledPackageFsPath('@chassis-ui/css', root), 'scss/vendor')
+  } catch {
+    return undefined
+  }
+}
+
+// Append `index.html` when the path names a page, and drop the hash.
+function toBuiltFilePath(docsPath: string): string {
+  const withoutHash = docsPath.split('#')[0]
+
+  return withoutHash.includes('.') ? withoutHash : path.join(withoutHash, 'index.html')
+}
+
+/**
+ * The Astro integration of `@chassis-ui/docs`. A site adds it in `astro.config.ts`.
+ *
+ * It reads `config.yml` and `data/sidebar.yml`, gives them to the layouts and components of
+ * the package, sets `site` and `markdown` of the Astro config, and imports the shortcodes
+ * into every MDX file.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'astro/config'
+ * import { chassisDocs } from '@chassis-ui/docs/integration'
+ *
+ * export default defineConfig({
+ *   integrations: [chassisDocs()]
+ * })
+ * ```
+ */
+export function chassisDocs<TSchema extends z.ZodType = typeof configSchema>(
+  options: ChassisDocsOptions<TSchema> = {}
+): AstroIntegration {
+  const { brokenDocsrefs = 'error' } = options
+
+  // Docs paths that `[[docsref:]]` links name, collected while the pages are rendered.
+  const linkedDocsPaths = new Set<string>()
+  let config: ChassisConfig
+  let typeDefinitions = ''
+
+  return {
+    name: '@chassis-ui/docs',
+    hooks: {
+      'astro:config:setup': ({ config: astroConfig, command, updateConfig, addWatchFile }) => {
+        const root = path.resolve(fileURLToPath(astroConfig.root))
+        const configFile = path.resolve(root, options.configFile ?? 'config.yml')
+
+        config =
+          options.config ??
+          loadConfig({
+            file: configFile,
+            schema: (options.configSchema ?? configSchema) as z.ZodType<ChassisConfig>
+          })
+        addWatchFile(configFile)
+
+        let sidebar: Sidebar = []
+
+        if (options.sidebarFile !== false) {
+          const sidebarFile = path.resolve(root, options.sidebarFile ?? 'data/sidebar.yml')
+
+          // The default file is optional. A file that the site names must exist.
+          if (options.sidebarFile !== undefined || fs.existsSync(sidebarFile)) {
+            sidebar = loadSidebar({ file: sidebarFile })
+            addWatchFile(sidebarFile)
+          }
+        }
+
+        const defaultStyles = path.join(root, 'src/scss/docs.scss')
+        const styles = options.styles
+          ? options.styles.map((file) => path.resolve(root, file))
+          : fs.existsSync(defaultStyles)
+            ? [defaultStyles]
+            : ['@chassis-ui/docs/scss/main.scss']
+
+        const autoImport = chassisAutoImport({ root, ...options.shortcodes })
+        typeDefinitions = autoImport.typeDefinitions
+
+        const paths = {
+          root,
+          publicDir: path.resolve(fileURLToPath(astroConfig.publicDir)),
+          sourceDir: path.resolve(root, config.sourceDir),
+          packageRoot: getPackageRoot()
+        }
+
+        const tokensLoadPath = getDefaultTokensLoadPath(root)
+
+        const update: AstroUserConfig = {
+          // A `site` that the Astro config sets itself is kept.
+          ...(astroConfig.site ? {} : { site: getSiteUrl(config) }),
+          markdown: getDocsMarkdownConfig({
+            anchors: config.anchors,
+            remarkPlugins: [
+              autoImport.plugin(),
+              [remarkCxConfig, { config }],
+              [
+                remarkCxDocsref,
+                {
+                  docsPath: config.docsPath,
+                  onDocsPath:
+                    command === 'build'
+                      ? (docsPath: string) => linkedDocsPaths.add(docsPath)
+                      : undefined
+                }
+              ],
+              ...(options.markdown?.remarkPlugins ?? [])
+            ],
+            rehypePlugins: options.markdown?.rehypePlugins,
+            remarkRehype: options.markdown?.remarkRehype
+          }),
+          vite: {
+            // Scripts of the package and of the site both import `@chassis-ui/css`, and two
+            // copies of it register every listener twice. In the dev server, a script of the
+            // package would be pre-bundled with a copy of its own, and a script of the site
+            // would get a pre-bundled copy while the package gets the source. Both packages
+            // are served from source, and every import resolves to the site's copy.
+            optimizeDeps: {
+              exclude: ['@chassis-ui/docs', '@chassis-ui/css'],
+              // The one CommonJS dependency of the package's scripts. It has no default export
+              // unless it is pre-bundled.
+              include: ['@chassis-ui/docs > clipboard']
+            },
+            resolve: {
+              dedupe: ['@chassis-ui/css']
+            },
+            // The styles of `@chassis-ui/css` load the design tokens as `chassis-tokens`. This
+            // adds its default as the last load path, after the site's own load paths, so a
+            // site with a `_chassis-tokens.scss` of its own puts that folder in its config.
+            ...(tokensLoadPath
+              ? { css: { preprocessorOptions: { scss: { loadPaths: [tokensLoadPath] } } } }
+              : {}),
+            plugins: [
+              virtualModules({
+                config: `export default ${JSON.stringify(config)}`,
+                sidebar: `export default ${JSON.stringify(sidebar)}`,
+                paths: Object.entries(paths)
+                  .map(([name, value]) => `export const ${name} = ${JSON.stringify(value)}`)
+                  .join('\n'),
+                styles: styles.map((file) => `import ${JSON.stringify(file)}`).join('\n')
+              })
+            ]
+          }
+        }
+
+        // The user config is wider than what `updateConfig()` declares for `markdown`.
+        updateConfig(update as Parameters<typeof updateConfig>[0])
+      },
+      'astro:config:done': ({ injectTypes }) => {
+        injectTypes({ filename: 'virtual.d.ts', content: virtualTypes })
+        injectTypes({ filename: 'auto-import.d.ts', content: typeDefinitions })
+      },
+      'astro:build:done': ({ dir, logger }) => {
+        if (brokenDocsrefs === 'ignore') return
+
+        const broken = [...linkedDocsPaths].filter((docsPath) => {
+          const builtPath = toBuiltFilePath(joinDocsPath(config.docsPath, docsPath))
+
+          return !fs.existsSync(path.join(fileURLToPath(dir), builtPath))
+        })
+
+        if (broken.length === 0) return
+
+        const message = `These [[docsref:]] links point to a page or file that was not built:\n${broken.map((docsPath) => `  - ${docsPath}`).join('\n')}`
+
+        if (brokenDocsrefs === 'error') {
+          throw new Error(message)
+        }
+
+        logger.warn(message)
+      }
+    }
+  }
+}

package/src/js/clipboard.ts

@@ -0,0 +1,65 @@
+import ClipboardJS from 'clipboard'
+import { Tooltip } from '@chassis-ui/css'
+
+const btnTitle = 'Copy'
+
+export function initCopyButtons(
+  selector: string,
+  textFn: (_element: Element) => string
+): ClipboardJS {
+  document.querySelectorAll(selector).forEach((btn) => {
+    Tooltip.getOrCreateInstance(btn, { title: btnTitle })
+  })
+
+  const clipboard = new ClipboardJS(selector, { text: textFn })
+
+  clipboard.on('success', (event) => {
+    const useEl = event.trigger.querySelector('.icon use')
+    const tooltipBtn = Tooltip.getInstance(event.trigger)
+    const originalHref = useEl?.getAttribute('href')
+
+    if (originalHref === '#check-solid') {
+      return
+    }
+
+    tooltipBtn?.setContent({ '.tooltip-inner': 'Copied!' })
+
+    event.trigger.addEventListener(
+      'hidden.cx.tooltip',
+      () => {
+        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+      },
+      { once: true }
+    )
+
+    event.clearSelection()
+
+    if (useEl) {
+      useEl.setAttribute('href', '#check-solid')
+    }
+
+    setTimeout(() => {
+      if (useEl && originalHref) {
+        useEl.setAttribute('href', originalHref)
+      }
+    }, 2000)
+  })
+
+  clipboard.on('error', (event) => {
+    const modifierKey = /mac/i.test(navigator.userAgent) ? '\u2318' : 'Ctrl-'
+    const fallbackMsg = `Press ${modifierKey}C to copy`
+    const tooltipBtn = Tooltip.getInstance(event.trigger)
+
+    tooltipBtn?.setContent({ '.tooltip-inner': fallbackMsg })
+
+    event.trigger.addEventListener(
+      'hidden.cx.tooltip',
+      () => {
+        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+      },
+      { once: true }
+    )
+  })
+
+  return clipboard
+}

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" />