@chassis-ui/docs 0.10.0 → 0.11.1

package/src/integration.ts

@@ -4,13 +4,14 @@ 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 { joinDocsPath, joinStaticPath } 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'
+import { versionStaticPath } from './libs/static-version'
 
 export interface ChassisDocsOptions<TSchema extends z.ZodType = typeof configSchema> {
   /**
@@ -56,7 +57,8 @@ type VitePlugin = Extract<NonNullable<ViteUserConfig['plugins']>[number], { name
 const virtualPrefix = 'virtual:chassis-docs/'
 const resolvedPrefix = '\0' + virtualPrefix
 
-function virtualModules(modules: Record<string, string>): VitePlugin {
+// The code of each module, or a function that returns it when the module is loaded.
+function virtualModules(modules: Record<string, string | (() => string)>): VitePlugin {
   return {
     name: 'chassis-docs:virtual',
     resolveId(id) {
@@ -66,7 +68,9 @@ function virtualModules(modules: Record<string, string>): VitePlugin {
     },
     load(id) {
       if (id.startsWith(resolvedPrefix)) {
-        return modules[id.slice(resolvedPrefix.length)]
+        const code = modules[id.slice(resolvedPrefix.length)]
+
+        return typeof code === 'function' ? code() : code
       }
     }
   }
@@ -92,6 +96,7 @@ declare module 'virtual:chassis-docs/paths' {
 
 declare module 'virtual:chassis-docs/static' {
   export const staticPath: string
+  export const spritePath: string
 }
 
 declare module 'virtual:chassis-docs/styles' {}
@@ -238,8 +243,21 @@ export function chassisDocs<TSchema extends z.ZodType = typeof configSchema>(
                 paths: Object.entries(paths)
                   .map(([name, value]) => `export const ${name} = ${JSON.stringify(value)}`)
                   .join('\n'),
-                // A config that was not loaded with `loadConfig()` may lack the default.
-                static: `export const staticPath = ${JSON.stringify(config.staticPath ?? '/static')}`,
+                // A config that was not loaded with `loadConfig()` may lack the default. The
+                // version of the sprite is read when a script loads the module: a site's own
+                // integration may copy the file into `public` after this hook.
+                static: () => {
+                  const staticPath = config.staticPath ?? '/static'
+                  const spritePath = versionStaticPath(
+                    joinStaticPath(staticPath, 'icons/chassis-icons.svg'),
+                    paths.publicDir
+                  )
+
+                  return [
+                    `export const staticPath = ${JSON.stringify(staticPath)}`,
+                    `export const spritePath = ${JSON.stringify(spritePath)}`
+                  ].join('\n')
+                },
                 styles: styles.map((file) => `import ${JSON.stringify(file)}`).join('\n')
               })
             ]

package/src/js/example-mode.js

@@ -1,5 +1,5 @@
 import { Tooltip } from '@chassis-ui/css'
-import { staticPath } from 'virtual:chassis-docs/static'
+import { spritePath } from 'virtual:chassis-docs/static'
 
 // Helper to detect the user's preferred theme
 function getPreferredTheme() {
@@ -44,7 +44,7 @@ function toggleTheme(button) {
   const iconUse = button.querySelector('use')
   if (iconUse) {
     const iconHref = newTheme === 'dark' ? 'sun-solid' : 'moon-solid'
-    iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
+    iconUse.setAttribute('href', `${spritePath}#${iconHref}`)
   }
 }
 
@@ -65,7 +65,7 @@ document.addEventListener('DOMContentLoaded', () => {
       const example = button.closest('.cxd-example-snippet')?.querySelector('.cxd-example')
       const currentTheme = example?.getAttribute('data-cx-theme') || preferredTheme
       const iconHref = currentTheme === 'dark' ? 'sun-solid' : 'moon-solid'
-      iconUse.setAttribute('href', `${staticPath}/icons/chassis-icons.svg#${iconHref}`)
+      iconUse.setAttribute('href', `${spritePath}#${iconHref}`)
     }
 
     // Add event listener if not already set through onclick

package/src/js/search.js

@@ -13,7 +13,7 @@
 // is needed here.
 
 import { getInstanceManager } from '@pagefind/component-ui'
-import { staticPath } from 'virtual:chassis-docs/static'
+import { spritePath } from 'virtual:chassis-docs/static'
 
 const DIALOG_SELECTOR = '#cxdSearchDialog'
 // The rows that are links. The loading skeleton reuses the class on a `<div>`,
@@ -237,7 +237,7 @@ const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, (char) =>
 const renderItem = ({ url, titleHtml, excerptHtml = '', icon, sub = false }) => `
   <a class="cxd-search-item${sub ? ' cxd-search-subitem' : ''}" href="${escapeHtml(url)}">
     <svg class="icon cxd-search-item-icon" width="16" height="16" aria-hidden="true">
-      <use href="${staticPath}/icons/chassis-icons.svg#${icon}"></use>
+      <use href="${spritePath}#${icon}"></use>
     </svg>
     <div class="cxd-search-item-body">
       <div class="cxd-search-item-title">${titleHtml}</div>
@@ -607,7 +607,8 @@ const isMac = () => {
 
 // Fill in `.cxd-search-trigger-shortcut` slots with the platform-correct hint
 // and reveal them. Rendered hidden by SearchTrigger.astro so non-JS visitors
-// never see a misleading shortcut key.
+// never see a misleading shortcut key. The hint stays out of the accessible
+// name, which is the trigger's label; `aria-keyshortcuts` announces it.
 const setupTriggerShortcuts = () => {
   const mac = isMac()
   const modifier = mac ? '⌘' : 'Ctrl '
@@ -615,6 +616,7 @@ const setupTriggerShortcuts = () => {
 
   for (const slot of document.querySelectorAll('.cxd-search-trigger-shortcut')) {
     slot.innerHTML = `<kbd class="cxd-search-trigger-key">${modifier}K</kbd>`
+    slot.setAttribute('aria-hidden', 'true')
     slot.hidden = false
     slot.closest('.cxd-search-trigger')?.setAttribute('aria-keyshortcuts', ariaKeyshortcut)
   }

package/src/layouts/head/Favicons.astro

@@ -11,6 +11,6 @@ import { getStaticPath } from '../../site'
 <link rel="apple-touch-icon" href={getStaticPath('images/apple-touch-icon.png')} sizes="180x180" />
 <link rel="icon" href={getStaticPath('images/favicon-32x32.png')} sizes="32x32" type="image/png" />
 <link rel="icon" href={getStaticPath('images/favicon-16x16.png')} sizes="16x16" type="image/png" />
-<link rel="manifest" href={getStaticPath('images/manifest.json')} />
+<link rel="manifest" href={getStaticPath('other/manifest.json')} />
 <link rel="icon" href={getStaticPath('images/favicon.png')} />
 <meta name="theme-color" content="#00A4CC" />

package/src/layouts/head/Head.astro

@@ -5,7 +5,7 @@
  * HTML head section with meta tags, stylesheets, and SEO configuration.
  */
 
-import { getConfig, getStaticPath } from '../../site'
+import { getConfig, getVersionedStaticPath } from '../../site'
 import { isHomePath } from '../../libs/docs-path'
 import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
@@ -46,7 +46,7 @@ const pageTitle = isHome
   family of every role. 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={getStaticPath('fonts/fonts.css')} />
+<link rel="stylesheet" href={getVersionedStaticPath('fonts/fonts.css')} />
 
 <meta name="description" content={description} />
 

package/src/layouts/head/Social.astro

@@ -7,14 +7,18 @@
 
 import { getRemoteImageSize, getStaticImageSize } from '../../libs/image'
 import type { Layout } from '../../libs/layout'
-import { getConfig, getPublicFsPath, getStaticPath } from '../../site'
+import { getImageType } from '../../libs/media'
+import { getConfig, getMediaUrl, getPublicFsPath, getStaticPath } from '../../site'
 
 interface Props {
   /** Page description */
   description: string
   /** Current layout context */
   layout: Layout
-  /** Social media thumbnail image */
+  /**
+   * Social media thumbnail image: a file in `static/` of the `public` directory, a URL, or
+   * `media:` and the path of an image in the media library
+   */
   thumbnail: string
   /** Page title */
   title: string
@@ -22,18 +26,27 @@ interface Props {
 
 const { description, layout, thumbnail, title } = Astro.props
 
-// A file in `static/` of the `public` directory is read from there, and linked under
-// `staticPath` of the config.
+// An image of the media library is linked as a JPEG copy at the size that the social
+// networks show, so its size is known without loading it. A file in `static/` of the
+// `public` directory is read from there, and linked under `staticPath` of the config.
+const mediaFile = thumbnail.match(/^media:(.+)$/)?.[1]
 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)
-  : await getStaticImageSize(getPublicFsPath(thumbnail))
+const mediaSize = { width: 1200, height: 630 }
+
+const socialImageUrl = mediaFile
+  ? getMediaUrl(mediaFile, { ...mediaSize, format: 'jpg' })
+  : new URL(staticFile ? getStaticPath(staticFile) : thumbnail, Astro.site).href
+const socialImageType = mediaFile ? 'image/jpeg' : getImageType(thumbnail)
+const socialImageSize = mediaFile
+  ? mediaSize
+  : isRemoteThumbnail
+    ? await getRemoteImageSize(thumbnail)
+    : await getStaticImageSize(getPublicFsPath(thumbnail))
 const { xUsername } = getConfig()
 ---
 
-<meta name="twitter:card" content="summary_lg_image" />
+<meta name="twitter:card" content="summary_large_image" />
 {xUsername && <meta name="twitter:site" content={`@${xUsername}`} />}
 {xUsername && <meta name="twitter:creator" content={`@${xUsername}`} />}
 <meta name="twitter:title" content={title} />
@@ -46,6 +59,6 @@ const { xUsername } = getConfig()
 <meta property="og:type" content={layout === 'docs' ? 'article' : 'website'} />
 <meta property="og:site_name" content={getConfig().title} />
 <meta property="og:image" content={socialImageUrl} />
-<meta property="og:image:type" content="image/png" />
+{socialImageType && <meta property="og:image:type" content={socialImageType} />}
 <meta property="og:image:width" content={String(socialImageSize.width)} />
 <meta property="og:image:height" content={String(socialImageSize.height)} />

package/src/layouts/head/Stylesheet.astro

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

package/src/layouts/header/SearchTrigger.astro

@@ -28,7 +28,6 @@ const { class: className, placeholder = 'Search docs…', target = '#cxdSearchDi
   data-cx-toggle="dialog"
   data-cx-target={target}
   aria-haspopup="dialog"
-  aria-label={placeholder}
 >
   <Icon name="search-solid" size={16} />
   <span class="cxd-search-trigger-label">{placeholder}</span>

package/src/libs/icon.ts

@@ -18,9 +18,16 @@ interface IconOptions {
  * This is needed because the `<Example />` shortcode renders its `code` prop as raw HTML via `set:html`
  * rather than as MDX, so nested Astro components (like `<Icon />`, similar to `<Placeholder />`) are never
  * actually invoked — they need to be expanded to their rendered markup ahead of time.
+ *
+ * @param staticPath The `staticPath` of the site.
+ * @param sprite URL of the sprite that an icon without a `sprite` attribute uses.
  * @see src/components/shortcodes/Icon.astro
  */
-export function replaceIconsInHtml(html: string, staticPath = '/static') {
+export function replaceIconsInHtml(
+  html: string,
+  staticPath = '/static',
+  sprite = `${staticPath}/icons/chassis-icons.svg`
+) {
   return html.replace(iconRegex, (match) => {
     const document = htmlparser2.parseDocument(match, { xmlMode: true })
     const iconElement = document.firstChild
@@ -34,11 +41,11 @@ export function replaceIconsInHtml(html: string, staticPath = '/static') {
       throw new Error('Invalid icon element.')
     }
 
-    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, staticPath))
+    return renderIconToString(getOptionsWithDefaults(iconElement.attribs, sprite))
   })
 }
 
-function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: string): IconOptions {
+function getOptionsWithDefaults(attribs: Record<string, string>, sprite: string): IconOptions {
   if (!attribs.name) {
     throw new Error('Icon element is missing the required "name" attribute.')
   }
@@ -48,7 +55,7 @@ function getOptionsWithDefaults(attribs: Record<string, string>, staticPath: str
     class: attribs.class,
     size: attribs.size ? Number(attribs.size.replace(/[{}]/g, '')) : 24,
     font: attribs.font !== undefined && attribs.font !== '{false}',
-    sprite: attribs.sprite || `${staticPath}/icons/chassis-icons.svg`,
+    sprite: attribs.sprite || sprite,
     title: attribs.title
   }
 }

package/src/libs/media.ts

@@ -0,0 +1,158 @@
+// Images of the media library, which is a Cloudinary account. A page names an image by its
+// path in the library, such as `blog/2026/color-system/cover.jpg`, and these functions build
+// the URL of a resized copy. Only this file knows the URL format of the provider, so a move
+// to another provider changes this file and `media` of the config, and no page.
+
+/** How the copy of an image is resized and encoded. */
+export interface MediaTransform {
+  /** Width of the copy in pixels. */
+  width?: number
+  /**
+   * Height of the copy in pixels. With `width`, the copy is cropped to that ratio around the
+   * subject of the image. Without, the copy keeps the ratio of the image.
+   */
+  height?: number
+  /** `auto` serves AVIF or WebP to a browser that accepts them. Default `auto`. */
+  format?: 'auto' | 'avif' | 'jpg' | 'png' | 'webp'
+  /** A number from 1 to 100, or `auto` for the lowest that looks the same. Default `auto`. */
+  quality?: 'auto' | number
+}
+
+const MEDIA_FORMAT_TYPES: Record<string, string> = {
+  avif: 'image/avif',
+  gif: 'image/gif',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  webp: 'image/webp'
+}
+
+/**
+ * The media type of an image file from its extension, e.g. `image/png` for `social.png`.
+ * `undefined` when the extension is not one of an image.
+ */
+export function getImageType(file: string): string | undefined {
+  const extension = file
+    .split(/[?#]/)[0]
+    .match(/\.([a-z0-9]+)$/i)?.[1]
+    ?.toLowerCase()
+
+  return extension ? MEDIA_FORMAT_TYPES[extension] : undefined
+}
+
+function assertPositiveInteger(name: string, value: number | undefined): void {
+  if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+    throw new Error(`The ${name} of a media image must be a positive integer, not ${value}.`)
+  }
+}
+
+/**
+ * Checks the path of an image in the media library and returns it encoded for a URL.
+ *
+ * @throws For a URL, a path that starts with `/`, an empty segment, `.` or `..`, a query or
+ *   a hash.
+ */
+export function encodeMediaPath(file: string): string {
+  const segments = file.split('/')
+
+  if (
+    /^[a-z][\w+.-]*:/i.test(file) ||
+    /[?#\\]/.test(file) ||
+    segments.some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    throw new Error(
+      `Expected the path of an image in the media library, such as "blog/cover.jpg", not "${file}".`
+    )
+  }
+
+  return segments.map((segment) => encodeURIComponent(segment)).join('/')
+}
+
+/** Whether `file` is the path of an image in the media library, as `encodeMediaPath()` takes it. */
+export function isMediaPath(file: string): boolean {
+  try {
+    encodeMediaPath(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * URL of a copy of an image of the media library.
+ *
+ * @example
+ * ```ts
+ * getMediaImageUrl('chassis', 'blog/cover.jpg', { width: 800, height: 420 })
+ * // https://res.cloudinary.com/chassis/image/upload/c_fill,g_auto,w_800,h_420,f_auto,q_auto/blog/cover.jpg
+ * ```
+ */
+export function getMediaImageUrl(
+  cloudName: string,
+  file: string,
+  transform: MediaTransform = {}
+): string {
+  const { format = 'auto', height, quality = 'auto', width } = transform
+
+  assertPositiveInteger('width', width)
+  assertPositiveInteger('height', height)
+
+  if (typeof quality === 'number' && (!Number.isInteger(quality) || quality < 1 || quality > 100)) {
+    throw new Error(`The quality of a media image must be from 1 to 100, not ${quality}.`)
+  }
+
+  // `c_fill` crops to the ratio of both sizes, around the subject (`g_auto`). `c_limit` keeps
+  // the ratio and never makes the image larger than it is.
+  const parts =
+    width && height
+      ? ['c_fill', 'g_auto', `w_${width}`, `h_${height}`]
+      : width || height
+        ? ['c_limit', width ? `w_${width}` : `h_${height}`]
+        : []
+
+  parts.push(`f_${format}`, `q_${quality}`)
+
+  return `https://res.cloudinary.com/${cloudName}/image/upload/${parts.join(',')}/${encodeMediaPath(file)}`
+}
+
+/** Widths that `getMediaImageWidths()` picks from. */
+export const MEDIA_IMAGE_WIDTHS = [320, 480, 640, 800, 1024, 1280, 1600, 1920, 2400]
+
+/**
+ * The widths of the copies of an image that is shown at most `width` pixels wide: the widths
+ * up to twice `width`, for screens with two device pixels per CSS pixel, and `width` itself.
+ */
+export function getMediaImageWidths(width: number, widths = MEDIA_IMAGE_WIDTHS): number[] {
+  assertPositiveInteger('width', width)
+
+  return [...new Set([...widths.filter((candidate) => candidate <= width * 2), width])].sort(
+    (a, b) => a - b
+  )
+}
+
+/**
+ * The `srcset` of an image of the media library: a copy at each of `widths`. With `height`,
+ * every copy is cropped to the ratio of `width` and `height`.
+ */
+export function getMediaImageSrcSet(
+  cloudName: string,
+  file: string,
+  widths: number[],
+  transform: MediaTransform = {}
+): string {
+  const { height, width } = transform
+
+  return widths
+    .map((copyWidth) => {
+      const copyHeight = width && height ? Math.round((copyWidth * height) / width) : undefined
+      const url = getMediaImageUrl(cloudName, file, {
+        ...transform,
+        width: copyWidth,
+        height: copyHeight
+      })
+
+      return `${url} ${copyWidth}w`
+    })
+    .join(', ')
+}

package/src/libs/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'astro/zod'
+import { isMediaPath } from './media'
 
 // Sites extend the schemas below. They must use this `z`, so that the site and the package
 // share one copy of Zod.
@@ -17,6 +18,14 @@ export const zPrefixedVersionSemver = z
 
 export const zLanguageCode = z.string().regex(/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
 
+/** The path of an image in the media library, e.g. `blog/2026/color-system/cover.jpg`. */
+export const zMediaPath = z
+  .string()
+  .refine(
+    isMediaPath,
+    'Expected the path of an image in the media library, such as "blog/cover.jpg"'
+  )
+
 const zHeadingRange = z.object({
   min: z.number().int().min(1).max(6),
   max: z.number().int().min(1).max(6)
@@ -57,6 +66,15 @@ export const configSchema = z.strictObject({
     .string()
     .regex(/^[\w.-]+$/, 'Expected a GitHub organisation name, not a URL')
     .optional(),
+  /**
+   * The media library that `<MediaImage>` and a `media:` thumbnail load images from: the
+   * cloud name of a Cloudinary account, e.g. `{ cloudinary: "chassis" }`.
+   */
+  media: z
+    .strictObject({
+      cloudinary: z.string().regex(/^[\w-]+$/, 'Expected a Cloudinary cloud name, not a URL')
+    })
+    .optional(),
   /** Repository URL, e.g. `"https://github.com/chassis-ui/css"`. */
   repo: z.url(),
   /** The branch that "View on GitHub" links to. */

package/src/libs/static-version.ts

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+// The hash of each file, kept until its size or time of change differs: a page of the build
+// reads the same stylesheet as every other page, and the dev server sees a file copied anew.
+const versions = new Map<string, { mtimeMs: number; size: number; version: string }>()
+
+/**
+ * The first 8 characters of the MD5 hash of a file's content, or `undefined` when there is
+ * no file at `fsPath`.
+ */
+export function getFileVersion(fsPath: string): string | undefined {
+  let stats: fs.Stats
+
+  try {
+    stats = fs.statSync(fsPath)
+  } catch {
+    return undefined
+  }
+
+  if (!stats.isFile()) return undefined
+
+  const cached = versions.get(fsPath)
+
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+    return cached.version
+  }
+
+  const version = createHash('md5').update(fs.readFileSync(fsPath)).digest('hex').slice(0, 8)
+  versions.set(fsPath, { mtimeMs: stats.mtimeMs, size: stats.size, version })
+
+  return version
+}
+
+/**
+ * Adds `?v=` and the version of the file to the URL path of a file of the public directory:
+ * `/static/css/chassis.min.css?v=8e2106f6`. A new content is a new URL, so the file can be
+ * kept by the browser until the page names another. A path that the public directory has no
+ * file at is returned as it is.
+ *
+ * @param urlPath URL path of the file, e.g. `"/static/css/chassis.min.css"`.
+ * @param publicDir Absolute path of the site's `public` directory.
+ */
+export function versionStaticPath(urlPath: string, publicDir: string): string {
+  const fsPath = path.join(publicDir, urlPath)
+
+  if (path.relative(publicDir, fsPath).startsWith('..')) return urlPath
+
+  const version = getFileVersion(fsPath)
+
+  return version ? `${urlPath}?v=${version}` : urlPath
+}

package/src/scss/_search.scss

@@ -77,25 +77,28 @@
     color: var(--cx-fg-subtle);
   }
 
-  .cxd-search-trigger-label,
-  .cxd-search-trigger-shortcut {
-    display: none;
-
-    @include media-breakpoint-up(lg) {
-      display: inline-flex;
-    }
-  }
-
+  // The label is the accessible name of the trigger, so on phones it is
+  // hidden from view only.
   .cxd-search-trigger-label {
+    display: inline-flex;
     flex: 1;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
+
+    @include media-breakpoint-down(lg) {
+      @include visually-hidden();
+    }
   }
 
   .cxd-search-trigger-shortcut {
+    display: none;
     flex-shrink: 0;
     gap: .125rem;
+
+    @include media-breakpoint-up(lg) {
+      display: inline-flex;
+    }
   }
 
   .cxd-search-trigger-key {

package/src/site.ts

@@ -14,6 +14,8 @@ import { getNodeModulesFsPaths, resolvePackageFilePath } from './libs/paths'
 import { replaceConfigInText, replaceDocsrefInText } from './libs/remark'
 import type { ChassisConfig, DocsPage, Sidebar } from './libs/schema'
 import { resolveSiteFileUrl, resolveSourceFsPath, resolveSourceUrl } from './libs/source'
+import { getMediaImageSrcSet, getMediaImageUrl, type MediaTransform } from './libs/media'
+import { versionStaticPath } from './libs/static-version'
 
 /**
  * The parsed `config.yml`.
@@ -43,6 +45,53 @@ export function getStaticPath(file = ''): string {
   return joinStaticPath(config.staticPath ?? '/static', file)
 }
 
+/**
+ * URL path of a static file with the version of its content:
+ * `getVersionedStaticPath('css/chassis.min.css')` is
+ * `/static/css/chassis.min.css?v=8e2106f6`. The version is read from the file of the site's
+ * `public` directory, so a page links the file of its own build, and a browser that keeps
+ * the file fetches it again when it changes. Without that file, the path is the one of
+ * `getStaticPath()`.
+ */
+export function getVersionedStaticPath(file: string): string {
+  return versionStaticPath(getStaticPath(file), paths.publicDir)
+}
+
+/**
+ * A URL path of a file of the site's `public` directory with the version of its content:
+ * `getVersionedPublicPath('/static/images/home/hero.webp')` is
+ * `/static/images/home/hero.webp?v=1a2b3c4d`. For a path that a page or a prop already holds.
+ * Without that file, the path is returned as it is.
+ */
+export function getVersionedPublicPath(urlPath: string): string {
+  return versionStaticPath(urlPath, paths.publicDir)
+}
+
+function getMediaCloudName(): string {
+  const cloudName = config.media?.cloudinary
+
+  if (!cloudName) {
+    throw new Error('An image of the media library needs `media.cloudinary` in `config.yml`.')
+  }
+
+  return cloudName
+}
+
+/**
+ * URL of a copy of an image of the media library, which `media` of the config names:
+ * `getMediaUrl('blog/cover.jpg', { width: 800 })`.
+ *
+ * @throws When the config has no `media`.
+ */
+export function getMediaUrl(file: string, transform?: MediaTransform): string {
+  return getMediaImageUrl(getMediaCloudName(), file, transform)
+}
+
+/** The `srcset` of an image of the media library, with a copy at each of `widths`. */
+export function getMediaSrcSet(file: string, widths: number[], transform?: MediaTransform): string {
+  return getMediaImageSrcSet(getMediaCloudName(), file, widths, transform)
+}
+
 /** 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

@@ -25,6 +25,8 @@ declare module 'virtual:chassis-docs/paths' {
 declare module 'virtual:chassis-docs/static' {
   /** `staticPath` of the config, for scripts that run in the browser. */
   export const staticPath: string
+  /** URL of the icon sprite, with the version of its content. */
+  export const spritePath: string
 }
 
 declare module 'virtual:chassis-docs/styles' {}