uidex 0.2.1 → 0.3.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uidex",
-  "version": "0.2.1",
-  "description": "A framework-agnostic library for highlighting and annotating UI elements",
+  "version": "0.3.0",
+  "description": "Convention-driven UI element registry and devtools surface for React apps.",
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,17 +12,26 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
-    },
-    "./core/style.css": "./dist/core/style.css",
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
       "require": "./dist/react/index.cjs"
     },
+    "./cloud": {
+      "types": "./dist/cloud/index.d.ts",
+      "import": "./dist/cloud/index.js",
+      "require": "./dist/cloud/index.cjs"
+    },
+    "./headless": {
+      "types": "./dist/headless/index.d.ts",
+      "import": "./dist/headless/index.js",
+      "require": "./dist/headless/index.cjs"
+    },
+    "./scan": {
+      "types": "./dist/scan/index.d.ts",
+      "import": "./dist/scan/index.js",
+      "require": "./dist/scan/index.cjs"
+    },
     "./playwright": {
       "types": "./dist/playwright/index.d.ts",
       "import": "./dist/playwright/index.js",
@@ -32,34 +41,21 @@
       "types": "./dist/playwright/reporter.d.ts",
       "import": "./dist/playwright/reporter.js",
       "require": "./dist/playwright/reporter.cjs"
-    },
-    "./styles.css": "./dist/core/style.css"
+    }
   },
-  "sideEffects": [
-    "*.css"
-  ],
+  "sideEffects": false,
   "files": [
     "dist",
-    "claude",
-    "uidex.schema.json"
+    "templates"
   ],
   "bin": {
-    "uidex": "dist/scripts/cli.cjs"
+    "uidex": "dist/cli/cli.cjs"
   },
-  "scripts": {
-    "dev": "tsup --watch",
-    "build": "npm run generate:css && tsup && npm run build:css",
-    "build:css": "cp src/core/style.css dist/core/style.css",
-    "generate:css": "tsx scripts/generate-css-text.ts",
-    "scan": "tsx scripts/cli.ts scan",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/",
-    "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx,css}\"",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm run test:run && npm run typecheck"
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40",
@@ -67,54 +63,76 @@
     "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    },
     "@playwright/test": {
       "optional": true
     }
   },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@zag-js/combobox": "^1.40.0",
+    "@zag-js/core": "^1.40.0",
+    "@zag-js/dialog": "^1.40.0",
+    "@zag-js/menu": "^1.40.0",
+    "@zag-js/popover": "^1.40.0",
+    "@zag-js/react": "^1.40.0",
+    "@zag-js/scroll-area": "^1.40.0",
+    "@zag-js/tabs": "^1.40.0",
+    "@zag-js/tooltip": "^1.40.0",
+    "@zag-js/types": "^1.40.0",
+    "@zag-js/utils": "^1.40.0",
+    "clsx": "^2.1.1",
+    "lucide": "^1.8.0",
+    "lucide-react": "^1.7.0",
+    "tailwind-merge": "^3.5.0",
+    "xstate": "^5.30.0",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.2"
+  },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
     "@playwright/test": "^1.58.2",
+    "@tailwindcss/cli": "^4.2.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.10.5",
-    "@types/react": "^18.3.18",
-    "@types/react-dom": "^18.3.5",
-    "@typescript-eslint/eslint-plugin": "^8.21.0",
-    "@typescript-eslint/parser": "^8.21.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.3.4",
-    "@vitest/coverage-v8": "^2.1.8",
     "eslint": "^9.18.0",
-    "eslint-plugin-react": "^7.37.4",
-    "eslint-plugin-react-hooks": "^5.1.0",
     "jsdom": "^26.0.0",
-    "prettier": "^3.4.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "tailwindcss": "^4.2.2",
     "tsup": "^8.3.5",
     "tsx": "^4.7.0",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.54.0",
-    "vitest": "^2.1.8"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.8",
+    "@uidex/eslint-config": "0.0.0",
+    "@uidex/tsconfig": "0.0.0"
   },
   "keywords": [
-    "annotation",
-    "highlight",
-    "overlay",
-    "component",
+    "uidex",
+    "devtools",
     "react",
-    "vanilla-js",
-    "framework-agnostic"
+    "playwright",
+    "feedback",
+    "scanner"
   ],
   "author": "soel",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/soel/uidex"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "pnpm run build:css && tsup && pnpm run check:bundles",
+    "build:css": "tailwindcss --input src/styles/tailwind.css --output src/styles/tailwind.built.css",
+    "check:bundles": "node scripts/check-bundles.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "views-map": "tsx scripts/extract-views-map.ts",
+    "views-map:check": "tsx scripts/extract-views-map.ts --check"
   }
-}
+}

package/templates/claude/audit.md

@@ -0,0 +1,37 @@
+Run `npx uidex scan --audit` and fix all reported diagnostics.
+
+1. **`marker-md-ignored`** — legacy `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` files from v1. Migrate their content:
+   - Copy the description and acceptance list into a `@uidex page <id>` or `@uidex feature <id>` JSDoc block on the corresponding module (`page.tsx` for pages; the feature's main index/component for features).
+   - Each `- [ ]` checkbox becomes one `@acceptance <text>` tag.
+   - Delete the `UIDEX_PAGE.md` / `UIDEX_FEATURE.md` file.
+
+2. **`acceptance-uncovered`** — a declared `@acceptance` criterion has no flow exercising it.
+   - For widgets: run `npx uidex scaffold widget <id>` to generate a Playwright stub in `e2e/` with one `test()` per criterion; fill in the stubs.
+   - For features/pages: write a Playwright spec under `e2e/**` tagged `{ tag: "@uidex:flow" }` that exercises the criterion by calling `uidex('<element-id>').*()` on the relevant elements.
+
+3. **`unknown-reference`** — a flow's `uidex('<id>')` call references an id that isn't in the registry.
+   - If the id is a typo, fix the string literal in the spec.
+   - If the component was removed, remove the call.
+   - If the component lost its `data-uidex`, restore it.
+   - Dynamic ids (variables, template literals) are invisible to the scanner. If a literal is flagged, it is actually a literal in the source.
+
+4. **`scope-leak`** — a primitive scoped to `feature:<name>` or `page:<name>` is being imported from outside that scope.
+   - Either move the primitive to `src/components/ui/**` so it becomes global, or route the consumer through an appropriate boundary.
+
+5. **`missing-element-annotation`** (INFO) — an interactive `<button>`, `<a>`, `<input>`, `<select>`, or `<textarea>` has no `data-uidex`.
+   - Add `data-uidex="<kebab-id>"`. Skip this diagnostic only when the element is purely decorative (e.g., a skip link that never needs automated reference).
+
+6. **`acceptance-orphan`** — an `@acceptance` tag appears on a JSDoc that doesn't declare `@uidex page|feature|widget`.
+   - Move the acceptance tags into the correct JSDoc block, or remove them.
+
+After fixing, run `npx uidex scan` to regenerate the gen file before re-running the audit.
+
+## Decision rules for primitives
+
+Add `data-uidex-primitive="kebab-name"` ONLY when the component lives outside `src/components/ui/**` and meets all of:
+
+- Exports a reusable presentational component (not a page, layout, or feature orchestrator).
+- Wraps native elements or other primitives — no business logic or data fetching (`useQuery`, `useMutation`, etc.).
+- Imported by multiple consumers.
+
+If it's in `src/components/ui/**`, the scanner auto-promotes it — no attribute needed.

package/templates/claude/rules.md

@@ -0,0 +1,212 @@
+# uidex conventions
+
+This project uses [uidex](https://github.com/soel/uidex) for UI element tracking and feedback ingestion.
+
+## Entity model
+
+Eight entity kinds make up the registry. Most are discovered by convention; annotations only override.
+
+| Kind        | Source                                                               | How discovered                                                                                                                                              |
+| ----------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `element`   | Interactive DOM element                                              | `data-uidex="id"` (always manual)                                                                                                                           |
+| `region`    | Structural area                                                      | `data-uidex-region="id"` OR HTML5 landmark (`<header>`/`<nav>`/`<main>`/`<aside>`/`<footer>`/`role="region"`)                                               |
+| `widget`    | Composite behavioural unit (video player, date picker, autocomplete) | `data-uidex-widget="id"` on the DOM root **AND** `export const uidex = { widget: "id", ... }` on the component module                                       |
+| `primitive` | Reusable presentational component definition                         | Any file under `src/components/ui/**` (auto-promoted); `data-uidex-primitive="name"` opts in a non-conventional location                                    |
+| `page`      | Route-rendered top-level                                             | Auto-derived from your framework's route detection (Next.js / Vite / TanStack Router); `export const uidex = { page: "id", ... }` overrides                 |
+| `feature`   | Cross-cutting capability                                             | Any directory under `src/features/*`; `export const uidex = { feature: "id", ... }` overrides                                                               |
+| `flow`      | End-to-end user journey                                              | Top-level `test.describe` in `e2e/**` (auto-promoted); `{ tag: "@uidex:flow" }` adds richer metadata; opt out with `export const uidex = { notFlow: true }` |
+| `route`     | URL → page mapping                                                   | Auto-derived from your framework's router                                                                                                                   |
+
+## DOM annotations
+
+Four attributes. All use kebab-case ids. DOM attributes are the sole surface for multi-per-file kinds (elements, regions, widget roots).
+
+### `data-uidex` — every interactive element
+
+```tsx
+<button data-uidex="save-btn">Save</button>
+<input data-uidex="email-field" />
+<a data-uidex="nav-home" href="/">Home</a>
+```
+
+`uidex scan --audit` flags unannotated `<button>`, `<a>`, `<input>`, `<select>`, `<textarea>` as INFO diagnostics. Rename carefully — ids are referenced by flow tests.
+
+### `data-uidex-region` — structural regions (only when HTML5 doesn't suffice)
+
+HTML5 landmarks (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `role="region"`) auto-register as regions. Only add `data-uidex-region` on non-semantic `<div>` wrappers you want in the registry:
+
+```tsx
+<div data-uidex-region="settings-form">
+  <button data-uidex="save-btn">Save</button>
+</div>
+```
+
+### `data-uidex-widget` — composite behavioural units
+
+Place on the root of a self-contained UI unit with internal state (video player, date picker, rich text editor). The DOM attribute is the runtime boundary; acceptance criteria live on the `export const uidex` at the component definition.
+
+```tsx
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  widget: "video-player",
+  acceptance: [
+    "Plays/pauses on Space",
+    "Scrubber updates as video plays",
+    "M toggles mute",
+  ],
+} as const satisfies Uidex.Widget
+
+export function VideoPlayer() {
+  return (
+    <div data-uidex-widget="video-player">
+      <button data-uidex="play">Play</button>
+      <input data-uidex="scrubber" type="range" />
+    </div>
+  )
+}
+```
+
+**Widget id duplication rule.** The id must appear in **both** places — on `data-uidex-widget="..."` at the DOM root (runtime boundary) **and** on `export const uidex = { widget: "..." }` (scan-time metadata). The scanner cross-validates: a mismatch or one-sided presence is an error.
+
+Child `data-uidex` elements are automatically composed onto the widget (via DOM nesting at scan time).
+
+### `data-uidex-primitive` — reusable component definitions
+
+Any `.tsx` under `src/components/ui/**` is auto-promoted to a primitive (name = kebab of filename). Add `data-uidex-primitive="name"` only to opt-in a reusable component that lives outside the convention directory.
+
+```tsx
+// src/components/ui/button.tsx — auto-promoted as 'button', no attribute needed
+export function Button({ children, ...props }) {
+  return <button {...props}>{children}</button>
+}
+```
+
+## `export const uidex` — module-scoped authoring surface
+
+One named export per module, on the file that **defines** the entity. The RHS must be a plain AST literal — object / array / string / number / boolean literals, optional `as const`, optional `satisfies Uidex.<Kind>`. Identifier references in value position, calls, spreads, conditionals, and template literals with expressions are rejected with an error diagnostic.
+
+```tsx
+// Page
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  page: "org-settings",
+  acceptance: [
+    "User can update the organization name",
+    "Error message is shown if the update fails",
+  ],
+  features: ["billing"],
+} as const satisfies Uidex.Page
+
+export default function SettingsPage() { ... }
+```
+
+Kinds (discriminator fields):
+
+| Kind        | Discriminator                     | Other fields                                                          |
+| ----------- | --------------------------------- | --------------------------------------------------------------------- |
+| `page`      | `page: PageId \| false`           | `acceptance?`, `features?`, `widgets?`, `description?`                |
+| `feature`   | `feature: FeatureId \| false`     | `acceptance?`, `description?`                                         |
+| `widget`    | `widget: WidgetId`                | `acceptance?`, `description?`                                         |
+| `primitive` | `primitive: PrimitiveId \| false` | `description?`                                                        |
+| `flow`      | `flow: FlowId`                    | `description?`                                                        |
+| opt-out     | `notFlow: true`                   | (no other fields — opts a Playwright spec out of flow auto-promotion) |
+
+Setting `page: false` / `feature: false` / `primitive: false` explicitly opts a module out of auto-promotion.
+
+### Typed cross-references
+
+`uidex.gen.ts` exports per-kind id unions (`PageId`, `FeatureId`, `WidgetId`, etc.) and a `Uidex` namespace of shape types. `satisfies Uidex.Page` makes `tsc` flag unknown ids at the literal — no `uidex scan --audit` round-trip required:
+
+```tsx
+export const uidex = {
+  page: "checkout",
+  features: ["billng"], // tsc error: "billng" is not assignable to FeatureId
+} as const satisfies Uidex.Page
+```
+
+### Precedence
+
+```
+configuration override  >  export const uidex  >  DOM attribute  >  convention
+```
+
+## Playwright flows
+
+End-to-end user journeys are Playwright tests in `e2e/**`. Any top-level `test.describe` auto-promotes to a flow; the `@uidex:flow` tag adds richer metadata. Opt out by adding `export const uidex = { notFlow: true } as const satisfies Uidex.NotFlow` at the top of the spec file.
+
+```ts
+import { expect, test } from "uidex/playwright"
+import type { Uidex } from "@/uidex.gen"
+
+export const uidex = {
+  flow: "add-and-complete-todo",
+  description: "User adds a todo and marks it complete.",
+} as const satisfies Uidex.Flow
+
+test.describe("Add and complete a todo", { tag: "@uidex:flow" }, () => {
+  test("adds a todo", async ({ uidex }) => {
+    await uidex("todo-field").fill("Buy milk")
+    await uidex("todo-add").click()
+  })
+})
+```
+
+Rules:
+
+- One tagged describe per `flow-*.spec.ts`.
+- Component ids inside `uidex(...)` MUST be string literals (static-analysable).
+- `page-*.spec.ts` and `feature-*.spec.ts` scoped tests remain untagged.
+
+## Scanner
+
+```bash
+npx uidex scan          # regenerate src/uidex.gen.ts
+npx uidex scan --check  # fail non-zero if the committed gen file is stale
+npx uidex scan --audit  # validate (--check + --lint; exits non-zero on errors)
+npx uidex scan --json   # emit diagnostics as JSON
+npx uidex scaffold widget <id>  # emit Playwright stub from declared acceptance
+```
+
+Run `uidex scan` after any `data-uidex*` attribute change, `export const uidex` edit, or new flow. The gen file (`src/uidex.gen.ts` by default) is auto-generated and **committed** — consumers import types from it directly.
+
+### Bundler plugins (optional)
+
+Install the matching bundler plugin so `uidex.gen.ts` regenerates on file save:
+
+- `@uidex/vite-plugin` — for Vite
+- `@uidex/webpack-plugin` — for raw Webpack
+- `@uidex/next-plugin` — `withUidex(config)` wrapper for Next.js (Webpack transport)
+
+## Configuration
+
+`.uidex.json` is flat. Example:
+
+```json
+{
+  "sources": [{ "rootDir": "src" }],
+  "output": "src/uidex.gen.ts",
+  "flows": ["e2e/**/*.spec.ts"],
+  "typeMode": "strict"
+}
+```
+
+`typeMode: "strict"` (default) emits literal id unions — `tsc` rejects unknown ids at the `satisfies Uidex.X` site. `typeMode: "loose"` emits `string` — a **temporary migration knob** for repos mid-migration from legacy JSDoc.
+
+Multi-source (monorepo) example:
+
+```json
+{
+  "sources": [
+    { "rootDir": "apps/web/src" },
+    { "rootDir": "packages/ui/src", "prefix": "@org/ui" }
+  ],
+  "output": "apps/web/src/uidex.gen.ts",
+  "flows": ["apps/web/e2e/**/*.spec.ts"]
+}
+```
+
+## Migration from legacy JSDoc
+
+JSDoc tags (`@uidex page|feature|widget`, `@acceptance`, `@uidex:not-flow`) are **no longer recognised** — the scanner registers nothing from them. `uidex scan --lint` ships a `legacy-jsdoc` rule that warns on every legacy tag and points at the replacement `export const uidex` form. Set `typeMode: "loose"` in `.uidex.json` during migration to keep `tsc` quiet; flip to `strict` once every JSDoc tag is gone.

package/claude/audit-command.md

@@ -1,16 +0,0 @@
-Run `npx uidex scan --check` and fix all reported issues:
-
-1. **Uncovered components** (components missing UIDEX_PAGE.md coverage):
-   - Create a `UIDEX_PAGE.md` in the nearest feature directory
-   - Include a heading, brief description, and acceptance criteria
-
-2. **Orphaned UIDEX_PAGE.md files** (docs with no components underneath):
-   - If the components were removed, delete the UIDEX_PAGE.md
-   - If components are missing `data-uidex` attributes, add them
-
-3. **Review interactive elements** without `data-uidex` attributes:
-   - Scan modified files for buttons, inputs, links, and other interactive elements
-   - Add `data-uidex="kebab-id"` attributes where missing
-   - Add `/** @uidex id - description */` JSDoc above each annotated element
-
-After fixing all issues, run `npx uidex scan` to regenerate the component registry.

package/claude/rules.md

@@ -1,88 +0,0 @@
-# uidex conventions
-
-This project uses [uidex](https://github.com/soel/uidex) for UI element tracking and documentation.
-
-## data-uidex attributes
-
-- Every user-facing interactive element MUST have a `data-uidex="kebab-id"` attribute.
-- IDs should be descriptive and kebab-cased: `data-uidex="submit-btn"`, `data-uidex="user-avatar"`.
-- When creating new components with interactive elements, always add `data-uidex` attributes.
-- When modifying components, preserve existing `data-uidex` attributes. If you rename or remove an element, update or remove its attribute accordingly.
-
-## @uidex JSDoc comments
-
-Add a JSDoc comment above annotated elements describing their purpose:
-
-```tsx
-/** @uidex submit-btn - Primary action button for form submission */
-<button data-uidex="submit-btn">Submit</button>
-```
-
-Multi-line format for longer descriptions:
-
-```tsx
-/**
- * @uidex user-profile-card
- * Displays user avatar, name, and role.
- * Shown in the sidebar and team directory.
- */
-<div data-uidex="user-profile-card">...</div>
-```
-
-## UIDEX_PAGE.md files
-
-Page docs describe a route/view. Components in the directory are automatically associated.
-
-- Each page directory should have a `UIDEX_PAGE.md` with acceptance criteria.
-- When adding components to a directory that lacks a `UIDEX_PAGE.md`, create one.
-- When removing all components from a directory, remove its `UIDEX_PAGE.md`.
-
-```markdown
-# Page Name
-
-Brief description of the page.
-
-## Acceptance
-- User can do X
-- Y is displayed when Z
-```
-
-## UIDEX_FEATURE.md files
-
-Feature docs describe a cross-cutting feature. Components are explicitly listed via frontmatter.
-
-- Use `UIDEX_FEATURE.md` for features that span multiple pages (e.g., auth, billing).
-- List associated component IDs in the `components:` frontmatter.
-
-```markdown
----
-components:
-  - login-form
-  - signup-btn
----
-# Feature Name
-
-Brief description of the feature.
-
-## Acceptance
-- User can do X
-- Y is displayed when Z
-```
-
-## Component registry
-
-For a project-wide view of all components, pages, and features, read the generated registry file (default: `src/uidex.gen.ts`). This file is kept up to date by the scanner.
-
-## Scanner
-
-After adding, removing, or renaming `data-uidex` attributes, run:
-
-```bash
-npx uidex scan
-```
-
-To validate that all components have UIDEX_PAGE.md coverage:
-
-```bash
-npx uidex scan --check
-```