@half-built/astro 0.3.0 → 0.4.0

package/README.md

@@ -43,6 +43,9 @@ name) instead of `hex`: the swatch then paints `var(token)` and
 follows the live cascade with no script, and the hex cell renders
 empty with a `data-token-hex` attribute for a consumer script to fill
 from computed styles. Entries with `hex` render exactly as before.
+The table's scroll box is a keyboard tab stop named by the `label`
+prop (default "Palette"), since the table scrolls sideways below the
+column's width.
 
 ## Ecosystem island
 
@@ -70,6 +73,26 @@ The document is `{ version: 1, entries: [...] }` where each entry has
 0 highest) and `family`. Entries are sorted with the self entry's own
 family first, then by priority, and capped at `limit`, default 6.
 
+## Footer reserve for bottom-docked controls
+
+A control cluster fixed to the viewport's bottom corner takes no room
+in flow, so the page's last lines end underneath it. Set the css
+package's `--dock-bottom` token to the room the cluster occupies
+(its height, inset, and air) and `Footer` pads its band by that much
+below the last link, so the page scrolls far enough to clear the
+cluster. The token is `0px` by default and can be set inside the same
+media block that pins the cluster.
+
+## Search flyout
+
+`scripts/site-header` drives the masthead's search flyout as a
+disclosure: the magnifier toggles it open and closed, opening moves
+focus to the field, Escape closes and returns focus to the magnifier,
+and a press or keyboard focus leaving the flyout closes it. The island
+marks the wrap `data-search-js`; without it, the stylesheet's
+focus-within rule opens the flyout on focus alone, so it still works
+with no script.
+
 ## Import notes
 
 Wildcard subpath imports need explicit file extensions under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@half-built/astro",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Astro components, islands, and pure helpers for the half-built design system.",
   "license": "MIT",
   "repository": {

package/src/components/Footer.astro

@@ -66,7 +66,7 @@ const year = new Date().getFullYear();
             {ecosystem.map((entry) => (
               <li>
                 {entry.key === ecosystemSelf ? (
-                  <span class="footer-sitemap-self">{entry.label}</span>
+                  <span class="footer-sitemap-self" aria-current="page">{entry.label}</span>
                 ) : entry.href !== null ? (
                   <a href={entry.href}>{entry.label}</a>
                 ) : (
@@ -97,8 +97,12 @@ const year = new Date().getFullYear();
 
 <style>
   .site-footer { margin-top: 50px; }
-  /* Tint comes from the .tint-overlay pattern (default 0.1 opacity). */
-  .bottom-footer { padding: 15px 0 20px; z-index: 1; }
+  /* Tint comes from the .tint-overlay pattern (default 0.1 opacity).
+     The bottom padding adds --dock-bottom (tokens/primitives.css): a
+     site with a viewport-fixed bottom cluster sets it to the room
+     that cluster occupies, and the tinted band runs on below the last
+     link by that much, so the page scrolls far enough to clear it. */
+  .bottom-footer { padding: 15px 0 calc(20px + var(--dock-bottom, 0px)); z-index: 1; }
   .bottom-footer-info {
     display: flex;
     flex-wrap: wrap;

package/src/components/SiteHeader.astro

@@ -112,9 +112,11 @@ const isCurrent = (href: string) =>
                 <div class="navigation-search-wrap">
                   {/* A control that reveals UI is a button, not a link: a
                       bare-hash anchor navigates (scroll jump + history
-                      entry), audit finding A3. focus-within still opens the
-                      flyout when the button takes focus. */}
-                  <button type="button" title="Search" class="navigation-search-icon icon-box">
+                      entry), audit finding A3. With the island mounted it
+                      is the flyout's toggle (site-header.ts); without
+                      JavaScript, focus-within still opens the flyout when
+                      the button takes focus. */}
+                  <button type="button" title="Search" class="navigation-search-icon icon-box" aria-expanded="false">
                     <svg viewBox="0 0 512 512" width="14" height="14" fill="currentColor" aria-hidden="true"><path d="M505 442.7L405.3 343c28.4-34.9 45.7-79 45.7-127C451 96.5 354.5 0 235.5 0S20 96.5 20 215.5 116.5 431 235.5 431c48 0 92.1-17.3 127-45.7L462.3 485c5.9 5.9 15.4 5.9 21.3 0l21.4-21.4c5.9-5.9 5.9-15.4 0-20.9zM235.5 371c-85.9 0-155.5-69.6-155.5-155.5S149.6 60 235.5 60 391 129.6 391 215.5 321.4 371 235.5 371z"/></svg>
                     <span class="screen-reader-text">Search</span>
                   </button>
@@ -293,8 +295,13 @@ const isCurrent = (href: string) =>
     .masthead-top { display: none; }
   }
 
-  /* Search flyout: icon on a primary-filled box, form revealed on focus-within
-     (the live theme toggles a .show class with jQuery; focus-within needs no script). */
+  /* Search flyout: icon on a primary-filled box. The island
+     (site-header.ts) marks the wrap data-search-js and drives the
+     .search-open class, so the magnifier can close what it opened
+     (owner report 2026-09-09: focus-within alone could never close on
+     the button's own click, since the click leaves focus on the
+     button). Without the island the focus-within rule stands, so the
+     flyout still opens with no script. */
   .navigation-search { width: 30px; position: relative; display: inline-block; text-align: center; }
   .navigation-search-form {
     position: absolute;
@@ -307,11 +314,17 @@ const isCurrent = (href: string) =>
     z-index: var(--z-search-flyout);
     background-color: var(--surface);
     border: var(--stroke) solid var(--rule);
-    transition: var(--transition);
+    /* Opacity fades both ways; visibility flips at once on open and
+       waits out the fade on close. Under the house all-transition the
+       visibility interpolation read hidden at the instant the open
+       class landed, so the island's focus() on the field was refused. */
+    transition: opacity 0.1s ease, visibility 0s linear 0.1s;
   }
-  .navigation-search-wrap:focus-within .navigation-search-form {
+  .navigation-search-wrap:not([data-search-js]):focus-within .navigation-search-form,
+  .navigation-search-wrap.search-open .navigation-search-form {
     opacity: 1;
     visibility: visible;
+    transition-delay: 0s;
   }
   /* Form anatomy comes from the .field-join house pattern (owner request
      2026-07-30, replacing the live theme's 75/25 split form). Only the

package/src/components/content/Palette.astro

@@ -10,10 +10,13 @@
    cell renders empty with data-token-hex for a consumer script to
    fill from computed styles; the component itself stays inert. */
 interface Entry { role: string; hex?: string; token?: string; note?: string }
-interface Props { entries: Entry[]; class?: string }
-const { entries, class: className } = Astro.props;
+interface Props { entries: Entry[]; class?: string; label?: string }
+const { entries, class: className, label = "Palette" } = Astro.props;
 ---
-<div class:list={["table-scroll", className]}>
+{/* The scroll box is a tab stop with a name: below the column's width
+    the table scrolls sideways, and a scrolling region a keyboard cannot
+    reach fails WCAG 2.1.1 (axe scrollable-region-focusable). */}
+<div class:list={["table-scroll", className]} tabindex="0" role="region" aria-label={label}>
   <table class="palette">
     <thead>
       <tr>

package/src/scripts/ecosystem.ts

@@ -215,10 +215,31 @@ export interface EcosystemOptions {
   cacheKey?: string;
 }
 
+/* Astro compiles a component's scoped rules to `.cls[data-astro-cid-x]`,
+   and it stamps that attribute at build time on markup it renders. An
+   element built here with createElement never gets stamped, so it
+   matches none of Footer.astro's scoped rules: the self entry loses its
+   bold, a pending entry loses its dimming, and every link falls back to
+   the browser's default underline. The server-rendered list is stamped,
+   so the fix is to read the attribute off it and carry it onto whatever
+   we create. Read rather than hardcoded, because the hash changes
+   whenever the component's styles change. Consumers who render the
+   footer unscoped simply have nothing to copy, and the loop is a no-op. */
+function scopeOf(list: Element): string | null {
+  for (const { name } of list.attributes) {
+    if (name.startsWith("data-astro-cid-")) return name;
+  }
+  return null;
+}
+
 function entryNode(doc: Document, entry: EcosystemDocEntry, selfKey: string): HTMLElement {
   if (entry.key === selfKey) {
     const self = doc.createElement("span");
     self.className = "footer-sitemap-self";
+    /* The bold is the visual "you are here"; this is the same statement
+       for a screen reader, which cannot see weight. Without it the self
+       entry is announced exactly like an undeployed one. */
+    self.setAttribute("aria-current", "page");
     self.textContent = entry.label;
     return self;
   }
@@ -263,10 +284,16 @@ export async function mountEcosystem(root: Document, opts: EcosystemOptions): Pr
   const entries = sortEntries(document_.entries, selfKey, limit);
   if (!entries || entries.length === 0) return;
 
+  const scope = scopeOf(list);
   const fragment = root.createDocumentFragment();
   for (const entry of entries) {
     const item = root.createElement("li");
-    item.append(entryNode(root, entry, selfKey));
+    const node = entryNode(root, entry, selfKey);
+    if (scope !== null) {
+      item.setAttribute(scope, "");
+      node.setAttribute(scope, "");
+    }
+    item.append(node);
     fragment.append(item);
   }
   list.replaceChildren(fragment);

package/src/scripts/site-header.ts

@@ -2,18 +2,28 @@ import { claim, release, type Island, type IslandHandle } from "./core/island";
 import { formatHeaderDate } from "../lib/header-date";
 import { docOf } from "./core/dom";
 
-/* The masthead header island (step 9): the date-box refresh and the
-   phone menu toggle, born from SiteHeader.astro's inline script.
-   The two halves are unconditional and independent, mirroring the
-   original: the date box refreshes on every mount regardless of the
-   menu (it is idempotent, same text each time), and the menu wiring
-   claims the button separately so a second mount does not double-bind
-   its click/pointerdown/keydown handlers. */
+/* The masthead header island (step 9): the date-box refresh, the
+   phone menu toggle, and the search flyout, born from SiteHeader.astro's
+   inline script. The halves are unconditional and independent,
+   mirroring the original: the date box refreshes on every mount
+   regardless of the menu (it is idempotent, same text each time), and
+   each pop-out claims its own button so a second mount does not
+   double-bind its click/pointerdown/keydown handlers.
+
+   The search flyout joined the island on 2026-09-09 (owner report: the
+   magnifier could open it but never close it, unlike the menu button).
+   It had opened on :focus-within alone, which no button click can undo
+   while the button holds the focus. The island marks the wrap
+   data-search-js, the stylesheet hands the open state to a class, and
+   the flyout becomes the same disclosure the menu is. */
 
 export interface SiteHeaderOptions {
   dateId?: string;
   menuButton?: string;
   menuId?: string;
+  searchButton?: string;
+  searchWrap?: string;
+  searchField?: string;
   /* Defaults to formatHeaderDate, the same function Base.astro uses for
      the server render. Its package-time home (staying in src/lib vs.
      moving into the library) is an 11.3 decision; this option just
@@ -21,8 +31,65 @@ export interface SiteHeaderOptions {
   formatDate?: (d: Date) => string;
 }
 
+/* One pop-out over the page, the menu's manners (step 9): the button
+   toggles, a press anywhere outside closes, Escape closes and hands
+   focus back to the button. The open state is a class on `panel` and
+   aria-expanded on the button. The flyout adds the two focus manners
+   its :focus-within past had: the field takes focus on open, and
+   keyboard focus leaving the panel closes it. A focusout with no
+   destination is not a leave: Safari blurs the field before a click
+   on the button lands, and closing there would make the button's own
+   click reopen what it meant to close. */
+interface Popout {
+  btn: HTMLElement;
+  panel: HTMLElement;
+  openClass: string;
+  onOpen?: () => void;
+  closeOnFocusLeave?: boolean;
+}
+
+function wirePopout(doc: Document, { btn, panel, openClass, onOpen, closeOnFocusLeave = false }: Popout): () => void {
+  const isOpen = (): boolean => panel.classList.contains(openClass);
+  const inside = (t: EventTarget | null): boolean => t instanceof Node && (panel.contains(t) || btn.contains(t));
+  const setOpen = (open: boolean): void => {
+    panel.classList.toggle(openClass, open);
+    btn.setAttribute("aria-expanded", String(open));
+    if (open) onOpen?.();
+  };
+  const onClick = (): void => { setOpen(!isOpen()); };
+  const onPointerdown = (ev: PointerEvent): void => {
+    if (isOpen() && !inside(ev.target)) setOpen(false);
+  };
+  const onKeydown = (ev: KeyboardEvent): void => {
+    if (ev.key !== "Escape" || !isOpen()) return;
+    setOpen(false);
+    btn.focus();
+  };
+  const onFocusout = (ev: FocusEvent): void => {
+    if (isOpen() && ev.relatedTarget !== null && !inside(ev.relatedTarget)) setOpen(false);
+  };
+  btn.addEventListener("click", onClick);
+  doc.addEventListener("pointerdown", onPointerdown);
+  doc.addEventListener("keydown", onKeydown);
+  if (closeOnFocusLeave) panel.addEventListener("focusout", onFocusout);
+  return () => {
+    btn.removeEventListener("click", onClick);
+    doc.removeEventListener("pointerdown", onPointerdown);
+    doc.removeEventListener("keydown", onKeydown);
+    if (closeOnFocusLeave) panel.removeEventListener("focusout", onFocusout);
+  };
+}
+
 export const mountSiteHeader: Island<SiteHeaderOptions> = (root, options = {}): IslandHandle => {
-  const { dateId = "header-date", menuButton = ".menu-toggle", menuId = "primary-menu", formatDate = formatHeaderDate } = options;
+  const {
+    dateId = "header-date",
+    menuButton = ".menu-toggle",
+    menuId = "primary-menu",
+    searchButton = ".navigation-search-icon",
+    searchWrap = ".navigation-search-wrap",
+    searchField = ".search-field",
+    formatDate = formatHeaderDate,
+  } = options;
   const doc = docOf(root);
 
   // Header date: live like the WordPress original (build-time text is the
@@ -30,44 +97,37 @@ export const mountSiteHeader: Island<SiteHeaderOptions> = (root, options = {}):
   const dateBox = doc.getElementById(dateId);
   if (dateBox) dateBox.textContent = formatDate(new Date());
 
+  const unwire: (() => void)[] = [];
+
   const btn = root.querySelector<HTMLButtonElement>(menuButton);
   const menu = doc.getElementById(menuId);
-  let onClick: (() => void) | null = null;
-  let onPointerdown: ((ev: PointerEvent) => void) | null = null;
-  let onKeydown: ((ev: KeyboardEvent) => void) | null = null;
+  if (btn && menu && claim(btn, "site-header")) {
+    const off = wirePopout(doc, { btn, panel: menu, openClass: "open" });
+    unwire.push(() => { off(); release(btn, "site-header"); });
+  }
 
-  if (btn && claim(btn, "site-header")) {
-    const isOpen = (): boolean => menu?.classList.contains("open") ?? false;
-    const setOpen = (open: boolean): void => {
-      menu?.classList.toggle("open", open);
-      btn.setAttribute("aria-expanded", String(open));
-    };
-    onClick = () => { setOpen(!isOpen()); };
-    btn.addEventListener("click", onClick);
-    /* A pop-out over the page closes the way the search flyout does: a
-       press anywhere outside it, or Escape (which hands focus back to the
-       button). */
-    onPointerdown = (ev) => {
-      if (!isOpen()) return;
-      const t = ev.target;
-      if (t instanceof Node && (menu?.contains(t) || btn.contains(t))) return;
-      setOpen(false);
-    };
-    onKeydown = (ev) => {
-      if (ev.key !== "Escape" || !isOpen()) return;
-      setOpen(false);
-      btn.focus();
-    };
-    doc.addEventListener("pointerdown", onPointerdown);
-    doc.addEventListener("keydown", onKeydown);
+  const searchBtn = root.querySelector<HTMLButtonElement>(searchButton);
+  const wrap = searchBtn?.closest<HTMLElement>(searchWrap) ?? null;
+  if (searchBtn && wrap && claim(searchBtn, "site-header")) {
+    const field = wrap.querySelector<HTMLInputElement>(searchField);
+    wrap.setAttribute("data-search-js", "");
+    const off = wirePopout(doc, {
+      btn: searchBtn,
+      panel: wrap,
+      openClass: "search-open",
+      onOpen: () => field?.focus(),
+      closeOnFocusLeave: true,
+    });
+    unwire.push(() => {
+      off();
+      wrap.removeAttribute("data-search-js");
+      release(searchBtn, "site-header");
+    });
   }
 
   return {
     destroy(): void {
-      if (btn && onClick) btn.removeEventListener("click", onClick);
-      if (onPointerdown) doc.removeEventListener("pointerdown", onPointerdown);
-      if (onKeydown) doc.removeEventListener("keydown", onKeydown);
-      if (btn && onClick) release(btn, "site-header");
+      for (const off of unwire) off();
     },
   };
 };