uidex 0.0.1 → 0.1.0

package/README.md

@@ -13,6 +13,24 @@ npm install uidex
 - React 18 or higher
 - React DOM 18 or higher
 
+## Quick Start
+
+```tsx
+// 1. Add data-uidex attributes to elements you want to track
+<button data-uidex="submit-btn">Submit</button>
+
+// 2. Run the scanner to generate the registry
+npx uidex-scan
+
+// 3. Import the generated file (auto-registers components)
+import './uidex.gen';
+
+// 4. Add UidexDevtools anywhere in your app
+import { UidexDevtools } from 'uidex';
+
+<UidexDevtools />
+```
+
 ## Configuration
 
 Create a `.uidex.json` file in your project root to customize default settings:
@@ -34,51 +52,30 @@ Create a `.uidex.json` file in your project root to customize default settings:
     "error": "#ef4444",
     "info": "#6366f1"
   },
-  "disabled": false
-}
-```
-
-### Using the Config Provider
-
-Wrap your app with `AnnotateProvider` to apply configuration:
-
-```tsx
-import { AnnotateProvider } from 'uidex';
-import config from './.uidex.json';
-
-function App() {
-  return (
-    <AnnotateProvider config={config}>
-      {/* Your app */}
-    </AnnotateProvider>
-  );
+  "scanner": {
+    "rootDir": "src",
+    "include": ["**/*.tsx", "**/*.jsx"],
+    "exclude": ["**/*.test.*", "**/*.spec.*"],
+    "outputPath": "src/uidex.gen.ts"
+  }
 }
 ```
 
-### Named Colors
-
-Use named colors from your config:
-
-```tsx
-<Annotate label="Error" color="error">
-  <button>Delete</button>
-</Annotate>
-```
-
-## Usage
+## Components
 
-### Annotate Component
+### UidexDevtools
 
-Wrap any component with `Annotate` to add hover-based highlighting:
+The main devtools component that displays a floating button with a list of all registered components:
 
 ```tsx
-import { Annotate } from 'uidex';
+import { UidexDevtools } from 'uidex';
 
 function App() {
   return (
-    <Annotate label="Submit Button" color="#10b981">
-      <button>Submit</button>
-    </Annotate>
+    <>
+      {/* Your app content */}
+      <UidexDevtools />
+    </>
   );
 }
 ```
@@ -87,102 +84,59 @@ function App() {
 
 | 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 |
+| `components` | `UidexMap` | - | Optional components map (uses registry if not provided) |
+| `config` | `UidexConfig` | - | Optional configuration for styling |
+| `buttonPosition` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Position of the floating button |
+| `trigger` | `ReactNode` | - | Custom trigger element |
+| `disabled` | `boolean` | `false` | Disable the devtools |
+| `onSelect` | `(id: string) => void` | - | Callback when a component is selected |
 
-### HighlightOverlay Component
+### UidexOverlay
 
-For more control, use `HighlightOverlay` with a ref to any element:
+For manual control over overlays:
 
 ```tsx
-import { useRef } from 'react';
-import { HighlightOverlay } from 'uidex';
+import { useState } from 'react';
+import { UidexOverlay } from 'uidex';
 
 function App() {
-  const buttonRef = useRef<HTMLButtonElement>(null);
+  const [target, setTarget] = useState<HTMLElement | null>(null);
 
   return (
     <>
-      <button ref={buttonRef}>Click me</button>
-      <HighlightOverlay
-        targetRef={buttonRef}
-        label="Action Button"
-        color="#f59e0b"
-        visible={true}
+      <button
+        ref={(el) => setTarget(el)}
+        onMouseEnter={(e) => setTarget(e.currentTarget)}
+        onMouseLeave={() => setTarget(null)}
+      >
+        Hover me
+      </button>
+      <UidexOverlay
+        target={target}
+        label="Button"
+        color="#3b82f6"
       />
     </>
   );
 }
 ```
 
-### Hooks
-
-#### useHighlight
-
-Simple state management for highlight visibility:
-
-```tsx
-import { useHighlight } from 'uidex';
-
-function App() {
-  const { isHighlighted, highlight, unhighlight, toggle } = useHighlight();
-
-  return (
-    <div>
-      <button onClick={toggle}>Toggle Highlight</button>
-      {isHighlighted && <div>Highlighted!</div>}
-    </div>
-  );
-}
-```
-
-#### useAnnotation
-
-Combines a ref with highlight state:
-
-```tsx
-import { useAnnotation, HighlightOverlay } from 'uidex';
-
-function App() {
-  const { ref, isHighlighted, toggle } = useAnnotation();
-
-  return (
-    <>
-      <div ref={ref}>Target element</div>
-      <button onClick={toggle}>Toggle</button>
-      <HighlightOverlay targetRef={ref} visible={isHighlighted} label="Target" />
-    </>
-  );
-}
-```
-
-#### useAnnotateConfig
-
-Access the current configuration:
-
-```tsx
-import { useAnnotateConfig } from 'uidex';
-
-function MyComponent() {
-  const config = useAnnotateConfig();
+#### Props
 
-  console.log(config.defaults?.color); // Current default color
-  console.log(config.colors?.primary); // Named color value
-}
-```
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `target` | `HTMLElement \| null` | required | The element to highlight |
+| `label` | `string` | - | Label text shown on the overlay |
+| `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 |
+| `colors` | `Record<string, string>` | - | Named colors map |
 
 ## Build-Time Scanner
 
-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.
+The `uidex-scan` CLI tool scans your source files for `data-uidex` attributes and generates a TypeScript registry file.
 
 ### Setup
 
@@ -194,17 +148,15 @@ Add scanner configuration to your `.uidex.json`:
   "scanner": {
     "include": ["**/*.tsx"],
     "exclude": ["**/*.test.*", "**/*.spec.*", "**/generated/**"],
-    "outputPath": "src/generated/annotations.ts",
+    "outputPath": "src/uidex.gen.ts",
     "rootDir": "src"
   }
 }
 ```
 
-Note: The `include` and `exclude` patterns are relative to `rootDir`. If `rootDir` is `src`, use patterns like `**/*.tsx` (not `src/**/*.tsx`).
-
 ### Monorepo Support
 
-For monorepos with multiple packages, use the `sources` array to scan multiple directories:
+For monorepos with multiple packages, use the `sources` array:
 
 ```json
 {
@@ -219,34 +171,19 @@ For monorepos with multiple packages, use the `sources` array to scan multiple d
         "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"
+    "exclude": ["**/*.test.*", "**/*.spec.*"],
+    "outputPath": "src/uidex.gen.ts"
   }
 }
 ```
 
-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.
-
 ### Usage
 
 Run the scanner as part of your build process:
 
 ```json
-// package.json
 {
   "scripts": {
     "prebuild": "npx uidex-scan",
@@ -261,7 +198,7 @@ Or run it directly:
 npx uidex-scan
 ```
 
-### Adding Annotations
+### Adding Components
 
 Add `data-uidex` attributes to your JSX elements:
 
@@ -273,55 +210,69 @@ Add `data-uidex` attributes to your JSX elements:
 <button data-uidex="cta-button">Click Me</button>
 ```
 
+### JSDoc Documentation
+
+Add documentation to components using JSDoc comments:
+
+```tsx
+/** @uidex cta-button - Primary call-to-action button */
+<button data-uidex="cta-button">Click Me</button>
+```
+
 ### Generated Output
 
-The scanner generates a TypeScript file with all discovered annotations:
+The scanner generates a TypeScript file with all discovered components:
 
 ```typescript
 // Auto-generated by uidex scanner
 // Do not edit this file manually
 
-export const annotations = {
+import { registerComponents } from 'uidex';
+
+export const components = {
   "cta-button": [{ filePath: "src/pages/Home.tsx", line: 12 }],
   "main-nav": [{ filePath: "src/components/Header.tsx", line: 5 }]
-} as const;
+};
+
+export const componentIds = ["cta-button", "main-nav"] as const;
 
-export const annotationIds = ["cta-button", "main-nav"] as const;
+export type ComponentId = typeof componentIds[number];
 
-export type AnnotationId = typeof annotationIds[number];
+// Auto-register components
+registerComponents(components);
 ```
 
 ### Using Generated Types
 
-Import the generated types for type-safe annotation access:
+Import the generated types for type-safe component access:
 
 ```tsx
-import { annotations, AnnotationId } from './generated/annotations';
+import { components, ComponentId } from './uidex.gen';
 
-function highlightElement(id: AnnotationId) {
-  const locations = annotations[id];
+function highlightElement(id: ComponentId) {
+  const locations = components[id];
   console.log(`Found at: ${locations[0].filePath}:${locations[0].line}`);
 }
 
-// Type error: "invalid-id" is not a valid AnnotationId
+// Type error: "invalid-id" is not a valid ComponentId
 highlightElement("invalid-id");
 ```
 
 ## TypeScript
 
-This package is written in TypeScript and includes full type definitions. All types are exported:
+This package is written in TypeScript and includes full type definitions:
 
 ```tsx
 import type {
-  AnnotateProps,
-  AnnotateProviderProps,
+  UidexConfig,
+  UidexDefaults,
+  UidexDevtoolsProps,
+  UidexOverlayProps,
+  UidexLocation,
+  UidexMap,
   BorderStyle,
-  HighlightOverlayProps,
   LabelPosition,
-  ReactAnnotateConfig,
-  ReactAnnotateDefaults,
-  UseAnnotationOptions,
-  UseHighlightOptions,
+  ButtonPosition,
 } from 'uidex';
 ```
 

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
+```