@fvc/hooks 1.1.1 → 1.1.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997

package/README.md

@@ -0,0 +1,216 @@
+# @fvc/hooks
+
+`@fvc/hooks` provides shared React utility hooks for FE-VIS applications. Exposes two low-level primitives that recur across the component library: stable ID resolution for accessibility wiring, and an imperative re-render trigger for state that lives outside React.
+
+## Installation
+
+```bash
+bun add @fvc/hooks
+```
+
+## Peer Dependencies
+
+```bash
+bun add react antd
+```
+
+## Import
+
+```ts
+import { useId, useForceUpdate } from '@fvc/hooks';
+```
+
+## Quick Start
+
+```tsx
+import { useId } from '@fvc/hooks';
+
+export function TextField({ id, label }: { id?: string; label: string }) {
+  const fieldId = useId(id);
+
+  return (
+    <>
+      <label htmlFor={fieldId}>{label}</label>
+      <input id={fieldId} type="text" />
+    </>
+  );
+}
+```
+
+## Available Hooks
+
+| Hook | Returns | Purpose |
+| --- | --- | --- |
+| [`useId`](#useid) | `string` | Stable unique ID — caller-supplied or auto-generated |
+| [`useForceUpdate`](#useforceupdate) | `() => void` | Unconditional re-render trigger for external state |
+
+## useId
+
+A reusable component that renders a `<label>` and `<input>` pair needs an `id` that is stable across re-renders, unique per instance, and overridable by the caller. `useId` handles exactly that: it returns `id` unchanged when provided, and generates a `fvc-{9 base36 chars}` fallback on mount that never changes.
+
+> Distinct from React's built-in `useId` — this hook's primary value is the caller-override pattern. React's `useId` is SSR-safe but cannot be overridden by a prop.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string \| undefined` | `undefined` | When provided, returned as-is — skips generation entirely. |
+| `generateId` | `() => string` | `randomId` | ID factory, called once on mount. Provide this for a custom naming scheme. |
+
+### Common Usage
+
+#### Auto-generated ID
+
+```tsx
+function FormField({ label }: { label: string }) {
+  const fieldId = useId();
+
+  return (
+    <>
+      <label htmlFor={fieldId}>{label}</label>
+      <input id={fieldId} />
+    </>
+  );
+}
+```
+
+#### Caller-supplied ID
+
+```tsx
+// Explicit id — required when a parent anchors aria-describedby or a test
+// selector to a predictable value
+<FormField id="signup-email" label="Email" />
+```
+
+#### Custom ID factory
+
+```tsx
+const prefixed = (prefix: string) => () =>
+  `${prefix}-${Math.random().toString(36).slice(2, 9)}`;
+
+const fieldId = useId(undefined, prefixed('form'));
+```
+
+## useForceUpdate
+
+Returns a stable dispatch function that triggers an unconditional re-render of the host component. Backed by `useReducer`, the returned reference never changes across renders — it is safe in `useEffect` dependency arrays and cleanup functions.
+
+Use this only when state lives outside React's model — a `useRef` value, an external store subscription, or a mutable object from a third-party library — and the view needs to reflect a change React did not observe.
+
+### Parameters
+
+`useForceUpdate` takes no parameters.
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `forceUpdate` | `() => void` | Calling it triggers an unconditional re-render. |
+
+### Common Usage
+
+#### Sync with an external interval
+
+```tsx
+function LiveClock() {
+  const forceUpdate = useForceUpdate();
+
+  useEffect(() => {
+    const timer = setInterval(forceUpdate, 1000);
+    return () => clearInterval(timer);
+  }, [forceUpdate]);
+
+  return <time>{new Date().toLocaleTimeString()}</time>;
+}
+```
+
+#### Sync with a mutable ref
+
+```tsx
+function MutableCounter() {
+  const forceUpdate = useForceUpdate();
+  const count = useRef(0);
+
+  return (
+    <button onClick={() => { count.current++; forceUpdate(); }}>
+      Count: {count.current}
+    </button>
+  );
+}
+```
+
+## Consumer Example
+
+```tsx
+import { useId, useForceUpdate } from '@fvc/hooks';
+import { useRef, useEffect } from 'react';
+
+interface ProgressBarProps {
+  id?: string;
+  getProgress: () => number;
+  label: string;
+}
+
+export function ProgressBar({ id, getProgress, label }: ProgressBarProps) {
+  const barId = useId(id);
+  const forceUpdate = useForceUpdate();
+
+  useEffect(() => {
+    const timer = setInterval(forceUpdate, 500);
+    return () => clearInterval(timer);
+  }, [forceUpdate]);
+
+  return (
+    <div>
+      <label htmlFor={barId}>{label}</label>
+      <progress id={barId} value={getProgress()} max={100} />
+    </div>
+  );
+}
+```
+
+## Testing
+
+Use `renderHook` from `@testing-library/react` to test hooks in isolation.
+
+```tsx
+import { renderHook, act } from '@testing-library/react';
+import { useId, useForceUpdate } from '@fvc/hooks';
+
+// useId
+it('returns the provided id', () => {
+  const { result } = renderHook(() => useId('my-id'));
+  expect(result.current).toBe('my-id');
+});
+
+it('generates a stable fvc-* id when no id is provided', () => {
+  const { result, rerender } = renderHook(() => useId());
+  const initial = result.current;
+  rerender();
+  expect(result.current).toBe(initial);
+  expect(result.current).toMatch(/^fvc-/);
+});
+
+// useForceUpdate
+it('triggers a re-render when called', () => {
+  let renderCount = 0;
+  const { result } = renderHook(() => {
+    renderCount++;
+    return useForceUpdate();
+  });
+  act(() => result.current());
+  expect(renderCount).toBe(2);
+});
+```
+
+## SSR Notes
+
+Neither hook accesses `window`, `document`, or any browser API — both are safe in server-side environments.
+
+`useId` generates its fallback ID with `Math.random()`. In SSR contexts, pass an explicit `id` prop to prevent hydration mismatches between server and client renders.
+
+## Development
+
+```bash
+bun run lint
+bun run type-check
+bun run test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fvc/hooks",
-  "version": "1.1.1",
+  "version": "1.1.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997",
   "main": "./dist/lib/index.js",
   "types": "./dist/lib/hooks/src/index.d.ts",
   "files": [
@@ -20,5 +20,17 @@
   "peerDependencies": {
     "react": "^18.0.0",
     "antd": "^5.0.0"
-  }
+  },
+  "keywords": [
+    "react",
+    "react-component",
+    "fvc",
+    "fe-vis-core",
+    "hooks",
+    "use-id",
+    "use-force-update",
+    "utilities",
+    "design-system",
+    "antd"
+  ]
 }