uidex 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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

@@ -0,0 +1,330 @@
+# uidex
+
+A React library for highlighting and annotating components. Perfect for building tutorials, onboarding experiences, or debugging tools.
+
+## Installation
+
+```bash
+npm install uidex
+```
+
+## Requirements
+
+- React 18 or higher
+- React DOM 18 or higher
+
+## Configuration
+
+Create a `.uidex.json` file in your project root to customize default settings:
+
+```json
+{
+  "$schema": "./node_modules/uidex/uidex.schema.json",
+  "defaults": {
+    "color": "#3b82f6",
+    "borderStyle": "solid",
+    "borderWidth": 2,
+    "showLabel": true,
+    "labelPosition": "top-left"
+  },
+  "colors": {
+    "primary": "#3b82f6",
+    "success": "#10b981",
+    "warning": "#f59e0b",
+    "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>
+  );
+}
+```
+
+### Named Colors
+
+Use named colors from your config:
+
+```tsx
+<Annotate label="Error" color="error">
+  <button>Delete</button>
+</Annotate>
+```
+
+## Usage
+
+### Annotate Component
+
+Wrap any component with `Annotate` to add hover-based highlighting:
+
+```tsx
+import { Annotate } from 'uidex';
+
+function App() {
+  return (
+    <Annotate label="Submit Button" color="#10b981">
+      <button>Submit</button>
+    </Annotate>
+  );
+}
+```
+
+#### Props
+
+| 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:
+
+```tsx
+import { useRef } from 'react';
+import { HighlightOverlay } from 'uidex';
+
+function App() {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  return (
+    <>
+      <button ref={buttonRef}>Click me</button>
+      <HighlightOverlay
+        targetRef={buttonRef}
+        label="Action Button"
+        color="#f59e0b"
+        visible={true}
+      />
+    </>
+  );
+}
+```
+
+### 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();
+
+  console.log(config.defaults?.color); // Current default color
+  console.log(config.colors?.primary); // Named color value
+}
+```
+
+## 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.
+
+### Setup
+
+Add scanner configuration to your `.uidex.json`:
+
+```json
+{
+  "$schema": "./node_modules/uidex/uidex.schema.json",
+  "scanner": {
+    "include": ["**/*.tsx"],
+    "exclude": ["**/*.test.*", "**/*.spec.*", "**/generated/**"],
+    "outputPath": "src/generated/annotations.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:
+
+```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"
+  }
+}
+```
+
+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",
+    "build": "next build"
+  }
+}
+```
+
+Or run it directly:
+
+```bash
+npx uidex-scan
+```
+
+### Adding Annotations
+
+Add `data-uidex` attributes to your JSX elements:
+
+```tsx
+<nav data-uidex="main-nav">
+  <a href="/">Home</a>
+</nav>
+
+<button data-uidex="cta-button">Click Me</button>
+```
+
+### Generated Output
+
+The scanner generates a TypeScript file with all discovered annotations:
+
+```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;
+
+export type AnnotationId = typeof annotationIds[number];
+```
+
+### Using Generated Types
+
+Import the generated types for type-safe annotation access:
+
+```tsx
+import { annotations, AnnotationId } from './generated/annotations';
+
+function highlightElement(id: AnnotationId) {
+  const locations = annotations[id];
+  console.log(`Found at: ${locations[0].filePath}:${locations[0].line}`);
+}
+
+// Type error: "invalid-id" is not a valid AnnotationId
+highlightElement("invalid-id");
+```
+
+## TypeScript
+
+This package is written in TypeScript and includes full type definitions. All types are exported:
+
+```tsx
+import type {
+  AnnotateProps,
+  AnnotateProviderProps,
+  BorderStyle,
+  HighlightOverlayProps,
+  LabelPosition,
+  ReactAnnotateConfig,
+  ReactAnnotateDefaults,
+  UseAnnotationOptions,
+  UseHighlightOptions,
+} from 'uidex';
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "uidex",
+  "version": "0.0.1",
+  "description": "A framework-agnostic library for highlighting and annotating UI elements",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "keywords": [
+    "annotation",
+    "highlight",
+    "overlay",
+    "component",
+    "react",
+    "vanilla-js",
+    "framework-agnostic"
+  ],
+  "files": []
+}