@exegia/corpora-ui 0.19.0 → 0.21.0

package/src/components/blocks/nav/sidebar/utils.ts

@@ -12,7 +12,7 @@ export function canContain(item: SidebarResource) {
 
 export function flattenResources(
   items: SidebarResource[],
-  expanded: Set<string>,
+  expanded: ReadonlySet<string>,
   depth = 0,
   parentId: string | null = null
 ): FlatResource[] {
@@ -38,6 +38,34 @@ export function findResource(
 }
 
 
+/** Ids of every ancestor of `id` (nearest last); empty when absent. */
+export function ancestorIdsOf(
+  items: SidebarResource[],
+  id: string
+): string[] {
+  const walk = (nodes: SidebarResource[], trail: string[]): string[] | null => {
+    for (const node of nodes) {
+      if (node.id === id) return trail
+      if (node.children) {
+        const found = walk(node.children, [...trail, node.id])
+        if (found) return found
+      }
+    }
+    return null
+  }
+  return walk(items, []) ?? []
+}
+
+/** Ids of every row that can hold children and has some — the set
+ * `expandAll` opens. */
+export function expandableIdsOf(items: SidebarResource[]): string[] {
+  return items.flatMap((item) =>
+    item.children?.length && canContain(item)
+      ? [item.id, ...expandableIdsOf(item.children)]
+      : []
+  )
+}
+
 export function containsResource(item: SidebarResource, id: string): boolean {
   return (
     item.id === id ||

package/src/components/blocks/profile/__tests__/profile-card-block.test.tsx

@@ -2,7 +2,12 @@ import { describe, expect, mock, test } from "bun:test";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
+import { act } from "@testing-library/react";
+
+import { AnimatedSidebarPanelContext } from "@/components/blocks/shell/utils";
 import { ProfileCardBlock } from "../profile-card-block";
+import { useProfileCardActions, useProfileCardState } from "../use-profile-card-state";
+import type { ProfileCardActions, ProfileCardState } from "../type";
 
 const USER = { name: "Jenny Hamilton", username: "@jennycodes" };
 
@@ -131,4 +136,193 @@ describe("ProfileCardBlock", () => {
     await new Promise((resolve) => setTimeout(resolve, 0));
     expect(onError).toHaveBeenCalled();
   });
+  test("variant=collapsed folds to the avatar but keeps the accessible name", () => {
+    const { rerender } = render(<ProfileCardBlock user={USER} variant="collapsed" />);
+
+    const trigger = screen.getByRole("button", {
+      name: "Jenny Hamilton @jennycodes, account menu",
+    });
+    expect(trigger.hasAttribute("data-collapsed")).toBe(true);
+    // Hover names the tile the way the rail's menu buttons do.
+    expect(trigger.getAttribute("title")).toBe("Jenny Hamilton @jennycodes");
+    // The avatar stays; the identity lines fold (hidden, not removed — that
+    // is what lets the fold animate back open).
+    expect(screen.getByText("JH")).toBeDefined();
+    const identity = trigger.querySelector('[data-slot="profile-card-identity"]');
+    expect(identity?.getAttribute("aria-hidden")).toBe("true");
+    expect(identity?.textContent).toContain("Jenny Hamilton");
+    // 40px tile, like the tree rail: no inset, avatar centred.
+    expect(trigger.className).toContain("justify-center");
+    expect(trigger.className).toContain("size-10");
+    expect(trigger.className).toContain("p-0");
+
+    rerender(<ProfileCardBlock user={USER} variant="expanded" />);
+    expect(trigger.hasAttribute("data-collapsed")).toBe(false);
+    expect(trigger.getAttribute("title")).toBeNull();
+    expect(identity?.getAttribute("aria-hidden")).toBeNull();
+  });
+
+  test("variant=collapsed still opens the menu", async () => {
+    const user = userEvent.setup();
+    render(<ProfileCardBlock user={USER} variant="collapsed" />);
+    await user.click(screen.getByRole("button"));
+    expect(await screen.findByRole("menuitem", { name: "Log out" })).toBeDefined();
+  });
+
+  test("follows the enclosing AnimatedPanel unless variant is set", () => {
+    const panel = { collapsed: true, collapsible: "icon", side: "left" } as const;
+    const { rerender } = render(
+      <AnimatedSidebarPanelContext.Provider value={panel}>
+        <ProfileCardBlock user={USER} />
+      </AnimatedSidebarPanelContext.Provider>,
+    );
+    const trigger = screen.getByRole("button");
+    expect(trigger.hasAttribute("data-collapsed")).toBe(true);
+
+    // An explicit prop wins over the panel.
+    rerender(
+      <AnimatedSidebarPanelContext.Provider value={panel}>
+        <ProfileCardBlock user={USER} variant="expanded" />
+      </AnimatedSidebarPanelContext.Provider>,
+    );
+    expect(trigger.hasAttribute("data-collapsed")).toBe(false);
+
+  });
+
+  test("outside any panel an unnamed card starts expanded", () => {
+    render(<ProfileCardBlock user={USER} />);
+    expect(screen.getByRole("button").hasAttribute("data-collapsed")).toBe(false);
+    expect(screen.getByRole("button").getAttribute("data-variant")).toBe("expanded");
+  });
+
+  test("defaultVariant seeds an uncontrolled card", () => {
+    render(<ProfileCardBlock defaultVariant="collapsed" user={USER} />);
+    expect(screen.getByRole("button").getAttribute("data-variant")).toBe("collapsed");
+  });
+  test("data-variant mirrors the fold and onVariantChange reports store-driven changes", () => {
+    const onVariantChange = mock(() => {});
+    let actions!: ProfileCardActions;
+    let state!: ProfileCardState;
+    function Probe() {
+      actions = useProfileCardActions("account");
+      state = useProfileCardState("account");
+      return null;
+    }
+    render(
+      <>
+        <ProfileCardBlock
+          onVariantChange={onVariantChange}
+          profileCardId="account"
+          user={USER}
+        />
+        <Probe />
+      </>,
+    );
+    const trigger = screen.getByRole("button");
+    expect(trigger.getAttribute("data-variant")).toBe("expanded");
+    expect(state.variant).toBe("expanded");
+
+    // Driven from outside by id — no controller, no ref.
+    act(() => actions.collapse());
+    expect(trigger.getAttribute("data-variant")).toBe("collapsed");
+    expect(state.variant).toBe("collapsed");
+    expect(onVariantChange).toHaveBeenCalledWith("collapsed");
+
+    act(() => actions.toggleVariant());
+    expect(trigger.getAttribute("data-variant")).toBe("expanded");
+    expect(onVariantChange).toHaveBeenLastCalledWith("expanded");
+  });
+
+  test("a controlled variant is never overwritten by the store", () => {
+    let actions!: ProfileCardActions;
+    function Probe() {
+      actions = useProfileCardActions("locked");
+      return null;
+    }
+    const onVariantChange = mock(() => {});
+    render(
+      <>
+        <ProfileCardBlock
+          onVariantChange={onVariantChange}
+          profileCardId="locked"
+          user={USER}
+          variant="expanded"
+        />
+        <Probe />
+      </>,
+    );
+    act(() => actions.collapse());
+    // Reported, not applied — the prop is truth.
+    expect(onVariantChange).toHaveBeenCalledWith("collapsed");
+    expect(screen.getByRole("button").getAttribute("data-variant")).toBe("expanded");
+  });
+
+  test("openMenu / closeMenu from outside drive the menu through the store", async () => {
+    let actions!: ProfileCardActions;
+    function Probe() {
+      actions = useProfileCardActions("menu");
+      return null;
+    }
+    render(
+      <>
+        <ProfileCardBlock profileCardId="menu" user={USER} />
+        <Probe />
+      </>,
+    );
+    act(() => actions.openMenu());
+    expect(await screen.findByRole("menuitem", { name: "Profile" })).toBeDefined();
+    act(() => actions.closeMenu());
+    await new Promise((r) => setTimeout(r, 300));
+    expect(screen.queryByRole("menuitem", { name: "Profile" })).toBeNull();
+  });
+
+  test("busy tracks a pending action in the store", async () => {
+    const user = userEvent.setup();
+    let resolve!: () => void;
+    let state!: ProfileCardState;
+    function Probe() {
+      state = useProfileCardState("busy");
+      return null;
+    }
+    render(
+      <>
+        <ProfileCardBlock
+          items={[
+            {
+              id: "slow",
+              label: "Slow",
+              onSelect: () => new Promise<void>((r) => (resolve = r)),
+            },
+          ]}
+          profileCardId="busy"
+          user={USER}
+        />
+        <Probe />
+      </>,
+    );
+    await user.click(screen.getByRole("button"));
+    await user.click(await screen.findByRole("menuitem", { name: "Slow" }));
+    expect(state.busy).toBe(true);
+    expect(state.pendingActionId).toBe("slow");
+    await act(async () => {
+      resolve();
+      await Promise.resolve();
+    });
+    expect(state.busy).toBe(false);
+  });
+
+  test("user.presence and the presence prop reach the avatar badge", () => {
+    const { rerender } = render(
+      <ProfileCardBlock user={{ ...USER, presence: "online" }} />,
+    );
+    const badge = () =>
+      document.querySelector('[data-slot="user-avatar-presence"]');
+    expect(badge()?.getAttribute("data-presence")).toBe("online");
+    rerender(
+      <ProfileCardBlock presence="offline" user={{ ...USER, presence: "online" }} />,
+    );
+    expect(badge()?.getAttribute("data-presence")).toBe("offline");
+    rerender(<ProfileCardBlock user={USER} />);
+    expect(badge()).toBeNull();
+  });
 });

package/src/components/blocks/profile/index.ts

@@ -0,0 +1,28 @@
+export {
+  ProfileCardBlock,
+  defaultProfileCardItems,
+} from "./profile-card-block"
+export type { ProfileCardBlockProps } from "./profile-card-block"
+export { useProfileCard } from "./use-profile-card"
+export type { ProfileCardBinding, UseProfileCardOptions } from "./use-profile-card"
+export {
+  useProfileCardActions,
+  useProfileCardState,
+} from "./use-profile-card-state"
+// The public atom surface. `@internal` atoms (config, handlers, projections,
+// the mount seed) stay unexported on purpose.
+export {
+  profileCardBusyAtom,
+  profileCardCollapsedAtom,
+  profileCardMenuOpenAtom,
+  profileCardPendingActionIdAtom,
+  profileCardStateAtom,
+  profileCardVariantAtom,
+  removeProfileCardInstance,
+  resetProfileCardAtom,
+  selectProfileCardActionAtom,
+  setProfileCardMenuOpenAtom,
+  setProfileCardVariantAtom,
+  toggleProfileCardVariantAtom,
+} from "./profile-card-atom"
+export type * from "./type"

package/src/components/blocks/profile/profile-card-atom.ts

@@ -0,0 +1,247 @@
+/**
+ * Profile card state — Jotai atom families keyed by a card id.
+ *
+ * Same layout as the tree (`components/composed/tree/tree-atom.ts`) and the
+ * avatar (`components/user-avatar/user-avatar-atom.ts`): in-house `keyed()`
+ * families per field, write-only action atoms, a composed read-only state
+ * atom, and `removeProfileCardInstance` to drop an id from every family.
+ */
+
+import { atom } from "jotai"
+import type { Getter, Setter } from "jotai"
+
+import type {
+  ProfileCardAction,
+  ProfileCardConfig,
+  ProfileCardHandlers,
+  ProfileCardInstanceId,
+  ProfileCardState,
+  ProfileCardVariant,
+} from "./type"
+
+const DEFAULT_CONFIG: ProfileCardConfig = {
+  controlsVariant: false,
+  controlsMenuOpen: false,
+}
+const NO_HANDLERS: ProfileCardHandlers = {}
+
+// ── families ───────────────────────────────────────────────────────────────
+
+type Family<AtomType> = ((id: ProfileCardInstanceId) => AtomType) & {
+  remove: (id: ProfileCardInstanceId) => void
+}
+
+const families: { remove: (id: ProfileCardInstanceId) => void }[] = []
+
+function keyed<AtomType>(create: (id: ProfileCardInstanceId) => AtomType) {
+  const cache = new Map<ProfileCardInstanceId, AtomType>()
+  const family = ((id: ProfileCardInstanceId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: ProfileCardInstanceId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `profileCard/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: ProfileCardInstanceId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `profileCard/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (
+    get: Getter,
+    set: Setter,
+    id: ProfileCardInstanceId,
+    ...args: Args
+  ) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `profileCard/${id}/${name}`
+    return instance
+  })
+}
+
+// ── primitives ─────────────────────────────────────────────────────────────
+
+export const profileCardVariantAtom = stateFamily<ProfileCardVariant>(
+  "variant",
+  "expanded"
+)
+
+export const profileCardMenuOpenAtom = stateFamily<boolean>("menuOpen", false)
+
+export const profileCardPendingActionIdAtom = stateFamily<string | null>(
+  "pendingActionId",
+  null
+)
+
+/** @internal */
+export const profileCardConfigAtom = stateFamily<ProfileCardConfig>(
+  "config",
+  DEFAULT_CONFIG
+)
+
+/** @internal */
+export const profileCardHandlersAtom = stateFamily<ProfileCardHandlers>(
+  "handlers",
+  NO_HANDLERS
+)
+
+// ── derived ────────────────────────────────────────────────────────────────
+
+export const profileCardCollapsedAtom = readFamily(
+  "collapsed",
+  (get, id) => get(profileCardVariantAtom(id)) === "collapsed"
+)
+
+export const profileCardBusyAtom = readFamily(
+  "busy",
+  (get, id) => get(profileCardPendingActionIdAtom(id)) !== null
+)
+
+/** Whole-state read for callers that want the object; the field atoms are
+ * cheaper for components that watch one thing. */
+export const profileCardStateAtom = readFamily<ProfileCardState>(
+  "state",
+  (get, id) => ({
+    variant: get(profileCardVariantAtom(id)),
+    menuOpen: get(profileCardMenuOpenAtom(id)),
+    pendingActionId: get(profileCardPendingActionIdAtom(id)),
+    busy: get(profileCardBusyAtom(id)),
+  })
+)
+
+// ── actions: variant ───────────────────────────────────────────────────────
+
+/** Reports through `onVariantChange` always; writes the store only when no
+ * `variant` prop controls the card — the prop is truth then. */
+export const setProfileCardVariantAtom = actionFamily<
+  [variant: ProfileCardVariant]
+>("setVariant", (get, set, id, variant) => {
+  if (get(profileCardVariantAtom(id)) === variant) return
+  if (!get(profileCardConfigAtom(id)).controlsVariant)
+    set(profileCardVariantAtom(id), variant)
+  get(profileCardHandlersAtom(id)).onVariantChange?.(variant)
+})
+
+export const toggleProfileCardVariantAtom = actionFamily<[]>(
+  "toggleVariant",
+  (get, set, id) => {
+    set(
+      setProfileCardVariantAtom(id),
+      get(profileCardVariantAtom(id)) === "collapsed" ? "expanded" : "collapsed"
+    )
+  }
+)
+
+// ── actions: menu ──────────────────────────────────────────────────────────
+
+/** Inert while an `open` prop controls the menu. */
+export const setProfileCardMenuOpenAtom = actionFamily<[open: boolean]>(
+  "setMenuOpen",
+  (get, set, id, open) => {
+    if (get(profileCardConfigAtom(id)).controlsMenuOpen) return
+    set(profileCardMenuOpenAtom(id), open)
+  }
+)
+
+// ── actions: selection ─────────────────────────────────────────────────────
+
+/**
+ * Run an action's `onSelect`. A returned promise marks the card busy until it
+ * settles; a rejection goes to `onError` and the card leaves its busy state
+ * either way. Because the pending id is a store value, it survives the card
+ * unmounting mid-flight (sign-out typically unmounts it) — the settle just
+ * writes to an instance nobody renders any more.
+ */
+export const selectProfileCardActionAtom = actionFamily<
+  [action: ProfileCardAction]
+>("selectAction", (get, set, id, action) => {
+  const result = action.onSelect?.()
+  if (!(result instanceof Promise)) return
+  set(profileCardPendingActionIdAtom(id), action.id)
+  result
+    .catch((cause: unknown) => get(profileCardHandlersAtom(id)).onError?.(cause))
+    .finally(() => {
+      // Only clear our own flight — a later action may have taken over.
+      if (get(profileCardPendingActionIdAtom(id)) === action.id)
+        set(profileCardPendingActionIdAtom(id), null)
+    })
+})
+
+// ── internal projections ───────────────────────────────────────────────────
+
+/** @internal Projection of the mounted component's controlled props. */
+export const projectProfileCardPropsAtom = actionFamily<
+  [
+    config: ProfileCardConfig,
+    variant: ProfileCardVariant | undefined,
+    menuOpen: boolean | undefined,
+  ]
+>("projectProps", (_get, set, id, config, variant, menuOpen) => {
+  set(profileCardConfigAtom(id), config)
+  if (config.controlsVariant && variant !== undefined)
+    set(profileCardVariantAtom(id), variant)
+  if (config.controlsMenuOpen && menuOpen !== undefined)
+    set(profileCardMenuOpenAtom(id), menuOpen)
+})
+
+/** @internal */
+export const setProfileCardHandlersAtom = actionFamily<
+  [handlers: ProfileCardHandlers]
+>("setHandlers", (_get, set, id, handlers) => {
+  set(profileCardHandlersAtom(id), handlers)
+})
+
+/** @internal Seed the uncontrolled variant on mount without firing
+ * `onVariantChange`. */
+export const seedProfileCardVariantAtom = actionFamily<
+  [variant: ProfileCardVariant]
+>("seedVariant", (_get, set, id, variant) => {
+  set(profileCardVariantAtom(id), variant)
+})
+
+// ── reset ──────────────────────────────────────────────────────────────────
+
+export const resetProfileCardAtom = actionFamily<[]>(
+  "reset",
+  (_get, set, id) => {
+    set(profileCardVariantAtom(id), "expanded")
+    set(profileCardMenuOpenAtom(id), false)
+    set(profileCardPendingActionIdAtom(id), null)
+    set(profileCardConfigAtom(id), DEFAULT_CONFIG)
+    set(profileCardHandlersAtom(id), NO_HANDLERS)
+  }
+)
+
+/** Forget a card entirely — every family drops the key so the store can
+ * release its state. Call on teardown of a named instance. */
+export function removeProfileCardInstance(id: ProfileCardInstanceId): void {
+  for (const family of families) family.remove(id)
+}