@chassis-ui/docs 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @chassis-ui/docs
 
+## 0.6.3
+
+### Patch Changes
+
+- The home page of a site under a path gets the home form of the title, `title · subtitle`. The layouts took the page at `/` as the home page, so a site with `baseURL` `https://chassis-ui.com/css/` never got it: its home page is at `/css/`. The home page is now the page at the path of `baseURL`. The title of such a home page changes with this release, and the `title` prop of its layout is used for the social tags only. Keep `title · subtitle` within 70 characters where the site validates its HTML.
+- The color mode script is inline in the head and runs before the first paint. It was a module, which runs after the document is parsed, so a page in dark mode showed light first.
+- Five fixes of the search dialog. The page scrolls again after a search result on the current page is opened: the dialog closed without removing the scroll lock of the body. The input has the focus when the dialog is opened with the button, so typing works at once. The keyboard shortcuts open the dialog as the button does: the page behind it no longer scrolls, and a click outside closes it. A click or Enter on a loading placeholder no longer closes the dialog and saves an empty visit. Escape closes the dialog in Safari when the focus is in the empty input.
+
 ## 0.6.2
 
 ### Patch Changes

package/README.md

@@ -109,7 +109,7 @@ currentVersion: '0.5.2'
 | Key                                           | Required | Meaning                                                                                                                    |
 | --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `title`, `subtitle`, `description`, `authors` | yes      | Used in the page title and the meta tags                                                                                   |
-| `baseURL`                                     | yes      | Canonical URL of the site                                                                                                  |
+| `baseURL`                                     | yes      | Canonical URL of the site. The page at its path is the home page: `/css/` for `https://chassis-ui.com/css/`                |
 | `docsPath`                                    | yes      | URL path of the docs pages. Starts with `/`                                                                                |
 | `staticPath`                                  | no       | URL path that the pages load the static files from. Default `/static`. See [A site under a prefix](#a-site-under-a-prefix) |
 | `repo`                                        | yes      | URL of the repository                                                                                                      |
@@ -207,7 +207,7 @@ staticPath: '/css/static'
 
 The layouts, the `Icon` shortcode and the scripts of the package then link `/css/static/css/chassis.min.css` and so on. The files do not move: they stay in `static/` of the `public` directory. Two rewrites make the path answer:
 
-- on the host, from `/css/static/*` to `/static/*` of the site's deployment. chassis-ui.com has one for each Chassis site.
+- on the host, from `/css/static/*` to `/static/*` of the site's deployment.
 - in the site's own `vercel.json`, from `/css/static/(.*)` to `/static/$1`, so that the deployment also works when it is opened directly.
 
 Two kinds of URL are the site's own to move:
@@ -229,6 +229,8 @@ import SingleLayout from '@chassis-ui/docs/layouts/SingleLayout.astro'
 </SingleLayout>
 ```
 
+The `<title>` of a page is its `title` and the `title` of `config.yml`: `About · Chassis UI`. The home page, which is the page at the path of `baseURL`, gets `title` and `subtitle` of `config.yml` instead: `Chassis UI · Design Systems that Scale & Sync`. Its own `title` is used for the social tags only. html-validate reports a `<title>` of more than 70 characters, so keep the two within that.
+
 ## Shortcodes
 
 Every component in `@chassis-ui/docs/shortcodes/` is available in MDX files without an import. So is every component in the site's `src/components/shortcodes/`. A component of the site replaces the package's component of the same name.
@@ -374,6 +376,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
 | ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.6.3              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.0              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.5.3 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "repository": {
     "type": "git",

package/src/js/search.js

@@ -16,6 +16,9 @@ import { getInstanceManager } from '@pagefind/component-ui'
 import { staticPath } from 'virtual:chassis-docs/static'
 
 const DIALOG_SELECTOR = '#cxdSearchDialog'
+// The rows that are links. The loading skeleton reuses the class on a `<div>`,
+// which must not be followed, focused or saved as a visit.
+const ITEM_SELECTOR = 'a.cxd-search-item'
 const SUB_RESULTS_LIMIT = 3
 // How long a search may take before we show the loading skeleton. Most queries
 // resolve faster, so the previous results stay on-screen instead of flashing.
@@ -294,12 +297,21 @@ class CxdSearchInput extends HTMLElement {
       return
     }
 
+    // Safari keeps Escape for the search field, even an empty one, and the
+    // dialog never gets its cancel event. With text in the field the key clears
+    // it, as in every browser; without text it closes the dialog here.
+    if (event.key === 'Escape' && !this.input.value) {
+      event.preventDefault()
+      closeSearchDialog(this.closest('dialog'))
+      return
+    }
+
     // Enter follows the first result link.
     // Always preventDefault so the form never implicit-submits.
     if (event.key === 'Enter') {
       event.preventDefault()
       const dialogEl = this.closest('dialog')
-      dialogEl?.querySelector('.cxd-search-item')?.click()
+      dialogEl?.querySelector(ITEM_SELECTOR)?.click()
     }
   }
 
@@ -339,11 +351,11 @@ class CxdSearchResults extends HTMLElement {
   }
 
   _getLinks() {
-    return [...this.querySelectorAll('.cxd-search-item')]
+    return [...this.querySelectorAll(ITEM_SELECTOR)]
   }
 
   _onKeydown(event) {
-    const link = event.target.closest('.cxd-search-item')
+    const link = event.target.closest(ITEM_SELECTOR)
     if (!link) return
 
     const links = this._getLinks()
@@ -617,6 +629,29 @@ const isEditableTarget = (target) => {
   return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT'
 }
 
+const TRIGGER_SELECTOR = `[data-cx-toggle="dialog"][data-cx-target="${DIALOG_SELECTOR}"]`
+
+// Puts the caret in the input once the dialog is open. The chassis Dialog
+// focuses the dialog element itself when it opens, so a key typed right after a
+// click on the trigger went nowhere.
+const focusSearchInput = (dialogEl) => {
+  requestAnimationFrame(() => {
+    if (!dialogEl.open) return
+    dialogEl.querySelector('cxd-search-input')?.focus()
+    if (!instance.searchTerm) {
+      dialogEl.querySelector('cxd-search-results')?._renderEmpty?.()
+    }
+  })
+}
+
+const registerTriggerHandler = () => {
+  document.addEventListener('click', (event) => {
+    if (!event.target.closest(TRIGGER_SELECTOR)) return
+    const dialogEl = document.querySelector(DIALOG_SELECTOR)
+    if (dialogEl) focusSearchInput(dialogEl)
+  })
+}
+
 const openSearchDialog = () => {
   const dialogEl = document.querySelector(DIALOG_SELECTOR)
   if (!dialogEl) return
@@ -626,15 +661,24 @@ const openSearchDialog = () => {
     return
   }
 
-  // Native showModal() — CSS @starting-style handles the entry animation without
-  // needing the chassis bundle. Works in both dev (no bundle) and prod.
-  dialogEl.showModal()
-  requestAnimationFrame(() => {
-    dialogEl.querySelector('cxd-search-input')?.focus()
-    if (!instance.searchTerm) {
-      dialogEl.querySelector('cxd-search-results')?._renderEmpty?.()
-    }
-  })
+  // Open through the trigger, so that a shortcut does what the button does: the
+  // chassis Dialog locks the scroll of the body, closes on a click on the
+  // backdrop and gives the focus back. Without the chassis bundle the click does
+  // nothing, and the native showModal() opens the dialog.
+  document.querySelector(TRIGGER_SELECTOR)?.click()
+  if (!dialogEl.open) {
+    dialogEl.showModal()
+    focusSearchInput(dialogEl)
+  }
+}
+
+// Closes through the dismiss button, so that the chassis Dialog animates the
+// dialog out, unlocks the scroll of the body and gives the focus back. Without
+// the chassis bundle the click does nothing, and the native close() closes it.
+const closeSearchDialog = (dialogEl) => {
+  if (!dialogEl?.open) return
+  dialogEl.querySelector('[data-cx-dismiss="dialog"]')?.click()
+  if (dialogEl.open && !dialogEl.classList.contains('hiding')) dialogEl.close()
 }
 
 const registerGlobalShortcuts = () => {
@@ -683,7 +727,7 @@ const setupDialogResetOnClose = () => {
 
 const registerResultLinkHandler = () => {
   document.addEventListener('click', (event) => {
-    const link = event.target.closest('.cxd-search-item')
+    const link = event.target.closest(ITEM_SELECTOR)
     if (!link) return
     const dialogEl = link.closest('dialog')
     if (!dialogEl?.matches(DIALOG_SELECTOR)) return
@@ -697,6 +741,14 @@ const registerResultLinkHandler = () => {
     })
 
     dialogEl.close()
+
+    // The trigger opens the dialog through the chassis Dialog, which locks the
+    // scroll of the body with this class and unlocks it in its own hide(). The
+    // native close() above skips that, so the class stays: when the result is on
+    // the current page, nothing reloads and the page can no longer scroll.
+    if (!document.querySelector('dialog[open]:modal')) {
+      document.body.classList.remove('dialog-open')
+    }
   })
 }
 
@@ -704,6 +756,7 @@ const registerResultLinkHandler = () => {
 
 defineSearchCustomElements()
 registerGlobalShortcuts()
+registerTriggerHandler()
 registerResultLinkHandler()
 
 if (document.readyState === 'loading') {

package/src/layouts/head/Head.astro

@@ -6,10 +6,12 @@
  */
 
 import { getConfig } from '../../site'
+import { isHomePath } from '../../libs/docs-path'
 import type { Layout } from '../../libs/layout'
 import Stylesheet from './Stylesheet.astro'
 import Favicons from './Favicons.astro'
 import Social from './Social.astro'
+import colorModes from '../../js/color-modes.js?raw'
 import 'virtual:chassis-docs/styles'
 
 interface Props {
@@ -29,7 +31,8 @@ const { description, layout, robots, thumbnail, title } = Astro.props
 
 const canonicalUrl = new URL(Astro.url.pathname, Astro.site)
 
-const isHome = Astro.url.pathname === '/'
+// The home page of a site under a path, such as `/css/`, is not at `/`
+const isHome = isHomePath(getConfig().baseURL, Astro.url.pathname)
 const pageTitle = isHome
   ? `${getConfig().title} · ${getConfig().subtitle}`
   : `${title} · ${getConfig().title}`
@@ -60,7 +63,11 @@ const pageTitle = isHome
 
 {robots && <meta name="robots" content={robots} />}
 
-<script src="../../js/color-modes.js"></script>
+<!--
+  Inline and not a module, so that it sets the theme before the first paint. A module runs
+  after the document is parsed, and a page in dark mode would show light first
+-->
+<script is:inline set:html={colorModes} />
 
 <Stylesheet />
 <slot name="styles" />

package/src/libs/docs-path.ts

@@ -17,3 +17,16 @@ export function joinStaticPath(staticPath: string, file = ''): string {
 
   return name ? `${staticPath}/${name}` : staticPath
 }
+
+/**
+ * Whether a page is the home page of the site: the page at the path of `baseURL`. That is
+ * `/` for `https://chassis-ui.com` and `/css/` for `https://chassis-ui.com/css/`.
+ *
+ * @param baseURL The `baseURL` of the site's `config.yml`.
+ * @param pathname URL path of the page, with or without a trailing slash.
+ */
+export function isHomePath(baseURL: string, pathname: string): boolean {
+  const trim = (value: string) => value.replace(/\/+$/, '')
+
+  return trim(pathname) === trim(new URL(baseURL).pathname)
+}