@integr8-media/config 1.1.0 → 1.2.0

package/README.md

@@ -291,6 +291,157 @@ git push origin v1.0.1
 A package without Trusted Publishing can still pass `secrets: { NPM_TOKEN: ... }` to
 `publish.yml`.
 
+## Registry site
+
+Feature packages that ship a shadcn registry also publish a static site on GitHub Pages: a landing
+page, one docs page per item, the registry JSON (`r/`) and a Ladle playground that the pages embed
+for live previews. The generator lives here, so a new package gets the site without copying files.
+It needs `typescript` installed (it reads the TSDoc comments with the TypeScript parser).
+
+What a package repo adds:
+
+```js
+// registry/site.config.mjs
+import { defineRegistrySite } from '@integr8-media/config/registry-site';
+
+export default defineRegistrySite({
+  brand: { name: 'Integr8 Window Manager', slug: 'window-manager' },
+  categories: [
+    ['shell', 'Shell'],
+    ['window', 'Windows'],
+  ],
+  stories: { window: ['--window-'], taskbar: ['--taskbar-'] },
+  ui: { registryUrl: 'https://minalouisleon.github.io/integr8-ui/r' },
+});
+```
+
+```json
+// package.json
+"scripts": {
+  "site:build": "integr8-registry-site build",
+  "site": "integr8-registry-site dev"
+}
+```
+
+```yaml
+# .github/workflows/registry.yml
+name: Registry
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions: # the reusable workflow cannot grant itself more than this
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  site:
+    uses: <owner>/integr8-config/.github/workflows/registry-site.yml@v1
+```
+
+The repo still owns `scripts/buildRegistry.mjs` (it turns the source into `dist/registry/`). The
+site generator only reads its output.
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `integr8-registry-site build` | Runs `commands.assets` (if set), builds the Ladle playground, runs `commands.registry`, writes `site/` |
+| `integr8-registry-site dev` | `build` for `http://localhost:4173/`, then serves `site/` (`PORT=5000` to change) |
+| `integr8-registry-site serve` | Serves an existing `site/` |
+| `integr8-registry-site enabled` | Prints `true` or `false` (the on/off switch) |
+| `integr8-registry-site size [exports…]` | Bundle-size breakdown (needs `bundleSizes` in the config) |
+
+Options: `--config <file>`, `--site-base-path <path>`, `--no-playground`.
+
+### Turn the site off
+
+One setting, in `package.json`:
+
+```json
+"integr8": { "site": false }
+```
+
+- A missing key means on. Only a JSON boolean is accepted: `"site": "false"` is an error, so a typo
+  never silently builds or skips the site.
+- The workflow's `settings` job reads it first. When it is `false`, the `build` and `deploy` jobs
+  are skipped and the run still succeeds (green, with a notice).
+- Every `integr8-registry-site` command prints a note and exits with code 0, so `npm run site` and
+  `npm run site:build` pass too.
+- `pr-checks.yml` has an input `site-build` (default `false`). When a repo turns it on, it runs
+  `npm run site:build`, which obeys the same switch.
+- A package that has no site needs only this line: no config file, no workflow call.
+
+There is deliberately no second switch (no `enabled` input, no `SITE_ENABLED` variable): two
+settings can disagree, and one committed line is easy to review. To switch the site off for a
+while, commit the one line.
+
+### Config reference
+
+`registry/site.config.mjs` default-exports `defineRegistrySite({...})`. Only `brand.name` is
+required; every other option has a default. Bad input throws `ConfigError` (`INVALID_OPTION`)
+naming the option, such as `registry-site config: "brand.name" is required and must be a non-empty string.`
+Unknown options are errors too (typo guard).
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `brand.name` | Product name, in titles and labels | required |
+| `brand.slug` | Shown after `integr8/` in the header | name without "Integr8", kebab-case |
+| `brand.mark` | Letters in the header badge | `i8` |
+| `brand.eyebrow` | Text above the hero title (`· v<version>` is added) | `Registry` |
+| `brand.heroTitle`, `brand.heroAccent` | Hero title; the accent is shown in the brand gradient | name, no accent |
+| `brand.lead` | Text under the hero title | `description` of `package.json` |
+| `brand.title`, `brand.description` | Landing page `<title>` and meta description | name, `package.json` description |
+| `brand.footer` | Footer start; `{packageName}` and `{version}` are filled in | `{packageName} · v{version}` |
+| `brand.repositoryUrl` | GitHub link in the header | `$GITHUB_REPOSITORY`, else `repository` in `package.json` |
+| `brand.playgroundLink` | "Playground" link in the header | `false` |
+| `brand.extraStats` | Extra hero numbers, `[{ value, label }]` | none |
+| `brand.heroCommand` | Command in the hero | command of the last setup step |
+| `categories` | Ordered `[id, label]` pairs, matched against each item's first category; the rest go under "Other" | categories found in the registry, in order |
+| `stories` | Item → parts of Ladle story ids (a story matches when its id contains a part), or a function `(item) => parts`. Items not listed have no preview | stories whose id starts with `<item>--` |
+| `defaultStory` | Story shown first in the landing preview: an item name or a story id | first story |
+| `ui` | `{ registryUrl, docsUrl?, packageName? }`: the ui registry the items depend on. Ui items link to the ui site, with the ui theme step. Leave out in the ui package | none |
+| `fonts` | `'copy-from-ui'` (copy `dist/fonts.css` and `dist/fonts/` from the installed ui package), `'build'` (copy the ones this repo built into `dist/`), `false` (system fonts) | `'copy-from-ui'` with `ui`, else `false` |
+| `setup` | "Get started": `steps` (`{ title, text?, command }`), `extras` (`{ title, text?, code, caption? }`), `namespace` (alias in `components.json`), `shortNames`, `title`, `accent`, `lead`. Text, commands and code may use `{registryUrl}`, `{uiRegistryUrl}`, `{version}`, `{packageName}`; other `{...}` stay as written | shadcn init, ui theme (with `ui`), add the first item |
+| `copy` | `previewLead`, `componentsLead`: longer landing texts | generic texts |
+| `previewThemes` | `[id, label]` pairs: adds a theme switcher to the previews (`&integr8Theme=<id>`) | none (no switcher) |
+| `themeNote` | `{ item, skip? }`: "add the theme first" note on item pages; `false` for none | the ui theme with `ui`, else none |
+| `bundleSizes` | `{ entry?, ownCodeLabel?, external? }` for `integr8-registry-site size` (esbuild comes with `@size-limit/esbuild`); `false` for off | off |
+| `commands` | `assets` (for example `node scripts/buildAssets.mjs`, needed with `fonts: 'build'`) and `registry` | registry: `node scripts/buildRegistry.mjs` |
+| `registryUrl` | Where `r/` is served; `{name}` and `{version}` are filled in. `REGISTRY_BASE_URL` wins | GitHub Pages URL from `repository` |
+| `playground` | Build and embed the Ladle playground | `true` |
+
+Programmatic use: `buildRegistrySite(options)` writes the site, and `renderSiteFiles(input)` returns
+the pages without touching the file system (pure, for tests).
+
+### Move the site
+
+Set two repository variables (Settings → Secrets and variables → Actions → Variables), or pass
+the same values as workflow inputs `registry-base-url` and `site-base-path`:
+
+- `REGISTRY_BASE_URL`: full URL of the JSON folder, such as `https://integr8-media.com/ui/r`.
+- `SITE_BASE_PATH`: the path the site is served from, such as `/ui/`.
+
+Without them the site is served at `https://<owner>.github.io/<repo>/`.
+
+### One-time Pages setup
+
+In the calling repo, Settings → Pages → Source: **GitHub Actions**. Without it `configure-pages`
+fails ("Get Pages site failed"). The calling workflow must also grant `pages: write` and
+`id-token: write`: a reusable workflow cannot raise its own permissions, and a caller that grants
+less fails at startup.
+
+### Local preview and the `--base` pitfall
+
+`npm run site` builds the site and serves it on `http://localhost:4173/`.
+
+The Ladle playground must be built with `--base <site path>playground/`. Without it, its HTML asks
+for `/assets/...`, which is a 404 under `site/playground/`, so every preview iframe is blank. By
+design, `integr8-registry-site` always passes the right base: `/playground/` locally,
+`${SITE_BASE_PATH}playground/` in CI. If a playground built the wrong way is already in
+`playground/dist`, the site build stops with `PLAYGROUND_BASE_MISMATCH` and the exact command to
+fix it, instead of publishing blank previews. Do not run `ladle build` yourself for the site.
+
 ## API
 
 | Import | Exports |
@@ -298,6 +449,9 @@ A package without Trusted Publishing can still pass `secrets: { NPM_TOKEN: ... }
 | `@integr8-media/config/vitest` | `integr8Vitest(options?)`, `ConfigError` |
 | `@integr8-media/config/tsdown` | `integr8Tsdown(options)`, `ConfigError` |
 | `@integr8-media/config/size-limit` | `integr8SizeLimit(entries)`, `ConfigError` |
+| `@integr8-media/config/registry-site` | `defineRegistrySite(config)`, `buildRegistrySite(options)`, `renderSiteFiles(input)`, `readSiteSwitch(pkg)`, `RegistrySiteError`, `ConfigError`, … (see the API reference) |
+
+The package also has a command, `integr8-registry-site` (see [Registry site](#registry-site)).
 
 Invalid options throw `ConfigError` with `code: 'INVALID_OPTION'`. The API reference is
 generated from TSDoc with `npm run docs` (output in `docs/api/`).