@half-built/astro 0.10.0 → 0.11.1

package/README.md

@@ -43,8 +43,9 @@ The two house conventions ship as `GENAI_BADGE` and `DEMO_BADGE`; a
 site's view-model lists the badges a post carries, in order, and can
 add its own without a package change. `PostCardModel.badges` carries
 them to the card. The content components (`BlogImage`, `GalleryImage`,
-`MediaText`) keep a `genai` boolean as authoring sugar for MDX and take
-`badges` for anything else.
+`MediaText`) take the same `badges` array, for example
+`badges={[GENAI_BADGE]}` with `GENAI_BADGE` imported from
+`@half-built/astro/scripts/core/badges.ts`.
 
 ## EditorNote
 
@@ -120,7 +121,9 @@ palette override. The variables resolve to the same hexes the theme
 bakes, so adopting the transformer changes no rendered pixel on its
 own. Pass it beside the theme: the `transformers` prop of
 `astro:components`' `Code`, or `markdown.shikiConfig.transformers` in
-an Astro config.
+an Astro config. It also encodes the `>` that Shiki's HTML serializer
+leaves raw in `Code` output, so that output passes the tooling
+html-validate preset.
 
 ## Palette token entries
 
@@ -140,7 +143,7 @@ JSON document, so adding a property to a family of sites does not mean
 rebuilding every one of them.
 
 ```js
-import { mountEcosystem } from "@half-built/astro/scripts/ecosystem";
+import { mountEcosystem } from "@half-built/astro/scripts/ecosystem.ts";
 
 void mountEcosystem(document, {
   endpoint: "https://example.com/ecosystem.json",
@@ -169,6 +172,12 @@ 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.
 
+## TwoColumn
+
+`components/TwoColumn.astro` renders its main column as `<main>`; pass
+`mainTag="div"` for a demo or nested use where the page already has
+its own main.
+
 ## Search flyout
 
 `scripts/site-header` drives the masthead's search flyout as a
@@ -179,6 +188,93 @@ 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.
 
+## Lightbox
+
+`scripts/lightbox` opens the images the content components link
+through `LightboxLink` (`BlogImage`, `GalleryImage`, `MediaText`,
+`Step`) in a full-window viewer. Links inside one `Gallery` or
+`Walkthrough` form a set with previous and next buttons, thumbnails,
+and the arrow keys.
+
+```js
+import "@half-built/css/plate-modal.css";
+import "@half-built/css/lightbox.css";
+import { mountLightbox } from "@half-built/astro/scripts/lightbox.ts";
+
+mountLightbox(document);
+```
+
+The image opens at fit: contained in the window, very tall images fit
+to width, and small images never scale past 100%. The wheel or a
+trackpad zooms under the pointer in proportion to the scroll; a
+sideways scroll does nothing. `+` and `-` step the zoom, `0` returns to fit, and a drag pans. Once
+the image is panned mostly out of view a HOME box appears that also
+returns to fit. Double-click at the fit view
+zooms to 100% under the cursor; anywhere else it returns to fit.
+
+A resize or rotation while the viewer is open refits the image to the
+new window. Any zoom and pan the reader had set is discarded, on
+purpose: the old view was measured against a window that no longer
+exists.
+
+`mountLightbox` takes options: `selector` (default `a.lightbox-link`)
+picks the links, `groupSelector` names the containers whose links form
+one set, and `labels` renames the viewer's controls for a site that is
+not in English.
+
+## Popout
+
+`components/Popout.astro` puts a short note behind a table cell: detail
+worth keeping but not worth a column. It renders a trigger button and a
+template holding its slot; `scripts/popout` opens the note. Like
+link-tip, the mounted island is a document-wide singleton: `root` only
+names the document, and triggers anywhere in it share the one surface.
+
+```astro
+<Popout label="Sample row · Sample product">
+  A short note with a <a href="#">link</a> and <code>code</code>.
+</Popout>
+```
+
+```js
+import "@half-built/css/popout.css";
+import { mountPopouts } from "@half-built/astro/scripts/popout.ts";
+
+mountPopouts(document);
+```
+
+`label` is required. It captions the open note and names the trigger
+for assistive tech (`<trigger>: <label>`, so `Note: <label>` by
+default), so write it to identify the row. `trigger` changes the button
+text from `Note`. The slot takes inline markup: links, code, emphasis.
+
+Above the phone breakpoint the note opens below its trigger (above it
+when there is no room below) and stays until Escape, the close box, a
+press outside, or another trigger. It also closes by itself when its
+trigger scrolls out of view or when keyboard focus leaves it. Shift+Tab
+off its first stop returns to the trigger; Tab off its last stop moves
+on to whatever follows the trigger. On a wide touch device a
+drag that starts outside the note closes it. At phone width it opens as
+a modal bottom sheet that closes on the close box, Escape or Back, a
+tap on the backdrop, or a downward swipe. One note is open at a time.
+With JavaScript off the trigger does nothing.
+
+A resize or rotation that crosses the phone breakpoint, in either
+direction, closes an open note instead of turning the box into a sheet
+or the sheet into a box. The reader reopens it and it opens in the mode
+for the new width. Focus is not moved back to the trigger, which may
+have scrolled away in the new layout. Resizes that stay on one side of
+the breakpoint keep the note open: the box re-places itself, and the
+sheet rides out the URL bar collapsing and the keyboard opening.
+
+`mountPopouts` takes options: `selector` (default `.popout-trigger`)
+picks the triggers, `edge` sets the anchored note's room against the
+viewport edges in px, and `closeLabel` (default `Close`) names the
+close box for a site that is not in English.
+
+Not covered yet: structured content (lists, sub-tables, images),
+triggers on chart marks, and hover previews.
+
 ## Import notes
 
 Wildcard subpath imports need explicit file extensions under

package/package.json

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

package/src/components/Footer.astro

@@ -193,6 +193,15 @@ const year = new Date().getFullYear();
     }
     .footer-sitemap-group { text-align: center; width: 100%; }
 
+    /* 24px tap targets (WCAG 2.2 target size, 2.5.8). The phone lists
+       sat at a 23.3px pitch with 16px link boxes. A 24px line on every
+       row keeps the rhythm within a pixel, including the rows that are
+       plain text (the current site, pending entries), and the
+       inline-block link takes the whole line box as its target
+       (spec 2026-09-29-wcag-2-2-design.md). */
+    .footer-sitemap-group li { margin: 0; line-height: 24px; }
+    .footer-sitemap a { display: inline-block; }
+
     .footer-sitemap-collapsible summary {
       display: block;
       position: relative;

package/src/components/LightboxLink.astro

@@ -1,5 +1,16 @@
 ---
-interface Props extends Record<string, unknown> {
+import type { HTMLAttributes } from "astro/types";
+
+type Owned =
+  | "href"
+  | "aria-label"
+  | "data-lb-w"
+  | "data-lb-h"
+  | "data-lb-caption"
+  | "class"
+  | "class:list";
+
+interface Props extends Omit<HTMLAttributes<"a">, Owned> {
   href: string;
   w: number;
   h: number;
@@ -11,12 +22,12 @@ const { href, w, h, caption = "", class: className, ...rest } = Astro.props;
 ---
 
 <a
+  {...rest}
   class:list={["lightbox-link", className]}
   href={href}
   data-lb-w={w}
   data-lb-h={h}
   data-lb-caption={caption}
   aria-label={`View full-size image${caption ? `: ${caption}` : ""}`}
-  {...rest}
   ><slot
 /></a>

package/src/components/Popout.astro

@@ -0,0 +1,33 @@
+---
+import type { HTMLAttributes } from "astro/types";
+
+type Owned =
+  | "type"
+  | "aria-haspopup"
+  | "aria-expanded"
+  | "aria-label"
+  | "data-popout-label"
+  | "class"
+  | "class:list";
+
+interface Props extends Omit<HTMLAttributes<"button">, Owned> {
+  label: string;
+  trigger?: string;
+  class?: string;
+}
+
+const { label, trigger = "Note", class: className, ...rest } = Astro.props;
+---
+
+<button
+  {...rest}
+  type="button"
+  class:list={["popout-trigger", className]}
+  aria-haspopup="dialog"
+  aria-expanded="false"
+  aria-label={`${trigger}: ${label}`}
+  data-popout-label={label}
+>
+  {trigger}
+</button
+><template class="popout-content"><slot /></template>

package/src/components/PostCard.astro

@@ -31,8 +31,8 @@ const Heading: "h2" | "h3" | "h4" = `h${headingLevel}`;
 const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
 ---
 
-{/* The mapper guarantees an image (Henry placeholder when no featured
-    image), so every card takes the thumbnail treatment. */}
+{/* The mapper guarantees an image (a consumer's own placeholder when no
+    featured image), so every card takes the thumbnail treatment. */}
 <article class:list={["has-post-thumbnail", className]}>
   <div class="post-item post-grid">
     <div class="post-item-image">
@@ -47,12 +47,14 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
         />
       </a>
       {draft && <span class="draft-stamp">DRAFT</span>}
-      <div class="read-time-comment">
-        <span class="reading-time chip">
-          <Icon name="clock" size={12} />
-          {`${minutes} ${minReadLabel}`}</span>
+      <div class="card-chips">
+        <div class="read-time-comment">
+          <span class="reading-time chip">
+            <Icon name="clock" size={12} />
+            {`${minutes} ${minReadLabel}`}</span>
+        </div>
+        <CornerBadges badges={badges} />
       </div>
-      <CornerBadges badges={badges} />
     </div>
     <div class="post-item-content">
       <div class="entry-cat">
@@ -114,18 +116,38 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
     font-size: var(--font-size-xl);
   }
 
-  /* Chip look comes from the .chip pattern; only placement is
-     contextual. display: flex, not a plain block: a block wrapper
-     gives the inline-flex chip a text line box whose descender gap
-     floats it off the true bottom, so this chip and the corner badges
-     (already a flex container) sat at different offsets (owner catch
-     2026-09-06). */
-  .read-time-comment {
+  /* One row along the image's bottom edge: the read-time chip at the
+     left, the corner badges pushed right. wrap-reverse keeps the read
+     time on the bottom line and lifts the badges to a line above it
+     when a narrow card cannot fit both, instead of overlapping (owner
+     catch 2026-09-28). pointer-events: none lets a press fall through
+     to the thumbnail link. */
+  .card-chips {
     position: absolute;
+    right: 10px;
     bottom: 10px;
     left: 10px;
     z-index: 1;
     display: flex;
+    flex-wrap: wrap-reverse;
+    gap: 6px;
+    align-items: flex-end;
+    pointer-events: none;
+  }
+
+  /* In the row, CornerBadges gives up its own corner placement. */
+  .card-chips :global(.corner-badges) {
+    position: static;
+    margin-left: auto;
+  }
+
+  /* Chip look comes from the .chip pattern. display: flex, not a plain
+     block: a block wrapper gives the inline-flex chip a text line box
+     whose descender gap floats it off the true bottom, so this chip and
+     the corner badges (already a flex container) sat at different
+     offsets (owner catch 2026-09-06). */
+  .read-time-comment {
+    display: flex;
   }
   .post-item-content { padding: 15px 0 0; padding-top: 10px; }
 
@@ -135,13 +157,18 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
     overflow: hidden;
     text-overflow: ellipsis;
 
-    /* The links' font box stands taller than this line-height:1 row, and
-       overflow clips at the padding box, so without vertical breathing
-       room the inset focus/hover ring loses its top and bottom bands.
-       The negative margin gives the padding back, keeping card layout
-       identical (smoke test pins the containment). */
-    padding-block: 3px;
-    margin-block: -3px;
+    /* Each link's box is padded to 24px (WCAG 2.2 target size, 2.5.8).
+       The links' font box already stands about 2px taller than this
+       line-height:1 row on each side, and overflow clips at the padding
+       box, so the row pads 6px to keep the whole 24px box, and with it
+       the inset focus/hover ring, inside the clip. The negative margin
+       gives the padding back above; below it gives back 2px less,
+       because 24px boxes that touch the title link fail 2.5.8's spacing
+       check (spec 2026-09-29-wcag-2-2-design.md, owner-approved nudge:
+       the title and everything under it sit 2px lower). The smoke tests
+       pin the containment and the 24px height. */
+    padding-block: 6px;
+    margin-block: -6px -4px;
     color: var(--ink);
     text-transform: uppercase;
     font-weight: bold;
@@ -151,6 +178,7 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
   }
 
   .entry-cat .post-categories a {
+    padding-block: 4px;
     color: inherit;
     text-decoration: none;
     transition: var(--transition);

package/src/components/Shell.astro

@@ -27,7 +27,7 @@ const {
         attribute. Kept tiny and dependency-free on purpose.
         The storage key rides define:vars from the required themeStorageKey
         prop (step 11.2), so the shell bakes in no brand of its own; the
-        caller (Base.astro) supplies it from lib/theme-key. */}
+        caller (the consumer's layout) supplies its own key. */}
     <script is:inline define:vars={{ themeKey: themeStorageKey }}>
       (function () {
         var t = null;

package/src/components/ThemeToggle.astro

@@ -23,7 +23,6 @@ const {
     className,
   ]}
   aria-label={label}
-  aria-pressed="false"
 >
   <span class="theme-toggle-moon"><Fragment set:html={ICON_MOON} /></span>
   <span class="theme-toggle-sun"><Fragment set:html={ICON_SUN} /></span>

package/src/components/TwoColumn.astro

@@ -1,12 +1,14 @@
 ---
 interface Props {
   class?: string;
+  mainTag?: "main" | "div";
 }
 
-const { class: className } = Astro.props;
+const { class: className, mainTag = "main" } = Astro.props;
+const Main = mainTag;
 ---
 
 <div class:list={["two-column", className]}>
-  <main class="site-main"><slot /></main>
+  <Main class="site-main"><slot /></Main>
   <slot name="aside" />
 </div>

package/src/components/content/BlogImage.astro

@@ -68,7 +68,6 @@ const {
   .blog-image :global(img) { max-width: 100%; height: auto; display: block; margin-inline: auto; }
   .blog-image-narrow :global(.lightbox-link) { max-width: min(495px, 100%); }
 
-  /* Type from the .caption pattern. Fidelity pass (handoff 5.5): live
-     figcaptions are centered. */
+  /* Type from the .caption pattern; figcaptions are centered. */
   figcaption { margin-top: 5px; text-align: center; }
 </style>

package/src/components/models.ts

@@ -32,12 +32,13 @@ export interface LinkListItem {
 }
 
 /* Chrome view-models (step 9.5, 2026-08-31): the header renders site
-   identity it is handed, never the blog's config. NavItem is the shape
-   config.ts's NAV already had; it moved here so the component and the
-   site share one definition without the component importing site code.
-   SocialItem carries its icon as inline SVG markup: the site's registry
-   (social-icons.ts, including the Henry portfolio glyph that stays out
-   of the package) is a lookup the caller performs, not the component. */
+   identity it is handed, never a consumer's own config. NavItem is the
+   shape a consumer's own site navigation config already used; it moved
+   here so the component and the site share one definition without the
+   component importing site code. SocialItem carries its icon as inline
+   SVG markup: a site's own icon registry (including any site-specific
+   brand glyphs that stay out of the package) is a lookup the caller
+   performs, not the component. */
 export interface NavItem {
   label: string;
   href: string;
@@ -51,10 +52,10 @@ export interface SocialItem {
   icon: string;
 }
 
-/* Footer view-models (step 9.5). These are the interfaces config.ts's
-   footer-sitemap comment always called "the future component-library
-   schema"; this is that move. The blog's data (FOOTER_SITEMAP,
-   ECOSYSTEM) stays in config.ts. */
+/* Footer view-models (step 9.5). These are the interfaces a consumer's
+   own footer-sitemap comment called "the future component-library
+   schema"; this is that move. A consumer's own footer data stays in its
+   own config, not here. */
 export interface SitemapLink {
   label: string;
   href: string;

package/src/lib/excerpt.ts

@@ -1,6 +1,6 @@
 /* Card text derived from a post body (owner call 2026-09-13; the rule
-   is recorded in the blog's docs/superpowers/specs/2026-09-13-derived-excerpts-design.md
-   and summarized in this package's README, "Derived excerpts"). The
+   was settled at the blog and is summarized in this package's README,
+   "Derived excerpts"). The
    card is the opening prose, consecutive paragraphs joined, cut at a
    word boundary within EXCERPT_LIMIT and always ended with an
    ellipsis, so every listing samples the post's own opening and the

package/src/lib/format-date.ts

@@ -1,7 +1,7 @@
 /* Package lib (step 11.2): the post date formatter, split from
-   post-display.ts so the package's formatDate never drags the Henry
-   placeholder along. Locale parameterized for N sites; en-US is the
-   house default. */
+   post-display.ts so the package's formatDate never drags a
+   site-specific placeholder along. Locale parameterized for N sites;
+   en-US is the house default. */
 export function formatPostDate(d: Date, locale = "en-US"): string {
   return d.toLocaleDateString(locale, {
     year: "numeric",

package/src/lib/header-date.ts

@@ -1,6 +1,6 @@
 /* The masthead date box: "25, Aug 2026", the live theme's format. Rendered
    at build time as the no-JS fallback (SiteHeader.astro) and refreshed on
-   load by Base.astro's script, from this one definition. */
+   load by the consumer's layout script, from this one definition. */
 export function formatHeaderDate(now: Date): string {
   return `${now.getDate()}, ${now.toLocaleDateString("en-US", { month: "short" })} ${now.getFullYear()}`;
 }

package/src/lib/ordering.ts

@@ -1,9 +1,10 @@
 /* Publication-time ordering, pure and framework-free so it is unit-testable.
    Single source of truth for a post's publication instant: `date` is the
-   date-only permalink field; `published` carries the full WP timestamp when
-   the migrator knew it. Every consumer (sorting, feeds, display) must go
-   through these instead of picking fields ad hoc: hand-picked fields are how
-   the same-day ordering bug shipped twice (audit A1/A2). */
+   date-only permalink field; `published` carries the full source timestamp
+   when a consumer's import knew it. Every consumer (sorting, feeds,
+   display) must go through these instead of picking fields ad hoc:
+   hand-picked fields are how the same-day ordering bug shipped twice
+   (audit A1/A2). */
 
 export interface Publishable {
   data: { date: Date; published?: Date };

package/src/scripts/code-island.ts

@@ -3,8 +3,8 @@ import { docOf } from "./core/dom";
 
 /* Code island decorator: builds the header bar (filename/language label +
    copy button) above every fenced block in article content. Runs client-side
-   from Base.astro; extracted to a module so the DOM behavior is testable
-   under jsdom (a phase-1 carry-over closed 2026-07-28). */
+   from the consumer's layout; extracted to a module so the DOM behavior is
+   testable under jsdom (a phase-1 carry-over closed 2026-07-28). */
 /* Island contract (step 9): mount(root, options?) returns a destroy handle;
    claim() makes a second mount over the same pre a no-op. */
 export interface CodeIslandOptions {
@@ -25,18 +25,22 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
 
   const doc = docOf(root);
 
-  /* resetTimer holds the copy-reset setTimeout id, one live per button at
-     most (a second click before the first reset overwrites it, dropping
-     the earlier timer's reference so it can no longer be cleared, which
-     is why doCopy clears the box before replacing it). A plain mutable
-     box, not a field on the mounted entry, so both doCopy and destroy()
-     close over the same cell. */
+  /* timers holds the two pending setTimeout ids per button: the queued
+     status announcement and the label reset, one live each at most (a
+     second click before either fires overwrites its id, dropping the
+     earlier reference so it can no longer be cleared, which is why doCopy
+     clears each before replacing it). A plain mutable box, not a field on
+     the mounted entry, so both doCopy and destroy() close over the same
+     cells and destroy() can cancel both. */
   const mounted: {
     pre: Element;
     bar: HTMLDivElement;
     btn: HTMLButtonElement;
     onClick: () => void;
-    resetTimer: { id: ReturnType<typeof setTimeout> | undefined };
+    timers: {
+      announce: ReturnType<typeof setTimeout> | undefined;
+      reset: ReturnType<typeof setTimeout> | undefined;
+    };
   }[] = [];
 
   for (const pre of root.querySelectorAll(selector)) {
@@ -45,6 +49,13 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     bar.className = "code-island-bar";
     const label = doc.createElement("span");
 
+    /* Visually the button's own text already shows the outcome, but a
+       screen reader is not sat watching the button: role="status" gets
+       the outcome announced as a live region without moving focus. */
+    const status = doc.createElement("span");
+    status.className = "screen-reader-text";
+    status.setAttribute("role", "status");
+
     const file = pre
       .closest("[data-code-filename]")
       ?.getAttribute("data-code-filename");
@@ -56,22 +67,41 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     btn.type = "button";
     btn.textContent = copy.copy;
 
-    const resetTimer: { id: ReturnType<typeof setTimeout> | undefined } = {
-      id: undefined,
-    };
+    const timers: {
+      announce: ReturnType<typeof setTimeout> | undefined;
+      reset: ReturnType<typeof setTimeout> | undefined;
+    } = { announce: undefined, reset: undefined };
 
     const doCopy = async (): Promise<void> => {
+      /* Cleared synchronously, before the outcome is known, so a repeat
+         copy inside the reset window is a real DOM change rather than
+         the same string written over itself. Setting the outcome text
+         itself waits one tick (below) so the clear is its own observable
+         step; a live region that never changes never gets announced. */
+      status.textContent = "";
+
+      let outcome: string;
+
       try {
         await navigator.clipboard.writeText(pre.textContent);
         btn.textContent = copy.copied;
+        outcome = copy.copied;
       } catch {
         btn.textContent = copy.failed;
+        outcome = copy.failed;
       }
 
-      clearTimeout(resetTimer.id);
+      clearTimeout(timers.announce);
+
+      timers.announce = setTimeout(() => {
+        status.textContent = outcome;
+      }, 0);
+
+      clearTimeout(timers.reset);
 
-      resetTimer.id = setTimeout(() => {
+      timers.reset = setTimeout(() => {
         btn.textContent = copy.copy;
+        status.textContent = "";
       }, resetMs);
     };
 
@@ -80,16 +110,17 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     };
 
     btn.addEventListener("click", onClick);
-    bar.append(label, btn);
+    bar.append(label, btn, status);
     pre.before(bar);
-    mounted.push({ pre, bar, btn, onClick, resetTimer });
+    mounted.push({ pre, bar, btn, onClick, timers });
   }
 
   return {
     destroy(): void {
-      for (const { pre, bar, btn, onClick, resetTimer } of mounted) {
+      for (const { pre, bar, btn, onClick, timers } of mounted) {
         btn.removeEventListener("click", onClick);
-        clearTimeout(resetTimer.id);
+        clearTimeout(timers.announce);
+        clearTimeout(timers.reset);
         bar.remove();
         release(pre, "code");
       }