immerser-react 1.0.0

package/src/ImmerserRoot.tsx

@@ -0,0 +1,54 @@
+import { CroppedFullAbsoluteStyles, NotInteractiveStyles } from 'immerser';
+import { useLayoutEffect, useRef, type HTMLAttributes } from 'react';
+
+import type { DeniedStyleProp } from './types';
+import { renderSolidsForLayer } from './utils/render-solids-for-layer';
+import { useImmerserConfigContext } from './context/use-immerser-config-context';
+
+type Props = Omit<HTMLAttributes<HTMLDivElement>, 'style'> & DeniedStyleProp;
+
+const maskStyle = {
+  ...CroppedFullAbsoluteStyles,
+} satisfies React.CSSProperties;
+
+/**
+ * Renders the fixed root container and the per-layer mask structure driven by the core controller.
+ * Direct children must be `ImmerserSolid` or `ImmerserPager` so each layer can receive its own solid classnames.
+ * Fragments and wrapper components are not accepted as direct children.
+ * In React mode, the core measures layer masks and moves their transitions; React owns the mask markup itself.
+ *
+ * @public
+ */
+export const ImmerserRoot = ({ children, style: _style, ...rest }: Props) => {
+  const { layerIds, registerMaskInner, setRendererRootNode, solidClassnamesByLayerId } =
+    useImmerserConfigContext('ImmerserRoot');
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  useLayoutEffect(() => {
+    setRendererRootNode(rootRef.current);
+
+    return () => {
+      setRendererRootNode(null);
+    };
+  }, [setRendererRootNode]);
+
+  return (
+    <div ref={rootRef} {...rest} data-immerser="" style={NotInteractiveStyles}>
+      {layerIds.map((layerId, layerIndex) => (
+        <div
+          key={layerId}
+          aria-hidden={layerIndex === 0 ? undefined : true}
+          data-immerser-layer-id={layerId}
+          data-immerser-mask=""
+          style={maskStyle}
+        >
+          <div ref={(node) => registerMaskInner(layerId, node)} data-immerser-mask-inner="" style={maskStyle}>
+            {renderSolidsForLayer(children, solidClassnamesByLayerId[layerId])}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+ImmerserRoot.displayName = 'ImmerserRoot';

package/src/ImmerserSolid.tsx

@@ -0,0 +1,41 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+import { InteractiveStyles } from 'immerser';
+import type { DeniedStyleProp } from './types';
+import { useImmerserConfigContext } from './context/use-immerser-config-context';
+
+type Props<T extends ElementType = 'div'> = {
+  /** Solid id used to read the matching classname from each layer configuration. */
+  name: string;
+  /** Element or component used to render the solid inside `ImmerserRoot`; defaults to `div`. */
+  as?: T;
+  /** Interactive content rendered inside every layer mask. Position it with your own CSS. */
+  children?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<T>, 'as' | 'children' | 'name' | 'style'> &
+  DeniedStyleProp;
+
+/**
+ * Declares content positioned inside `ImmerserRoot`, usually absolutely positioned within that root.
+ * React renders a copy into each mask and applies layer-specific classnames by solid name.
+ *
+ * @public
+ */
+export const ImmerserSolid = <T extends ElementType = 'div'>({
+  as,
+  children,
+  className,
+  name,
+  style: _style,
+  ...rest
+}: Props<T>) => {
+  useImmerserConfigContext('ImmerserSolid');
+
+  const Component = as ?? 'div';
+
+  return (
+    <Component {...rest} className={className} data-immerser-solid={name} style={InteractiveStyles}>
+      {children}
+    </Component>
+  );
+};
+
+ImmerserSolid.displayName = 'ImmerserSolid';

package/src/ImmerserSynchroLink.tsx

@@ -0,0 +1,57 @@
+import classNames from 'classnames';
+import { useContext, type ComponentPropsWithoutRef, type MouseEvent } from 'react';
+
+import { ImmerserSynchroContext } from './context/immerser-synchro-context';
+import type { DeniedStyleProp } from './types';
+
+type Props = {
+  /** Classname applied to generated copies of this link while any one of them is hovered. */
+  hoverClassName: string;
+  /** Stable hover group id for this source link. `ImmerserRoot` copies the link into every layer mask,
+   * so use the same `synchroId` for links that should share hover state,
+   * and different values for independent hover groups. */
+  synchroId: string;
+} & Omit<ComponentPropsWithoutRef<'a'>, 'style'> &
+  DeniedStyleProp;
+
+/**
+ * Anchor with synchronized hover state across layer clones.
+ * One source link is rendered into multiple layer-mask copies;
+ * `synchroId` keeps only those generated copies in the same hover group.
+ * This mirrors the core `data-immerser-synchro-hover` feature without relying on cloned DOM event wiring.
+ *
+ * @public
+ */
+export const ImmerserSynchroLink = ({
+  className,
+  hoverClassName,
+  onMouseEnter,
+  onMouseLeave,
+  synchroId,
+  ...rest
+}: Props) => {
+  const { activeSynchroId, setActiveSynchroId } = useContext(ImmerserSynchroContext);
+
+  function handleMouseEnter(event: MouseEvent<HTMLAnchorElement>) {
+    setActiveSynchroId(synchroId);
+    onMouseEnter?.(event);
+  }
+
+  function handleMouseLeave(event: MouseEvent<HTMLAnchorElement>) {
+    setActiveSynchroId((currentSynchroId) => (currentSynchroId === synchroId ? null : currentSynchroId));
+    onMouseLeave?.(event);
+  }
+
+  return (
+    <a
+      {...rest}
+      className={classNames(className, {
+        [hoverClassName]: activeSynchroId === synchroId,
+      })}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+    />
+  );
+};
+
+ImmerserSynchroLink.displayName = 'ImmerserSynchroLink';

package/src/context/immerser-config-context.ts

@@ -0,0 +1,10 @@
+import { createContext } from 'react';
+
+import type { ImmerserConfigContextValue } from '../types';
+
+/**
+ * Static render configuration shared by the provider with layer, solid and pager components.
+ *
+ * @internal
+ */
+export const ImmerserConfigContext = createContext<ImmerserConfigContextValue | null>(null);

package/src/context/immerser-context.ts

@@ -0,0 +1,10 @@
+import { createContext } from 'react';
+
+import type { ImmerserContextValue } from '../types';
+
+/**
+ * Active layer index reported by the core controller, or null before a provider is mounted.
+ *
+ * @internal
+ */
+export const ImmerserContext = createContext<ImmerserContextValue | null>(null);

package/src/context/immerser-synchro-context.ts

@@ -0,0 +1,14 @@
+import { createContext, type Dispatch, type SetStateAction } from 'react';
+
+/**
+ * Shared hover group state used to keep duplicated interactive solids visually in sync.
+ *
+ * @internal
+ */
+export const ImmerserSynchroContext = createContext<{
+  activeSynchroId: string | null;
+  setActiveSynchroId: Dispatch<SetStateAction<string | null>>;
+}>({
+  activeSynchroId: null,
+  setActiveSynchroId: () => {},
+});

package/src/context/use-immerser-config-context.ts

@@ -0,0 +1,16 @@
+import { useContext } from 'react';
+
+import { ImmerserConfigContext } from './immerser-config-context';
+import type { ImmerserConfigContextValue } from '../types';
+import { throwOutsideProviderError } from '../utils/throw-outside-provider-error';
+
+/** @internal */
+export const useImmerserConfigContext = (componentName: string) => {
+  const context = useContext(ImmerserConfigContext);
+
+  if (!context) {
+    throwOutsideProviderError(componentName);
+  }
+
+  return context as ImmerserConfigContextValue;
+};

package/src/context/use-immerser-context.ts

@@ -0,0 +1,16 @@
+import { useContext } from 'react';
+
+import { ImmerserContext } from './immerser-context';
+import type { ImmerserContextValue } from '../types';
+import { throwOutsideProviderError } from '../utils/throw-outside-provider-error';
+
+/** @internal */
+export const useImmerserContext = (componentName: string) => {
+  const context = useContext(ImmerserContext);
+
+  if (context === null) {
+    throwOutsideProviderError(componentName);
+  }
+
+  return context as ImmerserContextValue;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export { ImmerserProvider } from './ImmerserProvider';
+export { ImmerserRoot } from './ImmerserRoot';
+export { ImmerserLayer } from './ImmerserLayer';
+export { ImmerserPager } from './ImmerserPager';
+export { ImmerserSolid } from './ImmerserSolid';
+export { ImmerserSynchroLink } from './ImmerserSynchroLink';

package/src/types.ts

@@ -0,0 +1,30 @@
+import type { SolidClassnamesByLayerId } from 'immerser';
+import type { ReactNode } from 'react';
+
+export type DeniedStyleProp = {
+  /**
+   * Inline styles are not supported by Immerser React components.
+   * The adapter reserves the style attribute for technical Immerser styles.
+   */
+  style?: never;
+};
+
+/** @internal */
+export type ImmerserContextValue = number;
+
+/** @internal */
+export type ImmerserConfigContextValue = {
+  layerIds: string[];
+  registerLayer: (id: string) => void;
+  unregisterLayer: (id: string) => void;
+  registerMaskInner: (id: string, node: HTMLElement | null) => void;
+  setRendererRootNode: (node: HTMLDivElement | null) => void;
+  solidClassnamesByLayerId: SolidClassnamesByLayerId;
+};
+
+/** @internal */
+export type SolidElementProps = {
+  children?: ReactNode;
+  className?: string;
+  name?: string;
+};

package/src/utils/assign-ref.ts

@@ -0,0 +1,16 @@
+import ImmerserController from 'immerser';
+import { ForwardedRef } from 'react';
+
+/** @internal */
+export const assignRef = (ref: ForwardedRef<ImmerserController | null>, value: ImmerserController | null) => {
+  if (!ref) {
+    return;
+  }
+
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+
+  ref.current = value;
+};

package/src/utils/render-solids-for-layer.tsx

@@ -0,0 +1,24 @@
+import classNames from 'classnames';
+import { Children, cloneElement, isValidElement, type ReactNode } from 'react';
+
+import { ImmerserPager } from '../ImmerserPager';
+import { ImmerserSolid } from '../ImmerserSolid';
+import type { SolidElementProps } from '../types';
+
+/** @internal */
+export const renderSolidsForLayer = (children: ReactNode, solidClassnames: Record<string, string> = {}): ReactNode =>
+  Children.map(children, (child) => {
+    if (child === null || child === undefined || child === false) {
+      return child;
+    }
+
+    if (!isValidElement<SolidElementProps>(child) || (child.type !== ImmerserSolid && child.type !== ImmerserPager)) {
+      throw new Error('ImmerserRoot accepts only ImmerserSolid or ImmerserPager as direct children.');
+    }
+
+    const name = child.props.name ?? 'pager';
+
+    return cloneElement(child, {
+      className: classNames(child.props.className, solidClassnames[name]),
+    });
+  });

package/src/utils/throw-outside-provider-error.ts

@@ -0,0 +1,6 @@
+/** @internal */
+export const throwOutsideProviderError = (componentName: string) => {
+  const message = `${componentName} must be used inside <ImmerserProvider>.`;
+
+  throw new Error(message);
+};

package/src/utils/use-immerser-registry.ts

@@ -0,0 +1,58 @@
+import { useCallback, useRef, useState } from 'react';
+
+/**
+ * Tracks layer ids, mask inner nodes and readiness for the external renderer DOM.
+ *
+ * @internal
+ */
+export const useImmerserRegistry = () => {
+  const maskInnerNodesRef = useRef(new Map<string, HTMLElement>());
+  const [layerIds, setLayerIds] = useState<string[]>([]);
+  const [, setReadyVersion] = useState(0);
+
+  const isReady =
+    layerIds.length > 0 &&
+    maskInnerNodesRef.current.size === layerIds.length &&
+    layerIds.every((layerId) => maskInnerNodesRef.current.has(layerId));
+
+  const registerLayer = useCallback((id: string) => {
+    setLayerIds((currentLayerIds) => {
+      if (currentLayerIds.includes(id)) {
+        return currentLayerIds;
+      }
+
+      return [...currentLayerIds, id];
+    });
+  }, []);
+
+  const unregisterLayer = useCallback((id: string) => {
+    setLayerIds((currentLayerIds) => currentLayerIds.filter((layerId) => layerId !== id));
+  }, []);
+
+  const registerMaskInner = useCallback((id: string, node: HTMLElement | null) => {
+    if (node) {
+      if (maskInnerNodesRef.current.get(id) === node) {
+        return;
+      }
+
+      maskInnerNodesRef.current.set(id, node);
+    } else {
+      if (!maskInnerNodesRef.current.has(id)) {
+        return;
+      }
+
+      maskInnerNodesRef.current.delete(id);
+    }
+
+    setReadyVersion((version) => version + 1);
+  }, []);
+
+  return {
+    isReady,
+    layerIds,
+    maskInnerNodesRef,
+    registerLayer,
+    unregisterLayer,
+    registerMaskInner,
+  };
+};