npm - create-cartbase - Versions diffs - 0.1.3 → 0.1.5 - Mend

create-cartbase 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/package.json +1 -1
package/template/app/docs/BUILD-A-STOREFRONT.md +20 -10
package/template/app/docs/checkout.md +46 -0
package/template/app/docs/components.md +5 -3
package/template/app/docs/products.md +6 -0
package/template/app/docs/search.md +15 -6
package/template/app/package.json +3 -3
package/template/app/postcss.config.cjs +11 -6
package/template/app/src/app/gallery/[slug]/page.tsx +172 -0
package/template/app/src/app/gallery/_components/specimens.tsx +254 -0
package/template/app/src/app/gallery/_components/status.tsx +47 -0
package/template/app/src/app/gallery/_lib/catalog.ts +59 -0
package/template/app/src/app/gallery/_lib/registry.ts +401 -0
package/template/app/src/app/gallery/design-system/page.tsx +353 -0
package/template/app/src/app/gallery/layout.tsx +83 -0
package/template/app/src/app/gallery/page.tsx +81 -0
package/template/app/src/app/globals.css +22 -38
package/template/app/src/app/layout.tsx +12 -0
package/template/app/tsconfig.tsbuildinfo +1 -1
package/template/app/tailwind.config.cjs +0 -9

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md CHANGED Viewed

@@ -36,16 +36,26 @@ cd my-store && bun add @cartbase/storefront
 - The package is **source-shipped TypeScript** — add
   `transpilePackages: ["@cartbase/storefront"]` to `next.config` or nothing
   from it will compile.
-- The Tailwind preset is **Tailwind 3 format** (`tailwind-preset.cjs`).
-  `create-next-app --tailwind` scaffolds Tailwind 4 (CSS-first, no config
-  file) — either install `tailwindcss@3.4` + a `tailwind.config.cjs` with
-  `presets: [require("@cartbase/storefront/tailwind-preset")]` (include the
-  package source in `content`:
-  `"./node_modules/@cartbase/storefront/src/**/*.{ts,tsx}"`), or translate
-  the preset's tokens into Tailwind 4 `@theme` yourself. Then define the
-  shadcn-standard token variables (`--background`, `--primary`, … as raw
-  oklch channels) in your CSS — the working set is
-  `examples/storefront/src/app/globals.css`.
+- **Styling is two imports and nothing else.** Tailwind 4 is CSS-first, so
+  there is no config file and no preset to register. In your `globals.css`:
+  ```css
+  @import "tailwindcss";
+  @import "@cartbase/storefront/theme";
+  /* The package ships TypeScript source, so Tailwind must scan it or the
+     components render unstyled. */
+  @source "../../node_modules/@cartbase/storefront/src";
+  /* Dark mode is class-based: put `.dark` on <html>. */
+  @custom-variant dark (&:where(.dark, .dark *));
+  ```
+  The theme **ships filled**, so the store renders designed before you choose
+  a single value. To make it yours, override the token values (`--primary`,
+  `--background`, `--radius-base`, the font families) after the imports.
+  Never redefine the token *names*: components reference them, and the whole
+  library repaints from the values alone.
 - Pin the package version — storefronts never float `latest`.
 - Monorepo caveat: when the app lives in a workspace, set
   `outputFileTracingRoot` in `next.config` — Next infers the root from

package/template/app/docs/checkout.md CHANGED Viewed

@@ -478,6 +478,52 @@ curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
 ---
+## POST /api/store/checkout-errors — browser-side error reporting
+The browser half of checkout error capture. The server logs every money-path
+failure into the merchant's checkout error log on its own; failures that
+happen only in the customer's browser — a Stripe.js confirm error, a 3DS
+return that comes back not-succeeded, a place-order rejection — are reported
+through this endpoint. `useCheckoutOrchestration` reports them **by
+default**; you only call this yourself if you replaced the hook's `logError`
+and still want the platform log.
+Body (`.strict()`): `error_type` (≤64 chars), `message` (≤2000),
+optional `cart_id`, optional `context` object (redacted values only — ids,
+codes, flags; **never card data, never addresses**; oversized context is
+stored as `{truncated: true}`). Answers `204` always on accepted input;
+`400` malformed; `429` past 60 reports/store/minute. Fire-and-forget: the
+SDK's `reportCheckoutError()` swallows every failure — reporting an error
+must never take a checkout down.
+## Modifying checkout — the laws
+Checkout is **locked space** (LOCK_BOUNDARIES): critical-to-function code is
+closed; customize through props, slots and tokens, never by editing the
+package's files. What that means in practice:
+- **Fork the layout, never the logic.** `useCheckoutOrchestration` is the
+  one brain — session guard, amount sync, dead-PI recovery, 3DS return,
+  compensation-aware completion. A fork of the hook once dropped the
+  session guard and produced zombie Stripe sessions; the hook exists so
+  that class of bug is structurally impossible. Build your own screens on
+  top of the hook; do not reimplement it.
+- **The server owns every amount.** The client never sends an amount;
+  sessions charge `total − gift_card_total` computed server-side. Any
+  checkout change that puts a number in a request body is wrong by
+  construction.
+- **Logging is not optional.** Money failures must reach the merchant: the
+  hook's default sink does this. If you override `logError`, either call
+  `reportCheckoutError()` yourself or accept that browser failures vanish —
+  and that is a defect, not a preference.
+- **Debug output is opt-in.** `useCheckoutOrchestration({ debug: true })`
+  turns on verbose `[buy-click]` console output for local work. It prints
+  the full prepare payload (name, phone, email, address), so it must never
+  ship enabled.
+- **Test against the real wire.** Every request/response shape on this page
+  is executable against a store; a checkout change ships with its route
+  driven end to end, error branches included.
 ## Manual path — collections + sessions (step-by-step)
 ### POST /api/store/payment-collections

package/template/app/docs/components.md CHANGED Viewed

@@ -14,9 +14,11 @@ Import discipline: always import from the subpath
 (`@cartbase/storefront/tracking/meta-pixel`, `@cartbase/storefront/lib/money`) —
 tree-shaking and Next.js RSC boundary detection both work better than via
 barrels. Styling resolves against STOREFRONT theme tokens (`bg-card`,
-`text-foreground`, …, shadcn-standard names) — mount the Tailwind preset
-(`@cartbase/storefront/tailwind-preset`) and define the token variables in the
-app's CSS; no component hardcodes a color.
+`text-foreground`, …, shadcn-standard names) — `@import
+"@cartbase/storefront/theme"` in the app's CSS supplies both the token names
+and a filled default set of values, so components render designed out of the
+box. No component hardcodes a colour; retheming means overriding values, never
+renaming tokens.
 ---

package/template/app/docs/products.md CHANGED Viewed

@@ -86,6 +86,12 @@ foreign key → 400 `invalid_publishable_key`.
       "thumbnail": null,
       "allow_backorder": false,
       "manage_inventory": true,
+      // Computed server-side by the platform's availability predicate:
+      // untracked or backorderable variants are always true; otherwise true
+      // iff available stock (kit-aware, reservations subtracted) is above
+      // zero. Read this — never re-derive stock client-side (the exact
+      // quantity is deliberately not exposed).
+      "in_stock": true,
       "variant_rank": 0,
       "metadata": null,
       "options": [

package/template/app/docs/search.md CHANGED Viewed

@@ -171,15 +171,24 @@ curl -s "$BASE/api/store/products/search" -H "x-client-id: $CLIENT_ID" \
 ## GET /api/store/products/:idOrHandle/related
-- **Purpose** — the PDP's related-products rail. Manual admin picks first
-  (position order), then a DETERMINISTIC fallback fills to `limit`: same
-  primary collection (newest first), then most-shared-tags.
-  `auto_filled: true` when any fallback item is present.
+- **Purpose** — the PDP's product-to-product rails, BOTH of them,
+  discriminated by `kind`:
+  - `kind=related` (default) — the rail below the product. Manual admin picks
+    first (position order), then a DETERMINISTIC fallback fills to `limit`:
+    same primary collection (newest first), then most-shared-tags.
+    `auto_filled: true` when any fallback item is present.
+  - `kind=complementary` — the "goes with this" slot above the product. The
+    merchant's picks in their order and NOTHING else; `auto_filled` is always
+    false. There is no fallback by design: similarity can be computed,
+    complementarity is a merchant judgement, and a guessed upsell beside the
+    buy button is worse than an empty slot. An empty response means render
+    nothing.
 - **Auth** — anon: `x-client-id`; optional publishable key — the anchor
   product must be visible to the key, and scoped-away products never appear
   as related items; optional Bearer JWT (group pricing).
-- **Request** — query `{ limit? (1–24, default 12), currency_code?,
-  region_id? }`. Accepts a product id (`prod_…`) or handle.
+- **Request** — query `{ kind? (related|complementary, default related),
+  limit? (1–24, default 12), currency_code?, region_id? }`. Accepts a product
+  id (`prod_…`) or handle.
 - **Response**
 ```jsonc

package/template/app/package.json CHANGED Viewed

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.4.0",
+    "@cartbase/storefront": "^0.6.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"
@@ -17,9 +17,9 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "autoprefixer": "^10.4.20",
+    "@tailwindcss/postcss": "^4",
     "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.17",
+    "tailwindcss": "^4",
     "typescript": "^5"
   }
 }

package/template/app/postcss.config.cjs CHANGED Viewed

@@ -1,6 +1,11 @@
-module.exports = {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}
+/*
+ * Tailwind 4 ships its own PostCSS plugin and handles vendor prefixing
+ * internally, so the v3 pairing of `tailwindcss` + `autoprefixer` is gone.
+ * There is no tailwind.config file either: the theme is defined in CSS
+ * (see src/app/globals.css and the theme shipped by @cartbase/storefront).
+ */
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+}

package/template/app/src/app/gallery/[slug]/page.tsx ADDED Viewed

@@ -0,0 +1,172 @@
+/**
+ * One component, at its own permanent address.
+ *
+ * This is the page we sit on together: you say "let's do the hero", we open
+ * /gallery/hero, and everything about that one thing is here.
+ *
+ * Variants and states are shown as two separate blocks on purpose. They look
+ * similar and they are not: a variant is a permanent option in the
+ * component's API with an id a theme writes, a state is data the component
+ * has to survive and ships as nothing. Putting them in one row, which this
+ * page used to do, teaches the wrong thing.
+ */
+import Link from "next/link"
+import { notFound } from "next/navigation"
+import { findEntry, GROUPS } from "../_lib/registry"
+import { loadCatalog } from "../_lib/catalog"
+import { SPECIMENS, type StateCase, type Variant } from "../_components/specimens"
+import { StatusLabel } from "../_components/status"
+export const dynamic = "force-dynamic"
+export function generateStaticParams() {
+  return GROUPS.flatMap((g) => g.entries.map((e) => ({ slug: e.slug })))
+}
+export default async function ComponentPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const entry = findEntry(slug)
+  if (!entry) notFound()
+  const build = SPECIMENS[slug]
+  const specimen = build ? build({ catalog: await loadCatalog() }) : null
+  return (
+    <article>
+      <header className="mb-10">
+        <Link
+          href="/gallery"
+          className="text-xs uppercase tracking-widest text-muted-foreground hover:text-foreground"
+        >
+          {entry.group.name}
+        </Link>
+        <div className="flex flex-wrap items-baseline gap-4 mt-2">
+          <h1 className="text-3xl font-semibold">{entry.name}</h1>
+          <StatusLabel status={entry.status} />
+        </div>
+        <p className="text-muted-foreground mt-3 max-w-2xl">{entry.summary}</p>
+      </header>
+      {specimen ? (
+        <div className="space-y-14">
+          {specimen.variants?.length ? (
+            <Block
+              title="Variants"
+              blurb="Deliberate options. Each id below ships in the component's API, so a theme can select it and we can never rename it without breaking every storefront using it."
+              api={specimen.api}
+            >
+              {specimen.variants.map((v) => (
+                <Cell key={v.id} label={v.label} note={v.note} wide={v.wide} id={v.id}>
+                  {v.render}
+                </Cell>
+              ))}
+            </Block>
+          ) : (
+            <Block
+              title="Variants"
+              blurb="This component has none. It renders one way, and everything below is data it has to survive."
+            >
+              <p className="col-span-full text-sm text-muted-foreground">
+                No options to choose from.
+              </p>
+            </Block>
+          )}
+          {specimen.states?.length ? (
+            <Block
+              title="States"
+              blurb="Not choices. The same component receiving different data, which the catalogue produces whether we plan for it or not. These ship as nothing; they exist so we can see what breaks."
+            >
+              {specimen.states.map((s: StateCase) => (
+                <Cell key={s.label} label={s.label} note={s.note} wide={s.wide}>
+                  {s.render}
+                </Cell>
+              ))}
+            </Block>
+          ) : null}
+        </div>
+      ) : entry.status === "missing" ? (
+        <Empty
+          title={`${entry.name} does not exist yet`}
+          body="Nothing in the library renders this. Say the word and we design it here first, then it gets built into the package."
+        />
+      ) : (
+        <Empty
+          title={`${entry.name} exists but has never been reviewed`}
+          body="The code renders in the shop today. It has no specimen here yet, which means we have never put its variants and states side by side and decided whether it is right."
+        />
+      )}
+    </article>
+  )
+}
+function Block({
+  title,
+  blurb,
+  api,
+  children,
+}: {
+  title: string
+  blurb: string
+  api?: string
+  children: React.ReactNode
+}) {
+  return (
+    <section>
+      <div className="mb-6">
+        <h2 className="text-lg font-semibold">{title}</h2>
+        <p className="text-sm text-muted-foreground mt-1 max-w-2xl">{blurb}</p>
+        {api ? (
+          <code className="inline-block mt-3 text-xs bg-muted px-2 py-1 rounded font-mono">
+            {api}
+          </code>
+        ) : null}
+      </div>
+      <div className="grid gap-8 md:grid-cols-2">{children}</div>
+    </section>
+  )
+}
+function Cell({
+  label,
+  note,
+  id,
+  wide,
+  children,
+}: {
+  label: string
+  note?: string
+  id?: string
+  wide?: boolean
+  children: React.ReactNode
+}) {
+  return (
+    <div className={wide ? "col-span-full min-w-0" : "min-w-0"}>
+      <div className="mb-3 flex items-baseline gap-2 flex-wrap">
+        <span className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          {label}
+        </span>
+        {id ? (
+          <code className="text-[11px] font-mono text-muted-foreground/70">{id}</code>
+        ) : null}
+      </div>
+      {note ? <p className="text-xs text-muted-foreground/80 -mt-2 mb-3">{note}</p> : null}
+      <div className="rounded-lg border border-border p-4 bg-background">{children}</div>
+    </div>
+  )
+}
+function Empty({ title, body }: { title: string; body: string }) {
+  return (
+    <div className="rounded-lg border border-dashed border-border p-10 text-center">
+      <p className="font-medium">{title}</p>
+      <p className="text-sm text-muted-foreground mt-2 max-w-md mx-auto">{body}</p>
+    </div>
+  )
+}
+export type { Variant }

package/template/app/src/app/gallery/_components/specimens.tsx ADDED Viewed

@@ -0,0 +1,254 @@
+/**
+ * What each component looks like — split into the two things that are NOT
+ * the same, and that this file previously collapsed into one row.
+ *
+ * **VARIANTS are chosen.** They are deliberate design options that ship as
+ * part of the component's public surface. `variant="outline"` is a string a
+ * theme writes and a merchant's agent reads, so each one needs a stable id
+ * that we can never rename without breaking every storefront using it. A
+ * variant is a promise.
+ *
+ * **STATES are received.** The same component, the same options, different
+ * data: a long title, a missing image, a sold-out product, a reduced price.
+ * Nobody picks these — the catalogue produces them. They ship as nothing at
+ * all. They exist here because a component that only survives tidy data is
+ * not finished, and the only way to know is to see the untidy data next to
+ * the tidy data.
+ *
+ * The rule that follows: **adding a variant is an API decision, adding a
+ * state is a test.** One is expensive and permanent, the other is free.
+ */
+import type { ReactNode } from "react"
+import { Thumbnail } from "@cartbase/storefront/products/thumbnail"
+import { ProductPreview } from "@cartbase/storefront/products/product-preview"
+import { PreviewPrice } from "@cartbase/storefront/products/preview-price"
+import { ImageGallery } from "@cartbase/storefront/products/image-gallery"
+import { getProductPrice } from "@cartbase/storefront/lib/get-product-price"
+import { Button } from "@cartbase/storefront/primitives/ui/button"
+import { Input } from "@cartbase/storefront/primitives/ui/input"
+import { Label } from "@cartbase/storefront/primitives/ui/label"
+import type { StoreProduct } from "@cartbase/storefront/api/products"
+import type { Catalog } from "../_lib/catalog"
+export type SpecimenContext = { catalog: Catalog }
+/** A deliberate option. `id` is the value that ships in the component's API. */
+export type Variant = {
+  id: string
+  label: string
+  note?: string
+  wide?: boolean
+  render: ReactNode
+}
+/** A data condition the component must survive. Ships as nothing. */
+export type StateCase = {
+  label: string
+  note?: string
+  wide?: boolean
+  render: ReactNode
+}
+export type Specimen = {
+  /** How a merchant or theme selects a variant, e.g. `variant="outline"`. */
+  api?: string
+  variants?: Variant[]
+  states?: StateCase[]
+}
+export type SpecimenFn = (ctx: SpecimenContext) => Specimen
+function Absent({ what }: { what: string }) {
+  return (
+    <p className="text-xs text-muted-foreground italic">
+      This store has no product for the “{what}” case.
+    </p>
+  )
+}
+function Price({ product }: { product: StoreProduct }) {
+  const { cheapestPrice } = getProductPrice({ product })
+  if (!cheapestPrice) return <span className="text-xs text-muted-foreground">No price</span>
+  return <PreviewPrice price={cheapestPrice} />
+}
+export const SPECIMENS: Record<string, SpecimenFn | undefined> = {
+  "product-card": ({ catalog: { specimens } }) => ({
+    api: 'isFeatured',
+    variants: [
+      {
+        id: "default",
+        label: "Default",
+        note: "What every grid renders unless told otherwise.",
+        render: specimens.typical ? <ProductPreview product={specimens.typical} /> : <Absent what="typical" />,
+      },
+      {
+        id: "featured",
+        label: "Featured",
+        note: "A wider thumbnail ratio, for a hand-picked position.",
+        render: specimens.typical ? (
+          <ProductPreview product={specimens.typical} isFeatured />
+        ) : (
+          <Absent what="typical" />
+        ),
+      },
+    ],
+    states: [
+      {
+        label: "Long title",
+        note: "78 characters. Where card layouts usually break.",
+        render: specimens.longTitle ? (
+          <ProductPreview product={specimens.longTitle} />
+        ) : (
+          <Absent what="long title" />
+        ),
+      },
+      {
+        label: "No image",
+        note: "The fallback has to look deliberate, not broken.",
+        render: specimens.noImage ? <ProductPreview product={specimens.noImage} /> : <Absent what="no image" />,
+      },
+      {
+        label: "Reduced price",
+        note: "Coming from a real sale price list, not a decorative field.",
+        render: specimens.onSale ? <ProductPreview product={specimens.onSale} /> : <Absent what="reduced" />,
+      },
+      {
+        label: "Sold out",
+        note: "Nothing in the card says so today. That is a finding, not a state.",
+        render: specimens.soldOut ? <ProductPreview product={specimens.soldOut} /> : <Absent what="sold out" />,
+      },
+    ],
+  }),
+  "product-grid": ({ catalog: { all } }) => ({
+    states: [
+      {
+        label: "Eight products together",
+        note: "The real test of the card is its neighbours: different title lengths and image ratios in one row.",
+        wide: true,
+        render: (
+          <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
+            {all.slice(0, 8).map((p) => (
+              <ProductPreview key={p.id} product={p} />
+            ))}
+          </div>
+        ),
+      },
+    ],
+  }),
+  thumbnail: ({ catalog: { specimens } }) => {
+    const p = specimens.typical
+    return {
+      api: 'size="square" | "full" | "small"',
+      variants: [
+        { id: "square", label: "Square", render: <Thumbnail thumbnail={p?.thumbnail ?? null} images={p?.images} size="square" /> },
+        { id: "full", label: "Full", render: <Thumbnail thumbnail={p?.thumbnail ?? null} images={p?.images} size="full" /> },
+        { id: "small", label: "Small", render: <Thumbnail thumbnail={p?.thumbnail ?? null} images={p?.images} size="small" /> },
+      ],
+      states: [
+        {
+          label: "No image at all",
+          note: "Falls through to the placeholder.",
+          render: <Thumbnail thumbnail={null} images={[]} size="square" />,
+        },
+      ],
+    }
+  },
+  "preview-price": ({ catalog: { specimens } }) => ({
+    states: [
+      {
+        label: "Plain",
+        render: specimens.typical ? <Price product={specimens.typical} /> : <Absent what="typical" />,
+      },
+      {
+        label: "Reduced",
+        note: "Server computed the sale price below the original.",
+        render: specimens.onSale ? <Price product={specimens.onSale} /> : <Absent what="reduced" />,
+      },
+    ],
+  }),
+  "image-gallery": ({ catalog: { specimens } }) => ({
+    states: [
+      {
+        label: "Four images",
+        wide: true,
+        render: specimens.gallery ? (
+          <ImageGallery images={specimens.gallery.images ?? []} />
+        ) : (
+          <Absent what="deep gallery" />
+        ),
+      },
+      {
+        label: "One image",
+        wide: true,
+        render: specimens.typical ? (
+          <ImageGallery images={(specimens.typical.images ?? []).slice(0, 1)} />
+        ) : (
+          <Absent what="typical" />
+        ),
+      },
+      { label: "No images", wide: true, render: <ImageGallery images={[]} /> },
+    ],
+  }),
+  button: () => ({
+    api: 'variant="…" size="…"',
+    variants: [
+      { id: "default", label: "Default", note: "Add to cart is this one.", render: <Button>Add to cart</Button> },
+      { id: "secondary", label: "Secondary", render: <Button variant="secondary">Secondary</Button> },
+      { id: "outline", label: "Outline", render: <Button variant="outline">Outline</Button> },
+      { id: "ghost", label: "Ghost", render: <Button variant="ghost">Ghost</Button> },
+      { id: "destructive", label: "Destructive", render: <Button variant="destructive">Remove</Button> },
+      { id: "sm", label: "Small", render: <Button size="sm">Small</Button> },
+      { id: "lg", label: "Large", render: <Button size="lg">Large</Button> },
+    ],
+    states: [
+      {
+        label: "Disabled",
+        note: "What a sold-out add-to-cart looks like.",
+        render: <Button disabled>Add to cart</Button>,
+      },
+      {
+        label: "Full width",
+        note: "How it sits on a product page.",
+        render: <Button className="w-full">Add to cart</Button>,
+      },
+    ],
+  }),
+  input: () => ({
+    states: [
+      {
+        label: "Empty",
+        render: (
+          <div className="space-y-2">
+            <Label htmlFor="g-email">Email</Label>
+            <Input id="g-email" placeholder="you@example.com" />
+          </div>
+        ),
+      },
+      {
+        label: "Filled",
+        render: (
+          <div className="space-y-2">
+            <Label htmlFor="g-name">Full name</Label>
+            <Input id="g-name" defaultValue="Maria Petrova" />
+          </div>
+        ),
+      },
+      {
+        label: "Disabled",
+        render: (
+          <div className="space-y-2">
+            <Label htmlFor="g-locked">Country</Label>
+            <Input id="g-locked" defaultValue="Bulgaria" disabled />
+          </div>
+        ),
+      },
+    ],
+  }),
+}

package/template/app/src/app/gallery/_components/status.tsx ADDED Viewed

@@ -0,0 +1,47 @@
+/**
+ * Status, shown the same way everywhere: a dot in the nav, a word on the page.
+ *
+ * Three states and no fourth, so the board can never be ambiguous about what
+ * is finished. `missing` is deliberately loud — an empty slot with a name is
+ * the roadmap, and hiding it would make the library look more complete than
+ * it is.
+ */
+import type { Status } from "../_lib/registry"
+const COLOUR: Record<Status, string> = {
+  done: "bg-emerald-500",
+  built: "bg-amber-400",
+  missing: "bg-border",
+}
+const WORD: Record<Status, string> = {
+  done: "Agreed",
+  built: "Not reviewed",
+  missing: "Not built",
+}
+const EXPLAIN: Record<Status, string> = {
+  done: "We looked at it together, agreed it, and its styling values are tokens.",
+  built: "The code exists and renders, but we have never reviewed it.",
+  missing: "It does not exist. Building it is the work.",
+}
+export function StatusDot({ status }: { status: Status }) {
+  return (
+    <span
+      className={`inline-block w-1.5 h-1.5 rounded-full shrink-0 ${COLOUR[status]}`}
+      title={WORD[status]}
+    />
+  )
+}
+export function StatusLabel({ status }: { status: Status }) {
+  return (
+    <span className="inline-flex items-center gap-2" title={EXPLAIN[status]}>
+      <StatusDot status={status} />
+      <span className="text-xs uppercase tracking-wide text-muted-foreground">
+        {WORD[status]}
+      </span>
+    </span>
+  )
+}