feat: add layers to the slot system

Author: MartinCupela

src/components/ChatView/ChatViewNavigationContext.tsx

@@ -149,10 +149,23 @@ export type ChatViewOpenOptions = {
 };
 
 export type ChatViewNavigation = {
-  /** Release the binding held by `slot`. No-op for empty or persistent slots. */
+  /**
+   * Dismiss the top of `slot`. If the slot has layers (see {@link pushLayer}), pop the topmost
+   * layer, revealing what's beneath at its preserved state. Only when no layers remain does this
+   * release the base binding. No-op for empty or persistent slots.
+   */
   close: (slot: SlotName) => void;
   /** Hide `slot` without releasing its binding (subtree stays mounted). */
   hide: (slot: SlotName) => void;
+  /**
+   * Push `binding` as a **layer** on top of `slot`'s current content. The content beneath stays
+   * mounted (state/scroll preserved) and hidden; the layer covers it. Use for transient overlays
+   * that should return to the underlying view — e.g. a member profile opened over a thread, where
+   * `close`/`popLayer` restores the thread exactly where it was. Ephemeral (not serialized).
+   */
+  pushLayer: (slot: SlotName, binding: ChatViewEntityBinding) => void;
+  /** Pop `slot`'s top layer, revealing the layer/base beneath. No-op when there are no layers. */
+  popLayer: (slot: SlotName) => void;
   /**
    * Resolve a target slot for `binding` and bind it there, switching to the binding kind's view
    * first if needed (e.g. a `channel` binding activates the channels view).
@@ -187,6 +200,8 @@ const ChatViewNavigationContext = createContext<ChatViewNavigation>({
   hide: () => undefined,
   open: () => ({ reason: 'no-available-slot', status: 'rejected' }),
   openView: () => undefined,
+  popLayer: () => undefined,
+  pushLayer: () => undefined,
   unhide: () => undefined,
 });
 
@@ -223,7 +238,7 @@ export const useSlotForKey = (key?: string): SlotName | undefined => {
 export const ChatViewNavigationProvider = ({ children }: PropsWithChildren) => {
   const { layoutController, resolveActionTargetSlot } = useChatViewContext();
   const registry = useSlotRegistry();
-  const { availableSlots, slotBindings } = useLayoutViewState();
+  const { availableSlots, slotBindings, slotLayers } = useLayoutViewState();
   const { activeView } =
     useStateStore(layoutController.state, chatViewNavigationStateSelector) ??
     chatViewNavigationStateSelector(layoutController.state.getLatestValue());
@@ -363,6 +378,12 @@ export const ChatViewNavigationProvider = ({ children }: PropsWithChildren) => {
 
     const close: ChatViewNavigation['close'] = (slot) => {
       if (!availableSlots.includes(slot)) return;
+      // Layers dismiss top-down: pop the topmost layer first and only release the base binding
+      // once no layers remain.
+      if (slotLayers?.[slot]?.length) {
+        layoutController.popLayer(slot);
+        return;
+      }
       // Persistent kinds (nav-rail lists) are hide-only; close never releases them.
       if (isPersistentSlotKind(registry, slotKind(slot))) return;
       layoutController.release(slot);
@@ -372,18 +393,28 @@ export const ChatViewNavigationProvider = ({ children }: PropsWithChildren) => {
       if (availableSlots.includes(slot)) layoutController.hide(slot);
     };
 
+    const pushLayer: ChatViewNavigation['pushLayer'] = (slot, binding) => {
+      if (!availableSlots.includes(slot)) return;
+      layoutController.pushLayer(slot, createChatViewSlotBinding(binding));
+    };
+
+    const popLayer: ChatViewNavigation['popLayer'] = (slot) => {
+      if (availableSlots.includes(slot)) layoutController.popLayer(slot);
+    };
+
     const unhide: ChatViewNavigation['unhide'] = (slot) => {
       if (availableSlots.includes(slot)) layoutController.unhide(slot);
     };
 
-    return { close, hide, open, openView, unhide };
+    return { close, hide, open, openView, popLayer, pushLayer, unhide };
   }, [
     activeView,
     availableSlots,
     layoutController,
     registry,
     resolveActionTargetSlot,
     slotBindings,
+    slotLayers,
   ]);
 
   return (

src/components/ChatView/__tests__/ChatViewNavigation.test.tsx

@@ -545,6 +545,136 @@ describe('useChatViewNavigation', () => {
     expect(slot2Binding?.source).toBe(secondaryChannel);
   });
 
+  it('pushLayer stacks over the base binding and popLayer removes it', () => {
+    const channel = makeChannel('messaging:layer-base');
+    let capturedController: LayoutController | undefined;
+
+    const Harness = () => {
+      const navigation = useChatViewNavigation();
+      const { layoutController } = useChatViewContext();
+      capturedController = layoutController;
+
+      return (
+        <>
+          <button
+            onClick={() =>
+              navigation.open({
+                key: channel.cid ?? undefined,
+                kind: 'channel',
+                source: channel,
+              })
+            }
+            type='button'
+          >
+            open-channel
+          </button>
+          <button
+            onClick={() =>
+              navigation.pushLayer('slot1', {
+                key: 'u1',
+                kind: 'userProfile',
+                source: { userId: 'u1' },
+              })
+            }
+            type='button'
+          >
+            push-layer
+          </button>
+          <button onClick={() => navigation.popLayer('slot1')} type='button'>
+            pop-layer
+          </button>
+        </>
+      );
+    };
+
+    renderWithProviders(
+      <ChatView maxSlots={1}>
+        <Harness />
+      </ChatView>,
+    );
+
+    fireEvent.click(screen.getByText('open-channel'));
+    fireEvent.click(screen.getByText('push-layer'));
+
+    const layered = viewState(capturedController);
+    // Base binding is untouched; the profile lives in the layer stack on top of it.
+    expect(getChatViewEntityBinding(layered?.slotBindings.slot1)?.kind).toBe('channel');
+    expect(layered?.slotLayers?.slot1).toHaveLength(1);
+    expect(getChatViewEntityBinding(layered?.slotLayers?.slot1?.[0])?.kind).toBe(
+      'userProfile',
+    );
+
+    fireEvent.click(screen.getByText('pop-layer'));
+
+    const popped = viewState(capturedController);
+    expect(popped?.slotLayers?.slot1).toBeUndefined();
+    expect(getChatViewEntityBinding(popped?.slotBindings.slot1)?.kind).toBe('channel');
+  });
+
+  it('close pops the top layer first and releases the base only when no layers remain', () => {
+    const channel = makeChannel('messaging:layer-close');
+    let capturedController: LayoutController | undefined;
+
+    const Harness = () => {
+      const navigation = useChatViewNavigation();
+      const { layoutController } = useChatViewContext();
+      capturedController = layoutController;
+
+      return (
+        <>
+          <button
+            onClick={() =>
+              navigation.open({
+                key: channel.cid ?? undefined,
+                kind: 'channel',
+                source: channel,
+              })
+            }
+            type='button'
+          >
+            open-channel
+          </button>
+          <button
+            onClick={() =>
+              navigation.pushLayer('slot1', {
+                key: 'u1',
+                kind: 'userProfile',
+                source: { userId: 'u1' },
+              })
+            }
+            type='button'
+          >
+            push-layer
+          </button>
+          <button onClick={() => navigation.close('slot1')} type='button'>
+            close
+          </button>
+        </>
+      );
+    };
+
+    renderWithProviders(
+      <ChatView maxSlots={1}>
+        <Harness />
+      </ChatView>,
+    );
+
+    fireEvent.click(screen.getByText('open-channel'));
+    fireEvent.click(screen.getByText('push-layer'));
+
+    // First close: pops the layer, base channel stays bound.
+    fireEvent.click(screen.getByText('close'));
+    const afterFirstClose = viewState(capturedController);
+    expect(afterFirstClose?.slotLayers?.slot1).toBeUndefined();
+    expect(getChatViewEntityBinding(afterFirstClose?.slotBindings.slot1)?.kind).toBe(
+      'channel',
+    );
+
+    // Second close: no layers left, so the base binding is released.
+    fireEvent.click(screen.getByText('close'));
+    expect(viewState(capturedController)?.slotBindings.slot1).toBeUndefined();
+  });
+
   it('opens channel and thread into configured slotNames in order', () => {
     const channel = makeChannel('messaging:expand-named');
     const thread = makeThread('thread-expand-named');

src/components/ChatView/__tests__/useSlotEntity.test.tsx

@@ -11,6 +11,7 @@ import {
   useSlotChannel,
   useSlotEntity,
   useSlotThread,
+  useSlotTopLayerEntity,
 } from '../hooks';
 
 import { ChatProvider } from '../../../context/ChatContext';
@@ -133,6 +134,85 @@ describe('useSlotEntity hooks', () => {
     );
     expect(screen.getByTestId('resolved-thread')).toHaveTextContent('thread-1');
   });
+
+  it('resolves the top layer via useSlotTopLayerEntity without shadowing the base binding', () => {
+    const thread = makeThread('thread-under-layer');
+
+    const layoutController = new LayoutController({
+      initialState: {
+        availableSlots: ['slot1'],
+      },
+    });
+
+    // Base binding: a thread. Layer on top: a member profile.
+    layoutController.bind('slot1', {
+      key: `thread:${thread.id}`,
+      payload: { key: thread.id, kind: 'thread', source: thread },
+    });
+    layoutController.pushLayer('slot1', {
+      key: 'userProfile:u1',
+      payload: { key: 'userProfile:u1', kind: 'userProfile', source: { userId: 'u1' } },
+    });
+
+    const Harness = () => {
+      const topProfile = useSlotTopLayerEntity({ kind: 'userProfile', slot: 'slot1' });
+      // The base binding (thread) is unchanged — a layer never rewrites `slotBindings`.
+      const baseThread = useSlotThread({ slot: 'slot1' });
+      // Reading the profile as a base binding must NOT find it (it lives in the layer stack).
+      const profileAsBase = useSlotEntity({ kind: 'userProfile', slot: 'slot1' });
+
+      return (
+        <>
+          <div data-testid='top-profile'>{topProfile?.userId}</div>
+          <div data-testid='base-thread'>{baseThread?.id}</div>
+          <div data-testid='profile-as-base'>{profileAsBase?.userId ?? 'none'}</div>
+        </>
+      );
+    };
+
+    renderWithProviders(
+      <ChatView layoutController={layoutController}>
+        <Harness />
+      </ChatView>,
+    );
+
+    expect(screen.getByTestId('top-profile')).toHaveTextContent('u1');
+    expect(screen.getByTestId('base-thread')).toHaveTextContent('thread-under-layer');
+    expect(screen.getByTestId('profile-as-base')).toHaveTextContent('none');
+  });
+
+  it('returns undefined from useSlotTopLayerEntity when the top layer kind does not match', () => {
+    const layoutController = new LayoutController({
+      initialState: {
+        availableSlots: ['slot1'],
+      },
+    });
+
+    layoutController.pushLayer('slot1', {
+      key: 'userProfile:u2',
+      payload: { key: 'userProfile:u2', kind: 'userProfile', source: { userId: 'u2' } },
+    });
+
+    const Harness = () => {
+      const asThread = useSlotTopLayerEntity({ kind: 'thread', slot: 'slot1' });
+      const asProfile = useSlotTopLayerEntity({ kind: 'userProfile', slot: 'slot1' });
+      return (
+        <>
+          <div data-testid='as-thread'>{asThread ? 'match' : 'none'}</div>
+          <div data-testid='as-profile'>{asProfile?.userId ?? 'none'}</div>
+        </>
+      );
+    };
+
+    renderWithProviders(
+      <ChatView layoutController={layoutController}>
+        <Harness />
+      </ChatView>,
+    );
+
+    expect(screen.getByTestId('as-thread')).toHaveTextContent('none');
+    expect(screen.getByTestId('as-profile')).toHaveTextContent('u2');
+  });
 });
 
 describe('slot adapters', () => {

src/components/ChatView/hooks/useLayoutViewState.ts

@@ -19,6 +19,7 @@ export const getLayoutViewState = (
     slotBindings: { ...(layout?.slotBindings ?? {}) },
     slotForwardHistory: { ...(layout?.slotForwardHistory ?? {}) },
     slotHistory: { ...(layout?.slotHistory ?? {}) },
+    slotLayers: { ...(layout?.slotLayers ?? {}) },
     slotMeta: { ...(layout?.slotMeta ?? {}) },
     slotNames: layout?.slotNames ? [...layout.slotNames] : undefined,
   };

src/components/ChatView/hooks/useSlotEntity.ts

@@ -101,6 +101,40 @@ export const useSlotEntity = <TKind extends SlotEntityKind>({
   return undefined;
 };
 
+/**
+ * Like {@link useSlotEntity}, but resolves the source of the **topmost layer** on a slot (the last
+ * entry of `slotLayers[slot]`) rather than its base binding — when that layer's `kind` matches.
+ *
+ * Layers stack above the base binding and cover it while it stays mounted (see
+ * `ChatViewNavigation.pushLayer`). Read the base with `useSlotEntity`/`useSlotChannel`/… and the
+ * overlay on top with this hook, then render the overlay covering the base.
+ *
+ * @example
+ * ```tsx
+ * const profile = useSlotTopLayerEntity({ kind: 'userProfile', slot: 'main-thread' });
+ * // profile is { userId } | undefined — present while a userProfile layer covers the slot
+ * ```
+ */
+export const useSlotTopLayerEntity = <TKind extends SlotEntityKind>({
+  kind,
+  slot,
+  view,
+}: UseSlotEntityOptions<TKind>): SlotEntitySourceByKind<TKind> | undefined => {
+  const { availableSlots, slotLayers } = useLayoutViewState(view);
+
+  for (const candidateSlot of resolveCandidateSlots(slot, availableSlots)) {
+    const layers = slotLayers?.[candidateSlot];
+    const topBinding = layers?.[layers.length - 1];
+    const entity = getChatViewEntityBinding(topBinding);
+    if (isEntityOfKind(entity, kind)) {
+      // Safe due to discriminant check on `kind` above.
+      return entity.source as SlotEntitySourceByKind<TKind>;
+    }
+  }
+
+  return undefined;
+};
+
 /**
  * Resolves **every** matching ChatView entity binding as `{ slot, source }` pairs
  * (in active-view `availableSlots` order, or only `slot` when provided).