@integr8-media/config 1.0.0 → 1.2.0

package/README.md

@@ -29,9 +29,17 @@ npm install --save-dev typescript @biomejs/biome vitest @vitest/coverage-v8 tsdo
 
 ```jsonc
 // tsconfig.json
-{ "extends": "@integr8-media/config/tsconfig/react-library.json", "include": ["src"] }
+{
+  "extends": "@integr8-media/config/tsconfig/react-library.json",
+  "include": ["src"],
+  "exclude": ["**/*.config.ts", "playground/dist"]
+}
 ```
 
+`include` and `exclude` always go in the repo's own `tsconfig.json`. A preset can't carry them,
+because TypeScript resolves those paths relative to the preset file, which sits inside
+`node_modules`.
+
 | Preset | Use for |
 | --- | --- |
 | `@integr8-media/config/tsconfig/library.json` | Node or universal library: NodeNext, declarations, isolatedDeclarations |
@@ -63,10 +71,23 @@ Notes:
 - Linter: recommended rules, plus as errors: no default exports (allowed in `*.config.ts`),
   camelCase or PascalCase file names, no explicit `any`, `import type` for type-only imports,
   no non-null assertions. `console` is a warning.
-- Ignores `dist/`, `coverage/`, `playground/dist/` and Markdown files (Biome 2.6 formats
-  Markdown, which would rewrite docs such as `docs/SPEC.md`). Needs Biome 2.6 or newer.
+- Ignores `dist/`, `coverage/`, `playground/dist/`, `docs/api/` (TypeDoc output),
+  `test-results/` and `playwright-report/` (Playwright output), `.vscode/` and Markdown files
+  (Biome 2.6 formats Markdown, which would rewrite docs such as `docs/SPEC.md`). Needs Biome
+  2.6 or newer.
+- `vcs` is on (`clientKind: "git"`, `useIgnoreFile: true`), so Biome also skips everything in
+  `.gitignore`. Biome fails if there is no `.gitignore` in the folder where it runs, so every
+  repo needs one (any git repo has one already).
+- The CSS parser accepts Tailwind v4 directives (`@theme`, `@apply`, `@source`...). Repos
+  without Tailwind are not affected.
+- Overrides that turn rules off:
+  - `*.config.{ts,mts,js,mjs}`: `style.noDefaultExport`.
+  - `.size-limit.{js,mjs,ts}`: `style.noDefaultExport` and `style.useFilenamingConvention`
+    (size-limit needs a default export, and the file name starts with a dot).
+  - `playground/config.{js,mjs,ts}`: `style.noDefaultExport` (the Ladle config).
+  - `scripts/**`: `suspicious.noConsole` (build scripts print progress).
 - If your `biome.json` sets `files.includes`, Biome adds it to the preset's list, so list only
-  your extra ignores (for example `"!!.vscode"`) and don't repeat `"**"`.
+  your extra ignores (for example `"!!.idea"`) and don't repeat `"**"`.
 
 ### Vitest
 
@@ -74,12 +95,39 @@ Notes:
 // vitest.config.ts
 import { integr8Vitest } from '@integr8-media/config/vitest';
 
-export default integr8Vitest({ environment: 'node', coverageThreshold: 80 });
+export default integr8Vitest({
+  environment: 'node',
+  coverageThreshold: 80,
+  setupFiles: './test/setup.ts', // optional: string or list of strings
+});
 ```
 
 v8 coverage on `src/**` (tests, `src/index.ts` and `playground/` excluded). The run fails when
-line coverage is below the threshold. `environment: 'jsdom'` needs `jsdom` installed. To add
-your own settings, wrap it with `mergeConfig` from `vitest/config`.
+line coverage is below the threshold. `environment: 'jsdom'` needs `jsdom` installed.
+
+- `setupFiles` goes to `test.setupFiles` (for example a Testing Library setup file). It takes a
+  non-empty string or a non-empty list of non-empty strings; anything else throws
+  `ConfigError` with `INVALID_OPTION`.
+- Test collection excludes Vitest's defaults plus `playground/**`, so Playwright specs such as
+  `playground/smoke.spec.ts` are not run by `vitest run`.
+
+For settings the preset doesn't have, wrap it with `mergeConfig` from `vitest/config`:
+
+```ts
+// vitest.config.ts
+import { integr8Vitest } from '@integr8-media/config/vitest';
+import { defineConfig, mergeConfig } from 'vitest/config';
+
+export default mergeConfig(
+  integr8Vitest({ environment: 'jsdom', setupFiles: './test/setup.ts' }),
+  defineConfig({
+    test: {
+      // Process CSS files that tests import with ?raw.
+      css: { include: [/\.css$/] },
+    },
+  }),
+);
+```
 
 ### tsdown
 
@@ -100,15 +148,34 @@ dependencies stay external. Files are always named `.mjs` / `.d.mts`, so point `
 }
 ```
 
-### size-limit
+Option `unbundle?: boolean` (default `false`): with `true`, every source file is built as its own
+output file instead of one bundle. Use it for React libraries whose files start with
+`'use client'`. Each file keeps its own directive, so a Next.js server component can import the
+non-client exports from the same package. Rolldown warns `MODULE_LEVEL_DIRECTIVE` for every such
+file; with `unbundle: true` the preset hides that warning, because the directive is kept. With
+`false` the warning stays, because it is real there. A value that is not a boolean throws
+`ConfigError` with `INVALID_OPTION`.
 
 ```ts
-// .size-limit.ts
+export default integr8Tsdown({
+  entry: ['src/index.ts', 'src/Button.tsx'],
+  platform: 'browser',
+  unbundle: true,
+});
+```
+
+### size-limit
+
+```js
+// .size-limit.mjs
 import { integr8SizeLimit } from '@integr8-media/config/size-limit';
 
 export default integr8SizeLimit([{ path: 'dist/index.mjs', limit: '10 kB' }]);
 ```
 
+Use `.size-limit.mjs`: it loads without a TypeScript loader, and the Biome preset has an override
+for it (a default export and a dotted file name).
+
 Each entry takes `path`, `limit`, and optionally `name` and `import`. size-limit needs a
 plugin: `@size-limit/file` measures built files; `@size-limit/esbuild` is needed for `import`.
 
@@ -121,8 +188,22 @@ extends:
 ```
 
 - pre-commit: `biome check --write` on staged files, fixes re-staged.
-- pre-push, in order, stopping at the first failure: `typecheck`, `test:coverage`, `build`, and
-  `playground:smoke` when that script exists.
+- pre-push, in order, stopping at the first failure: `typecheck`, `test:coverage`, `build`.
+
+`playground:smoke` is not in the base: it builds the whole playground and runs Playwright, which
+is too slow for every push. A repo that wants it adds it back in its own `lefthook.yml`; the
+base's `piped: true` then runs it last:
+
+```yaml
+# lefthook.yml
+extends:
+  - node_modules/@integr8-media/config/lefthook/base.yml
+pre-push:
+  commands:
+    playground-smoke:
+      priority: 4
+      run: npm run playground:smoke
+```
 
 Add `"prepare": "lefthook install"` to your scripts so hooks are installed after `npm install`.
 
@@ -136,8 +217,9 @@ Add `"prepare": "lefthook install"` to your scripts so hooks are installed after
   "test": "vitest run",
   "test:coverage": "vitest run --coverage",
   "build": "tsdown",
-  "playground": "ladle serve",
-  "playground:smoke": "playwright test",
+  "playground": "ladle serve --config playground",
+  "playground:build": "ladle build --config playground --outDir playground/dist",
+  "playground:smoke": "npm run playground:build && playwright test",
   "size": "size-limit",
   "check:exports": "publint && attw --pack --profile esm-only"
 }
@@ -146,9 +228,14 @@ Add `"prepare": "lefthook install"` to your scripts so hooks are installed after
 `--profile esm-only` tells attw not to report the CommonJS problems that every ESM-only package
 has.
 
+A package that exports CSS files must exclude them from attw, which only knows JavaScript and
+types: `attw --pack --profile esm-only --exclude-entrypoints ./styles.css`.
+
 ### GitHub Actions
 
-The workflows live in this GitHub repo, not in the npm package. Because the repo is private, its
+The workflows live in this GitHub repo, not in the npm package. Until a `v1` tag exists, point
+callers at `@main` (`.../pr-checks.yml@main`); once it exists, switch them to `@v1`. The examples
+below show `@v1`. Because the repo is private, its
 **Settings → Actions → General → Access** must allow access from your other repositories.
 
 ```yaml
@@ -168,13 +255,14 @@ jobs:
 on:
   push:
     tags: ["v*.*.*"]
+permissions:
+  contents: read
+  id-token: write # npm Trusted Publishing
 jobs:
   publish:
     uses: <owner>/integr8-config/.github/workflows/publish.yml@v1
     with:
-      provenance: false # true only for public repos (then also grant id-token: write)
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      provenance: false # true only for public repos
 ```
 
 - `pr-checks.yml`: install, lint, typecheck, test:coverage, build, size, check:exports.
@@ -182,6 +270,178 @@ jobs:
 - `publish.yml`: checks the tag is `vX.Y.Z`, is on main and matches `package.json`; then
   install, build, test and `npm publish --access public`.
 
+#### Publishing with npm Trusted Publishing
+
+No npm token is stored in GitHub. The first version of a package has to be published by hand
+(`npm publish --access public`), because npm only offers Trusted Publishing for existing
+packages. Then, once per package:
+
+1. On npmjs.com open the package → **Settings → Trusted Publisher → GitHub Actions**.
+2. Enter the GitHub owner, the repo, and the workflow file the tag starts (`release.yml`).
+3. After one release works, set **Publishing access** to "Require two-factor authentication
+   and disallow tokens".
+
+To release: bump `version` in `package.json` by hand, merge to `main`, then push the tag:
+
+```sh
+git tag v1.0.1
+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 |
@@ -189,6 +449,9 @@ jobs:
 | `@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/`).

package/biome/biome.json

@@ -1,6 +1,26 @@
 {
   "files": {
-    "includes": ["**", "!**/dist", "!**/coverage", "!**/playground/dist", "!**/*.md"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/coverage",
+      "!**/playground/dist",
+      "!**/docs/api",
+      "!**/test-results",
+      "!**/playwright-report",
+      "!**/.vscode",
+      "!**/*.md"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
   },
   "formatter": {
     "enabled": true,
@@ -56,6 +76,37 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/.size-limit.js", "**/.size-limit.mjs", "**/.size-limit.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off",
+            "useFilenamingConvention": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/playground/config.js", "**/playground/config.mjs", "**/playground/config.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/scripts/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
     }
   ]
 }