{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "blog-card-grid", "title": "Blog Card Grid", "description": "A four-state article grid: one stretched link per card (category and author stay independently clickable), a featured post that spans two columns, and deliberate, configurable line clamping so mismatched title lengths still line up.", "dependencies": [ "zod", "lucide-react" ], "registryDependencies": [ "utils" ], "files": [ { "path": "src/registry/blocks/blog-card-grid.tsx", "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { ImageOff } from \"lucide-react\"\nimport { cn } from \"@/lib/utils\"\nimport type { BlogAuthor, BlogCardGridData, BlogCardGridItem } from \"./blog-card-grid.contract\"\n\n/**\n * The column count is breakpoint-driven because \"the featured post takes double width\" needs a\n * known count: at 1 column it never spans (a span would push out an implicit column and overflow\n * horizontally at 375px), at 2 it fills the row, at 3 it takes 2/3 — every step stays in the container.\n */\nconst GRID = \"grid gap-6 sm:grid-cols-2 lg:grid-cols-3\"\n\n/** The skeleton count only sets how dense loading looks, not a cap on rows — ready renders every item */\nconst SKELETON_CARDS = 6\n\nconst pulse = \"animate-pulse rounded bg-muted motion-reduce:animate-none\"\n\n/**\n * Clamping here is **deliberate and configurable**, not the accidental cut of a fixed height plus\n * `overflow:hidden`: `lines` is how many lines may show, and 0 (or a negative / NaN / Infinity\n * value) means no clamp — the whole thing renders. `reserve` then holds the box open to that same\n * line count, so a one-line title and a four-line title in the same row still leave the excerpt and\n * footer aligned across cards instead of drifting apart.\n *\n * Inline style rather than `line-clamp-N` because the count comes from a prop: Tailwind's JIT never\n * sees a class name assembled at runtime, so `line-clamp-[3]` silently vanishes and the clamp dies\n * with it.\n */\nfunction clampStyle(lines: number, reserve = false): React.CSSProperties | undefined {\n const n = Math.floor(lines)\n if (!Number.isFinite(n) || n <= 0) return undefined\n return {\n display: \"-webkit-box\",\n WebkitBoxOrient: \"vertical\",\n WebkitLineClamp: n,\n overflow: \"hidden\",\n ...(reserve ? { minHeight: `${n}lh` } : null),\n }\n}\n\nconst firstChar = (word: string) => Array.from(word)[0] ?? \"\"\n\n/** Initials fallback: two word-initials for Latin names; the first two characters for names that are not space-separated (CJK and the like) */\nfunction initialsOf(author: BlogAuthor) {\n if (author.initials) return author.initials\n const words = author.name.trim().split(/\\s+/).filter(Boolean)\n if (words.length === 0) return \"?\"\n if (words.length > 1) return words.slice(0, 2).map(firstChar).join(\"\").toUpperCase()\n const chars = Array.from(words[0])\n return (/[A-Za-z]/.test(words[0]) ? chars.slice(0, 1) : chars.slice(0, 2)).join(\"\").toUpperCase()\n}\n\n/** An invalid date string is neither swallowed nor thrown on: it prints as-is, and `dateTime` still carries exactly what the data said */\nfunction formatDate(formatter: Intl.DateTimeFormat, iso: string) {\n const date = new Date(iso)\n return Number.isNaN(date.getTime()) ? iso : formatter.format(date)\n}\n\nfunction CoverImage({ item, featured }: { item: BlogCardGridItem; featured: boolean }) {\n const [failed, setFailed] = React.useState(false)\n const showImage = Boolean(item.coverUrl) && !failed\n\n /**\n * On a prerendered page a cached image can already have failed before hydration attaches\n * onError — the event never comes and the broken image stays. The ref callback probes once,\n * synchronously.\n */\n const probe = React.useCallback((node: HTMLImageElement | null) => {\n if (node?.complete && node.naturalWidth === 0) setFailed(true)\n }, [])\n\n return (\n \n {showImage ? (\n // eslint-disable-next-line @next/next/no-img-element -- portable registry source, not bound to next/image\n setFailed(true)}\n ref={probe}\n src={item.coverUrl}\n />\n ) : (\n // a neutral icon block instead of the browser's broken image: title, excerpt and author are all still there\n
\n \n
\n )}\n \n )\n}\n\nfunction AuthorByline({ author }: { author: BlogAuthor }) {\n const [failed, setFailed] = React.useState(false)\n const showImage = Boolean(author.avatarUrl) && !failed\n\n const probe = React.useCallback((node: HTMLImageElement | null) => {\n if (node?.complete && node.naturalWidth === 0) setFailed(true)\n }, [])\n\n return (\n \n \n {showImage ? (\n // eslint-disable-next-line @next/next/no-img-element -- portable registry source, not bound to next/image\n setFailed(true)}\n ref={probe}\n src={author.avatarUrl}\n />\n ) : (\n // the name is right beside it, so the initials are decoration — reading them out just repeats it\n {initialsOf(author)}\n )}\n \n {author.href ? (\n // z-10 lifts the secondary link above the card-wide pseudo-element: the author name goes to the author, anywhere else goes to the post\n \n {author.name}\n \n ) : (\n {author.name}\n )}\n \n )\n}\n\nfunction PostCard({\n item,\n titleLines,\n excerptLines,\n dateFormatter,\n headingTag: Heading,\n}: {\n item: BlogCardGridItem\n titleLines: number\n excerptLines: number\n dateFormatter: Intl.DateTimeFormat\n headingTag: \"h2\" | \"h3\"\n}) {\n const featured = item.featured === true\n const minutes = item.readingMinutes === undefined ? undefined : Math.max(1, Math.round(item.readingMinutes))\n\n return (\n \n \n\n
\n {item.category &&\n (item.category.href ? (\n \n {item.category.label}\n \n ) : (\n // no destination, no link affordance: a plain tag\n \n {item.category.label}\n \n ))}\n\n \n {/*\n The legal way to make a whole card clickable: exactly one \"primary\" link in the card,\n with its ::after covering the card. Not an wrapped around the card (that would turn\n the category / author links into nested anchors — invalid HTML), and not a
\n \n )\n}\n\nexport interface BlogCardGridProps extends BlogCardGridData {\n /** Title clamp, in lines; the same height is reserved so cards in a row align internally. 0 = no clamp */\n titleLines?: number\n /** Excerpt clamp, in lines. 0 = no clamp (card height is then set by the longest excerpt) */\n excerptLines?: number\n /** BCP-47 locale for Intl; pass it explicitly so server and client do not each fall back to their own default */\n locale?: string\n onRetry?: () => void\n className?: string\n}\n\nexport function BlogCardGrid({\n status,\n heading,\n subheading,\n items,\n titleLines = 2,\n excerptLines = 3,\n locale = \"en-US\",\n onRetry,\n className,\n}: BlogCardGridProps) {\n const baseId = React.useId()\n\n /**\n * timeZone is pinned to \"UTC\": a date-only ISO string (\"2026-03-04\") parses as UTC midnight, and\n * formatting that in the reader's local zone slips back a day anywhere west of UTC. A publication\n * date should not move with where the reader happens to be.\n */\n const dateFormatter = React.useMemo(\n () => new Intl.DateTimeFormat(locale, { day: \"numeric\", month: \"short\", timeZone: \"UTC\", year: \"numeric\" }),\n [locale],\n )\n\n // with no section heading the card titles are the top level in this block — do not skip a level\n const headingTag = heading ? \"h3\" : \"h2\"\n\n return (\n \n {status === \"ready\" && (heading || subheading) && (\n
\n {heading && (\n

\n {heading}\n

\n )}\n {subheading &&

{subheading}

}\n
\n )}\n\n {status === \"loading\" && (\n <>\n \n Loading posts\n \n
\n {Array.from({ length: SKELETON_CARDS }, (_, i) => (\n \n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n ))}\n
\n \n )}\n\n {status === \"empty\" && (\n
\n

No posts published yet

\n

Articles appear here as soon as the first one ships.

\n
\n )}\n\n {status === \"error\" && (\n
\n

Couldn't load the posts

\n

The content source didn't respond.

\n {onRetry && (\n \n Try again\n \n )}\n
\n )}\n\n {status === \"ready\" && (\n
    \n {items.map(item => (\n \n ))}\n
\n )}\n \n )\n}\n\nexport default BlogCardGrid\n", "type": "registry:block" }, { "path": "src/registry/blocks/blog-card-grid.contract.ts", "content": "import { z } from \"zod\"\n\n/**\n * Interaction-honesty line: the card, category and author links all have to point somewhere real.\n * The contract rejects dead anchors like \"#\" outright — \"render something clickable for now\" is the\n * fake interaction this kind of card grid attracts most, and catching it in the data layer is\n * cheaper than catching it in review.\n */\nconst hrefSchema = z\n .string()\n .min(1)\n .refine(href => href.trim() !== \"\" && !href.trim().startsWith(\"#\"), {\n message: 'href must point at a real destination — dead anchors like \"#\" are rejected',\n })\n\nexport const blogCategorySchema = z.object({\n label: z.string().min(1),\n /** With an href it renders as a link, without one it is a plain tag — nothing gets a clickable look it cannot honour */\n href: hrefSchema.optional(),\n})\n\nexport const blogAuthorSchema = z.object({\n name: z.string().min(1),\n /** Avatar URL; missing **or failing to load** falls back to initials, never a broken image */\n avatarUrl: z.string().optional(),\n /** Overrides the derived initials (mononyms, stage names, non-Latin names) */\n initials: z.string().optional(),\n /** Author page; only rendered as a link when given (a secondary link in the card, never nested inside the stretched one) */\n href: hrefSchema.optional(),\n})\n\nexport const blogCardGridItemSchema = z.object({\n id: z.string(),\n title: z.string().min(1),\n /** Post URL. Every click on the card lands on this one anchor (its pseudo-element covers the card) */\n href: hrefSchema,\n /** Excerpt; clamped to `excerptLines` lines, and omitted entirely when absent */\n excerpt: z.string().optional(),\n coverUrl: z.string().optional(),\n /**\n * Cover alt text. An empty string declares the image decorative (the title already says what it\n * shows) — deliberately so: letting a screen reader skip it beats hearing the title paraphrased.\n */\n coverAlt: z.string().optional(),\n category: blogCategorySchema.optional(),\n author: blogAuthorSchema.optional(),\n /** ISO 8601 date or timestamp. Goes into `