@proyecto-viviana/solidaria-components 0.3.2 → 0.4.0

package/src/utils.tsx

@@ -6,16 +6,20 @@
 import {
   type JSX,
   type Accessor,
+  type Context,
   type FlowComponent,
-  type ParentComponent,
+  createComponent,
   createContext,
   useContext,
   createMemo,
   createSignal,
   onMount,
+  sharedConfig,
+  untrack,
   Show,
 } from "solid-js";
 import { isServer } from "solid-js/web";
+import { mergeProps } from "@proyecto-viviana/solidaria";
 
 /**
  * Render props pattern - children can be a function that receives state
@@ -73,6 +77,19 @@ export interface RenderPropsResult<T> {
    *   {renderProps.renderChildren()}
    */
   renderChildren: () => JSX.Element;
+  /**
+   * Render a render-prop child ONCE over a reactive view of the values,
+   * mirroring how React reconciles a render prop's returned tree in place.
+   *
+   * Prefer this over `renderChildren()` for interactive leaf components (a
+   * Tab, a toggle segment) whose child wraps the pressable element: re-invoking
+   * the render function on every values() change recreates that DOM subtree,
+   * which detaches the pointer/press target mid-gesture and makes the browser
+   * suppress the native `click` (createPress then has to synthesize an
+   * untrusted fallback click — a visible parity break vs React). Static (non
+   * function) children are returned untouched, exactly like `renderChildren`.
+   */
+  renderChildrenStable: () => JSX.Element;
   /** The raw children prop (function or JSX) - use renderChildren() in most cases */
   children: RenderChildren<T> | undefined;
   /** The render props values accessor */
@@ -115,9 +132,55 @@ export function useRenderProps<T extends object>(
     class: computedClass,
     style: computedStyle,
     renderChildren: () => {
-      const currentValues = values();
       const children = props.children;
-      return typeof children === "function" ? children(currentValues) : children;
+      // Only read values() for render-prop children. Static JSX children must
+      // not track the render-state memo: re-running the insertion effect
+      // recreates real DOM nodes on every hover/press/focus flip (React keeps
+      // them stable via vdom diffing), which detaches the pressed node
+      // mid-press and suppresses the browser's native click.
+      //
+      // A render prop takes the values argument, so classify by arity — the
+      // same convention `solid-js/h` uses for dynamic props. A zero-arg
+      // function child is an accessor (a compiled `{expression}` child, a
+      // solid-refresh dev wrapper, a one-shot `solid-js/h` element thunk):
+      // return it untouched so the insert machinery unwraps it in its own
+      // nested effect. Calling it here would track its reads in the shared
+      // insertion effect, and every re-run disposes the child computations
+      // that effect owns — a one-shot h thunk then hands back the same
+      // disposed node, leaving connected DOM whose reactivity is dead.
+      return typeof children === "function" && children.length > 0
+        ? children(values())
+        : (children as JSX.Element);
+    },
+    renderChildrenStable: () => {
+      const children = props.children;
+      if (typeof children !== "function" || children.length === 0) {
+        return children as JSX.Element;
+      }
+      // Invoke the render function exactly once, over a getter view of the
+      // values, so the returned DOM is created a single time and only the
+      // reactive reads inside it (JSX bindings, component props) re-run on a
+      // values() change — React's reconciliation, not Solid's recreation.
+      //
+      // `untrack` keeps the enclosing insert from tracking values() (so it
+      // never re-runs and never recreates), but does NOT change the owner:
+      // this still executes inside the caller's insert scope, so any slotted
+      // context the render prop reads binds against the surrounding provider.
+      //
+      // The value keys are read once here (untracked). Render-state memos in
+      // this codebase return a fixed-shape object, so the key set is stable.
+      return untrack(() => {
+        const snapshot = values();
+        const view = {} as T;
+        for (const key of Object.keys(snapshot) as Array<keyof T & string>) {
+          Object.defineProperty(view, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => values()[key],
+          });
+        }
+        return (children as (renderProps: T) => JSX.Element)(view);
+      });
     },
     get children() {
       return props.children;
@@ -139,41 +202,177 @@ export function composeRenderProps<T extends object>(
   };
 }
 
+/** A Solid ref target: a callback, a mutable `{ current }` object, or undefined. */
+export type RefLike<T> = T | ((el: T) => void) | { current?: T | null } | undefined;
+
+/** A value paired with an optional ref to merge onto the consuming element. */
+export type WithRef<T, E> = T & { ref?: RefLike<E> };
+
 /**
- * Context value that can be null or the actual value
+ * A context value carrying named slots (mirrors react-aria-components'
+ * `SlottedValue`). Each entry under `slots` is the props object delivered to the
+ * component rendered with the matching `slot` name.
  */
-export type ContextValue<T> = T | null;
+export interface SlottedValue<T> {
+  slots?: Record<string, T>;
+}
+
+/** A slotted context value: a slots record, a bare value, or null/undefined. */
+export type SlottedContextValue<T> = SlottedValue<T> | T | null | undefined;
+
+/**
+ * The value type for a context consumed via {@link useContextProps}. Mirrors
+ * upstream `ContextValue<T, E>`: it may carry `slots` and an optional `ref` to
+ * merge onto the consuming element.
+ */
+export type ContextValue<T, E = HTMLElement> = SlottedContextValue<WithRef<T, E>>;
 
 /**
- * Creates a context with props and ref merging support
+ * Creates a context that can carry either a bare value or a `slots` record.
  */
 export function createSlottedContext<T>() {
-  return createContext<T | null>(null);
+  return createContext<SlottedContextValue<T>>(null);
+}
+
+/** Assigns an element to a Solid ref (callback or mutable `{ current }` object). */
+export function assignRef<T>(ref: RefLike<T>, el: T): void {
+  if (!ref) {
+    return;
+  }
+
+  if (typeof ref === "function") {
+    (ref as (el: T) => void)(el);
+  } else if (typeof ref === "object" && "current" in ref) {
+    (ref as { current?: T | null }).current = el;
+  }
+}
+
+/** Merges multiple Solid refs into one callback that forwards to each, once. */
+export function mergeRefs<T>(...refs: Array<RefLike<T>>): (el: T) => void {
+  return (el: T) => {
+    const seen = new Set<RefLike<T>>();
+    for (const ref of refs) {
+      if (!ref || seen.has(ref)) {
+        continue;
+      }
+
+      seen.add(ref);
+      assignRef(ref, el);
+    }
+  };
 }
 
 /**
- * Use context with null check
+ * Resolves a (possibly slotted) context value for the given slot name. Port of
+ * react-aria-components' `useSlottedContext`:
+ * - `slot === null` opts out of the context entirely (returns `null`);
+ * - if the context carries a `slots` record, the entry for `slot` (or
+ *   {@link DEFAULT_SLOT}) is returned, throwing on an unknown slot name;
+ * - otherwise the bare context value is returned.
  */
 export function useSlottedContext<T>(
-  context: ReturnType<typeof createContext<T | null>>,
-): T | null {
-  return useContext(context);
+  context: Context<SlottedContextValue<T>>,
+  slot?: string | null,
+): T | null | undefined {
+  const ctx = useContext(context);
+  if (slot === null) {
+    // An explicit `null` slot means: ignore this context.
+    return null;
+  }
+
+  if (ctx && typeof ctx === "object" && "slots" in ctx && ctx.slots) {
+    const slots = ctx.slots as Record<string, T>;
+    const slotName = slot || DEFAULT_SLOT;
+    const slotValue = slots[slotName];
+    if (!slotValue) {
+      const validSlots = Object.keys(slots)
+        .map((name) => `"${name}"`)
+        .join(", ");
+      throw new Error(
+        slot
+          ? `Invalid slot "${slot}". Valid slot names are ${validSlots}.`
+          : `A slot prop is required. Valid slot names are ${validSlots}.`,
+      );
+    }
+    return slotValue;
+  }
+
+  return ctx as T | null | undefined;
 }
 
-export function useContextProps<TProps extends object, TRef>(
+/**
+ * Merges context-provided props and a context ref into a component's own props
+ * and ref. Port of react-aria-components' `useContextProps`:
+ * - the context is resolved for `props.slot` via {@link useSlottedContext};
+ * - props win over context props (handler props are chained by `mergeProps`);
+ * - the component's own ref and the context's ref merge into one callback.
+ *
+ * The prop merge stays reactive (Solid `mergeProps` preserves getters), so prop
+ * changes keep flowing; the context value is read once at setup, matching a single
+ * upstream render.
+ */
+export function useContextProps<TProps extends SlotProps, TRef>(
   props: TProps,
-  ref: TRef,
-  context?: ContextValue<Partial<TProps>>,
-): [TProps, TRef] {
-  if (!context) return [props, ref];
-  return [{ ...(context as TProps), ...props }, ref];
+  ref: RefLike<TRef>,
+  context: Context<ContextValue<TProps, TRef>>,
+): [TProps, (el: TRef) => void] {
+  const ctx = (useSlottedContext(context, props.slot) ?? {}) as WithRef<Partial<TProps>, TRef>;
+  const { ref: contextRef, ...contextProps } = ctx;
+  const mergedRef = mergeRefs(ref, contextRef);
+  const mergedProps = mergeProps(contextProps as object, props as object) as unknown as TProps;
+  return [mergedProps, mergedRef];
 }
 
-export const Provider: ParentComponent<{
-  values: Array<[ReturnType<typeof createContext<unknown>>, unknown]>;
-}> = (props) => {
-  return props.children;
-};
+/**
+ * Detects whether slotted content was rendered into a placeholder, for the
+ * aria-label fallback pattern. Port of react-aria-components' `useSlot`: returns a
+ * ref callback to attach to the placeholder and an accessor that is `true` while
+ * an element is mounted there. The accessor flips to `false` after mount if the
+ * ref never ran (no slotted content was provided).
+ */
+export function useSlot(initialState = true): [(el: Element | null) => void, Accessor<boolean>] {
+  const [hasSlot, setHasSlot] = createSignal(initialState);
+  let hasRun = false;
+  const ref = (el: Element | null) => {
+    hasRun = true;
+    setHasSlot(!!el);
+  };
+  onMount(() => {
+    if (!hasRun) {
+      setHasSlot(false);
+    }
+  });
+  return [ref, hasSlot];
+}
+
+/**
+ * Nests a set of context providers around `children`. Port of
+ * react-aria-components' `Provider`: each `[Context, value]` pair wraps the
+ * previous result, so the LAST pair is the outermost provider — matching upstream's
+ * wrap-in-iteration-order.
+ *
+ * `children` is read through a lazy getter inside the innermost provider so child
+ * components are *created* within every provider's owner; Solid binds `useContext`
+ * at component-execution time, so eager children would miss these providers.
+ */
+export function Provider(props: {
+  values: Array<[Context<unknown>, unknown]>;
+  children: JSX.Element;
+}): JSX.Element {
+  const build = (index: number): JSX.Element => {
+    if (index < 0) {
+      return props.children;
+    }
+    const [context, value] = props.values[index];
+    return createComponent(context.Provider, {
+      value,
+      get children() {
+        return build(index - 1);
+      },
+    });
+  };
+  return build(props.values.length - 1);
+}
 
 /**
  * Converts boolean state values to data attributes
@@ -299,7 +498,12 @@ export const ClientOnly: FlowComponent<ClientOnlyProps> = (props) => {
     return <>{props.fallback}</>;
   }
 
-  // On client, track if we've hydrated
+  // Outside a hydration walk there is nothing to defer (see useIsHydrated).
+  if (!sharedConfig.context) {
+    return <>{props.children}</>;
+  }
+
+  // Hydrating: render the fallback until the walk completes.
   const [isHydrated, setIsHydrated] = createSignal(false);
 
   // onMount runs after hydration is complete
@@ -334,16 +538,28 @@ export function useIsHydrated(): Accessor<boolean> {
     return () => false;
   }
 
-  // On client, start false (so the first render matches the server, which
+  // Outside a hydration walk (pure CSR, or a remount created after hydration
+  // finished) the caller is already "hydrated" — report true immediately.
+  // Solid sets `sharedConfig.context` only while synchronously walking
+  // server-rendered DOM, so this is exactly the window the false→true flip
+  // exists for. A fresh per-instance false→true flip on every remount is not
+  // just wasted work: ancestor `children()`/`Context.Provider` resolution
+  // unwraps and tracks the <Show> accessor this hook gates, so the post-mount
+  // flip re-resolves those children, recreates the subtree (with another fresh
+  // signal), and loops forever — a stack overflow with no overlay rendered.
+  if (!sharedConfig.context) {
+    return () => true;
+  }
+
+  // Hydrating: start false (so the first render matches the server, which
   // emitted nothing for hydrated-gated content) and flip to true after mount.
   const [isHydrated, setIsHydrated] = createSignal(false);
 
   // onMount runs in the effect phase — *after* the synchronous hydration pass
   // has finished walking the server DOM — so flipping here renders the gated
   // content as a fresh client-side update (Portal: no getNextElement walk, no
-  // mismatch), yet fires synchronously under `render()` (unit tests / pure CSR)
-  // where requestAnimationFrame would never run. This mirrors the component
-  // gate above and is strictly earlier than a rAF tick.
+  // mismatch). This mirrors the component gate above and is strictly earlier
+  // than a rAF tick.
   onMount(() => {
     setIsHydrated(true);
   });