@structuralists/scaffolding 0.0.2 → 0.1.1

package/src/components/Navigation/TabBar/TabBar.stories.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { TabBar } from './index';
 
 const meta: Meta<typeof TabBar> = {

package/src/components/Navigation/VerticalNav/VerticalNav.stories.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { VerticalNav } from './index';
 
 const meta: Meta<typeof VerticalNav> = {

package/src/components/Overlays/Popover/Popover.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useRef, useState } from 'react';
 import { Popover } from './index';
 import { Button } from '../../Forms/Button';

package/src/components/Overlays/Tooltip/Tooltip.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Tooltip } from './index';
 import type { TooltipPlacement } from './types';
 import { Button } from '../../Forms/Button';

package/src/components/Primitives/EmptyValue/EmptyValue.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { EmptyValue } from './index';
 
 const meta: Meta<typeof EmptyValue> = {

package/src/components/Primitives/LinedStack/LinedStack.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { LinedStack } from './index';
 import { Text } from '../../Content/Text';
 

package/src/components/Primitives/LongText/LongText.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { LongText } from './index';
 
 const meta: Meta<typeof LongText> = {

package/src/components/Primitives/Num/Num.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Num } from './index';
 
 const meta: Meta<typeof Num> = {

package/src/components/Primitives/Percent/Percent.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Percent } from './index';
 
 const meta: Meta<typeof Percent> = {

package/src/components/Primitives/RelativeTime/RelativeTime.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { RelativeTime } from './index';
 
 const meta: Meta<typeof RelativeTime> = {

package/src/components/Tables/BigTable/BigTable.stories.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   BigTable,
   badgeColumn,

package/src/components/Tables/QuickTable/QuickTable.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   QuickTable,
   QuickTableCell,

package/src/forms/CLAUDE.md

@@ -0,0 +1,144 @@
+# src/forms
+
+Strongly-typed React form state hook. The headline feature is **validation that
+propagates type refinements to the submit handler** — passing the right
+constraints means the submit handler's `values` argument has a tighter type
+than the initial form values.
+
+## Mental model
+
+A form has three types in flight:
+
+1. **`FormType`** — what fields exist and what they could hold. Often loose
+   (`{ a: string | undefined }`).
+2. **`Validations<FormType>`** — a per-field map of validator functions plus,
+   at the type level, refinement markers carried by each validator.
+3. **`SubmitType = Refine<FormType, typeof validations>`** — `FormType` with
+   each field narrowed by the refinement that field's validator carries.
+
+The form hook accepts `initialValues` of `FormType` and `constraints` of
+`Validations<FormType>`, then hands `SubmitType` to `onSubmit`. The user
+wrote a constraint, so the user has earned a tighter type at submit time.
+
+## The validator shape
+
+A validator is just:
+
+```ts
+(val: T) => string | null  // null = pass; string = error message
+```
+
+No library, no fluent builder, no schema DSL. Composition is via plain
+function composition.
+
+## Aggregation: `perField`
+
+```ts
+const constraints = perField({
+  a: (val: string | undefined) => !val ? "'a' cannot be empty" : null,
+}) as const satisfies Validations<FormType>;
+```
+
+`perField` is the entry point that produces a `Validations<FormType>`-shaped
+value while preserving the precise types of each individual validator.
+
+### Why `as const satisfies` (both required)
+
+- **`as const`** freezes the object's literal type — including each
+  validator's specific function type and any refinement markers attached
+  to it. Without `as const`, function types widen, markers are lost,
+  `Refine<>` has nothing to walk.
+- **`satisfies Validations<FormType>`** checks shape against `FormType`
+  (every key valid, every validator's input compatible) without widening
+  the inferred type the way an annotation `: Validations<FormType>` would.
+
+The combination = "type-check this shape, but don't lose any precision."
+
+## Standard-library validators carry refinements
+
+Built-in validators (e.g. `notEmpty`, `oneOf`, `matches`) expose a phantom
+property whose type encodes the refinement they enforce. Sketch:
+
+```ts
+type Refinement<Excluded = never> = { readonly __excludes: Excluded };
+
+type Validator<Input, Excluded = never> =
+  ((val: Input) => string | null) & Refinement<Excluded>;
+
+// notEmpty: rules out null, undefined, and the empty-string literal
+const notEmpty = (fieldName: string): Validator<unknown, null | undefined | ''> =>
+  Object.assign(
+    (val: unknown) => (val == null || val === '') ? `'${fieldName}' cannot be empty` : null,
+    {} as Refinement<null | undefined | ''>,
+  );
+```
+
+`__excludes` is the *operation* the validator performs at the type level
+(`Exclude<FieldType, __excludes>`), not the resulting type — because the
+field type isn't known when the validator is constructed. The result
+type is computed per-field by `Refine<>` at the use site.
+
+The marker is **required** on `Refinement<>` (not optional). This forces
+every validator to declare its refinement explicitly — even validators
+that narrow nothing must say so via `Excl = never`. It also keeps
+`infer Excl` extraction reliable; optional properties make inference
+unreliable in some intersections.
+
+## `Refine<FormType, typeof constraints>`
+
+Walks the constraints object, reads each field's validator's
+`__excludes` marker, applies `Exclude<FormType[K], __excludes>`. Fields
+without a constraint pass through unchanged. The result is the type
+handed to `onSubmit`.
+
+```ts
+type FormType   = { a: string | undefined; b: number };
+type C          = typeof constraints;             // a: notEmpty
+type SubmitType = Refine<FormType, C>;            // { a: string; b: number }
+```
+
+## Hook surface
+
+```ts
+useFormState({
+  initialValues: FormType,
+  constraints:   Validations<FormType>,    // optional; defaults to no refinement
+  onSubmit:      (values: Refine<FormType, typeof constraints>) => void,
+});
+```
+
+## Caveats — known and accepted
+
+- **`Exclude<string, ''>` is still `string`.** The empty-string refinement
+  only narrows fields whose type is a *union* containing the literal `''`.
+  For plain `string`, `notEmpty` still validates at runtime, but the
+  submit type is unchanged. This is a TypeScript-not-our-problem
+  limitation; we don't paper over it.
+- **Phantom markers must survive `as const`.** Any helper that wraps or
+  re-exports a validator must preserve its full type — no signature
+  re-annotation, no widening. If you write a higher-order validator
+  (e.g. `optional(notEmpty('a'))`), keep the marker conjunction explicit
+  in the return type.
+- **No runtime carrier.** Markers are pure type-level. Don't `Object.assign`
+  real values onto validators except as opaque type tags — anything else
+  invites consumers to depend on the runtime shape.
+
+## Why we're building it this way from the start
+
+The whole carrier-type approach falls apart if it gets retrofitted onto
+existing un-typed validators or onto a hook with looser types. The submit
+type's correctness depends on every layer (validator construction,
+`perField`, `as const`, `satisfies`, the hook signature) preserving
+precision end-to-end. So we wire it up before adding any consumers.
+
+## Layout
+
+- `useFormState/` — the hook + the value-model types (`FormValueSimple`,
+  `FormValuesObject`, `FormValueList`).
+- `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
+  Will be used for granular setters and for surfacing per-field
+  errors/touched state. Coupled to the form value model intentionally.
+- (planned) `validations/` — `perField`, `Validations<T>`, `Refine<T,V>`,
+  `Refinement<>` infra.
+- (planned) `validators/` — the standard-library validators
+  (`notEmpty`, `oneOf`, `matches`, …) each carrying its own refinement.

package/src/forms/path/path.ts

@@ -0,0 +1,50 @@
+import type { Cursor, CursorStep, Path, PathStep, ValueAt } from './types';
+
+const makeCursor = <T>(steps: readonly CursorStep[]): Cursor<T> => ({
+  at<P extends Path<T>>(p: P): Cursor<ValueAt<T, P>> {
+    const keySteps: CursorStep[] = (p as readonly PathStep[]).map((key) => ({
+      kind: 'key',
+      key,
+    }));
+
+    return makeCursor<ValueAt<T, P>>([...steps, ...keySteps]);
+  },
+  narrow<U extends T>(predicate: (val: T) => val is U): Cursor<U> {
+    return makeCursor<U>([
+      ...steps,
+      { kind: 'narrow', predicate: predicate as (val: unknown) => boolean },
+    ]);
+  },
+  build() {
+    return [...steps];
+  },
+});
+
+export const path = <T>(): Cursor<T> => makeCursor<T>([]);
+
+// Walk steps against a value. Returns undefined if any step fails — missing
+// key, out-of-bounds index, or a narrow predicate that rejects the current
+// value. Callers using the typed cursor know what shape to expect; this is
+// the runtime escape hatch that surfaces "the path didn't resolve."
+export const read = (root: unknown, steps: readonly CursorStep[]): unknown => {
+  let cursor: unknown = root;
+
+  for (const step of steps) {
+    if (cursor == null) return undefined;
+
+    if (step.kind === 'narrow') {
+      if (!step.predicate(cursor)) return undefined;
+      continue;
+    }
+
+    if (typeof step.key === 'number') {
+      if (!Array.isArray(cursor)) return undefined;
+      cursor = cursor[step.key];
+    } else {
+      if (typeof cursor !== 'object') return undefined;
+      cursor = (cursor as Record<string, unknown>)[step.key];
+    }
+  }
+
+  return cursor;
+};

package/src/forms/path/types.test-d.ts

@@ -0,0 +1,175 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { path } from './path';
+import type { Cursor, Path, ValueAt } from './types';
+
+type FlatObj = {
+  name: string;
+  age: number;
+  tags: string[]; // string[] is a FormValueSimple — treated as a leaf
+};
+
+type NestedObj = {
+  user: {
+    profile: { name: string; email: string };
+    settings: { theme: string };
+  };
+};
+
+type WithList = {
+  items: Array<{ title: string; qty: number }>;
+};
+
+type Mixed = {
+  user: { name: string };
+  items: Array<{
+    id: number;
+    nested: { label: string };
+  }>;
+};
+
+describe('Path<T>', () => {
+  it('expands flat object keys to single-step paths', () => {
+    type P = Path<FlatObj>;
+    expectTypeOf<P>().toEqualTypeOf<['name'] | ['age'] | ['tags']>();
+  });
+
+  it('descends into nested objects', () => {
+    type P = Path<NestedObj>;
+    expectTypeOf<P>().toEqualTypeOf<
+      | ['user']
+      | ['user', 'profile']
+      | ['user', 'profile', 'name']
+      | ['user', 'profile', 'email']
+      | ['user', 'settings']
+      | ['user', 'settings', 'theme']
+    >();
+  });
+
+  it('uses `number` for list indices', () => {
+    type P = Path<WithList>;
+    expectTypeOf<P>().toEqualTypeOf<
+      | ['items']
+      | ['items', number]
+      | ['items', number, 'title']
+      | ['items', number, 'qty']
+    >();
+  });
+
+  it('combines object and list traversal', () => {
+    type P = Path<Mixed>;
+    expectTypeOf<P>().toEqualTypeOf<
+      | ['user']
+      | ['user', 'name']
+      | ['items']
+      | ['items', number]
+      | ['items', number, 'id']
+      | ['items', number, 'nested']
+      | ['items', number, 'nested', 'label']
+    >();
+  });
+
+  it('produces `never` for FormValueSimple leaves', () => {
+    expectTypeOf<Path<string>>().toEqualTypeOf<never>();
+    expectTypeOf<Path<number>>().toEqualTypeOf<never>();
+    expectTypeOf<Path<string[]>>().toEqualTypeOf<never>();
+    expectTypeOf<Path<undefined>>().toEqualTypeOf<never>();
+  });
+});
+
+describe('ValueAt<T, P>', () => {
+  it('returns T when the path is empty', () => {
+    expectTypeOf<ValueAt<FlatObj, []>>().toEqualTypeOf<FlatObj>();
+  });
+
+  it('resolves a single key', () => {
+    expectTypeOf<ValueAt<FlatObj, ['name']>>().toEqualTypeOf<string>();
+    expectTypeOf<ValueAt<FlatObj, ['age']>>().toEqualTypeOf<number>();
+    expectTypeOf<ValueAt<FlatObj, ['tags']>>().toEqualTypeOf<string[]>();
+  });
+
+  it('resolves a nested object path', () => {
+    expectTypeOf<ValueAt<NestedObj, ['user']>>().toEqualTypeOf<
+      NestedObj['user']
+    >();
+    expectTypeOf<
+      ValueAt<NestedObj, ['user', 'profile', 'email']>
+    >().toEqualTypeOf<string>();
+  });
+
+  it('walks into list elements via a numeric step', () => {
+    expectTypeOf<ValueAt<WithList, ['items']>>().toEqualTypeOf<
+      Array<{ title: string; qty: number }>
+    >();
+    expectTypeOf<ValueAt<WithList, ['items', number]>>().toEqualTypeOf<{
+      title: string;
+      qty: number;
+    }>();
+    expectTypeOf<
+      ValueAt<WithList, ['items', number, 'title']>
+    >().toEqualTypeOf<string>();
+  });
+
+  it('resolves a deep mixed path', () => {
+    expectTypeOf<
+      ValueAt<Mixed, ['items', number, 'nested', 'label']>
+    >().toEqualTypeOf<string>();
+  });
+
+  it('returns `never` for an unknown key', () => {
+    // ValueAt's constraint is just `readonly PathStep[]`, so unknown keys
+    // don't error at the call site — they resolve to `never`.
+    expectTypeOf<ValueAt<FlatObj, ['nope']>>().toEqualTypeOf<never>();
+    expectTypeOf<ValueAt<FlatObj, [string]>>().toEqualTypeOf<never>();
+  });
+
+  it('returns `never` when indexing a non-list with a number', () => {
+    type Bad = ValueAt<FlatObj, [number]>;
+    expectTypeOf<Bad>().toEqualTypeOf<never>();
+  });
+});
+
+describe('Cursor<T>', () => {
+  it('infers ValueAt for a single .at() step', () => {
+    const c = path<NestedObj>().at(['user']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<NestedObj['user']>>();
+  });
+
+  it('chains .at() across nested objects', () => {
+    const c = path<NestedObj>().at(['user']).at(['profile']).at(['name']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<string>>();
+  });
+
+  it('descends into list elements via a numeric step', () => {
+    const c = path<WithList>().at(['items', 0, 'title']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<string>>();
+  });
+
+  it('rejects paths that are not part of Path<T>', () => {
+    // @ts-expect-error 'nope' is not a valid first step on NestedObj
+    path<NestedObj>().at(['nope']);
+
+    // @ts-expect-error string keys can't index a list
+    path<WithList>().at(['items', 'title']);
+
+    // @ts-expect-error number keys can't index a non-list object
+    path<NestedObj>().at(['user', 0]);
+  });
+
+  it('narrow() refines the cursor type', () => {
+    const c = path<{ value: string | number }>().at(['value']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<string | number>>();
+
+    const narrowed = c.narrow((v): v is string => typeof v === 'string');
+    expectTypeOf(narrowed).toEqualTypeOf<Cursor<string>>();
+  });
+
+  it('build() returns the recorded steps', () => {
+    const steps = path<NestedObj>().at(['user', 'profile', 'name']).build();
+    expectTypeOf(steps).toMatchTypeOf<
+      Array<
+        | { kind: 'key'; key: string | number }
+        | { kind: 'narrow'; predicate: (v: unknown) => boolean }
+      >
+    >();
+  });
+});

package/src/forms/path/types.ts

@@ -0,0 +1,35 @@
+import type { FormValuesObject, FormValueList } from '../useFormState/types';
+
+export type PathStep = string | number;
+
+export type Path<T> =
+  T extends FormValuesObject
+    ? {
+        [K in Extract<keyof T, PathStep>]: [K] | [K, ...Path<T[K]>];
+      }[Extract<keyof T, PathStep>]
+    : T extends FormValueList
+      ? [number] | [number, ...Path<T[number]>]
+      : never;
+
+export type ValueAt<T, P extends readonly PathStep[]> =
+  P extends readonly [infer Head, ...infer Rest]
+    ? Rest extends readonly PathStep[]
+      ? Head extends number
+        ? T extends FormValueList
+          ? ValueAt<T[number], Rest>
+          : never
+        : Head extends keyof T
+          ? ValueAt<T[Head], Rest>
+          : never
+      : never
+    : T;
+
+export type CursorStep =
+  | { kind: 'key'; key: PathStep }
+  | { kind: 'narrow'; predicate: (val: unknown) => boolean };
+
+export type Cursor<T> = {
+  at<P extends Path<T>>(path: P): Cursor<ValueAt<T, P>>;
+  narrow<U extends T>(predicate: (val: T) => val is U): Cursor<U>;
+  build(): CursorStep[];
+};

package/src/forms/useFormState/types.ts

@@ -0,0 +1,13 @@
+export type FormValueSimple = string | number | bigint | string[] | Set<string> | undefined | null;
+
+export type FormValuesObject = { [k in string]: FormValue };
+
+export type FormValueList = FormValuesObject[];
+
+export type FormValue = FormValuesObject | FormValueList | FormValueSimple;
+
+export type FormHelpers<T extends FormValuesObject> = {
+  values: T;
+  // todo: likely remove once other setter are available
+  onValueChanges: (val: T | ((prev: T) => T)) => void;
+};

package/src/forms/useFormState/useFormState.ts

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+import type { FormHelpers, FormValuesObject } from './types';
+
+type Args<T extends FormValuesObject> = {
+  initialValues: T;
+};
+
+export const useFormState = <T extends FormValuesObject>(args: Args<T>): FormHelpers<T> => {
+  const { initialValues } = args;
+
+  const [values, onValueChanges] = useState<T>(initialValues);
+
+  return { values, onValueChanges };
+};

package/src/forms/validations/types.test-d.ts

@@ -0,0 +1,26 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import type { Refinement, Validator } from './types';
+
+describe('Validator<Input, Excluded>', () => {
+  it('preserves the input type as the call parameter', () => {
+    type V = Validator<string | undefined, null | undefined>;
+    expectTypeOf<V>().parameter(0).toEqualTypeOf<string | undefined>();
+  });
+
+  it('always returns string | null', () => {
+    type V = Validator<string, never>;
+    expectTypeOf<V>().returns.toEqualTypeOf<string | null>();
+  });
+
+  it('carries the Excluded type, recoverable via `Refinement<infer X>`', () => {
+    type V = Validator<string | undefined, null | undefined | ''>;
+    type Extracted = V extends Refinement<infer X> ? X : never;
+    expectTypeOf<Extracted>().toEqualTypeOf<null | undefined | ''>();
+  });
+
+  it('defaults Excluded to never when omitted', () => {
+    type V = Validator<string>;
+    type Extracted = V extends Refinement<infer X> ? X : never;
+    expectTypeOf<Extracted>().toBeNever();
+  });
+});

package/src/forms/validations/types.ts

@@ -0,0 +1,15 @@
+// Phantom marker carried by validators. The runtime value of `__excludes`
+// is meaningless and never read — only its declared type matters. Required
+// (not optional) so validators can't accidentally drop the marker, and so
+// `Refine<>` can rely on extraction working uniformly. Construction sites
+// supply the marker via a cast: `Object.assign(fn, {} as Refinement<X>)`.
+export type Refinement<Excluded = never> = {
+  readonly __excludes: Excluded;
+};
+
+// A validator is a plain `(val: Input) => string | null` function intersected
+// with a `Refinement<Excluded>` marker. `Excluded` defaults to `never`,
+// meaning "this validator narrows nothing at the type level" (it still
+// validates at runtime; it just doesn't shrink the field's submit type).
+export type Validator<Input, Excluded = never> =
+  ((val: Input) => string | null) & Refinement<Excluded>;

package/src/hooks/useClickOutside/index.ts

@@ -0,0 +1,57 @@
+import { useEffect, useRef, type RefObject } from 'react';
+import { useStableCallback } from '../useStableCallback';
+
+type UseClickOutsideArgs<Element extends HTMLElement> = {
+  /** Optional external ref. When omitted, the hook owns an internal ref —
+   *  attach the returned `ref` to the element you want to guard. */
+  ref?: RefObject<Element | null>;
+  /** Callback fired on a `pointerdown` outside the guarded element. When
+   *  `undefined`, the listener is detached (lets callers gate via a prop
+   *  without conditionally calling the hook). */
+  onOutside: (() => void) | undefined;
+  /** Detach the listener when false. Defaults to true. */
+  enabled?: boolean;
+};
+
+type UseClickOutsideReturn<Element extends HTMLElement> = {
+  /** Mirror of the passed `ref`, or an internal ref when none was passed.
+   *  Attach this to the element to be guarded. */
+  ref: RefObject<Element | null>;
+};
+
+/** Calls `onOutside` when a `pointerdown` lands outside the guarded
+ *  element. `pointerdown` is used so dismissal precedes focus shifts and
+ *  text-selection starts on the underlying target.
+ *
+ *  The callback is internally stabilized, so callers can pass an inline
+ *  function without retriggering the listener attach/detach effect.
+ *
+ *  Note: clicks inside portal'd descendants of the guarded element
+ *  (popovers, tooltips, menus) count as outside since they are not
+ *  DOM-contained. Compose with additional refs or a custom predicate
+ *  if that is not desired. */
+export const useClickOutside = <Element extends HTMLElement = HTMLElement>(
+  args: UseClickOutsideArgs<Element>,
+): UseClickOutsideReturn<Element> => {
+  const { ref: passedRef, onOutside, enabled = true } = args;
+
+  const innerRef = useRef<Element | null>(null);
+  const ref = passedRef ?? innerRef;
+
+  const stableOnOutside = useStableCallback({ callback: onOutside });
+  const isActive = enabled && onOutside != null;
+
+  useEffect(() => {
+    if (!isActive) return;
+    const handler = (event: PointerEvent) => {
+      const el = ref.current;
+      if (el == null) return;
+      if (event.target instanceof Node && el.contains(event.target)) return;
+      stableOnOutside();
+    };
+    document.addEventListener('pointerdown', handler);
+    return () => document.removeEventListener('pointerdown', handler);
+  }, [ref, isActive, stableOnOutside]);
+
+  return { ref };
+};

package/src/hooks/useStableCallback/index.ts

@@ -0,0 +1,36 @@
+import { useEffect, useRef, useState } from 'react';
+
+type UseStableCallbackArgs<Args extends readonly unknown[], Return> = {
+  callback: ((...args: Args) => Return) | undefined;
+};
+
+/** Returns a function reference that is stable for the component's lifetime
+ *  but always invokes the latest `callback`. Use this to keep effect dep
+ *  arrays from re-firing when a parent passes an inline callback prop.
+ *
+ *  The wrapper is held in `useState` (not `useCallback`) because React may
+ *  discard a `useCallback` memo at any time, which would silently break
+ *  identity-based dependency tracking; `useState`'s initial value is
+ *  guaranteed stable for the mount's lifetime.
+ *
+ *  The latest callback is committed via `useEffect`, so the wrapper still
+ *  reflects the previous value during a given render — call it from event
+ *  handlers and effects, not inline during render. */
+export const useStableCallback = <Args extends readonly unknown[], Return>(
+  args: UseStableCallbackArgs<Args, Return>,
+): ((...args: Args) => Return | undefined) => {
+  const { callback } = args;
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  const [stableFn] = useState(
+    () =>
+      (...callArgs: Args): Return | undefined =>
+        callbackRef.current?.(...callArgs),
+  );
+
+  return stableFn;
+};

package/src/index.ts

@@ -85,3 +85,5 @@ export { RelativeTime, type RelativeTimeProps } from './components/Primitives/Re
 export { LinedStack, type LinedStackProps } from './components/Primitives/LinedStack';
 export { LongText, type LongTextProps } from './components/Primitives/LongText';
 export { type BackgroundToken } from './tokens';
+export { useStableCallback } from './hooks/useStableCallback';
+export { useClickOutside } from './hooks/useClickOutside';