@contentrain/astro-kit 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @contentrain/astro-kit
+
+Copy-in Astro components for Contentrain sites, the shadcn model: a site
+receives the component source and owns it from then on. Nothing here is a
+runtime dependency of the site. The package ships the components, a
+machine-readable catalog, builder mapping tables and a small API to copy
+components into a project.
+
+The components are made for [`templates/astro-starter`](../../templates/astro-starter).
+They read its design tokens and pass its gates: `astro check` with the
+`strictest` preset, knip, a single stylesheet and zero JavaScript by default.
+
+## Components
+
+| id | What it is | JavaScript |
+|---|---|---|
+| `header` | Brand, navigation, optional call to action | none |
+| `nav` | Inline menu with submenus; popover drawer or `<details>` on phones | none |
+| `footer` | Brand, link columns or a link row, social links, copyright | none |
+| `hero` | Page opener: heading, text, actions, image | none |
+| `card-grid` | Grid of cards (features, services, team) | none |
+| `post-card` | One post in a list | none |
+| `cta` | Call-to-action band | none |
+| `faq` | Questions as `<details>`, optional FAQPage JSON-LD | none |
+| `tabs` | Tabbed panels; readable as headed sections without JavaScript | Zag.js |
+| `testimonial` | Quotes with author and role | none |
+| `gallery` | Image grid with a popover lightbox | none |
+| `slider` | Carousel on a scroll-snap row | Embla |
+| `contact-form` | Contentrain Studio form in a section | Studio runtime |
+| `pagination` | WordPress-style `/page/N/` links | none |
+| `breadcrumb` | Ancestors, then the current page, optional JSON-LD | none |
+
+Each component lives in `components/<id>/`:
+
+- `<Name>.astro`: the component. Variants use `tailwind-variants`, props are typed, and every optional prop also accepts `undefined`.
+- `meta.json`: its catalog entry. Props are Contentrain `FieldDef`s with a description; the entry also lists variants, slots, JavaScript, npm dependencies, `sources` (the builder elements it replaces) and accessibility notes.
+- `fixtures.json`: the visual-regression cases. Every variant option is covered.
+
+`components/_shared/` holds `Section`, `Button`, `KitImage` and the value types
+(`ImageInput`, `LinkInput`, `ActionInput`, `NavItem`).
+
+## Tokens
+
+Components use colour roles and widths, never raw values. A site defines them
+in `@theme` (the starter already does): `--color-surface`,
+`--color-surface-muted`, `--color-ink`, `--color-ink-muted`, `--color-line`,
+`--color-accent`, `--color-accent-ink`, `--font-sans`, `--container-prose`,
+`--container-page`, `--container-wide` and `--radius-card`. The same list is in
+`catalog.json` under `tokens`.
+
+## API
+
+```ts
+import { copyComponents, KIT_COMPONENTS_DIR, loadCatalog, loadMapping, planCopy, rulesFor } from '@contentrain/astro-kit'
+
+const catalog = await loadCatalog()
+const plan = planCopy(catalog, ['header', 'card-grid']) // adds nav, the shared files, and the npm packages needed
+await copyComponents(plan, KIT_COMPONENTS_DIR, '/path/to/site') // → src/components/kit/<id>/…
+// install plan.dependencies in the site
+
+const gutenberg = await loadMapping('gutenberg')
+rulesFor(gutenberg, 'core/cover') // → the rule that turns a cover block into a hero, with its prop sources
+```
+
+`validateCatalog`, `componentsForSource`, `validateMapping` and
+`unmappedSources` check the catalog and the mapping tables against each other.
+
+## Mapping tables
+
+`mapping/<builder>.json` (`gutenberg`, `elementor`, `divi`, `classic`) map
+builder elements to components, with a source for each prop from a small closed
+set of expressions (see `src/mapping.ts`). They are versioned, and an element
+no rule covers stays rich text (`fallback: "prose"`). When one rule matches an
+element, the outermost match owns its subtree.
+
+## Development
+
+```bash
+pnpm --filter @contentrain/astro-kit catalog   # regenerate catalog.json from meta.json files
+pnpm --filter @contentrain/astro-kit test      # catalog, mapping and starter-copy checks
+node packages/astro-kit/scripts/visual.mjs --local-sdk [--only <id>] [--update]
+```
+
+`visual.mjs` copies the starter and installs every component into it. It
+renders each fixture at `/kit/<id>/`, type-checking the fixtures against the
+component props, then runs `astro check` and a build. Last, it compares
+screenshots at 390, 768 and 1280 px with `visual/<platform>/`. The starter
+carries some kit components in `src/components/kit/`, and a test keeps those
+copies identical to the source here.