create-kerf-component 0.15.2

package/README.md

@@ -0,0 +1,51 @@
+# create-kerf-component
+
+Scaffold a publishable [kerf](https://github.com/brianwestphal/kerf) component
+package that already follows kerf's hard packaging rules — so you don't have to
+reverse-engineer them.
+
+```bash
+npm create kerf-component@latest my-widgets
+# or: npm init kerf-component my-widgets
+# or: npx create-kerf-component my-widgets
+cd my-widgets
+npm install
+npm run build
+```
+
+Pass `.` to scaffold into the current directory. The target directory's basename
+is used as the package name.
+
+## What you get
+
+A ready-to-publish component package that encodes the rules from the kerf docs
+(*Building reusable component packages*):
+
+- **`kerfjs` as a `peerDependency`, `external` in the tsup build** — never
+  bundled, so `isSafeHtml` brand checks and signal identity stay intact across
+  the package boundary.
+- **ESM + `.d.ts` output** via `tsup`, with **subpath exports** (`.` and
+  `./counter`).
+- **`tsconfig` with `jsxImportSource: "kerfjs"`** so the author's `.tsx` compiles
+  against kerf's JSX runtime; consumers need no extra setup.
+- **An example `Counter` component** demonstrating the two patterns every kerf
+  component needs:
+  - **per-instance state via a factory + props** (`createCounter` → `<Counter store={…} />`), and
+  - **a `wire(root)` delegation disposer** (`wireCounter`) instead of inline event handlers.
+
+## Layout produced
+
+```
+my-widgets/
+├── package.json        # peerDependencies.kerfjs, exports map, files: [dist]
+├── tsconfig.json       # jsxImportSource: "kerfjs"
+├── tsup.config.ts      # external: ['kerfjs'], format esm, dts
+├── .gitignore
+├── README.md
+└── src/
+    ├── index.ts        # public barrel
+    └── counter.tsx     # factory + component + wire() disposer
+```
+
+This package is part of the kerf repository and releases in lockstep with
+`kerfjs`.

package/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// create-kerf-component — scaffold a publishable kerf component package that
+// already follows kerf's hard packaging rules (docs/13-component-packages.md):
+// kerfjs as a peerDependency + external in the build (never bundled), ESM +
+// .d.ts output, `jsxImportSource: "kerfjs"`, subpath exports, and an example
+// component showing per-instance state via a factory + props and a `wire(root)`
+// delegation disposer.
+//
+// Usage:
+//   npm create kerf-component@latest <dir>
+//   npm init kerf-component <dir>
+//   npx create-kerf-component <dir>
+//
+// <dir> is the target directory; its basename is the default package name (pass
+// `.` to scaffold into the current directory). No third-party dependencies — the
+// initializer is plain Node so `npm create` runs it with zero install latency.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'template');
+const TOKEN = /__PKG_NAME__/g;
+
+function fail(msg) {
+  process.stderr.write(`create-kerf-component: ${msg}\n`);
+  process.exit(1);
+}
+
+// npm package name rules, trimmed to what we actually need to guard: no spaces,
+// no uppercase, no leading dot/underscore, URL-safe. (Scoped names like
+// `@scope/name` are allowed.)
+function isValidPackageName(name) {
+  return /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
+}
+
+// Recursively walk a directory, returning absolute file paths.
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(abs));
+    else out.push(abs);
+  }
+  return out;
+}
+
+function main(argv) {
+  const target = argv[2];
+  if (target == null || target === '' || target === '--help' || target === '-h') {
+    process.stdout.write(
+      'Usage: npm create kerf-component@latest <dir>\n' +
+        '       (or: npx create-kerf-component <dir>)\n\n' +
+        'Scaffolds a kerf component package into <dir>. Pass `.` for the current directory.\n',
+    );
+    process.exit(target == null || target === '' ? 1 : 0);
+  }
+
+  const targetDir = resolve(process.cwd(), target);
+  const pkgName = target === '.' ? basename(targetDir) : basename(target);
+
+  if (!isValidPackageName(pkgName)) {
+    fail(`"${pkgName}" is not a valid npm package name.`);
+  }
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    fail(`target directory "${target}" already exists and is not empty.`);
+  }
+
+  // Copy the whole template tree, then post-process each file in place: replace
+  // the package-name token and rename the dotfile placeholders npm can't ship
+  // verbatim (`_gitignore` → `.gitignore`).
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+
+  for (const file of walk(targetDir)) {
+    const text = readFileSync(file, 'utf8');
+    if (TOKEN.test(text)) writeFileSync(file, text.replace(TOKEN, pkgName));
+  }
+
+  const dotfiles = [['_gitignore', '.gitignore']];
+  for (const [from, to] of dotfiles) {
+    const src = join(targetDir, from);
+    if (existsSync(src)) renameSync(src, join(targetDir, to));
+  }
+
+  const cdHint = target === '.' ? '' : `  cd ${target}\n`;
+  process.stdout.write(
+    `\nScaffolded kerf component package "${pkgName}" in ${target}\n\n` +
+      'Next steps:\n' +
+      cdHint +
+      '  npm install\n' +
+      '  npm run build      # tsup → ESM + .d.ts (kerfjs stays external)\n' +
+      '  npm run typecheck\n\n' +
+      'Edit src/counter.tsx, then publish with `npm publish --access public`.\n',
+  );
+}
+
+main(process.argv);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "create-kerf-component",
+  "version": "0.15.2",
+  "description": "Scaffold a publishable kerf component package that already follows kerf's hard packaging rules.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Brian Westphal <brian.westphal@bleugris.com>",
+  "homepage": "https://brianwestphal.github.io/kerf/docs/13-component-packages/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brianwestphal/kerf",
+    "directory": "create-kerf-component"
+  },
+  "bugs": {
+    "url": "https://github.com/brianwestphal/kerf/issues"
+  },
+  "keywords": [
+    "kerf",
+    "kerfjs",
+    "create",
+    "scaffold",
+    "initializer",
+    "component"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "create-kerf-component": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  }
+}

package/template/README.md

@@ -0,0 +1,54 @@
+# __PKG_NAME__
+
+A reusable [kerf](https://github.com/brianwestphal/kerf) component package,
+scaffolded with `create-kerf-component`.
+
+## Develop
+
+```bash
+npm install
+npm run build       # tsup → dist/ (ESM + .d.ts); kerfjs stays external
+npm run typecheck
+```
+
+## Use it
+
+A kerf app that already has `jsxImportSource: "kerfjs"` configured can import and
+render the component like any local function — there's no extra toolchain:
+
+```tsx
+import { mount } from 'kerfjs';
+import { Counter, createCounter, wireCounter } from '__PKG_NAME__';
+
+const counter = createCounter(0);          // per-instance state (a factory)
+const root = document.getElementById('app')!;
+
+mount(root, () => <Counter store={counter} label="Clicks" />);
+
+const dispose = wireCounter(root, counter); // delegation disposer (call on teardown)
+```
+
+## The rules this package follows
+
+These are kerf's hard packaging rules (see the kerf docs,
+*Building reusable component packages*). The scaffold encodes them so you don't
+have to:
+
+- **`kerfjs` is a `peerDependency` and is `external` in the build — never
+  bundled.** A bundled second copy of kerfjs would break `isSafeHtml` brand
+  checks and signal identity across the package boundary.
+- **No per-instance state in module scope.** A module-level `signal`/`store` is a
+  singleton shared by every instance and every app. Hand the consumer a factory
+  (`createCounter`) or accept a signal/store via props.
+- **No inline JSX event handlers.** Components are pure `(props) => SafeHtml`
+  string-builders; emit `data-action` hooks and let the host wire events with
+  `delegate()` (see `wireCounter`), which returns a disposer.
+- **Build emits ESM + `.d.ts`; `tsconfig` sets `jsxImportSource: "kerfjs"`.**
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+`prepublishOnly` runs the build first; `files` ships only `dist/` + docs.

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tsbuildinfo

package/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__PKG_NAME__",
+  "version": "0.1.0",
+  "description": "A reusable kerf component package.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./counter": {
+      "types": "./dist/counter.d.ts",
+      "import": "./dist/counter.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "kerfjs": ">=0.14.0"
+  },
+  "devDependencies": {
+    "kerfjs": "^0.15.0",
+    "tsup": "^8",
+    "typescript": "^5"
+  }
+}

package/template/src/counter.tsx

@@ -0,0 +1,70 @@
+import { defineStore, delegate, type SafeHtml } from 'kerfjs';
+
+export interface CounterState {
+  count: number;
+}
+
+/**
+ * (a) Per-instance state via a FACTORY.
+ *
+ * Each call returns an independent store, so two `<Counter>` on the same page —
+ * or two apps importing this package — never share state. The trap to avoid is a
+ * module-scope `signal`/`store`: that would be a singleton shared by every
+ * instance. A reusable component must never own per-instance module state; hand
+ * the consumer a factory (here) or accept a signal/store via props.
+ */
+export function createCounter(start = 0) {
+  return defineStore({
+    initial: (): CounterState => ({ count: start }),
+    actions: (set, get) => ({
+      inc: () => set({ count: get().count + 1 }),
+      dec: () => set({ count: get().count - 1 }),
+    }),
+  });
+}
+
+export type CounterStore = ReturnType<typeof createCounter>;
+
+export interface CounterProps {
+  store: CounterStore;
+  label?: string;
+}
+
+/**
+ * The component is a pure function `(props) => SafeHtml`. It emits stable
+ * `data-action` hooks instead of inline event handlers — inline `onClick={...}`
+ * handlers don't survive kerf's morph (and the `no-inline-jsx-event-handlers`
+ * lint rule flags them). The host wires the events; see `wireCounter` below.
+ */
+export function Counter({ store, label = 'Count' }: CounterProps): SafeHtml {
+  return (
+    <div class="kerf-counter">
+      <button type="button" data-action="counter:dec" aria-label="Decrement">
+        −
+      </button>
+      <output>
+        {label}: {store.state.value.count}
+      </output>
+      <button type="button" data-action="counter:inc" aria-label="Increment">
+        +
+      </button>
+    </div>
+  );
+}
+
+/**
+ * (b) A `wire(root)` delegation disposer.
+ *
+ * Components can't attach their own listeners (no lifecycle, re-rendered every
+ * paint), so the host calls this ONCE at its `mount()` root and disposes on
+ * teardown. `delegate()` lives on the root, not on the component's nodes, so the
+ * single listener survives every re-render. Returns the disposer `delegate()`
+ * hands back — call it when the host unmounts.
+ */
+export function wireCounter(root: HTMLElement, store: CounterStore): () => void {
+  return delegate(root, 'click', '[data-action^="counter:"]', (_event, el) => {
+    const action = el.getAttribute('data-action');
+    if (action === 'counter:inc') store.actions.inc();
+    else if (action === 'counter:dec') store.actions.dec();
+  });
+}

package/template/src/index.ts

@@ -0,0 +1,11 @@
+// Public barrel. Re-export everything consumers import from the package root.
+// (The `./counter` subpath export in package.json lets consumers also import the
+// component directly: `import { Counter } from '__PKG_NAME__/counter'`.)
+export {
+  Counter,
+  createCounter,
+  wireCounter,
+  type CounterProps,
+  type CounterState,
+  type CounterStore,
+} from './counter.js';

package/template/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "noEmit": true,
+
+    // The one piece of kerf-specific wiring: author .tsx compiles against kerf's
+    // JSX runtime. Consumers need no extra setup — your package ships compiled JS
+    // whose JSX is already lowered to `kerfjs/jsx-runtime` calls.
+    "jsx": "react-jsx",
+    "jsxImportSource": "kerfjs"
+  },
+  "include": ["src"]
+}

package/template/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup';
+
+// One entry per `exports` subpath. tsup emits ESM + `.d.ts` for each.
+export default defineConfig({
+  entry: ['src/index.ts', 'src/counter.tsx'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  // THE hard rule: kerfjs must NEVER be bundled. A component returns `SafeHtml`
+  // and reads signals; both rely on the consumer and this package sharing ONE
+  // SafeHtml class and ONE signals instance. Bundling a second copy of kerfjs
+  // would silently break `isSafeHtml` brand checks and signal identity across the
+  // boundary. Keep it external (it's a peerDependency).
+  external: ['kerfjs'],
+});