@nldoc/validation 1.0.0

package/README.md

@@ -0,0 +1,357 @@
+# @nldoc/validation
+
+Validation hooks and components for integrating NLdoc validation with TipTap editors.
+
+## Installation
+
+```bash
+npm install @nldoc/validation @nldoc/api @nldoc/types
+```
+
+## Features
+
+- **Validation Hooks**: React hooks for validating TipTap document content via the NLdoc API
+- **Validation Context**: Provider pattern for sharing validation state across components
+- **UI Components**: Headless UI components for displaying validation results
+- **Positioning & Stacking**: Sophisticated layout system for non-overlapping validation indicators
+- **Bundling**: Groups related validation findings from the same block-level element
+- **TypeScript**: Full TypeScript support with comprehensive type definitions
+
+## Quick Start
+
+### Using ValidationProvider (Recommended)
+
+The simplest way to add validation is with `ValidationProvider`. It **automatically tracks editor updates**, validates content with debouncing, and applies findings to the editor—no manual state management required.
+
+```tsx
+import { ValidationProvider, useValidationContext } from '@nldoc/validation'
+import { NLDocStarterKit } from '@nldoc/tiptap-extensions'
+import { useEditor, EditorContent } from '@tiptap/react'
+
+function ValidationStatus() {
+  const { findings, isValidating } = useValidationContext()
+  return <div>{isValidating ? 'Validating...' : `${findings.length} issues`}</div>
+}
+
+function MyEditor() {
+  const editor = useEditor({
+    extensions: [NLDocStarterKit],
+  })
+
+  return (
+    <ValidationProvider editor={editor} options={{ debounceDelay: 500 }}>
+      <EditorContent editor={editor} />
+      <ValidationStatus />
+    </ValidationProvider>
+  )
+}
+```
+
+**That's it!** ValidationProvider handles:
+- ✅ Tracking editor updates (while filtering out validation transactions)
+- ✅ Debouncing validation requests
+- ✅ Applying findings back to the editor automatically
+- ✅ Preventing infinite validation loops
+
+### Using the useValidation Hook (Advanced)
+
+For more control, use the `useValidation` hook directly and manage state yourself:
+
+```tsx
+import { useValidation } from '@nldoc/validation'
+import { useEditor } from '@tiptap/react'
+import { useState } from 'react'
+
+function MyEditor() {
+  const [editorJSON, setEditorJSON] = useState(null)
+
+  const editor = useEditor({
+    /* ...your extensions */
+    onUpdate: ({ editor }) => setEditorJSON(editor.getJSON())
+  })
+
+  const { findings, isValidating, error } = useValidation(editorJSON, {
+    debounceDelay: 500,
+    debounceMaxWait: 5000,
+  })
+
+  return (
+    <div>
+      <EditorContent editor={editor} />
+      {isValidating && <p>Validating...</p>}
+      {findings.length > 0 && <p>{findings.length} issues found</p>}
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useValidation(editorJSON, options)`
+
+Main validation hook that converts TipTap JSON to validation format and fetches validation findings.
+
+**Parameters:**
+- `editorJSON: JSONContent | null` - The TipTap editor JSON content
+- `options?: ValidationHookOptions` - Configuration options
+
+**Returns:** `Validation`
+- `findings: ValidationFinding[]` - Array of validation findings
+- `isValidating: boolean` - Whether validation is in progress
+- `error: Error | null` - Error if validation failed
+
+**Options:**
+- `debounceDelay?: number` - Delay in ms before starting validation (default: 500)
+- `debounceMaxWait?: number` - Maximum wait time in ms before forcing validation (default: 5000)
+- `includeAssets?: boolean` - Whether to include image assets in validation (default: false)
+
+#### `useValidationContext()`
+
+Access validation state from context. Must be used within a `ValidationProvider`.
+
+**Returns:** `Validation`
+
+#### `useTiptapValidation(editorJSON, options)`
+
+Low-level hook that converts TipTap JSON to validation format with debouncing.
+
+### Components
+
+#### `<ValidationProvider>`
+
+Provider component that manages validation state and applies findings to the editor.
+
+**Automatically tracks editor updates** and validates content with debouncing. Excludes validation transactions to prevent infinite loops.
+
+**Props:**
+- `editor: Editor | null` - The TipTap editor instance
+- `editorJSON?: JSONContent | null` - (Optional) Manual editor JSON. If not provided, ValidationProvider tracks updates automatically
+- `options?: ValidationHookOptions` - Validation configuration
+- `autoApplyFindings?: boolean` - Whether to automatically apply findings (default: true)
+- `onApplyFindings?: (editor, findings) => void` - Custom callback to apply findings
+
+**Example (Automatic):**
+```tsx
+<ValidationProvider editor={editor}>
+  <EditorContent editor={editor} />
+</ValidationProvider>
+```
+
+**Example (Manual Control):**
+```tsx
+const [editorJSON, setEditorJSON] = useState(null)
+
+<ValidationProvider editor={editor} editorJSON={editorJSON}>
+  <EditorContent editor={editor} />
+</ValidationProvider>
+```
+
+#### `<ValidationResult>`
+
+Headless component for displaying individual validation results. Highly customizable via render props.
+
+**Props:**
+- `findings: ValidationFinding[]` - Array of findings to display
+- `isBundle?: boolean` - Whether this is a bundle of findings
+- `variant?: 'default' | 'stack'` - Display variant
+- `onResolve?: (ids: string[]) => void` - Callback when user resolves findings
+- `onRetrigger?: () => void` - Callback to retrigger validation
+- `renderIcon?: (type, props) => ReactNode` - Custom icon renderer
+- `renderMessage?: (finding, count, isBundle) => ReactNode` - Custom message renderer
+- `renderResolution?: (ids, onResolved) => ReactNode` - Custom resolution renderer
+- `className?: string` - CSS class for styling
+- `styles?: object` - Style overrides for specific elements
+
+#### `<ValidationResultSummary>`
+
+Main component that orchestrates the layout of all validation results with sophisticated positioning, stacking, and bundling.
+
+**Props:**
+- `findings: ValidationFinding[]` - All validation findings
+- `isAnimating?: boolean` - Whether editor is animating (delays layout updates)
+- `positioningConfig?: PositioningConfig` - Configuration for position calculations
+- `buildFindingBlockMap?: (findings) => Map<string, string>` - Custom function to map findings to parent blocks
+- `validationResultProps?: Partial<ValidationResultProps>` - Props to pass to ValidationResult components
+- `resizeDebounceDelay?: number` - Debounce delay for window resize (default: 100ms)
+
+## Utilities
+
+### Positioning
+
+```tsx
+import {
+  makePositionedFindings,
+  calculateDesiredYLocation,
+} from '@nldoc/validation'
+
+const positionedFindings = makePositionedFindings(findings, {
+  editorSelector: '#my-editor', // Default: '#tiptap'
+})
+```
+
+### Bundling
+
+```tsx
+import { computeBundles, BUNDLEABLE_RULES } from '@nldoc/validation'
+
+// Rules that support bundling:
+// - 'no-underline'
+// - 'style-bold-in-header'
+// - 'style-italic-in-header'
+
+const bundles = computeBundles(positionedFindings, findingBlockMap)
+```
+
+### Stacking
+
+```tsx
+import {
+  createInitialStacksFromItems,
+  mergeOverlappingStacksWithBundles,
+  positionStacksWithBundles,
+} from '@nldoc/validation'
+
+const initialStacks = createInitialStacksFromItems(items)
+const mergedStacks = mergeOverlappingStacksWithBundles(
+  initialStacks,
+  itemHeights,
+  expandedStackIds
+)
+const positioned = positionStacksWithBundles(mergedStacks, stackRefs)
+```
+
+## Advanced Usage
+
+### Custom Validation Result Display
+
+```tsx
+import { ValidationResult } from '@nldoc/validation'
+
+function MyValidationResult({ findings }) {
+  return (
+    <ValidationResult
+      findings={findings}
+      renderIcon={(type) => {
+        const icons = {
+          error: <ErrorIcon />,
+          warning: <WarningIcon />,
+          suggestion: <InfoIcon />,
+        }
+        return icons[type]
+      }}
+      renderMessage={(finding, count) => (
+        <div>
+          <h4>{finding.rule}</h4>
+          <p>{finding.message}</p>
+          {count > 1 && <span>{count} occurrences</span>}
+        </div>
+      )}
+      renderResolution={(ids, onResolved) => (
+        <button onClick={() => {
+          // Custom resolution logic
+          resolveFindings(ids)
+          onResolved()
+        }}>
+          Fix Issue
+        </button>
+      )}
+    />
+  )
+}
+```
+
+### Complete Example with TipTap
+
+```tsx
+import { ValidationProvider, useValidationContext } from '@nldoc/validation'
+import { NLDocStarterKit } from '@nldoc/tiptap-extensions'
+import { useEditor, EditorContent } from '@tiptap/react'
+
+function ValidationSidebar() {
+  const { findings, isValidating, error } = useValidationContext()
+
+  if (isValidating) return <div>Validating...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <aside>
+      <h3>Accessibility Issues</h3>
+      {findings.length === 0 ? (
+        <p>No issues found!</p>
+      ) : (
+        <ul>
+          {findings.map((finding, i) => (
+            <li key={i}>
+              [{finding.severity}] {finding.rule}
+            </li>
+          ))}
+        </ul>
+      )}
+    </aside>
+  )
+}
+
+function MyEditor() {
+  const editor = useEditor({
+    extensions: [
+      NLDocStarterKit.configure({
+        // Configure your extensions
+      }),
+    ],
+    content: '<p>Start typing...</p>',
+  })
+
+  return (
+    <ValidationProvider
+      editor={editor}
+      options={{
+        debounceDelay: 500,
+        debounceMaxWait: 5000,
+        includeAssets: false,
+      }}
+    >
+      <div style={{ display: 'flex' }}>
+        <EditorContent editor={editor} />
+        <ValidationSidebar />
+      </div>
+    </ValidationProvider>
+  )
+}
+```
+
+**Key Points:**
+- No manual state management needed
+- ValidationProvider automatically tracks updates
+- Findings are automatically applied to the editor
+- Validation transactions are filtered to prevent loops
+- Use `useValidationContext()` anywhere within the provider to access validation state
+
+## TypeScript
+
+All exports are fully typed. Key types:
+
+```typescript
+import type {
+  Validation,
+  ValidationHookOptions,
+  ValidationResultProps,
+  ValidationResultSummaryProps,
+  PositionedFinding,
+  Bundle,
+  Stack,
+  StackableItem,
+  PositioningConfig,
+} from '@nldoc/validation'
+```
+
+## Related Packages
+
+- `@nldoc/tiptap-extensions` - Custom TipTap extensions including ValidationFindingsExtension
+- `@nldoc/api` - API client for NLdoc services
+- `@nldoc/types` - Shared TypeScript types
+
+## License
+
+EUPL-1.2