feat(react): implement useInteractionTrace hook with pre-typed API

[frankieyan]

This PR adds a React hook useInteractionTrace that provides a declarative way to sign interaction traces when components mount. It follows the same withTypes() pattern as signInteractionTrace for compile-time type safety.

Stacked on top of #11
Documentation updates: #17

Example

import { useInteractionTrace } from '@doist/interaction-trace/react'

// Basic usage - signs trace on mount
function SettingsModal() {
    useInteractionTrace('open modal', { modalId: 'settings' })
    return <div>...</div>
}

// With pre-typed API (recommended)
type MyTraces = {
    'open modal': { modalId: string }
    'submit form': { formId: string; success: boolean }
}

const useTrace = useInteractionTrace.withTypes<MyTraces>()

function SettingsModal() {
    useTrace('open modal', { modalId: 'settings' })  // ✅ autocomplete works!
    return <div>...</div>
}

// Errors caught at compile time:
useTrace('opne modal', { modalId: 'settings' })  // ❌ Error: typo caught
useTrace('open modal', { formId: 'wrong' })      // ❌ Error: wrong details shape

Test Plan

To verify the type safety works:

1. Create a pre-typed hook:

   type MyTraces = {
       'test trace': { id: string }
   }
   const useTrace = useInteractionTrace.withTypes<MyTraces>()

2. Verify TypeScript catches errors:

   • Invalid trace names (e.g., useTrace('typo trace', ...))
   • Wrong payload shapes (e.g., useTrace('test trace', { wrong: 123 }))
   • Missing required properties (e.g., useTrace('test trace', {}))

3. Verify autocomplete suggests 'test trace' when typing the first argument

[doistbot-app]

This PR introduces a useInteractionTrace React hook, offering a declarative and type-safe way to sign interaction traces on component mount, complete with a withTypes() pattern for enhanced compile-time safety. This feature improves the developer experience by providing robust interaction tracing, and no issues were flagged during the review.

[Bloomca]

I am not sure how to test it, but the code looks good 👍

[frankieyan]

@Bloomca just something like this to verify type checking works should be enough: