@half-built/astro 0.1.0 → 0.2.0

package/README.md

@@ -14,3 +14,42 @@ is the design record for this package.
 
 Default icon glyphs are derived from Lucide (https://lucide.dev), ISC
 license. See `ICONS-LICENSE`.
+
+## EditorNote
+
+`content/EditorNote.astro` is a reminder block for content that must
+not ship: by default it renders only when the consuming build runs in
+dev mode, and a deploy build emits nothing for it. A consumer with a
+wider preview concept (the blog's SHOW_DRAFTS builds, for example)
+passes its own gate through the `shown` prop; the component reads no
+consumer config itself.
+
+## Live code colors
+
+`shiki/code-theme` bakes its amber values into every highlighted span
+at build time. `shiki/code-vars` is a Shiki transformer that rewrites
+those baked values to the css package's `--code-token-*` and
+`--code-*` custom properties, so highlighted code follows a runtime
+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.
+
+## Palette token entries
+
+A `content/Palette.astro` entry may carry `token` (a custom property
+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.
+
+## Import notes
+
+Wildcard subpath imports need explicit file extensions under
+TypeScript's bundler mode: `@half-built/astro/lib/slug.ts` and
+`@half-built/astro/components/Shell.astro`, not extensionless forms.
+Vite resolves either; `tsc --noEmit` only accepts the explicit one.
+
+The `Masthead.astro` export is an alias for `SiteHeader.astro`, the
+same component under its public name.

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@half-built/astro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Astro components, islands, and pure helpers for the half-built design system.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/curthenrichs/half-built-ui.git",
+    "directory": "packages/astro"
+  },
   "type": "module",
   "files": ["src", "ICONS-LICENSE"],
   "exports": {
@@ -11,7 +16,8 @@
     "./content/*": "./src/components/content/*",
     "./scripts/*": "./src/scripts/*",
     "./lib/*": "./src/lib/*",
-    "./shiki/code-theme": "./src/shiki/code-theme.mjs"
+    "./shiki/code-theme": "./src/shiki/code-theme.mjs",
+    "./shiki/code-vars": "./src/shiki/code-vars.mjs"
   },
   "peerDependencies": { "astro": "^5.0.0" },
   "publishConfig": { "access": "public" }

package/src/components/PostCard.astro

@@ -90,12 +90,18 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
     z-index: 2;
     font-size: var(--font-size-xl);
   }
-  /* Chip look comes from the .chip pattern; only placement is contextual. */
+  /* 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 {
     position: absolute;
     bottom: 10px;
     left: 10px;
     z-index: 1;
+    display: flex;
   }
   .post-item-content { padding: 15px 0 0; padding-top: 10px; }
   .entry-cat .post-categories {

package/src/components/content/EditorNote.astro

@@ -0,0 +1,57 @@
+---
+/* Editor note: a reminder in content that renders on the dev server
+   and stays out of deploy builds. Moved up from the blog's
+   content/EditorNote.astro (owner call 2026-09-06: it is generic and
+   should have crossed in the 11.3 extraction; the blog swaps onto this
+   copy at its next pin bump). The blog's gate read its own SHOW_DRAFTS
+   config, which a package component must not do, so visibility is the
+   `shown` prop instead: the default is the consumer build's dev mode,
+   and a consumer with a preview concept passes its own wider gate.
+   Anatomy follows Callout (box, label straddling the top rule), but the
+   rule is dashed and amber: nothing else in the system is dashed, so a
+   note cannot be mistaken for content or for a callout. */
+
+/* The label always reads "Editor's Note", with the title after a colon
+   when one is given (owner call 2026-08-27). */
+interface Props { title?: string; shown?: boolean; class?: string }
+const { title, shown = import.meta.env.MODE === "development", class: className } = Astro.props;
+const label = title ? `Editor's Note: ${title}` : "Editor's Note";
+---
+{shown && (
+  <div class:list={["editor-note", "rule-box", className]} role="note">
+    <strong class="editor-note-label boxed-label">{label}</strong>
+    <div class="editor-note-body"><slot /></div>
+  </div>
+)}
+
+<style>
+  /* Box from .rule-box; the dashed amber stroke and the margin are here. */
+  .editor-note {
+    position: relative;
+    border-style: dashed;
+    border-color: var(--accent-1);
+    margin: 30px 0;
+  }
+  .editor-note-label {
+    position: absolute;
+    top: 0;
+    left: 20px;
+    /* Center the label on the 2px top rule, not on the padding-box edge. */
+    transform: translateY(calc(-50% - 2px));
+    padding: 4px 10px;
+    font-size: var(--font-size-xs);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    line-height: 1;
+    color: var(--accent-1-ink);
+    border-color: var(--accent-1);
+  }
+  /* Reads as an annotation, not a paragraph: a step smaller than prose. */
+  .editor-note-body {
+    position: relative;
+    font-size: var(--font-size-sm);
+    color: var(--accent-1-ink);
+  }
+  .editor-note-body > :global(:last-child) { margin-bottom: 0; }
+</style>

package/src/components/content/Palette.astro

@@ -3,8 +3,13 @@
    page: bordered swatch, role, hex. Hand-authored-page component (the
    migrator never emits it). Chip color is per-entry data, so it rides an
    inline background-color, which the html-validate gate whitelists for
-   exactly this dynamic-value case. */
-interface Entry { role: string; hex: string; note?: string }
+   exactly this dynamic-value case.
+   An entry may carry `token` instead of `hex` (owner ask 2026-09-06,
+   the reference site's live token sheet): the chip then paints
+   var(token), following the live cascade with no script, and the hex
+   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;
 ---
@@ -21,9 +26,9 @@ const { entries, class: className } = Astro.props;
     <tbody>
       {entries.map((e) => (
         <tr>
-          <td><span class="palette-chip" aria-hidden="true" style={`background-color:${e.hex}`}></span></td>
+          <td><span class="palette-chip" aria-hidden="true" style={`background-color:${e.token ? `var(${e.token})` : e.hex}`}></span></td>
           <td>{e.role}</td>
-          <td><code>{e.hex}</code></td>
+          <td>{e.token ? <code data-token-hex={e.token}></code> : <code>{e.hex}</code>}</td>
           <td>{e.note}</td>
         </tr>
       ))}

package/src/scripts/ecosystem.ts

@@ -0,0 +1,79 @@
+/* The ecosystem island: the footer's Ecosystem column, fetched at
+   runtime from a shared document so adding a property to the family
+   never means rebuilding every site (design record
+   2026-09-06-ecosystem-endpoint-design.md in this repo's docs).
+
+   The component keeps rendering its typed props, which are the static
+   baseline. This island replaces that list only on a validated,
+   non-empty document that contains the site's own key. Every other
+   path leaves the baseline standing, so a reader with JavaScript off,
+   a dead endpoint or a malformed payload sees a slightly stale footer
+   rather than a blank one.
+
+   The endpoint is a parameter. This package hardcodes no consumer URL. */
+
+export interface EcosystemDocEntry {
+  key: string;
+  label: string;
+  /* null: the property exists but is not deployed. Renders unlinked. */
+  href: string | null;
+  /* Ascending rank, 0 highest. */
+  priority: number;
+  family: string;
+}
+
+export interface EcosystemDocument {
+  version: number;
+  entries: EcosystemDocEntry[];
+}
+
+const SCHEMA_VERSION = 1;
+
+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 !== "" &&
+    (entry.href === null || typeof entry.href === "string") &&
+    typeof entry.priority === "number" && Number.isFinite(entry.priority) &&
+    typeof entry.family === "string" && entry.family !== ""
+  );
+}
+
+/** The document, or null when anything about it is unusable. */
+export function validateDocument(raw: unknown): EcosystemDocument | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const doc = raw as Record<string, unknown>;
+  if (doc.version !== SCHEMA_VERSION) return null;
+  if (!Array.isArray(doc.entries) || doc.entries.length === 0) return null;
+  /* filter, not every: a type predicate narrows the array through
+     filter and does not through every, so this is the form that hands
+     back EcosystemDocEntry[] instead of any[]. Comparing lengths is
+     what makes it a refusal rather than a silent drop of bad rows. */
+  const entries = doc.entries.filter(isEntry);
+  if (entries.length !== doc.entries.length) return null;
+  return { version: SCHEMA_VERSION, entries };
+}
+
+/** The self entry's family first, each group by ascending priority and
+    then label, capped at limit. Null when selfKey is absent, which is
+    the refusal that keeps a site out of a list missing itself. */
+export function sortEntries(
+  entries: EcosystemDocEntry[],
+  selfKey: string,
+  limit: number,
+): EcosystemDocEntry[] | null {
+  const self = entries.find((entry) => entry.key === selfKey);
+  if (!self) return null;
+  const own = self.family;
+  return [...entries]
+    .sort((a, b) => {
+      const aOwn = a.family === own ? 0 : 1;
+      const bOwn = b.family === own ? 0 : 1;
+      if (aOwn !== bOwn) return aOwn - bOwn;
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.label.localeCompare(b.label);
+    })
+    .slice(0, limit);
+}

package/src/shiki/code-vars.mjs

@@ -0,0 +1,33 @@
+// Shiki transformer: rewrite the code theme's baked hex values to the
+// css package's custom properties, so highlighted code follows a live
+// palette override (spec 2026-09-06, live code colors). Shiki inlines
+// literal colors on every span at build; with this transformer the
+// build emits var() instead, and the variables resolve to the exact
+// same hexes until something overrides them, so adopting it changes
+// no rendered pixel. Pass it wherever shiki options go: the transformers
+// prop of astro:components' Code, or markdown.shikiConfig.transformers
+// in a consumer's astro config.
+const HEX_TO_VAR = {
+  "#ffaa3c": "var(--code-token-keyword)",
+  "#ffd18a": "var(--code-token-function)",
+  "#e07c14": "var(--code-token-string)",
+  "#8a7a63": "var(--code-token-comment)",
+  "#e8d9c3": "var(--code-fg)",
+  "#1b140c": "var(--code-bg)",
+};
+
+function swap(node) {
+  const style = node.properties?.style;
+  if (typeof style !== "string") return;
+  node.properties.style = style.replace(/#[0-9a-fA-F]{6}/g, (hex) => HEX_TO_VAR[hex.toLowerCase()] ?? hex);
+}
+
+export default {
+  name: "half-built-code-vars",
+  pre(node) {
+    swap(node);
+  },
+  span(node) {
+    swap(node);
+  },
+};