@exxatdesignux/ui 0.2.9 → 0.2.11

package/template/components/templates/discovery-hub-template.tsx

@@ -0,0 +1,273 @@
+"use client"
+
+import * as React from "react"
+import Link from "next/link"
+import { useRouter } from "next/navigation"
+
+import { useAskLeo } from "@/components/ask-leo-sidebar"
+import { PrimaryPageTemplate, type PrimaryPageTemplateProps } from "@/components/templates/primary-page-template"
+import { Button } from "@/components/ui/button"
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command"
+import { Shortcut } from "@/components/ui/dropdown-menu"
+import { Kbd, KbdGroup } from "@/components/ui/kbd"
+import { Tip } from "@/components/ui/tip"
+import { useAltKeyLabel, useModKeyLabel } from "@/hooks/use-mod-key-label"
+import type { DiscoveryHubSearchGroup, DiscoveryHubSearchItem } from "@/lib/discovery-hub"
+
+export interface DiscoveryHubPrimaryAction {
+  label: string
+  onClick: () => void
+  shortcutKeys?: string
+}
+
+export interface DiscoveryHubAskLeoPromo {
+  title: string
+  description: string
+  prompts: readonly string[]
+}
+
+export interface DiscoveryHubTemplateProps
+  extends Pick<PrimaryPageTemplateProps, "siteHeader" | "maxWidthClassName" | "contentClassName" | "bodyClassName"> {
+  title: string
+  description: string
+  inputPlaceholder: string
+  inputAriaLabel: string
+  emptyMessage: string
+  groups: DiscoveryHubSearchGroup[]
+  primaryAction: DiscoveryHubPrimaryAction
+  askLeoPromo: DiscoveryHubAskLeoPromo
+  browseLibraryHref: string
+  browseLibraryLabel?: string
+}
+
+const DiscoveryHubSearchRow = React.memo(function DiscoveryHubSearchRow({
+  item,
+  onLink,
+  onLeo,
+}: {
+  item: DiscoveryHubSearchItem
+  onLink: (href: string) => void
+  onLeo: (prompt: string) => void
+}) {
+  const isLeo = Boolean(item.askLeoPrompt)
+  const iconClass = isLeo
+    ? "fa-duotone fa-solid fa-star-christmas w-5 shrink-0 text-center text-brand"
+    : `${item.icon ?? "fa-light fa-arrow-right"} w-5 shrink-0 text-center`
+
+  return (
+    <CommandItem
+      className="mx-2 rounded-lg py-2.5"
+      keywords={item.keywords ? [item.keywords] : undefined}
+      onSelect={() => {
+        if (item.askLeoPrompt) onLeo(item.askLeoPrompt)
+        else if (item.href) onLink(item.href)
+      }}
+    >
+      <i className={iconClass} aria-hidden="true" />
+      <span>{item.label}</span>
+    </CommandItem>
+  )
+})
+
+/**
+ * Discovery hub — centered command-style natural language search, create CTA, and Ask Leo promo.
+ * Hubs can pass `groups` from a domain module (e.g. Ask Leo prompt suggestions from `lib/question-bank-hub-search.ts`).
+ */
+export function DiscoveryHubTemplate({
+  title,
+  description,
+  inputPlaceholder,
+  inputAriaLabel,
+  emptyMessage,
+  groups,
+  primaryAction,
+  askLeoPromo,
+  browseLibraryHref,
+  browseLibraryLabel = "Browse library",
+  siteHeader,
+  maxWidthClassName = "max-w-3xl",
+  contentClassName,
+  bodyClassName,
+}: DiscoveryHubTemplateProps) {
+  const router = useRouter()
+  const { openWithPrompt, toggle } = useAskLeo()
+  const mod = useModKeyLabel()
+  const alt = useAltKeyLabel()
+  const [inputValue, setInputValue] = React.useState("")
+  const searchInputRef = React.useRef<HTMLInputElement>(null)
+
+  const navigate = React.useCallback(
+    (href: string) => {
+      setInputValue("")
+      router.push(href)
+    },
+    [router],
+  )
+
+  const sendLeoSuggestion = React.useCallback(
+    (prompt: string) => {
+      setInputValue("")
+      openWithPrompt(prompt)
+    },
+    [openWithPrompt],
+  )
+
+  React.useEffect(() => {
+    const id = window.setTimeout(() => searchInputRef.current?.focus(), 0)
+    return () => window.clearTimeout(id)
+  }, [])
+
+  const trimmedQuery = inputValue.trim()
+  const leoShortcut = `${mod}${alt}K`
+  const createShortcut = primaryAction.shortcutKeys ?? `${mod}${alt}N`
+
+  return (
+    <PrimaryPageTemplate
+      siteHeader={siteHeader}
+      maxWidthClassName={maxWidthClassName}
+      contentClassName={contentClassName}
+      bodyClassName={bodyClassName}
+    >
+      <Shortcut keys={createShortcut} onInvoke={primaryAction.onClick} />
+      {/* ⌘⌥K (Ask Leo toggle) is bound globally in AskLeoProvider — do not double-bind here. */}
+
+      <div className="flex min-h-0 flex-1 flex-col px-4 py-8 md:px-6 md:py-10">
+        <div className="mx-auto flex w-full min-w-0 flex-1 flex-col gap-8">
+          <header className="space-y-2 text-center">
+            <h1
+              className="text-2xl font-semibold tracking-tight text-foreground md:text-3xl"
+              style={{ fontFamily: "var(--font-heading)" }}
+            >
+              {title}
+            </h1>
+            <p className="mx-auto max-w-2xl text-sm text-muted-foreground md:text-base">{description}</p>
+          </header>
+
+          <section
+            aria-label="Natural language search"
+            className="overflow-hidden rounded-2xl border border-border/60 bg-card shadow-sm ring-1 ring-foreground/10"
+          >
+            <Command
+              loop
+              label={inputAriaLabel}
+              className="rounded-2xl border-0 bg-transparent p-0 shadow-none"
+            >
+              <div className="flex min-h-14 items-center gap-3 border-b border-border/50 px-4 md:min-h-16 md:px-5">
+                <CommandInput
+                  ref={searchInputRef}
+                  variant="palette"
+                  aria-label={inputAriaLabel}
+                  onValueChange={setInputValue}
+                  placeholder={inputPlaceholder}
+                  value={inputValue}
+                  className="h-14 text-base md:h-16 md:text-lg"
+                />
+                <span className="hidden shrink-0 text-xs text-muted-foreground sm:inline">
+                  <KbdGroup>
+                    <Kbd>{mod}</Kbd>
+                    <Kbd>K</Kbd>
+                  </KbdGroup>
+                  <span className="ms-1.5">global search</span>
+                </span>
+              </div>
+
+              <CommandList className="max-h-[min(420px,50vh)] py-2">
+                <CommandEmpty>{emptyMessage}</CommandEmpty>
+                {groups.map(group => {
+                  if (group.items.length === 0) return null
+                  if (group.searchOnly && !trimmedQuery) return null
+                  return (
+                    <CommandGroup key={group.id} heading={group.heading}>
+                      {group.items.map(item => (
+                        <DiscoveryHubSearchRow
+                          key={item.id}
+                          item={item}
+                          onLeo={sendLeoSuggestion}
+                          onLink={navigate}
+                        />
+                      ))}
+                    </CommandGroup>
+                  )
+                })}
+              </CommandList>
+            </Command>
+          </section>
+
+          <div className="grid gap-4 md:grid-cols-[minmax(0,1fr)_auto] md:items-start">
+            <section
+              aria-labelledby="discovery-hub-ask-leo"
+              className="rounded-2xl border border-brand/20 bg-brand/5 p-4 md:p-5"
+            >
+              <div className="flex flex-wrap items-start justify-between gap-3">
+                <div className="min-w-0 space-y-1">
+                  <h2 id="discovery-hub-ask-leo" className="text-sm font-semibold text-foreground">
+                    {askLeoPromo.title}
+                  </h2>
+                  <p className="text-sm text-muted-foreground">{askLeoPromo.description}</p>
+                </div>
+                <Tip
+                  label={(
+                    <span className="inline-flex items-center gap-1.5">
+                      Ask Leo
+                      <KbdGroup>
+                        <Kbd>{mod}</Kbd>
+                        <Kbd>{alt}</Kbd>
+                        <Kbd>K</Kbd>
+                      </KbdGroup>
+                    </span>
+                  )}
+                >
+                  <Button type="button" variant="outline" size="sm" onClick={toggle}>
+                    <i className="fa-duotone fa-solid fa-star-christmas text-brand" aria-hidden="true" />
+                    Ask Leo
+                    <KbdGroup className="ms-1.5 hidden sm:inline-flex">
+                      <Kbd variant="bare">{leoShortcut}</Kbd>
+                    </KbdGroup>
+                  </Button>
+                </Tip>
+              </div>
+              <ul className="mt-4 flex flex-col gap-2" role="list">
+                {askLeoPromo.prompts.map(prompt => (
+                  <li key={prompt}>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      className="h-auto w-full justify-start whitespace-normal px-3 py-2.5 text-left text-sm font-normal"
+                      onClick={() => sendLeoSuggestion(prompt)}
+                    >
+                      <i className="fa-light fa-sparkles me-2 shrink-0 text-brand" aria-hidden="true" />
+                      <span>{prompt}</span>
+                    </Button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+
+            <div className="flex flex-col gap-2 md:min-w-[14rem]">
+              <Button type="button" size="lg" className="w-full" onClick={primaryAction.onClick}>
+                <i className="fa-light fa-plus" aria-hidden="true" />
+                {primaryAction.label}
+                <KbdGroup className="ms-1.5">
+                  <Kbd variant="bare">{createShortcut}</Kbd>
+                </KbdGroup>
+              </Button>
+              <Button type="button" variant="outline" size="lg" className="w-full" asChild>
+                <Link href={browseLibraryHref}>
+                  <i className="fa-light fa-table-list" aria-hidden="true" />
+                  {browseLibraryLabel}
+                </Link>
+              </Button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </PrimaryPageTemplate>
+  )
+}

package/template/components/templates/list-page.tsx

@@ -124,6 +124,8 @@ export interface ListPageTemplateProps {
    * `TablePropertiesDrawer` when `onEditView` is omitted.
    */
   tablePropertiesRef?: React.RefObject<OpenTablePropertiesHandle | null>
+  /** When true, hide the views tab strip (tabs + add view) — e.g. search landing with a single table surface. */
+  hideViewsToolbar?: boolean
 }
 
 /** Collision-proof id for a dynamically-added tab. Module-level counters reset
@@ -177,6 +179,7 @@ export function ListPageTemplate({
   exportTotalRows = 0,
   onEditView,
   tablePropertiesRef,
+  hideViewsToolbar = false,
 }: ListPageTemplateProps) {
   const controlled =
     tabsProp !== undefined &&
@@ -270,14 +273,14 @@ export function ListPageTemplate({
 
   return (
     <>
-      {VIEW_TYPES.slice(0, 9).map((v, i) => (
+      {!hideViewsToolbar && VIEW_TYPES.slice(0, 9).map((v, i) => (
         <Shortcut
           key={v.type}
           keys={`⌘⇧${i + 1}`}
           onInvoke={() => addView(v.type)}
         />
       ))}
-      {activeTab && (
+      {activeTab && !hideViewsToolbar && (
         <>
           <Shortcut keys="F2" onInvoke={() => openRename(activeTab)} />
           <Shortcut
@@ -299,6 +302,8 @@ export function ListPageTemplate({
       {showMetrics && metrics}
 
       {/* ── Views toolbar (not tablist: settings/close are not tabs — WCAG 1.3.1 / ARIA) ── */}
+      {!hideViewsToolbar && (
+      <>
       {/* Outer: horizontal scroll only. Inner: vertical padding so ring-offset focus rings are not clipped
           (`overflow-x-auto` forces overflow-y to clip in a single box). */}
       <div className="mt-3 shrink-0 overflow-x-auto px-4 lg:px-6">
@@ -350,7 +355,7 @@ export function ListPageTemplate({
                     </button>
                   </DropdownMenuTrigger>
                 </Tip>
-                <DropdownMenuContent align="start" className="w-56">
+                <DropdownMenuContent align="start">
                   <DropdownMenuLabel className="text-xs text-muted-foreground">
                     View: {VIEW_TYPES.find(v => v.type === tab.viewType)?.label}
                   </DropdownMenuLabel>
@@ -471,7 +476,7 @@ export function ListPageTemplate({
                 Add view
               </Button>
             </DropdownMenuTrigger>
-            <DropdownMenuContent align="start" className="w-40">
+            <DropdownMenuContent align="start">
               <DropdownMenuLabel className="text-xs">Add a view</DropdownMenuLabel>
               <DropdownMenuSeparator />
               {VIEW_TYPES.map((v, i) => (
@@ -488,6 +493,8 @@ export function ListPageTemplate({
           </DropdownMenu>
         </div>
       </div>
+      </>
+      )}
 
       {/* ── Content — keyed by tab so each view tab owns its height (no stale min-height). ── */}
       {activeTab ? (

package/template/components/templates/nested-secondary-panel-shell.tsx

@@ -0,0 +1,57 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+export interface NestedSecondaryPanelShellProps {
+  /** When false, the shell is visually hidden (no width). */
+  open: boolean
+  /** Icon-only rail (same width token as primary `Sidebar` collapsible icon mode). */
+  compact: boolean
+  children: React.ReactNode
+  /** Forwarded to the outer `<nav>`. */
+  "aria-label"?: string
+  className?: string
+}
+
+/**
+ * Shared chrome for a nested hub rail — full width vs icon rail, aligned with primary sidebar tokens.
+ * Domain panels render their header + nav inside `children`.
+ */
+export function NestedSecondaryPanelShell({
+  open,
+  compact,
+  children,
+  "aria-label": ariaLabel = "Secondary navigation",
+  className,
+}: NestedSecondaryPanelShellProps) {
+  return (
+    <nav
+      aria-label={ariaLabel}
+      data-state={open ? "open" : "closed"}
+      data-layout={open ? (compact ? "icon" : "expanded") : "closed"}
+      className={cn(
+        "flex flex-col overflow-hidden",
+        "transition-[width,margin,opacity] duration-200 ease-linear",
+        open
+          ? cn(
+              "shrink-0 m-2 mx-2 rounded-xl ring-1 ring-sidebar-border shadow-sm relative md:sticky md:top-2",
+              compact
+                ? "w-12 min-w-12 max-w-12 h-[min(calc(100svh-2rem),800px)] md:h-[min(calc(100svh-1rem),800px)]"
+                : "w-64 min-w-64 max-w-64 h-[min(calc(100svh-2rem),800px)] md:h-[min(calc(100svh-1rem),800px)]",
+            )
+          : "h-0 min-h-0 shrink overflow-hidden border-0 p-0 m-0 min-w-0 w-0 max-w-0 opacity-0 pointer-events-none",
+        className,
+      )}
+      style={open ? { backgroundColor: "var(--secondary-panel-bg, #FAFBFF)" } : undefined}
+    >
+      <div
+        className={cn(
+          "flex flex-1 flex-col overflow-y-auto overflow-x-hidden",
+          open ? "min-w-0" : "hidden min-w-0 w-0 p-0",
+        )}
+      >
+        {children}
+      </div>
+    </nav>
+  )
+}

package/template/components/templates/secondary-panel-hub-template.tsx

@@ -0,0 +1,54 @@
+import * as React from "react"
+
+import { PrimaryPageTemplate, type PrimaryPageTemplateProps } from "@/components/templates/primary-page-template"
+import { useAutoPanel } from "@/components/secondary-panel"
+
+export interface SecondaryPanelHubActivatorProps {
+  panelId: string
+}
+
+/** Opens the nested secondary panel while the activator stays mounted (e.g. a route-segment layout). */
+export function SecondaryPanelHubActivator({ panelId }: SecondaryPanelHubActivatorProps) {
+  useAutoPanel(panelId)
+  return null
+}
+
+export interface SecondaryPanelHubTemplateProps
+  extends Omit<PrimaryPageTemplateProps, "beforeSiteHeader"> {
+  /** Bridges hub state into the secondary nav (folder tree, access sheet, …). */
+  bridges?: React.ReactNode
+  /** Extra chrome before `SiteHeader`. */
+  beforeSiteHeader?: React.ReactNode
+}
+
+/**
+ * Primary hub shell with optional bridges + `PrimaryPageTemplate` body.
+ * Mount `useAutoPanel` / `SecondaryPanelHubActivator` on a parent layout that stays mounted across
+ * hub child routes (see `app/(app)/question-bank/layout.tsx`) so the panel does not close between navigations.
+ *
+ * Pair with `useSecondaryPanelHubNav` and hub-specific `lib/*-nav.ts` helpers for URL scope.
+ */
+export function SecondaryPanelHubTemplate({
+  bridges,
+  beforeSiteHeader,
+  siteHeader,
+  children,
+  maxWidthClassName,
+  contentClassName,
+  bodyClassName,
+}: SecondaryPanelHubTemplateProps) {
+  return (
+    <>
+      {bridges}
+      <PrimaryPageTemplate
+        beforeSiteHeader={beforeSiteHeader}
+        siteHeader={siteHeader}
+        maxWidthClassName={maxWidthClassName}
+        contentClassName={contentClassName}
+        bodyClassName={bodyClassName}
+      >
+        {children}
+      </PrimaryPageTemplate>
+    </>
+  )
+}

package/template/docs/card-vs-rows-pattern.md

@@ -0,0 +1,36 @@
+# Cards vs table rows vs list rows
+
+> **Related:** **`AGENTS.md` §4–§5**, **`.cursor/rules/exxat-data-tables.mdc`**, **`.cursor/rules/exxat-board-cards.mdc`**, **`docs/data-views-pattern.md`**.
+
+## When to use **rows** (table or dense list)
+
+- **Many similar records** (roughly **10+**) where users **scan**, **sort**, **filter**, and **compare columns**.
+- **Same fields** across entities — columns align; export and **TablePropertiesDrawer** apply.
+- **Primary hub** pattern — **`DataTable`** + **`ListPageTemplate`** per **`exxat-data-tables`**.
+
+**Use:** `DataTable`, shared toolbar, row actions, pinned columns.
+
+## When to use **cards** (tile / board / marketing)
+
+- **Lower cardinality** or **visual-first** browsing — folders, dashboards, “pick a template”, hero metrics beside a chart.
+- **Heterogeneous content** — each card has a different layout (title, badge, avatar, two-line body) where a rigid grid of columns would fight the design.
+- **Kanban** — **`ListPageBoardCard`** + column model; still fed by **`tableState.rows`**.
+
+**Use:** `ListPageBoardCard`, `ChartCard`, icon grids under **`ListPageViewFrame`**, dashboard chart tiles.
+
+## When to use **list rows** (not full DataTable)
+
+- **Medium density** — fewer columns than a grid; reading order is **vertical** (timeline, activity, simple roster without heavy operators).
+- Still wire **search** when the list is the main surface and item count grows.
+
+**Prefer** graduating to **`DataTable`** once the hub needs filters, column hide, density, or export parity with other list hubs.
+
+## Anti-patterns
+
+- **Cards for 50+ homogeneous records** when the product expects sort/filter/compare — that belongs in **`DataTable`**.
+- **A second bespoke “table”** alongside **`DataTable`** for the same dataset — extend the table stack instead (**`exxat-centralized-list-dataset`**).
+- **Raw `<table>`** for product data lists — forbidden (**`exxat-data-tables`**).
+
+## See also
+
+- **`.cursor/rules/exxat-card-vs-list-rows.mdc`**, **`.cursor/skills/exxat-card-vs-list-rows/SKILL.md`**

package/template/docs/collaboration-access-pattern.md

@@ -0,0 +1,114 @@
+# Collaboration & access pattern
+
+Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Question bank — `QuestionBankPageHeader`, `QuestionBankClient`, `InviteCollaboratorsDrawer`.
+
+## When to use
+
+- A list hub or library is **shared** across people (not a private directory).
+- Users need to see **who has access**, **invite by email**, and assign **library access** (Owner / Editor / Commenter / Viewer).
+- The hub already uses **`ListPageTemplate`** + **`PageHeader`** (or an entity header built on it).
+
+**Do not** use this for org-wide **role** administration (Faculty, Program coordinator, Director) as the only story — those are **directory role tags** on people, not library access.
+
+## Vocabulary
+
+| Concept | Meaning | Source |
+|--------|---------|--------|
+| **Library access** | What someone can do **in this hub** (Owner, Editor, Commenter, Viewer) | `lib/collaborator-access.ts` |
+| **Directory roles** | Org/job tags on a person (Faculty, Program coordinator, Director) | `PageHeaderCollaborator.roles` |
+| **Face rail** | Overlapping avatars in the header when the roster is non-empty | `PageHeader` `variant="collaboration"` |
+| **Empty roster CTA** | Outline **Add collaborator** in the header when `collaborators` is empty | `PageHeader` + `COLLABORATION_HEADER_ADD_LABEL` |
+| **Invite sheet** | Floating right **`Sheet`** for roster + invite form | `InviteCollaboratorsDrawer` |
+| **Hub wiring** | Roster state + invite sheet in one render-prop shell | `CollaborationAccessFlow` |
+
+## Header (`PageHeader`)
+
+- Set **`variant="collaboration"`**.
+- Pass **`collaborators`** (`PageHeaderCollaborator[]`) and optional **`accessInfo`**.
+- **Non-empty roster** — overlapping **face rail** only; each face and **`+N`** open the invite sheet via **`onCollaboratorsOpen`**.
+- **Empty roster** — outline **`Add collaborator`** (`addCollaboratorLabel`, default **`COLLABORATION_HEADER_ADD_LABEL`**) opens the same sheet.
+- **Invite** also lives under **⋯ More** on the entity page header (first item when `variant="collaboration"`).
+
+```tsx
+<CollaborationAccessFlow
+  initialCollaborators={QUESTION_BANK_HEADER_COLLABORATORS}
+  resourceLabel={hubHeader.title}
+>
+  {({ collaborators, openInvite }) => (
+    <QuestionBankPageHeader
+      variant="collaboration"
+      title={hubHeader.title}
+      questionCount={count}
+      collaborators={collaborators}
+      onAddCollaborator={openInvite}
+      onCollaboratorsOpen={openInvite}
+      onExport={() => setExportOpen(true)}
+      showMetrics={showMetrics}
+      onToggleMetrics={() => setShowMetrics(v => !v)}
+    />
+  )}
+</CollaborationAccessFlow>
+```
+
+## Hub client state
+
+- Prefer **`CollaborationAccessFlow`** — owns **`collaborators`**, **`openInvite`**, and **`InviteCollaboratorsDrawer`**; pass **`openInvite`** to **`onAddCollaborator`** / **`onCollaboratorsOpen`**.
+- Without the flow: **`collaborators`** — `useState` seeded from `lib/mock/<entity>-header-collaborators.ts` (or API later); **`inviteOpen`** — boolean; mount **`InviteCollaboratorsDrawer`** beside **`ListPageTemplate`**.
+- On invite success, append to **`collaborators`** so the **face rail** and sheet roster stay aligned.
+- **Change access** — roster menu updates **`collaborators`** via **`onCollaboratorAccessChange`** ( **`CollaborationAccessFlow`** default).
+- **Remove access** — confirm dialog then **`onCollaboratorRemove`**; blocked for the only **Owner**.
+
+## `PageHeaderCollaborator`
+
+| Field | Use |
+|-------|-----|
+| `id`, `name`, `imageUrl`, `initials` | Face rail + roster row |
+| `email` | Roster (below name); invite form |
+| `access` | Library access badge (Owner … Viewer) |
+| `roles` | Optional **outline** chips (Faculty, Program coordinator, Director) |
+
+## Invite sheet (`InviteCollaboratorsDrawer`)
+
+Mirror **`ExportDrawer`** chrome: floating **`Sheet`**, no overlay, **`showCloseButton={false}`**, footer **Cancel** / **Send invite** with inline **`Kbd`** (**Esc** / **⏎**), **`Shortcut`** for Enter on the open surface.
+
+**Invite field:** one bordered row — email input + **access** menu on the right.
+
+- Use **`Select`** with **`SelectGroup`** for access (invite row in **`InputGroupAddon`**, roster row standalone); **`position="popper"`** inside the sheet; **no** toast on success (**§6.5**).
+
+**People with access:** one **`rounded-lg border`** list with **`divide-y`** — **not** one card per person.
+
+Row order:
+
+1. **Name** (`text-sm font-medium`)
+2. **Email** (`text-xs text-muted-foreground`)
+3. **Role tags** (`Badge variant="outline"`) when `roles` is set
+4. Trailing **library access** **`Select`** when the hub wires **`onCollaboratorAccessChange`**; **Remove access** (trash) opens a confirm **`Dialog`** when **`onCollaboratorRemove`** is set. The sole **Owner** cannot be removed or demoted until another owner exists.
+
+## Library access constants
+
+- Types and invite options: **`lib/collaborator-access.ts`**
+- **`INVITE_COLLABORATOR_ACCESS_OPTIONS`** — Editor / Commenter / Viewer (no Owner on invite)
+- Customize option **descriptions** per hub; keep **values** stable for forms/API
+
+## File map
+
+| Piece | Path |
+|-------|------|
+| Access types | `lib/collaborator-access.ts` |
+| Hub flow | `components/collaboration-access-flow.tsx` |
+| Collaborator type | `components/page-header.tsx` (`PageHeaderCollaborator`) |
+| Invite sheet | `components/invite-collaborators-drawer.tsx` |
+| Entity header | `components/question-bank-page-header.tsx` |
+| Hub wiring | `components/question-bank-client.tsx` |
+| Demo roster | `lib/mock/question-bank-header-collaborators.ts` |
+
+## Checklist (new hub)
+
+- [ ] `PageHeader` / entity header uses **`variant="collaboration"`** when the product is shared.
+- [ ] **Empty roster** shows **Add collaborator**; **non-empty** shows face rail; both open the invite sheet.
+- [ ] **Invite people** under **⋯ More**; **`CollaborationAccessFlow`** (or equivalent) owns roster + sheet.
+- [ ] Roster: single bordered list; **name → email → role tags**; access badge on the right.
+- [ ] Invite row: email + access menu; **`FormDescription`** for format; **no** toast.
+- [ ] Labels from **`collaborator-access.ts`**; mock/API rows extend **`PageHeaderCollaborator`** once.
+
+**Handbook:** `AGENTS.md` §4.7 · **Rule:** `.cursor/rules/exxat-collaboration-access.mdc` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md`

package/template/docs/data-views-pattern.md

@@ -45,7 +45,7 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 ## Mock data and connected views
 
 1. **Put entity rows in `lib/mock/<entity>.ts`** — Export a typed array (e.g. `TeamMember[]`, `Placement[]`) and reuse it from the page client and from KPI helpers.
-2. **KPI / summary helpers** — Add `lib/mock/<entity>-kpi.ts` (or next to the mock file) with pure functions **`entityKpiMetrics(rows: T[])`** and **`entityKpiInsight(rows: T[])`** returning `MetricItem[]` and `MetricInsight` from `@/components/key-metrics`. Drive **both** the template **`metrics`** slot and the **dashboard view** from the **same helpers**, passing **`tableState.rows`** in the table component so filters/search apply everywhere.
+2. **KPI / summary helpers** — Add `lib/mock/<entity>-kpi.ts` (or next to the mock file) with pure functions **`entityKpiMetrics(rows: T[])`** and **`entityKpiInsight(rows: T[])`** returning `MetricItem[]` and `MetricInsight` from `@/components/key-metrics`. Set **`MetricItem.trendPolarity`** when an increase is **not** favorable (see **`docs/kpi-trend-pattern.md`**). Drive **both** the template **`metrics`** slot and the **dashboard view** from the **same helpers**, passing **`tableState.rows`** in the table component so filters/search apply everywhere.
 3. **Single table component** — One component (e.g. `TeamTable`) receives **`members`** (full mock) + **`view`**. It calls **`useTableState(members, columns, …)`** once. Branch on `view`:
    - **`table`** → `DataTable` with that state.
    - **`list` / `board`** → `DataTableToolbar` + list/board UI with **`tableState.rows`**.
@@ -72,6 +72,12 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 
 **Import:** `@/components/table-properties` re-exports the drawer and types.
 
+## Dropdown menus (view settings, row actions)
+
+**`DropdownMenuContent`** in **`@exxatdesignux/ui`** merges a **default surface** (**`DROPDOWN_MENU_CONTENT_SURFACE_CLASS`**: **`min-w-52 w-max max-w-[min(24rem,calc(100vw-2rem))]`**) so **ListPageTemplate** view settings / Add view, **`DataTable`** filter and column menus, and hub **row ⋯** menus size to their labels (including shortcut hints) without fixed **`w-40` / `w-48`** rails. Sizing is **pure CSS** — do **not** add **`ResizeObserver`** or per-open measurement for standard menus.
+
+**Override** when product intent needs a fixed width (e.g. pagination **page size** **`w-20`**, **`NavUser`** trigger-width + **`min-w-60`**, school switcher **`!w-max min-w-72 …`**).
+
 ## Board UI reuse
 
 **Handbook:** **`AGENTS.md` §4.4** — board card shell, badge row, shared status maps, and MUST/MUST NOT. **Cursor:** **`.cursor/rules/exxat-board-cards.mdc`**, skill **`.cursor/skills/exxat-board-cards/SKILL.md`**.
@@ -138,9 +144,11 @@ Reference: `components/placements-page-header.tsx`, `components/team-page-header
 
 **When to use a new page (route):** The flow is **primary**, **long-form**, **multi-step**, or should have its **own URL** / bookmark / history **without** the parent page behind it — e.g. full create/edit, wizards, or detail that *is* the task.
 
-**Rule of thumb:** **Context + quick** → **drawer**; **otherwise** → **new page**.
+**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **otherwise** → **new page**.
+
+**Modal vs side panel (same route):** When the overlay stays on the same URL, prefer **`docs/drawer-vs-dialog-pattern.md`** and **`.cursor/rules/exxat-drawer-vs-dialog.mdc`** — drawers keep the hub visible; dialogs trap focus for confirms.
 
-Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**.
+Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 
 ---
 
@@ -160,7 +168,7 @@ When a route is a **primary** destination in nav (main hub for an entity) **and*
 - [ ] **>10 items** → search, filter, sort, properties (per surface type above).
 - [ ] **Has data to export** → **More** menu with **Export** + shared `ExportDrawer` pattern.
 - [ ] **Primary + large / main hub** → `ListPageTemplate`-style shell where applicable.
-- [ ] **Page vs drawer (§6.4)** — Quick actions with parent **context** → drawer/sheet; primary or long flows → **new route**.
+- [ ] **Page vs drawer vs dialog (§6.4)** — Quick with parent **context** → drawer/sheet; **blocking** confirm → **dialog**; primary or long flows → **new route** (`docs/drawer-vs-dialog-pattern.md`).
 - [ ] **Primary button** → `Button` default variant (`size="lg"` for parity with Placements), not outline.
 - [ ] **Dashboard view tab** → `KeyMetrics` + shared KPI helpers from **`tableState.rows`**; no duplicate one-off metric cards.
 - [ ] **Data view charts** → `ChartFigure` + `chart-keyboard-selection`; layout persistence via **`data-view-dashboard-storage`** (see `AGENTS.md` §4.3).