@structuralists/scaffolding 0.0.1 → 0.1.0

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';

package/src/storybook/Composition.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 { Button } from '../components/Forms/Button';
 import { Field } from '../components/Forms/Field';

package/src/storybook/_StoryUtils.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Lorem, Placeholder, Toggle, Repeat } from './index';
 import { Button } from '../components/Forms/Button';
 import { Stack } from '../components/Layout/Stack';