@naturaldesign/dev 0.0.0-stage → 0.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Fitch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @naturaldesign/dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional, development-only plugin for apps you open in a Natural Design webframe or use as a component library. It stamps JSX so every element names its source exactly:
+
+```html
+<div data-nd-source="src/app/page.tsx:42:7" data-nd-owner="src/components/Hero.tsx:Hero">
+```
+
+- `data-nd-source`: the file (relative to the project root), line and column of a host element's opening tag (`div`, `p`, `section`…), where an edit to it lands.
+- `data-nd-owner`: the exported component whose body the host element sits in (`file:ExportName`, `default` for a default export), so a component's elements group into one instance with no fiber, server components included. Omitted outside exported PascalCase components; an anonymous default export counts, named after its file.
+- `data-nd-call`: on component elements (`<Card>`, `<ui.Card>`, `<motion.div>`), the call site, passed as a prop. React ignores a prop a component does not read; a component that spreads `...rest` onto a host element carries it to the DOM, harmlessly. `Fragment` and `*.Fragment` never get one. A component that iterates its props or uses exact prop-types goes in `exclude`.
+
+With stamps on the page, the webframe names an element's source exactly, pairs re-rendered elements by their source, and recognises the page's render of markup it just wrote, instead of inferring all of that from the framework's debug data. Pages without the plugin keep working through the inference path. Nothing is stamped in production builds.
+
+Every entry point takes the same stamp options: `exclude` (component names, `Foo` or `Foo.Bar`), `calls: false` and `owners: false` to turn either stamp off.
+
+## Setup
+
+```sh
+npx @naturaldesign/dev init        # or: pnpm dlx / bunx @naturaldesign/dev init
+```
+
+Adds the package as a dev dependency with the project's package manager (from its lockfile) and wires the plugin into `next.config.*` or `vite.config.*`, as below. A config that already uses the plugin is left alone. `--no-install` only edits the config. Restart the dev server afterwards.
+
+## Next.js
+
+```js
+// next.config.mjs
+import { withNaturalDesign } from '@naturaldesign/dev/next'
+export default withNaturalDesign({ /* your config */ }, { exclude: ['Trans'] })
+```
+
+Adds a loader for `.jsx`/`.tsx` outside `node_modules` under `next dev` (webpack and Turbopack). Server and client compiles both stamp, so server-rendered markup carries the attributes and hydration sees the same values on both sides. The loader also keeps the component index and the render registry (below). Options: `root`, `exclude`, `calls`, `owners`, `register`, `index`, `indexFolders`.
+
+## Vite
+
+```js
+// vite.config.ts
+import naturalDesign from '@naturaldesign/dev/vite'
+export default { plugins: [naturalDesign({ exclude: ['Trans'] }), react()] }
+```
+
+Runs before the JSX transform, in `vite dev` only. Options: `root`, `exclude`, `calls`, `owners`, `index`, `indexFolders`, `registry`, `styles`.
+
+## Babel
+
+```js
+plugins: [['@naturaldesign/dev/babel', { root: process.cwd(), exclude: ['Trans'] }]]
+```
+
+For `@vitejs/plugin-react`'s `babel` option or any Babel setup; a no-op when `NODE_ENV=production`. Stamps only (no index or registry).
+
+## Component index
+
+One entry per exported component in `src/components`, `components`, `src/lib/components`, `app/components` and `src/ui` (stories, tests and `.d.ts` skipped):
+
+```json
+{ "name": "Button", "file": "src/components/Button.tsx", "exportName": "Button", "framework": "react",
+  "props": [{ "name": "size", "type": "enum", "options": ["sm", "md", "lg"], "optional": true, "default": "md" }] }
+```
+
+Prop types are `enum` (string literal unions, with `options`), `text`, `number`, `boolean`, `slot` (`children`, `ReactNode`, `ReactElement`, Svelte `Snippet`, Vue/Svelte/Astro `<slot>`; an unnamed slot is `children`) and `other` (functions, objects, anything imported that does not resolve). Defaults are static values from destructuring, `withDefaults`, `export let` or Vue's `default:`.
+
+- React (`.tsx`/`.jsx`, exported PascalCase function, const, `memo`/`forwardRef` or class): the type of the first parameter through the project's own `typescript` (loaded from its node_modules, reusing one program), so imported types and `VariantProps<typeof cva>` resolve. Props declared only in `node_modules` types (`ButtonHTMLAttributes`…) are left out, except `children`. Without `typescript`, `@babel/parser` reads local types only.
+- Svelte: `let { … }: Props = $props()` (Svelte 5) or `export let` (Svelte 3/4).
+- Vue: `defineProps<T>()`, `withDefaults(defineProps<T>(), {…})`, `defineProps({…})` or the Options API's `props`.
+- Astro: `interface Props` / `type Props` in the frontmatter, defaults from `Astro.props`.
+
+Where it is served:
+
+- Vite: `GET /__natural/components.json` returns `{ root, components }` (CORS open, recomputed after source changes).
+- Next (no routes from a config): the loader writes one descriptor per component file it compiles to `<root>/.next/natural/index/<encodeURIComponent(file)>.json`, `{ file, framework, components }`, shortly after the compile, and removes it when the file no longer exports a component. Only files a page has imported are compiled, so the folder fills as the app is used.
+- CLI: `naturaldesign-dev index <root> [--folders a,b] [--no-typescript]` prints `{ root, components }`.
+- Node: `indexComponents(root, { folders, typescript })` from `@naturaldesign/dev`.
+
+## Render registry
+
+Mounts a component by name inside the running app, with the app's own framework instance, so hooks and context work.
+
+- Vite: the virtual module `virtual:natural-design/registry` is injected into the app's pages and installs `window.__nd`: `components` (name → `{ name, file, exportName, framework, load() }`; a clashing name is keyed `file#exportName`), `register(name, component, file, exportName)`, `render(name, props, element)` (resolves after mount and two frames) and `unmount(element)`. React 18/19 mounts through the project's `react-dom/client`; Svelte (5 `mount`, 4 `new`) and Vue (`createApp`) are best effort; Astro cannot mount in a browser. A prop value `{ "__html": "…" }` is slot markup, rendered as each framework's children.
+- `GET /__natural/host` is a bare page (the project's `<html>`/`<body>` attributes, Vite's client, the React refresh preamble) with the project's global stylesheet (found from `index.html` and the entry's CSS imports; override with `styles`) and the registry, through `virtual:natural-design/host`. `?component=Button&props={…}` renders straight into `#nd-host-root`.
+- `natural.config.(tsx|ts|jsx|js|mjs)` at the root may export `decorator`, a component that wraps every rendered component in the app's providers (React).
+- Next: the loader appends `window.__nd.register(name, Component, file, exportName)` to `'use client'` files for each exported component with a binding (client only; never on the server). When the agent has not installed `register` yet, the component waits in `window.__nd.components[name].component`. Server components are not registered.
+
+## Derive
+
+```sh
+naturaldesign-dev derive <root> <file> <exportName> --out <dir> [--props '{"size":"lg"}'] [--esbuild dir] [--node-paths a,b] [--bundler vite|esbuild] [--styles a,b]
+```
+
+Bundles one component into `<out>/component.js`, an ES module exporting `mount(element, props)` → `{ update(props), unmount() }`, `defaultProps` (from `--props`) and `meta`, and `<out>/component.css`. Host elements carry `data-nd-source` and `data-nd-owner` (React). A render error leaves the container empty with `data-nd-error` on it. Prints `{ ok, partial, js, css, warnings, bundler, framework, stubs }` and exits 1 when `ok` is false.
+
+- With `node_modules` and Vite: the project's own Vite in library mode with its config file, so its plugins, Tailwind/PostCSS and aliases apply; everything bundled, the project's externals and chunking overridden.
+- Otherwise esbuild: the project's, then `--esbuild` (an esbuild package folder, or a folder whose node_modules has one, e.g. the app's sidecar), then `$NATURAL_ESBUILD`, then this package's own. The project's PostCSS config runs over project CSS and Svelte compiles through the project's `svelte/compiler`; Vue and Astro need Vite. Every import that does not resolve becomes a stub whose exports are components rendering their children, and the result is `partial` (also whenever the project has no `node_modules`). If the framework runtime itself is stubbed, `ok` is false: `--node-paths` names folders to resolve `react`/`react-dom` from.
+- `next/link`, `next/image`, `next/font/*`, `next/navigation`, `next/router`, `next/head`, `next/script`, `next/dynamic`, `server-only` and `client-only` are the plugin's own shims in both paths. Nothing else in a component is rewritten: one that does not build reports why.
+- Async server components are refused (they cannot mount in a browser). Astro components are refused.
+- In node: `derive({ root, file, exportName, out, props, esbuild, nodePaths, bundler, styles })` from `@naturaldesign/dev`. The CLI changes directory to `<root>` first, since Tailwind resolves its sources from there; do the same when calling `derive` directly.
+
+## Svelte, Astro, Vue
+
+The stamps are JSX-only: their dev builds already record each element's source, which the webframe reads directly. The index and the registry cover them as above.