@half-built/astro 0.9.0 → 0.10.0

package/README.md

@@ -57,20 +57,37 @@ consumer config itself.
 
 ## WhenPublished and PostLink
 
-`content/WhenPublished.astro` renders its children only when the post
-at `slug` is visible, so a published post can tease one still in
-draft and the passage appears on its own when the target ships.
 `content/PostLink.astro` links to a post by slug and resolves the
 href at build time through `postPath`, so a re-dated post does not
-strand the links pointing at it. Both take the consumer's collection
-as the `posts` prop (the full collection, drafts included, so an
-unknown slug can throw instead of hiding as "still a draft");
-`WhenPublished` also takes the consumer's draft gate as `showDrafts`,
-and `PostLink` accepts an optional `tip` carried as `data-tooltip` for
-the link-tip island. A consumer wraps each in a one-line site
-component that injects `getCollection` and its own gate, the way the
-blog does. The resolvers live in `lib/drafts.ts` for consumers that
-want the logic without the components.
+strand the links pointing at it. While the target is hidden (a draft, with the
+draft gate off) it renders its text alone, with no element and no
+styling, and becomes a link on its own when the post ships. That makes
+it the right tool for a draft's name in published prose.
+
+`content/WhenPublished.astro` renders its children only when the post
+at `slug` is visible. Use it when a whole phrase only makes sense once
+the post exists ("its own post", "see it here"). An optional `fallback`
+slot renders while the target is hidden:
+
+```mdx
+<WhenPublished slug="my-draft">
+  It has <PostLink slug="my-draft">its own post</PostLink> now.
+  <Fragment slot="fallback">A post on it is coming.</Fragment>
+</WhenPublished>
+```
+
+Both take the consumer's collection as the `posts` prop (the full
+collection, drafts included, so an unknown slug can throw instead of
+hiding as "still a draft") and the consumer's draft gate as
+`showDrafts`. `showDrafts` defaults to false, so a preview build must
+pass its own draft gate through to `PostLink` to keep draft links
+live. `PostLink` also accepts an optional `tip` carried as
+`data-tooltip` for the link-tip island; a hidden `PostLink` drops it. A
+consumer wraps each in a one-line site component that injects
+`getCollection` and its own gate, the way the blog does. The resolvers
+(`postLinkHref`, `resolvePostHref`, `forwardLinkVisible`) live in
+`lib/drafts.ts` for consumers that want the logic without the
+components.
 
 ## Derived excerpts
 

package/package.json

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

package/src/components/content/PostLink.astro

@@ -1,15 +1,22 @@
 ---
-import { resolvePostHref, type Linkable } from "../../lib/drafts";
+import { postLinkHref, type Linkable } from "../../lib/drafts";
 
 interface Props {
   slug: string;
   posts: Linkable[];
+  showDrafts?: boolean;
   tip?: string;
   class?: string;
 }
 
-const { slug, posts, tip, class: className } = Astro.props;
-const href = resolvePostHref(slug, posts);
+const { slug, posts, showDrafts = false, tip, class: className } = Astro.props;
+const href = postLinkHref(slug, posts, showDrafts);
 ---
 
-<a href={href} data-tooltip={tip} class={className}><slot /></a>
+{href ? (
+  <a href={href} data-tooltip={tip} class={className}>
+    <slot />
+  </a>
+) : (
+  <slot />
+)}

package/src/components/content/WhenPublished.astro

@@ -11,4 +11,4 @@ const { slug, posts, showDrafts = false } = Astro.props;
 const visible = forwardLinkVisible(slug, posts, showDrafts);
 ---
 
-{visible && <slot />}
+{visible ? <slot /> : <slot name="fallback" />}

package/src/lib/drafts.ts

@@ -43,17 +43,21 @@ export function forwardLinkVisible(
 /* Post links by slug. A hand-typed post URL bakes in the target's date,
    so a re-dated draft silently breaks every earlier link to it. The
    PostLink content component resolves the slug through postPath() at
-   build time instead. It resolves drafts too, and must: Astro renders
-   MDX slot children eagerly, so a PostLink inside a hidden WhenPublished
-   still runs (learned the hard way 2026-08-24). The deploy-build guard
-   against a bare link to a draft is therefore a test, not a throw here:
-   test/post-link.test.ts asserts no draft slug appears in any built
-   page. Unknown slugs throw for the same reason forwardLinkVisible's do. */
+   build time instead. postLinkHref() is its policy: a visible target
+   gets its href, a hidden one gets null and the component renders its
+   text with no link (owner decision 2026-09-26), so a draft's name can
+   sit in published prose and becomes a link on its own when the draft
+   ships. resolvePostHref() still resolves drafts: consumers use it for
+   lookups keyed by href, and Astro renders MDX slot children eagerly,
+   so a PostLink inside a hidden WhenPublished still runs. The
+   deploy-build guard against a link to a draft stays a consumer test
+   (no draft slug in any built page). Unknown slugs throw for the same
+   reason forwardLinkVisible's do. */
 
 import { postPath } from "./slug";
 
 export interface Linkable {
-  data: { slug: string; date: Date };
+  data: { slug: string; date: Date; draft?: boolean };
 }
 
 export function resolvePostHref(slug: string, posts: Linkable[]): string {
@@ -61,3 +65,14 @@ export function resolvePostHref(slug: string, posts: Linkable[]): string {
   if (!target) throw new Error(`PostLink: no post has slug "${slug}"`);
   return postPath(target);
 }
+
+export function postLinkHref(
+  slug: string,
+  posts: Linkable[],
+  showDrafts: boolean,
+): string | null {
+  const target = posts.find((p) => p.data.slug === slug);
+  if (!target) throw new Error(`PostLink: no post has slug "${slug}"`);
+  if (target.data.draft && !showDrafts) return null;
+  return resolvePostHref(slug, posts);
+}