@chassis-ui/docs 0.5.0 → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ozgur Gunes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 > Shared Astro layouts, components, and utilities for Chassis documentation sites.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.5.0](https://img.shields.io/badge/Version-0.5.0-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Version: 0.5.1](https://img.shields.io/badge/Version-0.5.1-blue.svg)](https://www.npmjs.com/package/@chassis-ui/docs) [![npm](https://img.shields.io/npm/v/@chassis-ui/docs.svg)](https://www.npmjs.com/package/@chassis-ui/docs)
 
 ## Overview
 
@@ -27,7 +27,7 @@ npm install @chassis-ui/docs
 ```json
 {
   "@astrojs/markdown-remark": "^7.0.0",
-  "@chassis-ui/css": ">=0.3.2",
+  "@chassis-ui/css": "^0.5.0-0",
   "@pagefind/component-ui": "^1.0.0",
   "@shikijs/transformers": "^4.3.1",
   "astro": "^7.0.0",
@@ -51,7 +51,7 @@ import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
 import TableOfContents from '@chassis-ui/docs/components/TableOfContents.astro'
 import ThemeToggler from '@chassis-ui/docs/components/ThemeToggler.astro'
 
-import { generateTOC, processImage } from '@chassis-ui/docs'
+import { generateToc, getStaticImageSize } from '@chassis-ui/docs'
 ---
 
 <SingleLayout title="About" description="…">
@@ -59,6 +59,53 @@ import { generateTOC, processImage } from '@chassis-ui/docs'
 </SingleLayout>
 ```
 
+## What a site must provide
+
+The layouts and components read from the consuming site. A site must provide the
+following, or the build fails.
+
+### Modules behind the `@libs/*` path alias
+
+The site maps `@libs/*` to its own `src/libs/*` in `tsconfig.json`, and each module
+exports:
+
+| Module            | Exports                                                                         | Read by                                |
+| ----------------- | ------------------------------------------------------------------------------- | -------------------------------------- |
+| `@libs/config`    | `getConfig()`, returning the parsed `config.yml`                                | most layouts and components            |
+| `@libs/content`   | `docsPages`, the `docs` collection. `getCalloutByName(name)` and `CalloutName`. | `DocsLayout`, `DocsSidebar`, `Callout` |
+| `@libs/data`      | `getData('sidebar')`, and the types `SidebarItem` and `SidebarSubItem`          | `DocsSidebar`                          |
+| `@libs/path`      | `getChassisDocsPath(path)` and `getDocsPublicFsPath()`                          | `DocsLayout`, `Social`                 |
+| `@libs/clipboard` | `initCopyButtons(selector, getText)`                                            | `Code`                                 |
+
+The site also defines a `docs` content collection. Its entry type is used by
+`BaseLayout` and `DocsLayout`.
+
+### Keys in `config.yml`
+
+`getConfig()` must return these keys:
+
+- `title`, `subtitle`, `description`, `authors`
+- `repo`, `current_version`, `docsPath`
+- `github_org`, `figma_handle`, `x_username`
+- `anchors.min`, `anchors.max`
+- `analytics.google_id`
+
+These keys are optional. They say where files live when the site is not built from the
+root of its repository:
+
+| Key          | Meaning                                                                                                           | Example           |
+| ------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `sourceDir`  | Directory that the `file` props of the source-file shortcodes are relative to, from the build's working directory | `"../css"`        |
+| `sourcePath` | The same directory, from the root of the repository                                                               | `"packages/css"`  |
+| `sitePath`   | The site's root, from the root of the repository                                                                  | `"packages/site"` |
+| `siteBranch` | The branch that "View on GitHub" links to. Defaults to `main`.                                                    | `"main"`          |
+
+The source-file shortcodes are `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and
+`<Code filePath>`. They link to their files at the tag `v<current_version>`.
+
+A site that validates `config.yml` with `z.object` must add the optional keys to its
+schema. Otherwise they are dropped silently.
+
 ## Exports
 
 | Subpath                         | Contents                                                                                                                     |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -25,7 +25,8 @@
   "files": [
     "src",
     "index.ts",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "main": "index.ts",
   "exports": {
@@ -40,6 +41,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "scripts": {
     "astro": "astro"
   },
@@ -56,7 +60,7 @@
   },
   "dependencies": {
     "github-slugger": "^2.0.0",
-    "image-size": "^2.0.2",
+    "image-size": "^2.0.4",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
@@ -65,8 +69,8 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4",
-    "astro": "^7.0.6",
+    "@types/hast": "^3.0.5",
+    "astro": "^7.3.5",
     "unified": "^11.0.5"
   }
 }

package/src/components/ThemeToggler.astro

@@ -26,9 +26,8 @@ const { layout } = Astro.props
   data-cx-placement="bottom-end"
 >
   <Icon name="circle-half-solid" class="theme-icon-active" />
-  <span
-    class=`${layout === 'examples' ? 'visually-hidden' : 'lg:d-none ms-xs'}`
-    id="cxd-theme-text">Toggle theme</span
+  <span class=`${layout === 'examples' ? 'visually-hidden' : 'lg:d-none ms-xs'}` id="cxd-theme-text"
+    >Toggle theme</span
   >
 </button>
 <ul class="menu" role="menu" aria-label="Theme options">

package/src/components/shortcodes/CSSOnly.astro

@@ -15,8 +15,6 @@ const { tooltip = 'This feature is only available in CSS and not in Figma compon
   Astro.props
 ---
 
-<span
-  class="badge lg info smooth mb-md rounded-md"
-  data-cx-toggle="tooltip"
-  title={tooltip}>CSS Only</span
+<span class="badge lg info smooth mb-md rounded-md" data-cx-toggle="tooltip" title={tooltip}
+  >CSS Only</span
 >

package/src/components/shortcodes/Code.astro

@@ -1,9 +1,8 @@
 ---
 import fs from 'node:fs'
-import path from 'node:path'
 import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'
-import { getConfig } from '@libs/config'
 import { highlightCode } from '../../libs/highlight'
+import { getSourceFsPath, getSourceUrl } from '../../libs/source'
 import Icon from './Icon.astro'
 
 interface Props {
@@ -41,7 +40,8 @@ interface Props {
    */
   fileMatch?: string
   /**
-   * A path to the file containing the code to highlight relative to the root of the repository.
+   * A path to the file containing the code to highlight, relative to the `sourceDir` of the
+   * site's `config.yml` (the working directory of the build when it is not set).
    * This takes precedence over the `code` prop.
    */
   filePath?: string
@@ -87,9 +87,7 @@ const {
   hasPreview = false
 } = Astro.props
 
-const fileUrl = file
-  ? `${getConfig().repo}/blob/v${getConfig().current_version}/${file}`.replaceAll('\\', '/')
-  : null
+const fileUrl = file ? getSourceUrl(file) : null
 
 // Extract language from multiple possible sources (for markdown code blocks)
 // Priority: lang prop > data-language attribute > className pattern
@@ -121,7 +119,7 @@ const displayLang = detectedLang
   : ''
 
 let codeToDisplay = filePath
-  ? fs.readFileSync(path.join(process.cwd(), filePath), 'utf8')
+  ? fs.readFileSync(getSourceFsPath(filePath), 'utf8')
   : Array.isArray(code)
     ? code.join('\n')
     : code

package/src/components/shortcodes/InFigma.astro

@@ -19,8 +19,6 @@ const tooltipText =
   `This variant${plural ? 's' : ''} exist${plural ? '' : 's'} in the Figma component library with bound design tokens.`
 ---
 
-<span
-  class="badge lg primary smooth mb-md rounded-md"
-  data-cx-toggle="tooltip"
-  title={tooltipText}>In Figma</span
+<span class="badge lg primary smooth mb-md rounded-md" data-cx-toggle="tooltip" title={tooltipText}
+  >In Figma</span
 >

package/src/components/shortcodes/JsDocs.astro

@@ -1,5 +1,6 @@
 ---
 import fs from 'node:fs'
+import { getSourceFsPath } from '../../libs/source'
 import Code from './Code.astro'
 
 // Prints everything between `// js-docs-start "name"` and `// js-docs-end "name"`
@@ -11,7 +12,8 @@ interface Props {
    */
   name: string
   /**
-   * File path that contains the content to display relative to the root of the repository.
+   * File path that contains the content to display, relative to the `sourceDir` of the site's
+   * `config.yml` (the working directory of the build when it is not set).
    */
   file: string
 }
@@ -27,7 +29,7 @@ if (!name || !file) {
 let content: string
 
 try {
-  const fileContent = fs.readFileSync(file, 'utf8')
+  const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
   const matches = fileContent.match(
     new RegExp(`// js-docs-start ${name}\n((?:.|\n)*)// js-docs-end ${name}`, 'm')

package/src/components/shortcodes/ScssDocs.astro

@@ -2,6 +2,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import * as sass from 'sass'
+import { getSourceFsPath } from '../../libs/source'
 import Code from './Code.astro'
 
 // Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
@@ -14,7 +15,8 @@ interface Props {
    */
   name: string
   /**
-   * File path that contains the content to display relative to the root of the repository.
+   * File path that contains the content to display, relative to the `sourceDir` of the site's
+   * `config.yml` (the working directory of the build when it is not set).
    */
   file: string
   /**
@@ -74,7 +76,7 @@ let content: string
 let lang: string = 'scss'
 
 try {
-  const fileContent = fs.readFileSync(file, 'utf8')
+  const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
   const matches = fileContent.match(
     new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
@@ -90,7 +92,7 @@ try {
 
   if (compile) {
     // Derive the SCSS load path from the file argument (e.g. "scss/_foo.scss" → "scss/")
-    const scssLoadPath = path.resolve(process.cwd(), file.split('/')[0])
+    const scssLoadPath = getSourceFsPath(file.split('/')[0])
 
     const scssInput = [
       '@use "config" as *;',
@@ -107,7 +109,7 @@ try {
     const result = await sass.compileStringAsync(scssInput, {
       loadPaths: [
         scssLoadPath,
-        path.resolve(process.cwd(), 'scss/vendor'),
+        getSourceFsPath('scss/vendor'),
         // Vite's own Sass importer resolves bare npm specifiers (e.g. `@chassis-ui/tokens/...`)
         // through its module resolver, independent of `loadPaths`. This raw Sass JS API call
         // bypasses Vite, so `node_modules` must be added here explicitly.

package/src/components/shortcodes/ScssDocsSimple.astro

@@ -1,5 +1,6 @@
 ---
 import fs from 'node:fs'
+import { getSourceFsPath } from '../../libs/source'
 import Code from './Code.astro'
 
 // Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
@@ -11,7 +12,8 @@ interface Props {
    */
   name: string
   /**
-   * File path that contains the content to display relative to the root of the repository.
+   * File path that contains the content to display, relative to the `sourceDir` of the site's
+   * `config.yml` (the working directory of the build when it is not set).
    */
   file: string
 }
@@ -29,7 +31,7 @@ if (!name || !file) {
 let content: string
 
 try {
-  const fileContent = fs.readFileSync(file, 'utf8')
+  const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
   const matches = fileContent.match(
     new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')

package/src/layouts/DocsLayout.astro

@@ -8,8 +8,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 { getSlug, processMarkdownToHtml } from '../libs/utils'
 import BaseLayout from './BaseLayout.astro'
 import DocsSidebar from '../components/DocsSidebar.astro'
@@ -23,10 +25,20 @@ interface Props {
   headings?: MarkdownHeading[]
   /** Document ID from the docs collection */
   id: CollectionEntry<'docs'>['id']
+  /**
+   * Path of the page's source file from the site's root. Looked up from the docs collection
+   * by `id` when omitted.
+   */
+  filePath?: string
 }
 
 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 githubUrl = filePath ? getSiteFileUrl(filePath) : `${getConfig().repo}/blob/${id}.mdx`
+
 type DocSection = NonNullable<typeof frontmatter.sections>[number]
 
 // Extract the directory/section from the ID (format: "directory/filename.mdx")
@@ -71,9 +83,7 @@ if (frontmatter.toc) {
     <main class="cxd-main">
       <div class="cxd-intro">
         <slot name="intro">
-          <div
-            class="md:d-flex md:flex-row-reverse justify-content-between align-items-start"
-          >
+          <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
@@ -88,7 +98,7 @@ if (frontmatter.toc) {
               }
               <a
                 class="button default sm"
-                href={`${getConfig().repo}/blob/${id}.mdx`}
+                href={githubUrl}
                 title="View and edit this file on GitHub"
                 target="_blank"
                 rel="noopener"

package/src/libs/source.ts

@@ -0,0 +1,62 @@
+import path from 'node:path'
+import { getConfig } from '@libs/config'
+
+/**
+ * The part of the site's `config.yml` that says where files live, on disk and on GitHub.
+ *
+ * All four location keys are optional. A site that sets none of them is assumed to be built
+ * from the root of its repository, with its source files in that root.
+ */
+interface SourceConfig {
+  /** Repository URL (e.g. `"https://github.com/chassis-ui/css"`). */
+  repo: string
+  /** Version of the release that links to source files name. */
+  current_version: string
+  /**
+   * Directory the `file` props of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code>` are
+   * relative to, itself relative to the working directory of the build (e.g. `"../css"` for a
+   * site in `packages/site`).
+   */
+  sourceDir?: string
+  /** The same directory from the root of the repository (e.g. `"packages/css"`). */
+  sourcePath?: string
+  /** The site's root from the root of the repository (e.g. `"packages/site"`). */
+  sitePath?: string
+  /** The branch that "View on GitHub" links to. Defaults to `"main"`. */
+  siteBranch?: string
+}
+
+function getSourceConfig(): SourceConfig {
+  return getConfig() as SourceConfig
+}
+
+/** Joins URL segments, skipping empty ones, and resolves any `..` in them. */
+function toUrl(segments: (string | undefined)[]): string {
+  const url = segments.filter(Boolean).join('/').replaceAll('\\', '/')
+
+  return new URL(url).href
+}
+
+/** Absolute path of a file or directory that a `file` prop names. */
+export function getSourceFsPath(file = ''): string {
+  return path.resolve(process.cwd(), getSourceConfig().sourceDir ?? '.', file)
+}
+
+/** URL of a source file on GitHub, in the tag of the current version. */
+export function getSourceUrl(file: string): string {
+  const { repo, current_version: version, sourcePath } = getSourceConfig()
+
+  return toUrl([repo, 'blob', `v${version}`, sourcePath, file])
+}
+
+/**
+ * URL of a file of the site on GitHub, on the site's branch.
+ *
+ * @param filePath Path of the file from the site's root, as Astro stores it in a content
+ * entry's `filePath` (e.g. `"content/docs/getting-started/introduction.mdx"`).
+ */
+export function getSiteFileUrl(filePath: string): string {
+  const { repo, sitePath, siteBranch = 'main' } = getSourceConfig()
+
+  return toUrl([repo, 'blob', siteBranch, sitePath, filePath])
+}