@twobirds/microcomponents 0.13.0 → 0.13.1

package/README.md

@@ -138,7 +138,7 @@ Once installed from npm the same command is available as `mc` (and as `microcomp
 
 ```bash
 mc new my-card [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--force] [--dry-run]
-mc create --namespace <ns> [--dir <path>] [--force] [--dry-run]
+mc create --namespace <ns> [--dir <path>] [--force] [--yes] [--dry-run]
 mc dev [--port <n>] [--host <addr>]
 mc bundle
 mc preview [--port <n>] [--host <addr>]
@@ -165,7 +165,7 @@ npx -p @twobirds/microcomponents mc new my-card --target-html --target-css
 npx -p @twobirds/microcomponents microcomponents-mcp
 ```
 
-The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. `--js` emits a plain JavaScript file for the rapid-prototyping path.
+The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. Every hyphen becomes a folder, so the tag's segments are the DOM containment chain — `<cart-container-articles>` sits inside `<cart-container>`, so it is `src/cart/container/articles.ts` — and the last segment names what the component does, not what shape it is: `panel`, `box`, `wrapper` are superfluous, because a folder level costs a segment that has to say something. `--js` emits a plain JavaScript file for the rapid-prototyping path.
 
 ## Examples
 
@@ -414,7 +414,7 @@ Feel free to contact me for any questions or inquiries:
 
 email [Frank Thürigen](mailto:fthuerigen@gmail.com?subject=Micro%20Components)
 
-You can [fund this](https://www.gofundme.com/f/nachhaltige-programmierung).
+You can [fund this](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=fthuerigen@gmail.com&item_name=Micro+Components&currency_code=EUR).
 
 ## Disclaimer
 

package/dist/cli/index.js

@@ -267,7 +267,7 @@ function packageJson(namespace) {
 			typecheck: "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
 			test: "vitest run"
 		},
-		dependencies: { "@twobirds/microcomponents": "^0.13.0" },
+		dependencies: { "@twobirds/microcomponents": "^0.13.1" },
 		devDependencies: {
 			typescript: "^6.0.3",
 			vitest: "^4.1.10",
@@ -400,7 +400,9 @@ Never write an import map. \`autoload()\` fetches a component by its tag (\`ns-n
 npx mc new ${namespace}-name --target-html --target-css
 \`\`\`
 
-The tag must be kebab-case with at least one hyphen. \`ns-name\` becomes \`src/ns/name.ts\`: the first hyphen becomes the folder, which is the same rule the autoloader uses.
+The tag must be kebab-case with at least one hyphen. Every hyphen becomes a folder, so \`ns-parent-name\` becomes \`src/ns/parent/name.ts\` — the same rule the autoloader uses, so the tag is the file path.
+
+The segments are the DOM containment chain: the namespace, then the components the element sits inside, then the component's own name. \`<cart-container-articles>\` sits inside \`<cart-container>\`, so it is \`src/cart/container/articles.ts\`. The last segment names what the component does, not what shape it is: \`<${namespace}-header-search>\` → \`src/${namespace}/header/search.ts\`. Generic structural words (\`panel\`, \`box\`, \`wrapper\`, \`widget\`, \`view\`) are superfluous — \`<${namespace}-header-panel>\` → \`src/${namespace}/header/panel.js\` buys a folder level that says nothing.
 
 \`--js\` writes \`src/ns/name.js\` instead of \`.ts\`. \`tsc\` compiles only \`.ts\`, so the dev server and \`mc bundle\` copy a plain \`.js\` component to \`build/\` verbatim — it autoloads and bundles like a compiled component, with no type checking and no \`.d.ts\`.
 

package/dist/docs/cli.d.ts

@@ -44,18 +44,25 @@ mc create --namespace shop
 # project "shop" created in shop/ — run: cd shop && pnpm install && pnpm dev
 ```
 
-Flags: `--namespace <ns>` (1 to 4 lowercase letters, required), `--dir <path>` (default:
-the namespace), `--force`, `--dry-run`.
+Flags: `--namespace <ns>` (lowercase letters and digits, starting with a letter, any
+length, required), `--dir <path>` (default: the namespace), `--force`, `--yes` (`-y`,
+skip the confirmation), `--dry-run`. The project owns its namespace, so length is the
+user's call; past 5 characters `mc create` warns and asks the terminal to confirm before
+anything is written, and `--dry-run` warns without prompting.
 
 ## mc dev
 
 Runs `tsc -w` plus a `node:http` server that serves `build/`. The page loads components
 on demand through `autoload()` — nothing is bundled, and a new component is picked up
-without restarting.
+without restarting. The server rewrites the `@twobirds/microcomponents` specifier in the
+JS it serves to the `/microcomponents.min.js` it answers, so the page carries no import
+map, and it mirrors the files `tsc` does not compile — companion assets and plain `.js`
+components — into `build/` next to the compiled component.
 
 ```sh
-mc dev            # dev server on port 5173
+mc dev                 # dev server on port 5173, bound to 127.0.0.1
 mc dev --port 3000
+mc dev --host 0.0.0.0  # widen the bind to the LAN
 ```
 
 ## mc bundle
@@ -70,11 +77,13 @@ mc bundle
 
 ## mc preview
 
-Serves the production site in `public/`.
+Serves the production site in `public/`. Like `mc dev`, it binds to `127.0.0.1` by
+default, so the served files are not reachable off the machine; `--host` widens the bind.
 
 ```sh
-mc preview        # preview server on port 5174
+mc preview                 # preview server on port 5174, bound to 127.0.0.1
 mc preview --port 8080
+mc preview --host 0.0.0.0  # widen the bind to the LAN
 ```
 
 ## mc clean
@@ -101,7 +110,7 @@ mc check
 Reports the version of the installed library, not the version of the project it runs in.
 
 ```sh
-mc --version      # 0.13.0
+mc --version      # 0.13.1
 ```
 
 ## mc --help

package/dist/docs/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/docs/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiHE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/docs/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0HE"}

package/dist/docs/installation.d.ts

@@ -14,10 +14,11 @@ the prompt).
 npx @twobirds/microcomponents create --namespace shop
 # created shop/package.json
 # created shop/opencode.jsonc
+# created shop/src/bundle.json
 # created shop/src/index.html
 # created shop/src/index-dev.html
 # created shop/src/shop/app.ts
-# created shop/src/shop/app.target.html
+# created shop/src/shop/app.html
 # created shop/src/shop/app.target.css
 # created shop/src/shop/bundle.ts
 # ...
@@ -36,7 +37,11 @@ the project.
 `mc new` derives the file path from the tag using the same rule the runtime autoloader
 uses (`shop-app` → `shop/app.ts`), names companion assets after the runtime's asset
 descriptors (`targetHtml` → `app.target.html`), and wires them into a `static assets`
-declaration.
+declaration. Every hyphen becomes a folder, so the segments are the DOM containment
+chain: a child of `<cart-container>` is `<cart-container-articles>` →
+`src/cart/container/articles.ts`. The last segment names what the component does, not
+what shape it is — `panel`, `box`, `wrapper` are superfluous, because a folder level
+costs a segment that has to say something.
 
 ```sh
 mc new shop-app --target-html --target-css

package/dist/docs/installation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/docs/installation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BE;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CE"}
+{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/docs/installation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BE;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkDE"}

package/dist/mcp/api.json

@@ -1,5 +1,5 @@
 {
-  "libraryVersion": "0.13.0",
+  "libraryVersion": "0.13.1",
   "exportedCount": 59,
   "entries": {
     "MC": {

package/dist/mcp/concepts/custom-element-registry.md

@@ -47,6 +47,14 @@ src/
 
 The DOM hierarchy is therefore immediately visible in the file system.
 
+The name is the shortest one that says what the component does. The leaf segment is the
+component's function, not its shape: `<shop-header-search>` → `src/shop/header/search.js`
+says what the child of the header does. `<shop-header-panel>` → `src/shop/header/panel.js`
+is wrong — `panel` describes a shape, so the file carries no information about the
+component, and the folder level the tag creates is paid for by a word that says nothing.
+Generic structural words (`panel`, `box`, `wrapper`, `widget`, `view`) are superfluous:
+the nesting a tag encodes costs a directory, so the segment must be worth it.
+
 ---
 
 ## General-Purpose Components in Side Folders

package/dist/mcp/concepts/mc-types.md

@@ -111,6 +111,11 @@ External design of the composed unit is driven by namespaced CSS custom properti
 </cart-container>
 ```
 
+A child's tag carries its parent's prefix, so its file lands in the parent's folder
+(`<cart-container-articles>` → `src/cart/container/articles.ts`), and the last segment
+names what the child does — `articles`, `checkout`, `pay`. A generic structural word
+(`panel`, `box`, `wrapper`) makes the folder level it creates say nothing.
+
 ### 1d. Leaf Components
 
 Self-contained visual units that project no child custom elements — a button, a badge,

package/dist/mcp/concepts/microcomponent-architecture.md

@@ -16,7 +16,7 @@ Every `.ts` or `.js` file contains exactly **one class**, regardless of which ty
 visual, logic-only, style-only, or pure logic. This applies to `DC` subclasses, `MC`
 subclasses, and any other class defined in `src/`.
 
-Why:
+For the classes the toolchain registers, three mechanisms make the rule loadable:
 
 - **Autoload resolution** — `autoload()` maps a tag name to a single script path
   (`<shop-header>` → `./shop/header.js`). One class per file keeps that mapping
@@ -27,5 +27,25 @@ Why:
 - **Registry clarity** — `defineCE()` is called once per file, so file, class, and
   registered tag stay in a 1:1 relationship.
 
+The three logic types are where the rule is easiest to lose, because none of those three
+mechanisms can catch a violation:
+
+- **Logic-only `DC`** (`static tag = ''`) — the class is registered, so the 1:1 contract
+  holds, and the asset name is the host's tag name, which for a removed host is the
+  registered tag (`app-router` → `./app/router.css`). The class runs setup logic on a
+  host it is attached to with `DC.add(host, key, instance)`: one instance under one key,
+  so a second class in the file is a second attachable unit with no key of its own. Its
+  companions are `.css` and `.json` — the constructor removes the host after the assets
+  are applied, so a markup companion has nothing to inject into.
+- **Style-only `DC`** (`static tag = ''`, `static assets = ['css']`) — the class is a
+  delivery vehicle for one stylesheet. File, class, registered tag, and the `.css`
+  companion are one thing under four names: `page-cockpit` in `src/page/cockpit.ts`
+  fetches `./page/cockpit.css`. A second class in the file would ship a second
+  stylesheet under a basename the first one owns.
+- **Pure logic `MC`** — no tag, no `defineCE`, no autoload path, so nothing in the
+  toolchain sees the file at all. The rule holds for the reason a reusable unit gets its
+  own file: the import is by path, so one file is one capability and the file name is
+  the capability. A helper that is not a class is a utility function, not an `MC`.
+
 Non-class entities that belong to the class — interfaces, types, constants, plain
 functions — may live alongside it. A class that is reusable on its own gets its own file.

package/dist/mcp/concepts/project-layout.md

@@ -4,9 +4,11 @@ A Micro Components project keeps one folder per stage of the chain:
 src/  →  (tsc)  →  build/  →  (bundle)  →  public/
 ```
 
-- `src/` holds the authored sources: component `.ts` files, the companion
-  `.target.html` / `.target.css` / `.shadow.css` assets, the dev shell
-  (`index-dev.html`) and the production shell (`index.html`).
+- `src/` holds the authored sources: component `.ts` files, plain `.js` components
+  written with `mc new --js`, the companion `.target.html` / `.target.css` /
+  `.shadow.css` assets, the bundle barrel `src/<namespace>/bundle.ts` with the
+  `src/bundle.json` that names it, the dev shell (`index-dev.html`) and the production
+  shell (`index.html`).
 - `build/` is the `tsc` output: one `.js` per component at its own autoload path,
   plus the files `tsc` does not compile — mirrored companion assets, plain `.js`
   components, and the dev shell. `mc dev` serves it, so the page loads components
@@ -23,7 +25,8 @@ served from `public/` in production. Do not add a fourth tree for it.
 
 A new component is picked up by the dev server automatically, because `autoload()`
 resolves its tag to a file under `build/`. The bundle is not: the bundler walks a single
-entry, so every component must be imported by the barrel `src/<namespace>/bundle.ts`.
+entry, the one `src/bundle.json` names, so every component must be imported by the barrel
+`src/<namespace>/bundle.ts` that file points at.
 
 ## Shells
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",