@chassis-ui/docs 0.6.0 → 0.6.2

package/src/layouts/head/Head.astro

@@ -10,7 +10,6 @@ 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 'virtual:chassis-docs/styles'
 
 interface Props {
@@ -41,6 +40,14 @@ const pageTitle = isHome
 
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<!--
+  A link, not an `@import` in the styles, so that the browser finds it with the page and
+  not after the stylesheet that imports it
+-->
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&family=Inter:wght@100..900&family=Archivo+Narrow:ital,wght@0,400..700;1,400..700&display=swap"
+/>
 
 <meta name="description" content={description} />
 
@@ -59,4 +66,3 @@ const pageTitle = isHome
 <slot name="styles" />
 <Favicons />
 <Social description={description} layout={layout} thumbnail={thumbnail} title={title} />
-<Analytics />

package/src/layouts/head/Social.astro

@@ -7,7 +7,7 @@
 
 import { getRemoteImageSize, getStaticImageSize } from '../../libs/image'
 import type { Layout } from '../../libs/layout'
-import { getConfig, getPublicFsPath } from '../../site'
+import { getConfig, getPublicFsPath, getStaticPath } from '../../site'
 
 interface Props {
   /** Page description */
@@ -22,7 +22,10 @@ interface Props {
 
 const { description, layout, thumbnail, title } = Astro.props
 
-const socialImageUrl = new URL(thumbnail, Astro.site)
+// A file in `static/` of the `public` directory is read from there, and linked under
+// `staticPath` of the config.
+const staticFile = thumbnail.match(/^\/?static\/(.+)$/)?.[1]
+const socialImageUrl = new URL(staticFile ? getStaticPath(staticFile) : thumbnail, Astro.site)
 const isRemoteThumbnail = /^https?:\/\//i.test(thumbnail)
 const socialImageSize = isRemoteThumbnail
   ? await getRemoteImageSize(thumbnail)

package/src/layouts/head/Stylesheet.astro

@@ -6,9 +6,10 @@
  */
 
 import type { HTMLAttributes } from 'astro/types'
+import { getStaticPath } from '../../site'
 
 function getChassisCssProps() {
-  let cxCssLinkHref = '/static/css/chassis'
+  let cxCssLinkHref = getStaticPath('css/chassis')
 
   if (import.meta.env.PROD) {
     cxCssLinkHref = `${cxCssLinkHref}.min`
@@ -26,4 +27,4 @@ function getChassisCssProps() {
 ---
 
 <link {...getChassisCssProps()} />
-<link rel="stylesheet" href={`/static/icons/chassis-icons.css`} />
+<link rel="stylesheet" href={getStaticPath('icons/chassis-icons.css')} />

package/src/layouts/header/Navigation.astro

@@ -6,7 +6,7 @@
  */
 
 import type { Layout } from '../../libs/layout'
-import { getConfig } from '../../site'
+import { getConfig, getStaticPath } from '../../site'
 import NavLink from '../../components/NavLink.astro'
 import ThemeToggler from '../../components/ThemeToggler.astro'
 import SearchTrigger from './SearchTrigger.astro'
@@ -55,7 +55,7 @@ const isActive = (path: string) => {
     {layout !== 'docs' && <div class="lg:d-none" style="width: 4.25rem;" />}
 
     <a class="navbar-brand m-0 py-sm lg:me-md" href="/" aria-label="Chassis">
-      <img src="/static/images/site-logo.svg" alt="Chassis UI" width="123" height="32" />
+      <img src={getStaticPath('images/site-logo.svg')} alt="Chassis UI" width="123" height="32" />
     </a>
 
     <div class="d-flex">
@@ -94,6 +94,7 @@ const isActive = (path: string) => {
           <NavLink active={isActive('/tokens')} href="/tokens">Tokens</NavLink>
           <NavLink active={isActive('/figma')} href="/figma">Figma</NavLink>
           <NavLink active={isActive('/css')} href="/css">CSS</NavLink>
+          <NavLink active={isActive('/react')} href="/react">React</NavLink>
           <NavLink active={isActive('/assets')} href="/assets">Assets</NavLink>
           <NavLink active={isActive('/icons')} href="/icons">Icons</NavLink>
           <li class="nav-item col-12 lg:col-auto lg:d-flex">

package/src/libs/docs-path.ts

@@ -10,3 +10,10 @@ export function joinDocsPath(docsPath: string, inputPath: string): string {
 
   return page ? `${base}/${page}` : base
 }
+
+/** Joins the static path of the config and a file: `('/css/static', 'css/chassis.css')`. */
+export function joinStaticPath(staticPath: string, file = ''): string {
+  const name = file.replace(/^\/+/, '')
+
+  return name ? `${staticPath}/${name}` : staticPath
+}

package/src/libs/highlight.ts

@@ -1,5 +1,5 @@
 import { codeToHtml, type ShikiTransformer } from 'shiki'
-import { DOCS_SHIKI_THEMES } from './markdown'
+import { DOCS_SHIKI_THEMES, focusableTransformer } from './markdown'
 
 /**
  * Shiki transformer that renames the `shiki` CSS class on `<pre>` elements to
@@ -44,7 +44,7 @@ export async function highlightCode(
     lang,
     themes: DOCS_SHIKI_THEMES,
     defaultColor: false,
-    transformers: [...extraTransformers, classTransformer]
+    transformers: [...extraTransformers, classTransformer, focusableTransformer]
   })
 
   return { html: replaceShikiClasses(highlighted) }

package/src/libs/icon.ts

@@ -20,7 +20,7 @@ interface IconOptions {
  * actually invoked — they need to be expanded to their rendered markup ahead of time.
  * @see src/components/shortcodes/Icon.astro
  */
-export function replaceIconsInHtml(html: string) {
+export function replaceIconsInHtml(html: string, staticPath = '/static') {
   return html.replace(iconRegex, (match) => {
     const document = htmlparser2.parseDocument(match, { xmlMode: true })
     const iconElement = document.firstChild
@@ -34,11 +34,11 @@ export function replaceIconsInHtml(html: string) {
       throw new Error('Invalid icon element.')
     }
 
-    return renderIconToString(getOptionsWithDefaults(iconElement.attribs))
+    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, staticPath))
   })
 }
 
-function getOptionsWithDefaults(attribs: Record<string, string>): IconOptions {
+function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: string): IconOptions {
   if (!attribs.name) {
     throw new Error('Icon element is missing the required "name" attribute.')
   }
@@ -48,7 +48,7 @@ function getOptionsWithDefaults(attribs: Record<string, string>): IconOptions {
     class: attribs.class,
     size: attribs.size ? Number(attribs.size.replace(/[{}]/g, '')) : 24,
     font: attribs.font !== undefined && attribs.font !== '{false}',
-    sprite: attribs.sprite || '/static/icons/chassis-icons.svg',
+    sprite: attribs.sprite || `${staticPath}/icons/chassis-icons.svg`,
     title: attribs.title
   }
 }

package/src/libs/markdown.ts

@@ -35,6 +35,17 @@ const addLanguageAttributeTransformer: ShikiTransformer = {
   }
 }
 
+/**
+ * Shiki transformer that puts `<pre>` in the tab order. A code block that is wider than the
+ * page scrolls sideways, and a keyboard can scroll it only when it can take focus.
+ */
+export const focusableTransformer: ShikiTransformer = {
+  name: 'focusable-pre',
+  pre(node) {
+    node.properties['tabindex'] = '0'
+  }
+}
+
 /**
  * Options accepted by `getDocsMarkdownConfig`.
  */
@@ -121,7 +132,8 @@ export function getDocsMarkdownConfig(options: DocsMarkdownConfigOptions): Markd
       transformers: [
         transformerNotationDiff(),
         transformerNotationHighlight(),
-        addLanguageAttributeTransformer
+        addLanguageAttributeTransformer,
+        focusableTransformer
       ]
     }
   }

package/src/libs/schema.ts

@@ -38,7 +38,7 @@ const zHeadingRange = z.object({
  * ```
  */
 export const configSchema = z.strictObject({
-  /** Google Analytics is loaded in production builds when `googleId` is set. */
+  /** Google Analytics is offered in production builds when `googleId` is set, and loads after the visitor accepts. */
   analytics: z.strictObject({ googleId: z.string().optional() }).default({}),
   /** Heading levels that get an anchor link. */
   anchors: zHeadingRange.default({ min: 2, max: 5 }),
@@ -70,6 +70,16 @@ export const configSchema = z.strictObject({
   sourceDir: z.string().default('.'),
   /** The same directory from the root of the repository, e.g. `"packages/css"`. */
   sourcePath: z.string().optional(),
+  /**
+   * URL path that the pages load the static files from, e.g. `"/css/static"`. The files stay
+   * in `static/` of the `public` directory: a site under a prefix of another host sets this
+   * and rewrites the path to `/static`.
+   */
+  staticPath: z
+    .string()
+    .regex(/^\/(.*[^/])?$/, 'Expected a URL path that starts with "/" and has no trailing slash')
+    .refine((value) => value !== '/', 'Expected a path below the root, such as "/static"')
+    .default('/static'),
   subtitle: z.string(),
   title: z.string(),
   /** Heading levels that the table of contents lists. */

package/src/scss/_consent.scss

@@ -0,0 +1,14 @@
+//
+// Consent
+//
+
+@layer custom {
+  // Above the sticky header, below dialogs and drawers
+  .cxd-consent {
+    position: fixed;
+    inset-block-end: 0;
+    inset-inline: 0;
+    z-index: 1030;
+    padding-block: var(--cx-space-md);
+  }
+}

package/src/scss/_footer.scss

@@ -14,7 +14,8 @@
       }
     }
 
-    a {
+    a,
+    .cxd-footer-link {
       color: var(--cx-fg-color);
       text-decoration: none;
 
@@ -24,5 +25,14 @@
         text-decoration: underline;
       }
     }
+
+    // A button that looks like the links next to it
+    .cxd-footer-link {
+      padding: 0;
+      font: inherit;
+      cursor: pointer;
+      background: none;
+      border: 0;
+    }
   }
 }

package/src/scss/main.scss

@@ -1,6 +1,5 @@
 @use "@chassis-ui/css/scss/mixins" as *;
 
-@forward "./fonts";
 @forward "./navbar";
 @forward "./content";
 @forward "./skippy";
@@ -8,6 +7,7 @@
 @forward "./layout";
 @forward "./toc";
 @forward "./footer";
+@forward "./consent";
 @forward "./snippets";
 @forward "./callouts";
 @forward "./placeholder-img";

package/src/site.ts

@@ -9,7 +9,7 @@ import sidebar from 'virtual:chassis-docs/sidebar'
 import * as paths from 'virtual:chassis-docs/paths'
 import { getCollection, getEntry, type render } from 'astro:content'
 import { loadData } from './libs/config'
-import { joinDocsPath } from './libs/docs-path'
+import { joinDocsPath, joinStaticPath } from './libs/docs-path'
 import { getNodeModulesFsPaths, resolvePackageFilePath } from './libs/paths'
 import { replaceConfigInText, replaceDocsrefInText } from './libs/remark'
 import type { ChassisConfig, DocsPage, Sidebar } from './libs/schema'
@@ -35,6 +35,14 @@ export function getDocsPath(inputPath: string): string {
   return joinDocsPath(config.docsPath, inputPath)
 }
 
+/**
+ * URL path of a static file, under `staticPath` of the config:
+ * `getStaticPath('images/site-logo.svg')` is `/static/images/site-logo.svg` by default.
+ */
+export function getStaticPath(file = ''): string {
+  return joinStaticPath(config.staticPath ?? '/static', file)
+}
+
 /** Absolute path of the site's root: the directory that holds `astro.config.ts`. */
 export function getSiteRoot(): string {
   return paths.root

package/virtual.d.ts

@@ -22,4 +22,9 @@ declare module 'virtual:chassis-docs/paths' {
   export const packageRoot: string
 }
 
+declare module 'virtual:chassis-docs/static' {
+  /** `staticPath` of the config, for scripts that run in the browser. */
+  export const staticPath: string
+}
+
 declare module 'virtual:chassis-docs/styles' {}

package/src/layouts/head/Analytics.astro

@@ -1,31 +0,0 @@
----
-/**
- * Analytics
- *
- * Google Analytics script tags. Rendered in production builds, when `analytics.googleId` is
- * set in `config.yml`.
- */
-
-import { getConfig } from '../../site'
-
-const isProd = import.meta.env.PROD
-const { googleId } = getConfig().analytics
----
-
-{
-  isProd && googleId && (
-    <>
-      <script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleId}`} />
-      <script
-        is:inline
-        set:html={`
-  window.dataLayer = window.dataLayer || [];
-  function gtag(){dataLayer.push(arguments);}
-  gtag('js', new Date());
-
-  gtag('config', '${googleId}');
-`}
-      />
-    </>
-  )
-}

package/src/scss/fonts.scss

@@ -1 +0,0 @@
-@import "https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&family=Inter:wght@100..900&family=Archivo+Narrow:ital,wght@0,400..700;1,400..700&display=swap";