uidex 0.0.1 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # uidex
 
-A React library for highlighting and annotating components. Perfect for building tutorials, onboarding experiences, or debugging tools.
+A framework-agnostic library for highlighting and annotating UI elements. Works with React, vanilla JS, or any framework. Includes a build-time scanner, inspect mode, Playwright integration, and Claude Code tooling.
 
 ## Installation
 
@@ -8,14 +8,61 @@ A React library for highlighting and annotating components. Perfect for building
 npm install uidex
 ```
 
-## Requirements
+## Quick Start
 
-- React 18 or higher
-- React DOM 18 or higher
+```bash
+# 1. Initialize config
+npx uidex init
+
+# 2. Add data-uidex attributes to your elements
+#    <button data-uidex="submit-btn">Submit</button>
+
+# 3. Run the scanner
+npx uidex scan
+```
+
+### React
+
+```tsx
+import './uidex.gen';
+import { UidexDevtools } from 'uidex';
+
+function App() {
+  return (
+    <>
+      <button data-uidex="submit-btn">Submit</button>
+      <UidexDevtools />
+    </>
+  );
+}
+```
+
+### Vanilla JS
+
+```js
+import './uidex.gen';
+import { createUidexUI } from 'uidex/core';
+
+const ui = createUidexUI();
+ui.mount();
+
+// Cleanup
+ui.destroy();
+```
+
+### Script Tag
+
+```html
+<script src="https://unpkg.com/uidex/dist/core/index.global.js"></script>
+<script>
+  const ui = UidexCore.createUidexUI({ components: { ... } });
+  ui.mount();
+</script>
+```
 
 ## Configuration
 
-Create a `.uidex.json` file in your project root to customize default settings:
+`npx uidex init` creates a `.uidex.json` file:
 
 ```json
 {
@@ -34,297 +81,285 @@ Create a `.uidex.json` file in your project root to customize default settings:
     "error": "#ef4444",
     "info": "#6366f1"
   },
-  "disabled": false
+  "scanner": {
+    "rootDir": "src",
+    "include": ["**/*.tsx", "**/*.jsx"],
+    "exclude": ["**/*.test.*", "**/*.spec.*"],
+    "outputPath": "src/uidex.gen.ts"
+  }
 }
 ```
 
-### Using the Config Provider
+## Scanner
 
-Wrap your app with `AnnotateProvider` to apply configuration:
+The scanner finds `data-uidex` attributes in your source files and generates a typed registry.
 
-```tsx
-import { AnnotateProvider } from 'uidex';
-import config from './.uidex.json';
-
-function App() {
-  return (
-    <AnnotateProvider config={config}>
-      {/* Your app */}
-    </AnnotateProvider>
-  );
-}
+```bash
+npx uidex scan           # Generate registry
+npx uidex scan --check   # Validate UIDEX_PAGE.md coverage
 ```
 
-### Named Colors
+Add it to your build:
 
-Use named colors from your config:
-
-```tsx
-<Annotate label="Error" color="error">
-  <button>Delete</button>
-</Annotate>
+```json
+{
+  "scripts": {
+    "prebuild": "npx uidex scan",
+    "build": "next build"
+  }
+}
 ```
 
-## Usage
-
-### Annotate Component
-
-Wrap any component with `Annotate` to add hover-based highlighting:
+### Annotating Components
 
 ```tsx
-import { Annotate } from 'uidex';
+<nav data-uidex="main-nav">
+  <a href="/">Home</a>
+</nav>
 
-function App() {
-  return (
-    <Annotate label="Submit Button" color="#10b981">
-      <button>Submit</button>
-    </Annotate>
-  );
-}
+/** @uidex cta-button - Primary call-to-action button */
+<button data-uidex="cta-button">Click Me</button>
 ```
 
-#### Props
+### Generated Output
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | required | The content to wrap |
-| `label` | `string` | - | Label text shown on hover |
-| `color` | `string` | `#3b82f6` | Highlight color (hex or named color) |
-| `borderStyle` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | Border style |
-| `borderWidth` | `number` | `2` | Border width in pixels |
-| `showLabel` | `boolean` | `true` | Whether to show the label |
-| `labelPosition` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-left'` | Label position |
-| `disabled` | `boolean` | `false` | Disable highlighting |
-| `className` | `string` | - | Additional CSS class |
-| `style` | `CSSProperties` | - | Additional inline styles |
-| `onHover` | `(isHovered: boolean) => void` | - | Callback on hover state change |
-
-### HighlightOverlay Component
-
-For more control, use `HighlightOverlay` with a ref to any element:
+The scanner generates `src/uidex.gen.ts` (gitignored) with:
 
-```tsx
-import { useRef } from 'react';
-import { HighlightOverlay } from 'uidex';
+- `components` — map of id to file locations
+- `componentIds` — array of all ids
+- `ComponentId` — union type of all ids
+- `pages` — from `UIDEX_PAGE.md` files (directory-based component association)
+- `features` — from `UIDEX_FEATURE.md` files (explicit component association)
+- Auto-registration calls
 
-function App() {
-  const buttonRef = useRef<HTMLButtonElement>(null);
+### Monorepo Support
 
-  return (
-    <>
-      <button ref={buttonRef}>Click me</button>
-      <HighlightOverlay
-        targetRef={buttonRef}
-        label="Action Button"
-        color="#f59e0b"
-        visible={true}
-      />
-    </>
-  );
+Use `sources` for multiple scan roots:
+
+```json
+{
+  "scanner": {
+    "sources": [
+      { "rootDir": "src", "include": ["**/*.tsx"] },
+      { "rootDir": "../packages/ui/src", "include": ["**/*.tsx"], "prefix": "@myorg/ui" }
+    ],
+    "exclude": ["**/*.test.*"],
+    "outputPath": "src/uidex.gen.ts"
+  }
 }
 ```
 
-### Hooks
+## Components
 
-#### useHighlight
+### UidexDevtools (React)
 
-Simple state management for highlight visibility:
+Floating devtools panel with component list, pages, features, and inspect mode.
 
 ```tsx
-import { useHighlight } from 'uidex';
+import { UidexDevtools } from 'uidex';
 
-function App() {
-  const { isHighlighted, highlight, unhighlight, toggle } = useHighlight();
-
-  return (
-    <div>
-      <button onClick={toggle}>Toggle Highlight</button>
-      {isHighlighted && <div>Highlighted!</div>}
-    </div>
-  );
-}
+<UidexDevtools
+  buttonPosition="bottom-right"
+  onSelect={(id) => console.log(id)}
+/>
 ```
 
-#### useAnnotation
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `components` | `UidexMap` | registry | Components map |
+| `config` | `UidexConfig` | - | Styling configuration |
+| `buttonPosition` | `ButtonPosition` | `'bottom-right'` | Initial button position |
+| `disabled` | `boolean` | `false` | Disable devtools |
+| `onSelect` | `(id: string) => void` | - | Selection callback |
+| `inspectShortcut` | `KeyboardShortcut \| false` | `Shift+Cmd+U` | Inspect mode shortcut |
 
-Combines a ref with highlight state:
+### UidexOverlay (React)
+
+Standalone overlay for highlighting a single element.
 
 ```tsx
-import { useAnnotation, HighlightOverlay } from 'uidex';
+import { UidexOverlay } from 'uidex';
 
-function App() {
-  const { ref, isHighlighted, toggle } = useAnnotation();
+<UidexOverlay
+  target={element}
+  label="Button"
+  color="#3b82f6"
+/>
+```
 
-  return (
-    <>
-      <div ref={ref}>Target element</div>
-      <button onClick={toggle}>Toggle</button>
-      <HighlightOverlay targetRef={ref} visible={isHighlighted} label="Target" />
-    </>
-  );
-}
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `target` | `HTMLElement \| null` | required | Element to highlight |
+| `label` | `string` | - | Label text |
+| `color` | `string` | - | Border color (hex or named) |
+| `borderStyle` | `BorderStyle` | `'solid'` | `solid`, `dashed`, or `dotted` |
+| `borderWidth` | `number` | `2` | Border width in px |
+| `showLabel` | `boolean` | `true` | Show label |
+| `labelPosition` | `LabelPosition` | `'top-left'` | Label position |
+| `colors` | `Record<string, string>` | - | Named colors map |
+
+### createUidexUI (Vanilla JS)
+
+```js
+import { createUidexUI } from 'uidex/core';
+
+const ui = createUidexUI({
+  components: { ... },
+  pages: [ ... ],
+  features: [ ... ],
+  config: { defaults: { color: '#3b82f6' } },
+  buttonPosition: 'bottom-right',
+  inspectShortcut: { key: 'u', shiftKey: true, metaKey: true },
+  onSelect: (id) => console.log(id),
+});
+
+ui.mount();
+ui.destroy();
 ```
 
-#### useAnnotateConfig
+## Inspect Mode
 
-Access the current configuration:
+Press **Shift+Cmd+U** (Shift+Ctrl+U on Windows/Linux) to enter inspect mode. Hover over elements to highlight them, click to select. Press **Escape** to exit.
 
-```tsx
-import { useAnnotateConfig } from 'uidex';
+Disable or customize the shortcut:
 
-function MyComponent() {
-  const config = useAnnotateConfig();
+```tsx
+// Disable
+<UidexDevtools inspectShortcut={false} />
 
-  console.log(config.defaults?.color); // Current default color
-  console.log(config.colors?.primary); // Named color value
-}
+// Custom shortcut
+<UidexDevtools inspectShortcut={{ key: 'i', ctrlKey: true }} />
 ```
 
-## Build-Time Scanner
+## Playwright Integration
 
-The `uidex-scan` CLI tool scans your source files for `data-uidex` attributes and generates a TypeScript registry file. This enables type-safe access to all annotations in your codebase.
+Test your annotated components with type-safe locators and coverage reporting.
 
-### Setup
+### Test Fixture
 
-Add scanner configuration to your `.uidex.json`:
+```ts
+import { test, expect } from 'uidex/playwright';
 
-```json
-{
-  "$schema": "./node_modules/uidex/uidex.schema.json",
-  "scanner": {
-    "include": ["**/*.tsx"],
-    "exclude": ["**/*.test.*", "**/*.spec.*", "**/generated/**"],
-    "outputPath": "src/generated/annotations.ts",
-    "rootDir": "src"
-  }
-}
+test('submit button works', async ({ uidex }) => {
+  await uidex('submit-btn').click();
+  await uidex('success-message').waitFor();
+});
 ```
 
-Note: The `include` and `exclude` patterns are relative to `rootDir`. If `rootDir` is `src`, use patterns like `**/*.tsx` (not `src/**/*.tsx`).
+### Coverage Reporter
 
-### Monorepo Support
+Track which `data-uidex` components are covered by tests:
 
-For monorepos with multiple packages, use the `sources` array to scan multiple directories:
+```ts
+// playwright.config.ts
+import UidexCoverageReporter from 'uidex/playwright/reporter';
+import { componentIds } from './src/uidex.gen.test';
 
-```json
-{
-  "$schema": "./node_modules/uidex/uidex.schema.json",
-  "scanner": {
-    "sources": [
-      {
-        "rootDir": "src",
-        "include": ["**/*.tsx"]
-      },
-      {
-        "rootDir": "../packages/ui/src",
-        "include": ["**/*.tsx"],
-        "prefix": "@myorg/ui"
-      },
-      {
-        "rootDir": "../packages/components/src",
-        "include": ["**/*.tsx"],
-        "exclude": ["**/internal/**"],
-        "prefix": "@myorg/components"
-      }
-    ],
-    "exclude": ["**/*.test.*", "**/*.spec.*", "**/generated/**"],
-    "outputPath": "src/generated/annotations.ts"
-  }
-}
+export default defineConfig({
+  reporter: [
+    ['html'],
+    [UidexCoverageReporter, { componentIds }],
+  ],
+});
 ```
 
-Each source can have:
-- `rootDir` - Directory to scan (can be relative path like `../packages/ui`)
-- `include` - Glob patterns for files to include
-- `exclude` - Additional exclude patterns for this source only
-- `prefix` - Optional prefix for file paths in output (e.g., `@myorg/ui/Button.tsx`)
-
-The `exclude` at the top level applies globally to all sources.
+Outputs `uidex-coverage.json` with covered/uncovered components and percentage.
 
-### Usage
+### Scaffold Tests
 
-Run the scanner as part of your build process:
-
-```json
-// package.json
-{
-  "scripts": {
-    "prebuild": "npx uidex-scan",
-    "build": "next build"
-  }
-}
-```
-
-Or run it directly:
+Generate test stubs from your pages and features:
 
 ```bash
-npx uidex-scan
+npx uidex scaffold [dir]
 ```
 
-### Adding Annotations
-
-Add `data-uidex` attributes to your JSX elements:
+## Claude Code Integration
 
-```tsx
-<nav data-uidex="main-nav">
-  <a href="/">Home</a>
-</nav>
+Set up Claude Code with uidex-aware rules, a `/uidex-audit` skill, and a post-edit hook that validates coverage:
 
-<button data-uidex="cta-button">Click Me</button>
+```bash
+npx uidex claude init       # Add rules + skill + hooks
+npx uidex claude teardown   # Remove everything
 ```
 
-### Generated Output
-
-The scanner generates a TypeScript file with all discovered annotations:
+Manage individually:
 
-```typescript
-// Auto-generated by uidex scanner
-// Do not edit this file manually
-
-export const annotations = {
-  "cta-button": [{ filePath: "src/pages/Home.tsx", line: 12 }],
-  "main-nav": [{ filePath: "src/components/Header.tsx", line: 5 }]
-} as const;
-
-export const annotationIds = ["cta-button", "main-nav"] as const;
+```bash
+npx uidex claude rules add|remove    # .claude/rules/uidex.md
+npx uidex claude skill add|remove    # .claude/commands/uidex-audit.md
+npx uidex claude hooks add|remove    # PostToolUse hook in .claude/settings.json
+```
 
-export type AnnotationId = typeof annotationIds[number];
+## Theming
+
+All UI renders inside a Shadow DOM with CSS custom properties. Override any token at `:root`:
+
+```css
+:root {
+  --uidex-color-primary: #2e2e2e;
+  --uidex-color-bg: #ffffff;
+  --uidex-color-bg-elevated: #f5f5f5;
+  --uidex-color-text: #1f2937;
+  --uidex-color-text-strong: #111827;
+  --uidex-color-text-muted: #6b7280;
+  --uidex-color-surface-hover: #f3f4f6;
+  --uidex-color-surface-active: #e5e7eb;
+  --uidex-color-border: #d1d5db;
+  --uidex-color-border-light: #e5e7eb;
+}
 ```
 
-### Using Generated Types
+33 tokens available across colors, shadows, border-radius, z-index, typography, and transitions. The default theme is dark monochromatic with zero border-radius and monospace typography.
 
-Import the generated types for type-safe annotation access:
+## Package Exports
 
-```tsx
-import { annotations, AnnotationId } from './generated/annotations';
+| Import | Description |
+|--------|-------------|
+| `uidex` | React components (re-exports `uidex/react`) |
+| `uidex/core` | Vanilla JS classes (`createUidexUI`, `Overlay`, `Inspector`) |
+| `uidex/react` | React wrappers (`UidexDevtools`, `UidexOverlay`) |
+| `uidex/playwright` | Test fixture and helpers |
+| `uidex/playwright/reporter` | Coverage reporter |
+| `uidex/styles.css` | Standalone CSS (optional, auto-injected via Shadow DOM) |
 
-function highlightElement(id: AnnotationId) {
-  const locations = annotations[id];
-  console.log(`Found at: ${locations[0].filePath}:${locations[0].line}`);
-}
+## CLI Reference
 
-// Type error: "invalid-id" is not a valid AnnotationId
-highlightElement("invalid-id");
+```
+npx uidex                    Initialize project (alias for init)
+npx uidex init               Create .uidex.json and update .gitignore
+npx uidex scan               Run component scanner
+npx uidex scan --check       Validate UIDEX_PAGE.md coverage
+npx uidex scaffold [dir]     Generate Playwright test stubs
+npx uidex claude init        Set up Claude Code integration
+npx uidex claude teardown    Remove Claude Code integration
 ```
 
 ## TypeScript
 
-This package is written in TypeScript and includes full type definitions. All types are exported:
+Full type definitions included:
 
-```tsx
+```ts
 import type {
-  AnnotateProps,
-  AnnotateProviderProps,
+  UidexConfig,
+  UidexDefaults,
+  UidexMap,
+  UidexLocation,
+  UidexPage,
+  UidexFeature,
   BorderStyle,
-  HighlightOverlayProps,
   LabelPosition,
-  ReactAnnotateConfig,
-  ReactAnnotateDefaults,
-  UseAnnotationOptions,
-  UseHighlightOptions,
+  ButtonPosition,
+  KeyboardShortcut,
 } from 'uidex';
 ```
 
+## Examples
+
+See `examples/` for working demos:
+
+- `examples/next-app/` — Next.js App Router
+- `examples/vite-app/` — Vite + React
+
 ## License
 
 MIT

package/claude/audit-command.md

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,88 @@
+# 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
+```