@exegia/corpora-ui 0.20.0 → 0.21.0

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

@@ -8,9 +8,16 @@ import {
   UserPlusIcon,
   UsersIcon,
 } from "lucide-react"
+import { motion, useReducedMotion } from "motion/react"
 import * as React from "react"
 
-import { UserAvatar } from "@/components/composed/user-avatar"
+import {
+  AnimatedSidebarPanelContext,
+  LABEL_ENTER_TRANSITION,
+  LABEL_EXIT_TRANSITION,
+  REDUCED_TRANSITION,
+} from "@/components/blocks/shell/utils"
+import { UserAvatar } from "@/components/user-avatar"
 import { Button } from "@/components/ui/button"
 import {
   DropdownMenu,
@@ -26,48 +33,25 @@ import {
 import { playCue } from "@/lib/sound"
 import { cn } from "@/lib/utils"
 
-/** The identity shown on the card. */
-export interface ProfileCardUser {
-  name: string
-  /** Secondary line under the name — a handle, an email, a role. */
-  username?: string
-  /** Avatar image URL. Falls back to the initials when absent or broken. */
-  avatar?: string
-  /** Fallback initials. Derived from `name` when omitted. */
-  initials?: string
-}
-
-/** An actionable row of the menu. */
-export interface ProfileCardAction {
-  type?: "item"
-  id: string
-  label: string
-  icon?: React.ReactNode
-  /** Right-aligned hint, e.g. "⌘K". Purely decorative — bind the key yourself. */
-  shortcut?: string
-  disabled?: boolean
-  variant?: "default" | "destructive"
-  /** Returning a promise puts the card in its loading state until it settles. */
-  onSelect?: () => void | Promise<void>
-}
-
-/** A heading over the rows that follow it, up to the next separator. */
-export interface ProfileCardLabel {
-  type: "label"
-  label: string
-}
-
-/** A rule between two sections. */
-export interface ProfileCardSeparator {
-  type: "separator"
-}
+import { useProfileCard } from "./use-profile-card"
+import type {
+  ProfileCardAction,
+  ProfileCardItem,
+  ProfileCardUser,
+  ProfileCardVariant,
+} from "./type"
 
-/**
- * One entry of `items`. Authored flat; the block renders each run between
- * separators as its own menu group so a label actually names its section.
- */
-export type ProfileCardItem =
-  ProfileCardAction | ProfileCardLabel | ProfileCardSeparator
+export type {
+  ProfileCardAction,
+  ProfileCardActions,
+  ProfileCardInstanceId,
+  ProfileCardItem,
+  ProfileCardLabel,
+  ProfileCardSeparator,
+  ProfileCardState,
+  ProfileCardUser,
+  ProfileCardVariant,
+} from "./type"
 
 /**
  * The menu the card ships with. Spread it to keep the shape and attach your
@@ -114,6 +98,31 @@ export interface ProfileCardBlockProps {
    * width, so `align` stops mattering horizontally.
    */
   menuWidth?: "content" | "card"
+  /**
+   * `expanded` shows avatar, name and handle; `collapsed` folds the card to
+   * its avatar — for an icon-collapsed sidebar rail. The fold animates: the
+   * identity lines and chevron slide to zero width, the avatar stays put.
+   * Controlled when passed. Left unset, the card follows the `AnimatedPanel`
+   * it sits in (a `SidebarBlock` footer folds with the rail on its own), and
+   * outside a panel starts from `defaultVariant`.
+   */
+  variant?: ProfileCardVariant
+  defaultVariant?: ProfileCardVariant
+  onVariantChange?: (variant: ProfileCardVariant) => void
+  /**
+   * Name this card's slice of the store so `useProfileCardState(id)` /
+   * `useProfileCardActions(id)` can read or drive it (fold it, open its
+   * menu) from anywhere under `ExegiaProvider`. Unnamed cards key off
+   * `useId` and are dropped on unmount.
+   */
+  profileCardId?: string
+  /**
+   * Presence badge on the avatar — overrides `user.presence`. Name the avatar
+   * with `avatarId` and `useUserAvatarActions(id).setPresence()` can flip it
+   * from a socket handler instead.
+   */
+  presence?: ProfileCardUser["presence"]
+  avatarId?: string
   /**
    * Emit cuelume press/release on the card and play the open/close cues.
    * Inert unless the app opts into interaction sound via `bindSounds()`.
@@ -164,6 +173,12 @@ export function ProfileCardBlock({
   side = "bottom",
   sideOffset = 8,
   menuWidth = "content",
+  variant: variantProp,
+  defaultVariant,
+  onVariantChange,
+  profileCardId,
+  presence,
+  avatarId,
   open,
   defaultOpen,
   onOpenChange,
@@ -171,81 +186,145 @@ export function ProfileCardBlock({
   onError,
   className,
 }: ProfileCardBlockProps): React.ReactElement {
-  const [pending, setPending] = React.useState<string | null>(null)
-  // Actions can outlive the card (sign-out unmounts it, typically).
-  const mounted = React.useRef(true)
-  React.useEffect(() => {
-    mounted.current = true
-    return () => {
-      mounted.current = false
-    }
-  }, [])
-
   const groups = React.useMemo(() => toGroups(items), [items])
 
-  function select(action: ProfileCardAction) {
-    const result = action.onSelect?.()
-    if (!(result instanceof Promise)) return
-    setPending(action.id)
-    result
-      .catch((cause: unknown) => onError?.(cause))
-      .finally(() => {
-        if (mounted.current) setPending(null)
-      })
-  }
-
-  const busy = pending !== null
+  // Optional, not required: the card is a standalone block that also lands
+  // in sidebar footers, so it reads the panel context when there is one and
+  // does not throw when there is not. Inside a panel the rail is the truth
+  // for the fold, so it is projected as a controlled variant.
+  const panel = React.useContext(AnimatedSidebarPanelContext)
+  const card = useProfileCard({
+    profileCardId,
+    variant:
+      variantProp ??
+      (panel ? (panel.collapsed ? "collapsed" : "expanded") : undefined),
+    defaultVariant,
+    onVariantChange,
+    open,
+    defaultOpen,
+    onError,
+  })
+  const { collapsed, busy, menuOpen, setMenuOpen, select } = card
+  const reduce = useReducedMotion()
+  const identity = `${user.name}${user.username ? ` ${user.username}` : ""}`
 
   const handleOpenChange: MenuPrimitive.Root.Props["onOpenChange"] = (
     nextOpen,
     details
   ) => {
     if (sound) playCue(nextOpen ? "bloom" : "droplet")
+    setMenuOpen(nextOpen)
     onOpenChange?.(nextOpen, details)
   }
 
   return (
-    <DropdownMenu
-      defaultOpen={defaultOpen}
-      onOpenChange={handleOpenChange}
-      open={open}
-    >
+    // The store mirrors the menu: `open` (when passed) is projected into it,
+    // and this always renders from it, so `useProfileCardActions(id).openMenu()`
+    // works the same whether or not the consumer controls the prop.
+    <DropdownMenu onOpenChange={handleOpenChange} open={menuOpen}>
       <DropdownMenuTrigger
         disabled={busy}
         render={
           <Button
             // Spelled out rather than left to the name-from-contents rule: the
             // avatar sits inside the button and the handle is a second line.
-            aria-label={`${user.name}${user.username ? ` ${user.username}` : ""}, account menu`}
+            aria-label={`${identity}, account menu`}
             className={cn(
               // Quiet at rest — the background only surfaces on hover or
               // while the menu is open.
               "h-auto w-full justify-between py-1.5 pl-1.5 data-popup-open:bg-accent sm:h-auto",
+              // Folded: a 40px avatar tile, the size the tree rail uses. It
+              // is 8px wider than a footer's 32px inner box on purpose — the
+              // -mx-1 lets it borrow the footer padding so the 32px avatar
+              // clears the 1px border and sits dead centre. The label spans
+              // below fold to zero width rather than unmounting so the change
+              // animates. Button's own gap-2 stays: its always-mounted loading
+              // slot carries a -ms-2 that cancels it, so zeroing the gap would
+              // pull the avatar 8px left; the folded chevron cancels its own
+              // gap instead (see below). `sm:size-10` because the base carries
+              // an `sm:h-auto` that an unprefixed size would not beat.
+              collapsed &&
+                "-mx-1 size-10 shrink-0 justify-center rounded-xl p-0 sm:size-10",
               className
             )}
+            data-collapsed={collapsed ? "" : undefined}
             data-slot="profile-card"
+            data-variant={collapsed ? "collapsed" : "expanded"}
             loading={busy}
             sound={sound}
+            // The visible name is gone while folded — name the tile on hover
+            // the way the rail's menu buttons do.
+            title={collapsed ? identity : undefined}
             variant="ghost"
           >
-            <span className="flex w-full min-w-0 items-center justify-start gap-2">
+            <span
+              className={cn(
+                "flex min-w-0 items-center justify-start",
+                collapsed ? "w-auto gap-0" : "w-full gap-2"
+              )}
+            >
               <UserAvatar
                 // Decorative: the name beside it already labels the card.
                 alt=""
+                avatarId={avatarId}
                 initials={user.initials}
                 name={user.name}
+                presence={presence ?? user.presence}
                 src={user.avatar}
               />
-              <span className="flex min-w-0 flex-col text-left">
+              <motion.span
+                animate={{
+                  width: collapsed ? 0 : "auto",
+                  opacity: collapsed ? 0 : 1,
+                  x: collapsed ? -4 : 0,
+                }}
+                aria-hidden={collapsed || undefined}
+                className={cn(
+                  "flex min-w-0 flex-col overflow-hidden text-left whitespace-nowrap",
+                  collapsed && "pointer-events-none"
+                )}
+                data-slot="profile-card-identity"
+                initial={false}
+                transition={
+                  reduce
+                    ? REDUCED_TRANSITION
+                    : collapsed
+                      ? LABEL_EXIT_TRANSITION
+                      : LABEL_ENTER_TRANSITION
+                }
+              >
                 <span className="truncate font-medium">{user.name}</span>
                 {user.username ? (
                   <span className="truncate text-xs font-normal text-muted-foreground">
                     {user.username}
                   </span>
                 ) : null}
-              </span>
+              </motion.span>
             </span>
-            <ChevronsUpDownIcon aria-hidden="true" className="size-3.5" />
+            <motion.span
+              animate={{
+                width: collapsed ? 0 : "auto",
+                opacity: collapsed ? 0 : 1,
+                x: collapsed ? 4 : 0,
+              }}
+              aria-hidden="true"
+              className={cn(
+                "flex shrink-0 items-center overflow-hidden",
+                // 0px wide while folded, but the flex gap before it would
+                // still offset the avatar — pull it back by that gap.
+                collapsed && "-ml-2"
+              )}
+              initial={false}
+              transition={
+                reduce
+                  ? REDUCED_TRANSITION
+                  : collapsed
+                    ? LABEL_EXIT_TRANSITION
+                    : LABEL_ENTER_TRANSITION
+              }
+            >
+              <ChevronsUpDownIcon aria-hidden="true" className="size-3.5" />
+            </motion.span>
           </Button>
         }
       />

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

@@ -0,0 +1,95 @@
+import type * as React from "react"
+
+import type { UserPresence } from "@/components/user-avatar"
+
+/** The identity shown on the card. */
+export interface ProfileCardUser {
+  name: string
+  /** Secondary line under the name — a handle, an email, a role. */
+  username?: string
+  /** Avatar image URL. Falls back to the initials when absent or broken. */
+  avatar?: string
+  /** Fallback initials. Derived from `name` when omitted. */
+  initials?: string
+  /** Presence badge on the avatar. Omitted, no badge. */
+  presence?: UserPresence
+}
+
+/** An actionable row of the menu. */
+export interface ProfileCardAction {
+  type?: "item"
+  id: string
+  label: string
+  icon?: React.ReactNode
+  /** Right-aligned hint, e.g. "⌘K". Purely decorative — bind the key yourself. */
+  shortcut?: string
+  disabled?: boolean
+  variant?: "default" | "destructive"
+  /** Returning a promise puts the card in its loading state until it settles. */
+  onSelect?: () => void | Promise<void>
+}
+
+/** A heading over the rows that follow it, up to the next separator. */
+export interface ProfileCardLabel {
+  type: "label"
+  label: string
+}
+
+/** A rule between two sections. */
+export interface ProfileCardSeparator {
+  type: "separator"
+}
+
+/**
+ * One entry of `items`. Authored flat; the block renders each run between
+ * separators as its own menu group so a label actually names its section.
+ */
+export type ProfileCardItem =
+  | ProfileCardAction
+  | ProfileCardLabel
+  | ProfileCardSeparator
+
+/** `expanded` shows avatar, name and handle; `collapsed` folds to the avatar
+ * alone — for an icon-collapsed sidebar rail. */
+export type ProfileCardVariant = "expanded" | "collapsed"
+
+/** Key for one card's state in the store. Any stable string; `useProfileCard`
+ * generates one when the component does not name itself. */
+export type ProfileCardInstanceId = string
+
+/** Everything the store knows about one card. */
+export interface ProfileCardState {
+  variant: ProfileCardVariant
+  menuOpen: boolean
+  /** Id of the action whose promise is in flight, `null` while idle. */
+  pendingActionId: string | null
+  /** `pendingActionId !== null` — the trigger is disabled and shows a spinner. */
+  busy: boolean
+}
+
+/** Write-only handles onto one card. Nothing here re-renders the caller. */
+export interface ProfileCardActions {
+  setVariant: (variant: ProfileCardVariant) => void
+  toggleVariant: () => void
+  /** Convenience over `setVariant`. */
+  collapse: () => void
+  expand: () => void
+  setMenuOpen: (open: boolean) => void
+  openMenu: () => void
+  closeMenu: () => void
+  reset: () => void
+}
+
+/** @internal Which fields the mounted component controls from props. The
+ * store must never overwrite a controlled value. */
+export interface ProfileCardConfig {
+  controlsVariant: boolean
+  controlsMenuOpen: boolean
+}
+
+/** @internal Latest option callbacks. Only write atoms read this, so it can
+ * be refreshed every commit without re-rendering anything. */
+export interface ProfileCardHandlers {
+  onVariantChange?: (variant: ProfileCardVariant) => void
+  onError?: (error: unknown) => void
+}

package/src/components/blocks/profile/use-profile-card-state.ts

@@ -0,0 +1,67 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  profileCardStateAtom,
+  resetProfileCardAtom,
+  setProfileCardMenuOpenAtom,
+  setProfileCardVariantAtom,
+  toggleProfileCardVariantAtom,
+} from "./profile-card-atom"
+import type {
+  ProfileCardActions,
+  ProfileCardInstanceId,
+  ProfileCardState,
+} from "./type"
+
+/**
+ * Read the card registered under `profileCardId` from anywhere below
+ * `ExegiaProvider` — no props, no ref, no provider of its own.
+ *
+ * ```tsx
+ * const { variant, busy } = useProfileCardState("account")
+ * ```
+ *
+ * Returns the whole state object, so the caller re-renders on any change. A
+ * component that watches one field should subscribe to that atom instead:
+ * `useAtomValue(profileCardVariantAtom("account"))`.
+ */
+export function useProfileCardState(
+  profileCardId: ProfileCardInstanceId
+): ProfileCardState {
+  return useAtomValue(profileCardStateAtom(profileCardId))
+}
+
+/**
+ * Write-only handles onto the card registered under `profileCardId`. Nothing
+ * here subscribes, so a rail toggle can fold the card without re-rendering
+ * when the card changes.
+ *
+ * ```tsx
+ * const { collapse, expand } = useProfileCardActions("account")
+ * ```
+ */
+export function useProfileCardActions(
+  profileCardId: ProfileCardInstanceId
+): ProfileCardActions {
+  const setVariant = useSetAtom(setProfileCardVariantAtom(profileCardId))
+  const toggleVariant = useSetAtom(toggleProfileCardVariantAtom(profileCardId))
+  const setMenuOpen = useSetAtom(setProfileCardMenuOpenAtom(profileCardId))
+  const reset = useSetAtom(resetProfileCardAtom(profileCardId))
+
+  return React.useMemo(
+    () => ({
+      setVariant,
+      toggleVariant,
+      collapse: () => setVariant("collapsed"),
+      expand: () => setVariant("expanded"),
+      setMenuOpen,
+      openMenu: () => setMenuOpen(true),
+      closeMenu: () => setMenuOpen(false),
+      reset,
+    }),
+    [setVariant, toggleVariant, setMenuOpen, reset]
+  )
+}

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

@@ -0,0 +1,126 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  profileCardBusyAtom,
+  profileCardMenuOpenAtom,
+  profileCardVariantAtom,
+  projectProfileCardPropsAtom,
+  removeProfileCardInstance,
+  seedProfileCardVariantAtom,
+  selectProfileCardActionAtom,
+  setProfileCardHandlersAtom,
+  setProfileCardMenuOpenAtom,
+} from "./profile-card-atom"
+import type {
+  ProfileCardAction,
+  ProfileCardConfig,
+  ProfileCardHandlers,
+  ProfileCardInstanceId,
+  ProfileCardVariant,
+} from "./type"
+
+export interface UseProfileCardOptions {
+  profileCardId?: ProfileCardInstanceId
+  /** Controlled fold. `undefined` leaves the store (and `defaultVariant`) in charge. */
+  variant?: ProfileCardVariant
+  defaultVariant?: ProfileCardVariant
+  onVariantChange?: (variant: ProfileCardVariant) => void
+  /** Controlled menu. */
+  open?: boolean
+  defaultOpen?: boolean
+  onError?: (error: unknown) => void
+}
+
+export interface ProfileCardBinding {
+  profileCardId: ProfileCardInstanceId
+  variant: ProfileCardVariant
+  collapsed: boolean
+  menuOpen: boolean
+  busy: boolean
+  /** Hand to the menu's `onOpenChange` (first argument). Stable. */
+  setMenuOpen: (open: boolean) => void
+  /** Run an action: `onSelect`, promise → busy, rejection → `onError`. Stable. */
+  select: (action: ProfileCardAction) => void
+}
+
+/**
+ * Binds one profile card to its slice of the store: projects the controlled
+ * `variant` / `open` props (one-way, with write gates so the store never
+ * overwrites a prop), publishes the latest handlers, and returns the values
+ * the component renders from.
+ *
+ * Unnamed cards key off `useId` and are dropped on unmount; a named
+ * `profileCardId` outlives its component, so a fold set from elsewhere
+ * (`useProfileCardActions(id).collapse()`) survives a route change.
+ */
+export function useProfileCard(options: UseProfileCardOptions): ProfileCardBinding {
+  const {
+    variant: variantProp,
+    defaultVariant = "expanded",
+    onVariantChange,
+    open: openProp,
+    onError,
+  } = options
+  const generatedId = React.useId()
+  const profileCardId = options.profileCardId ?? generatedId
+
+  const controlsVariant = variantProp !== undefined
+  const controlsMenuOpen = openProp !== undefined
+  const config = React.useMemo<ProfileCardConfig>(
+    () => ({ controlsVariant, controlsMenuOpen }),
+    [controlsVariant, controlsMenuOpen]
+  )
+  const handlers = React.useMemo<ProfileCardHandlers>(
+    () => ({ onVariantChange, onError }),
+    [onVariantChange, onError]
+  )
+
+  const project = useSetAtom(projectProfileCardPropsAtom(profileCardId))
+  const publishHandlers = useSetAtom(setProfileCardHandlersAtom(profileCardId))
+  const seedVariant = useSetAtom(seedProfileCardVariantAtom(profileCardId))
+  const setMenuOpen = useSetAtom(setProfileCardMenuOpenAtom(profileCardId))
+  const select = useSetAtom(selectProfileCardActionAtom(profileCardId))
+
+  // Seed the uncontrolled fold once per mount, before the projection — the
+  // `default*` options describe the mount, not every render. Layout effects
+  // so children read settled values in the same commit; primitive deps, so
+  // no loop guard is needed.
+  const [seed] = React.useState(() => ({
+    variant: variantProp ?? defaultVariant,
+    open: openProp ?? options.defaultOpen ?? false,
+  }))
+  React.useLayoutEffect(() => {
+    if (!controlsVariant) seedVariant(seed.variant)
+    if (!controlsMenuOpen) setMenuOpen(seed.open)
+    // Mount-time seed only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  React.useLayoutEffect(() => {
+    project(config, variantProp, openProp)
+  }, [project, config, variantProp, openProp])
+  React.useLayoutEffect(() => {
+    publishHandlers(handlers)
+  }, [publishHandlers, handlers])
+
+  React.useEffect(() => {
+    if (options.profileCardId !== undefined) return
+    return () => removeProfileCardInstance(profileCardId)
+  }, [options.profileCardId, profileCardId])
+
+  const variant = useAtomValue(profileCardVariantAtom(profileCardId))
+  const menuOpen = useAtomValue(profileCardMenuOpenAtom(profileCardId))
+  const busy = useAtomValue(profileCardBusyAtom(profileCardId))
+
+  return {
+    profileCardId,
+    variant,
+    collapsed: variant === "collapsed",
+    menuOpen,
+    busy,
+    setMenuOpen,
+    select,
+  }
+}