@half-built/astro 0.4.2 → 0.6.0

package/src/scripts/core/icons.ts

@@ -6,25 +6,102 @@
    Home: the js package's core (owner decision 1, 2026-08-31); Lucide,
    ISC license, attribution retained. */
 
+interface Glyph {
+  paths: string;
+  fill?: string;
+}
+
+/* Every glyph the package draws, keyed by its Lucide name. Components
+   render one through Icon.astro; client scripts take the ICON_*
+   strings below. Add a glyph here, never as inline <svg> markup in a
+   component (test/icons.test.ts guards that). */
+const GLYPHS = {
+  x: { paths: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>' },
+  /* Play is the one filled icon: a stroke-only triangle reads as a hollow
+     arrow, not a play control. */
+  play: {
+    paths: '<polygon points="7 4 19 12 7 20 7 4"/>',
+    fill: "currentColor",
+  },
+  /* The AI Art badge (CornerBadges.astro). */
+  sparkles: {
+    paths:
+      '<path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>',
+  },
+  pause: {
+    paths:
+      '<line x1="9" x2="9" y1="5" y2="19"/><line x1="15" x2="15" y1="5" y2="19"/>',
+  },
+  "rotate-ccw": {
+    paths:
+      '<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>',
+  },
+  "chevron-left": { paths: '<path d="m15 18-6-6 6-6"/>' },
+  /* Pagination's previous and next (Pagination.astro): arrows, not
+     chevrons, which read too faint in a 30px box. */
+  "arrow-left": { paths: '<path d="m12 19-7-7 7-7"/><path d="M19 12H5"/>' },
+  "arrow-right": { paths: '<path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>' },
+  "chevron-right": { paths: '<path d="m9 18 6-6-6-6"/>' },
+  /* The to-top link (Shell.astro). */
+  "chevron-up": { paths: '<path d="m18 15-6-6-6 6"/>' },
+  /* Day/night toggle in the header (owner request 2026-08-25). */
+  sun: {
+    paths:
+      '<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>',
+  },
+  moon: { paths: '<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>' },
+  /* The header's search button (SiteHeader.astro) and the post card's
+     meta row (PostCard.astro). These replaced Font Awesome glyphs that
+     had been inlined in the templates (owner call 2026-09-10), which
+     also puts every glyph the package ships under the one
+     ICONS-LICENSE. */
+  search: {
+    paths: '<path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/>',
+  },
+  clock: { paths: '<circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/>' },
+  user: {
+    paths:
+      '<path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/>',
+  },
+  calendar: {
+    paths:
+      '<path d="M8 2v3"/><path d="M16 2v3"/><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18"/>',
+  },
+  circle: { paths: '<circle cx="12" cy="12" r="10"/>' },
+} as const satisfies Record<string, Glyph>;
+
+export type IconName = keyof typeof GLYPHS;
+
+export interface IconOptions {
+  /* A CSS length, or a pixel count. The default tracks the parent's
+     font size. */
+  size?: number | string;
+  strokeWidth?: number;
+  class?: string;
+}
+
 /* 1em sizing: icons track their button's font size instead of a fixed
    pixel box. */
 /* pointer-events none: a click on a button must target the button, not
    the decorative svg. A targeted svg detached by an innerHTML swap
    mid-bubble made the plate-modal's veil check read a pause click as
    outside the zone and close the dialog (found 2026-08-23). */
-const icon = (paths: string, fill = "none"): string =>
-  `<svg viewBox="0 0 24 24" width="1em" height="1em" fill="${fill}" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" pointer-events="none" aria-hidden="true">${paths}</svg>`;
+export function iconMarkup(
+  name: IconName,
+  { size = "1em", strokeWidth = 2.5, class: className }: IconOptions = {},
+): string {
+  const glyph: Glyph = GLYPHS[name];
+  const dim = typeof size === "number" ? String(size) : size;
+  const cls = className === undefined ? "" : ` class="${className}"`;
+  return `<svg${cls} viewBox="0 0 24 24" width="${dim}" height="${dim}" fill="${glyph.fill ?? "none"}" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" pointer-events="none" aria-hidden="true">${glyph.paths}</svg>`;
+}
 
-export const ICON_X = icon('<path d="M18 6 6 18"/><path d="m6 6 12 12"/>');
-/* Play is the one filled icon: a stroke-only triangle reads as a hollow
-   arrow, not a play control. */
-export const ICON_PLAY = icon('<polygon points="7 4 19 12 7 20 7 4"/>', "currentColor");
-/* The AI Art badge (CornerBadges.astro). */
-export const ICON_SPARKLES = icon('<path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>');
-export const ICON_PAUSE = icon('<line x1="9" x2="9" y1="5" y2="19"/><line x1="15" x2="15" y1="5" y2="19"/>');
-export const ICON_ROTATE_CCW = icon('<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>');
-export const ICON_CHEVRON_LEFT = icon('<path d="m15 18-6-6 6-6"/>');
-export const ICON_CHEVRON_RIGHT = icon('<path d="m9 18 6-6-6-6"/>');
-/* Day/night toggle in the header (owner request 2026-08-25). */
-export const ICON_SUN = icon('<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>');
-export const ICON_MOON = icon('<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>');
+export const ICON_X = iconMarkup("x");
+export const ICON_PLAY = iconMarkup("play");
+export const ICON_SPARKLES = iconMarkup("sparkles");
+export const ICON_PAUSE = iconMarkup("pause");
+export const ICON_ROTATE_CCW = iconMarkup("rotate-ccw");
+export const ICON_CHEVRON_LEFT = iconMarkup("chevron-left");
+export const ICON_CHEVRON_RIGHT = iconMarkup("chevron-right");
+export const ICON_SUN = iconMarkup("sun");
+export const ICON_MOON = iconMarkup("moon");

package/src/scripts/ecosystem.ts

@@ -34,16 +34,20 @@ function isEntry(value: unknown): value is EcosystemDocEntry {
   if (typeof value !== "object" || value === null) return false;
   const entry = value as Record<string, unknown>;
   return (
-    typeof entry.key === "string" && entry.key !== "" &&
-    typeof entry.label === "string" && entry.label !== "" &&
+    typeof entry.key === "string" &&
+    entry.key !== "" &&
+    typeof entry.label === "string" &&
+    entry.label !== "" &&
     /* href is checked by scheme, not just type, because it is assigned
        straight to link.href below. The document and the cached copy
        are both untrusted input, and a javascript: or data: URL there
        would run on the consumer's origin when clicked. */
     (entry.href === null ||
       (typeof entry.href === "string" && /^https?:\/\//i.test(entry.href))) &&
-    typeof entry.priority === "number" && Number.isFinite(entry.priority) &&
-    typeof entry.family === "string" && entry.family !== ""
+    typeof entry.priority === "number" &&
+    Number.isFinite(entry.priority) &&
+    typeof entry.family === "string" &&
+    entry.family !== ""
   );
 }
 
@@ -110,7 +114,11 @@ function sleep(ms: number): Promise<void> {
 
 async function attemptFetch(endpoint: string): Promise<Attempt> {
   const controller = new AbortController();
-  const timer = setTimeout(() => { controller.abort(); }, ATTEMPT_TIMEOUT_MS);
+
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, ATTEMPT_TIMEOUT_MS);
+
   /* The timer is cleared once in this single finally, which covers the
      header fetch and the body read alike: the 3 second budget bounds
      the whole attempt, not just the response headers, so a stalled
@@ -118,18 +126,25 @@ async function attemptFetch(endpoint: string): Promise<Attempt> {
      forever. */
   try {
     let response: Response;
+
     try {
-      response = await fetch(endpoint, { signal: controller.signal, credentials: "omit" });
+      response = await fetch(endpoint, {
+        signal: controller.signal,
+        credentials: "omit",
+      });
     } catch {
       return { kind: "transport", status: null };
     }
+
     if (!response.ok) return { kind: "transport", status: response.status };
     let text: string;
+
     try {
       text = await response.text();
     } catch {
       return { kind: "transport", status: null };
     }
+
     try {
       return { kind: "body", body: JSON.parse(text) as unknown };
     } catch {
@@ -141,8 +156,13 @@ async function attemptFetch(endpoint: string): Promise<Attempt> {
   }
 }
 
-function readCache(storage: Storage | null, cacheKey: string, now: number): EcosystemDocument | null {
+function readCache(
+  storage: Storage | null,
+  cacheKey: string,
+  now: number,
+): EcosystemDocument | null {
   if (!storage) return null;
+
   try {
     const raw = storage.getItem(cacheKey);
     if (raw === null) return null;
@@ -158,8 +178,14 @@ function readCache(storage: Storage | null, cacheKey: string, now: number): Ecos
   }
 }
 
-function writeCache(storage: Storage | null, cacheKey: string, now: number, document: EcosystemDocument): void {
+function writeCache(
+  storage: Storage | null,
+  cacheKey: string,
+  now: number,
+  document: EcosystemDocument,
+): void {
   if (!storage) return;
+
   try {
     storage.setItem(cacheKey, JSON.stringify({ fetchedAt: now, document }));
   } catch {
@@ -183,17 +209,22 @@ export async function loadDocument(
   for (const delay of [0, ...retryDelaysMs]) {
     await sleep(delay);
     const result = await attemptFetch(endpoint);
+
     if (result.kind === "body") {
       const document = validateDocument(result.body);
+
       if (document) {
         writeCache(storage, cacheKey, now, document);
         return document;
       }
+
       break;
     }
+
     if (result.kind === "content") break;
     if (!retryable(result.status)) break;
   }
+
   return readCache(storage, cacheKey, now);
 }
 
@@ -229,10 +260,15 @@ 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 {
+function entryNode(
+  doc: Document,
+  entry: EcosystemDocEntry,
+  selfKey: string,
+): HTMLElement {
   if (entry.key === selfKey) {
     const self = doc.createElement("span");
     self.className = "footer-sitemap-self";
@@ -243,12 +279,14 @@ function entryNode(doc: Document, entry: EcosystemDocEntry, selfKey: string): HT
     self.textContent = entry.label;
     return self;
   }
+
   if (entry.href !== null) {
     const link = doc.createElement("a");
     link.href = entry.href;
     link.textContent = entry.label;
     return link;
   }
+
   const pending = doc.createElement("span");
   pending.className = "footer-sitemap-pending";
   pending.textContent = entry.label;
@@ -272,13 +310,31 @@ function safeStorage(view: Window | null): Storage | null {
     it has no claim() guard, so a caller that mounts it twice on the
     same document runs the fetch and the swap twice; every known
     caller mounts it once. */
-export async function mountEcosystem(root: Document, opts: EcosystemOptions): Promise<void> {
-  const { endpoint, selfKey, limit = DEFAULT_LIMIT, retryDelaysMs, cacheKey = CACHE_KEY } = opts;
+export async function mountEcosystem(
+  root: Document,
+  opts: EcosystemOptions,
+): Promise<void> {
+  const {
+    endpoint,
+    selfKey,
+    limit = DEFAULT_LIMIT,
+    retryDelaysMs,
+    cacheKey = CACHE_KEY,
+  } = opts;
+
   const list = root.querySelector<HTMLElement>("[data-ecosystem]");
   if (!list) return;
 
   const storage = safeStorage(root.defaultView);
-  const document_ = await loadDocument(endpoint, storage, Date.now(), retryDelaysMs, cacheKey);
+
+  const document_ = await loadDocument(
+    endpoint,
+    storage,
+    Date.now(),
+    retryDelaysMs,
+    cacheKey,
+  );
+
   if (!document_) return;
 
   const entries = sortEntries(document_.entries, selfKey, limit);
@@ -286,15 +342,19 @@ export async function mountEcosystem(root: Document, opts: EcosystemOptions): Pr
 
   const scope = scopeOf(list);
   const fragment = root.createDocumentFragment();
+
   for (const entry of entries) {
     const item = root.createElement("li");
     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/focus-mode.ts

@@ -15,9 +15,13 @@ export interface FocusModeOptions {
   target?: EventTarget;
 }
 
-export const mountFocusMode: Island<FocusModeOptions> = (root, options = {}): IslandHandle => {
+export const mountFocusMode: Island<FocusModeOptions> = (
+  root,
+  options = {},
+): IslandHandle => {
   const el = root as HTMLElement;
   const target = options.target ?? window;
+
   if (!claim(el, "focus-mode")) {
     return {
       destroy(): void {
@@ -26,8 +30,15 @@ export const mountFocusMode: Island<FocusModeOptions> = (root, options = {}): Is
       },
     };
   }
-  const onKeydown = (): void => { el.dataset.focus = "keyboard"; };
-  const onPointerdown = (): void => { el.dataset.focus = "pointer"; };
+
+  const onKeydown = (): void => {
+    el.dataset.focus = "keyboard";
+  };
+
+  const onPointerdown = (): void => {
+    el.dataset.focus = "pointer";
+  };
+
   target.addEventListener("keydown", onKeydown, true);
   target.addEventListener("pointerdown", onPointerdown, true);