@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.3 → 3.0.0-alpha.5

package/components/ChapterHeader.astro

@@ -1,13 +1,16 @@
 ---
 /**
  * ChapterHeader — renders the metadata block at the top of every chapter.
- * Surfaces provenance signals the LaTeX book conveyed implicitly:
- *   - Part + chapter number (position in the book)
- *   - Volatility class (freshness calibration for the reader)
- *   - Tools compared (scope signal)
- *   - Last verified date (how stale are the claims?)
  *
- * Driven entirely from the chapter's frontmatter (see content.config.ts).
+ * Schema-agnostic: the package supports two profile schemas (academic and
+ * tools), so this component renders only the fields that are present on
+ * the chapter data. Tools-profile metadata (volatility, last_verified,
+ * tools_compared) appears when defined; academic-profile metadata (week,
+ * status) appears in its place.
+ *
+ * Use a chapter card's metadata to calibrate how much trust to place in
+ * its specific claims — stable principles age slowly; feature surfaces
+ * age fast.
  */
 import type { CollectionEntry } from 'astro:content';
 import { getFreshness, freshnessLabel } from '../src/lib/freshness';
@@ -17,45 +20,97 @@ interface Props {
 }
 const { data } = Astro.props;
 
-function formatDate(d: Date): string {
-  return d.toISOString().slice(0, 10);
+// Widen for cross-schema field probing. The consumer's content.config.ts
+// resolves `data` to exactly one of the two schemas at build time; this
+// runtime probe handles either without crashing.
+const d = data as Record<string, unknown>;
+
+const hasToolsMeta =
+  typeof d.volatility === 'string' &&
+  d.last_verified instanceof Date &&
+  Array.isArray(d.tools_compared);
+
+const hasAcademicMeta =
+  typeof d.week === 'number' && typeof d.status === 'string';
+
+function formatDate(date: unknown): string {
+  return date instanceof Date ? date.toISOString().slice(0, 10) : '';
 }
 
-const freshness = getFreshness(data.last_verified, data.volatility);
-const freshnessText =
-  freshness.status === 'fresh'
+// Tools-profile freshness — only when all inputs are present + typed.
+const freshness =
+  hasToolsMeta && d.last_verified instanceof Date && typeof d.volatility === 'string'
+    ? getFreshness(d.last_verified, d.volatility as Parameters<typeof getFreshness>[1])
+    : null;
+
+const freshnessText = freshness
+  ? freshness.status === 'fresh'
     ? 'Fresh'
     : freshness.status === 'verify-soon'
       ? 'Verify soon'
-      : 'Stale';
+      : 'Stale'
+  : null;
+
+// Display strings, profile-tagged for clarity in markup.
+const partLabel = (() => {
+  const p = d.part;
+  if (typeof p === 'number') return `Part ${p}`;
+  if (typeof p === 'string' && p.length > 0) return `Part: ${p}`;
+  return null;
+})();
+const chapterNum =
+  typeof d.chapter === 'number' ? `Chapter ${d.chapter}` : null;
+const weekNum = typeof d.week === 'number' ? `Week ${d.week}` : null;
+const statusBadge =
+  typeof d.status === 'string' ? d.status.replace(/_/g, ' ') : null;
+const title = typeof d.title === 'string' ? d.title : '(untitled)';
+const description = typeof d.description === 'string' ? d.description : null;
+const toolsCompared = Array.isArray(d.tools_compared)
+  ? (d.tools_compared as string[])
+  : [];
+const lastVerified = d.last_verified instanceof Date ? d.last_verified : null;
+const updated = d.updated instanceof Date ? d.updated : null;
+const volatility = typeof d.volatility === 'string' ? d.volatility : null;
 ---
 <header class="chapter-header">
   <div class="chapter-meta">
-    <span>Part {data.part}</span>
-    <span>Chapter {data.chapter}</span>
-    <span>
-      Last verified {formatDate(data.last_verified)}
-      <span
-        class="freshness-badge"
-        data-status={freshness.status}
-        aria-label={freshnessLabel(freshness)}
-        title={freshnessLabel(freshness)}
-      >{freshnessText}</span>
-    </span>
-    {data.updated && <span>Updated {formatDate(data.updated)}</span>}
-  </div>
-  <h1>{data.title}</h1>
-  {data.description && <p class="chapter-description">{data.description}</p>}
-  <div class="chapter-badge-row">
-    <span class="chapter-badge-row-label">Volatility:</span>
-    <span class={`volatility-badge volatility-${data.volatility}`}>
-      {data.volatility}
-    </span>
+    {partLabel && <span>{partLabel}</span>}
+    {chapterNum && <span>{chapterNum}</span>}
+    {weekNum && <span>{weekNum}</span>}
+    {statusBadge && (
+      <span class="status-badge" data-status={d.status as string}>
+        {statusBadge}
+      </span>
+    )}
+    {lastVerified && (
+      <span>
+        Last verified {formatDate(lastVerified)}
+        {freshness && freshnessText && (
+          <span
+            class="freshness-badge"
+            data-status={freshness.status}
+            aria-label={freshnessLabel(freshness)}
+            title={freshnessLabel(freshness)}
+          >{freshnessText}</span>
+        )}
+      </span>
+    )}
+    {updated && <span>Updated {formatDate(updated)}</span>}
   </div>
-  {data.tools_compared.length > 0 && (
+  <h1>{title}</h1>
+  {description && <p class="chapter-description">{description}</p>}
+  {hasToolsMeta && volatility && (
+    <div class="chapter-badge-row">
+      <span class="chapter-badge-row-label">Volatility:</span>
+      <span class={`volatility-badge volatility-${volatility}`}>
+        {volatility}
+      </span>
+    </div>
+  )}
+  {hasToolsMeta && toolsCompared.length > 0 && (
     <div class="chapter-badge-row">
       <span class="chapter-badge-row-label">Tools compared:</span>
-      {data.tools_compared.map((t) => <span class="tool-badge">{t}</span>)}
+      {toolsCompared.map((t) => <span class="tool-badge">{t}</span>)}
     </div>
   )}
 </header>

package/dist/index.mjs

@@ -153,8 +153,8 @@ var ALWAYS_ON_STYLES = [
 var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
 var DEFAULT_ROUTES_ALL = [
   { pattern: "/references", file: "references.astro" },
-  { pattern: "/print", file: "print.astro" },
-  { pattern: "/search", file: "search.astro" }
+  { pattern: "/search", file: "search.astro" },
+  { pattern: "/print", file: "print.astro" }
 ];
 var DEFAULT_ROUTES_TOOLS = [
   { pattern: "/chapters", file: "chapters.astro" },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.5",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -40,6 +40,7 @@
       "types": "./dist/schemas.d.ts",
       "import": "./dist/schemas.mjs"
     },
+    "./package.json": "./package.json",
     "./components/CaseStudy.astro": "./components/CaseStudy.astro",
     "./components/ChapterHeader.astro": "./components/ChapterHeader.astro",
     "./components/ChapterNav.astro": "./components/ChapterNav.astro",
@@ -109,7 +110,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && rm -f dist/types-*.d.ts",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/dist/types-Cz-pwE1N.d.ts

@@ -1,61 +0,0 @@
-import { AstroIntegration, AstroUserConfig } from 'astro';
-
-/**
- * Shared types for @brandon_m_behring/book-scaffold-astro.
- *
- * Public types referenced from PACKAGE_DESIGN.md §4 / §5 / §6. Kept in
- * one place so consumer IntelliSense surfaces a coherent API.
- */
-
-type BookProfile = 'academic' | 'tools' | 'minimal';
-declare const BOOK_PROFILES: readonly ["academic", "tools", "minimal"];
-/**
- * Options for `defineBookConfig`. See PACKAGE_DESIGN.md §4.
- *
- * Note on the index signature: `AstroUserConfig` carries generic
- * parameters (`Locales`, `SessionDriverName`, fonts) that can't be
- * threaded cleanly through a wrapper. Instead we type the package-
- * specific fields strictly and allow arbitrary AstroUserConfig keys
- * via the index signature — consumer types will lint clean but lose
- * full IDE autocomplete on non-package fields. Acceptable trade.
- */
-interface BookConfigOptions {
-    /** Required. Book's deployed origin (sitemap, canonical, Pagefind). */
-    site: string;
-    /**
-     * Optional. Falls back to `process.env.BOOK_PROFILE`, then `'minimal'`.
-     * Explicit param always wins over env.
-     */
-    profile?: BookProfile;
-    /** Optional. Appended to the package-provided integration list. */
-    extraIntegrations?: AstroIntegration[];
-    /**
-     * Optional. CSS basenames to inject in addition to the profile-resolved
-     * set. Cross-profile escape hatch (e.g. an academic book using
-     * `<Convergence>`). Example: `['convergence.css']`.
-     */
-    extraStyles?: string[];
-    /** Optional. Spread-merged into the package-provided markdown config. */
-    markdown?: AstroUserConfig['markdown'];
-    /** Escape hatch for any other AstroUserConfig field. */
-    [key: string]: unknown;
-}
-/** Options for `defineBookSchemas`. See PACKAGE_DESIGN.md §5. */
-interface BookSchemasOptions {
-    profile?: BookProfile;
-    /** Defaults to `'./src/content/chapters'`. */
-    chaptersBase?: string;
-}
-/** Options for the internal `bookScaffoldIntegration`. See PACKAGE_DESIGN.md §6. */
-interface BookScaffoldIntegrationOptions {
-    profile: BookProfile;
-    extraStyles?: string[];
-}
-/** Raised when the resolved profile is not one of `BOOK_PROFILES`. */
-declare class BookConfigError extends Error {
-    constructor(message: string);
-}
-/** Resolve profile from explicit param → env → default. Throws on invalid. */
-declare function resolveProfile(explicit?: BookProfile): BookProfile;
-
-export { BOOK_PROFILES as B, BookConfigError as a, type BookConfigOptions as b, type BookProfile as c, type BookScaffoldIntegrationOptions as d, type BookSchemasOptions as e, resolveProfile as r };