@exxatdesignux/ui 0.2.6 → 0.2.7

package/template/components/data-views/list-page-tree-column-header.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+export interface ListPageTreeColumnHeaderProps {
+  title: string
+  /** Right side (e.g. icon buttons) — keep touch targets ≥ 24px */
+  trailing?: React.ReactNode
+  className?: string
+}
+
+/**
+ * Shared left-column header for tree / outline surfaces — matches Question bank “Questions” bar.
+ */
+export function ListPageTreeColumnHeader({
+  title,
+  trailing,
+  className,
+}: ListPageTreeColumnHeaderProps) {
+  return (
+    <div className={cn("shrink-0 border-b border-border/50 bg-muted/10 px-3 py-2", className)}>
+      <div className="flex h-9 items-center justify-between gap-2">
+        <h3 className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{title}</h3>
+        {trailing ? (
+          <div className="flex shrink-0 items-center gap-0.5">{trailing}</div>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/template/components/data-views/list-page-tree-panel-shell.tsx

@@ -0,0 +1,91 @@
+"use client"
+
+/**
+ * Generic two-pane layout: scrollable **tree / outline** column + **details** column,
+ * with persisted split sizes (`ResizablePanelGroup` `id`) and shared **split hub chrome**
+ * (`ListPageSplitHubChrome`) so tree views match finder / folder panels across the app.
+ *
+ * Domain hubs pass `tree` and `details` nodes; this module stays entity-agnostic.
+ */
+
+import * as React from "react"
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable"
+import { ListPageSplitHubChrome } from "@/components/data-views/list-page-split-hub-chrome"
+import {
+  LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS,
+  LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS,
+  LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS,
+} from "@/components/data-views/list-page-split-hub-tokens"
+import {
+  LIST_PAGE_VIEW_FRAME_GUTTER,
+  LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+} from "@/components/data-views/list-page-view-frame"
+
+export interface ListPageTreePanelShellProps {
+  /** Stable id for `react-resizable-panels` layout persistence (per hub / route). */
+  resizableGroupId: string
+  /** Left column (tree chrome + body). */
+  tree: React.ReactNode
+  /** Right column (detail / inspector). */
+  details: React.ReactNode
+  /** Accessible name for the split surface, e.g. “Curriculum tree and details”. */
+  ariaLabel: string
+  treePanelId?: string
+  detailsPanelId?: string
+  treeDefaultSize?: string
+  treeMinSize?: string
+  treeMaxSize?: string
+  detailsDefaultSize?: string
+  detailsMinSize?: string
+  gutterClassName?: string
+  maxWidthClassName?: string
+}
+
+export function ListPageTreePanelShell({
+  resizableGroupId,
+  tree,
+  details,
+  ariaLabel,
+  treePanelId = "tree",
+  detailsPanelId = "details",
+  treeDefaultSize = "40%",
+  treeMinSize = "20%",
+  treeMaxSize = "60%",
+  detailsDefaultSize = "60%",
+  detailsMinSize = "30%",
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  maxWidthClassName = LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+}: ListPageTreePanelShellProps) {
+  return (
+    <ListPageSplitHubChrome
+      aria-label={ariaLabel}
+      gutterClassName={gutterClassName}
+      maxWidthClassName={maxWidthClassName}
+    >
+      <ResizablePanelGroup id={resizableGroupId} direction="horizontal" className="h-full min-h-0 w-full flex-1">
+        <ResizablePanel
+          id={treePanelId}
+          defaultSize={treeDefaultSize}
+          minSize={treeMinSize}
+          maxSize={treeMaxSize}
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          {tree}
+        </ResizablePanel>
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+        <ResizablePanel
+          id={detailsPanelId}
+          defaultSize={detailsDefaultSize}
+          minSize={detailsMinSize}
+          className={LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS}
+        >
+          {details}
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </ListPageSplitHubChrome>
+  )
+}

package/template/components/data-views/list-page-view-frame.tsx

@@ -0,0 +1,53 @@
+"use client"
+
+/**
+ * ListPageViewFrame — shared horizontal gutter + optional centered max-width for list-hub **view bodies**
+ * (folder icon grid, finder panel chrome, OS-style folder explorer, dashboard slices, etc.).
+ *
+ * **MUST** be used instead of ad-hoc `mx-4 lg:mx-6` + `mx-auto max-w-*` pairs on each page — see
+ * `AGENTS.md` §4.5 and `.cursor/rules/exxat-list-page-view-shells.mdc`.
+ *
+ * **MUST NOT** wrap `DataTable` when its toolbar already applies the same inset (avoid double gutter);
+ * use this for **non-table** view branches or **sections below** the shared toolbar.
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+/** Default horizontal rhythm for view bodies under `ListPageTemplate` (matches `FolderGridView`). */
+export const LIST_PAGE_VIEW_FRAME_GUTTER = "mx-4 mb-6 lg:mx-6"
+
+/** Typical max width for icon grids / dense tile views on ultra-wide monitors. */
+export const LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID = "max-w-6xl"
+
+/** Slightly wider shell when a view includes toolbar + breadcrumbs + grid (e.g. OS folder explorer). */
+export const LIST_PAGE_VIEW_FRAME_MAX_WIDE = "max-w-7xl"
+
+export interface ListPageViewFrameProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode
+  /**
+   * When set, children are wrapped in `mx-auto w-full min-w-0` + this max-width so the block stays
+   * centered inside the primary page column.
+   */
+  maxWidthClassName?: string
+  /** Override outer gutter; default `LIST_PAGE_VIEW_FRAME_GUTTER`. */
+  gutterClassName?: string
+}
+
+export function ListPageViewFrame({
+  children,
+  className,
+  maxWidthClassName,
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  ...rest
+}: ListPageViewFrameProps) {
+  return (
+    <div className={cn(gutterClassName, className)} {...rest}>
+      {maxWidthClassName ? (
+        <div className={cn("mx-auto w-full min-w-0", maxWidthClassName)}>{children}</div>
+      ) : (
+        children
+      )}
+    </div>
+  )
+}

package/template/components/data-views/os-folder-glyph.tsx

@@ -0,0 +1,121 @@
+"use client"
+
+/**
+ * Windows 11–style folder art (Icons8) + optional FA glyph on the pocket.
+ * Static asset: `public/folders/icons8-folder-windows-11.svg`
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import type { QuestionBankFolderColorKey } from "@/lib/mock/question-bank-folders"
+
+/** Served from `apps/web/public/folders/` (copied from Icons8 “folder windows 11 color”). */
+export const OS_FOLDER_GLYPH_SRC = "/folders/icons8-folder-windows-11.svg"
+
+/** Subtle hue tweak so “color” choice still reads on the shared yellow asset. */
+const COLOR_TINT_FILTER: Record<QuestionBankFolderColorKey, string> = {
+  brand: "hue-rotate(-42deg) saturate(1.25) brightness(0.97)",
+  success: "hue-rotate(82deg) saturate(1.2) brightness(0.95)",
+  warning: "hue-rotate(-5deg) saturate(1.35) brightness(1.02)",
+  destructive: "hue-rotate(300deg) saturate(1.15) brightness(0.92)",
+  muted: "saturate(0.15) brightness(1.08)",
+  chart1: "hue-rotate(200deg) saturate(1.2) brightness(0.96)",
+  chart2: "hue-rotate(95deg) saturate(1.15) brightness(0.96)",
+  chart3: "hue-rotate(265deg) saturate(1.2) brightness(0.96)",
+}
+
+const SIZE_MAP = {
+  /** Compact — folder inspector / column headers (matches ~36px row height). */
+  xs: "h-9 w-[2.6rem]",
+  sm: "h-[3.35rem] w-[3.85rem]",
+  md: "h-[4.6rem] w-[5.25rem]",
+  lg: "h-[6.5rem] w-[7.25rem]",
+}
+
+const ICON_TEXT: Record<keyof typeof SIZE_MAP, string> = {
+  xs: "text-[13px] leading-none",
+  sm: "text-lg",
+  md: "text-2xl",
+  lg: "text-4xl",
+}
+
+/** Darker version of each folder color for punched icon appearance. */
+const ICON_COLOR: Record<QuestionBankFolderColorKey, string> = {
+  brand: "text-orange-800 dark:text-orange-600",
+  success: "text-emerald-800 dark:text-emerald-600",
+  warning: "text-amber-800 dark:text-amber-600",
+  destructive: "text-red-800 dark:text-red-600",
+  muted: "text-slate-600 dark:text-slate-400",
+  chart1: "text-blue-800 dark:text-blue-600",
+  chart2: "text-lime-800 dark:text-lime-600",
+  chart3: "text-purple-800 dark:text-purple-600",
+}
+
+export interface OsFolderGlyphProps {
+  colorKey: QuestionBankFolderColorKey
+  /** Font Awesome icon classes without weight (e.g. `fa-stethoscope`). */
+  icon: string
+  size?: keyof typeof SIZE_MAP
+  className?: string
+  variant?: "solid" | "outline"
+  /**
+   * When false, exposes `role="img"` + `aria-label` (use with a short label, e.g. sheet preview).
+   * When true (default), hides the glyph from AT — parent control should name the action.
+   */
+  decorative?: boolean
+  /** Required when `decorative={false}` */
+  label?: string
+}
+
+export function OsFolderGlyph({
+  colorKey,
+  icon,
+  size = "md",
+  className,
+  variant = "solid",
+  decorative = true,
+  label,
+}: OsFolderGlyphProps) {
+  const outline = variant === "outline"
+  const tint = COLOR_TINT_FILTER[colorKey]
+
+  return (
+    <div
+      className={cn(
+        "group relative shrink-0 select-none transition-[transform,box-shadow] duration-200 ease-out",
+        "hover:z-[1] hover:scale-105 motion-reduce:transform-none motion-reduce:hover:scale-100",
+        SIZE_MAP[size],
+        className,
+      )}
+      role={!decorative && label ? "img" : undefined}
+      aria-label={!decorative ? label : undefined}
+      aria-hidden={decorative ? true : undefined}
+    >
+      <img
+        src={OS_FOLDER_GLYPH_SRC}
+        alt=""
+        width={240}
+        height={240}
+        draggable={false}
+        className={cn(
+          "h-full w-full object-contain",
+          "transition-[filter] duration-200",
+          outline && "opacity-75 saturate-[0.65]",
+        )}
+        style={outline ? undefined : { filter: tint }}
+      />
+      <span
+        className={cn(
+          "pointer-events-none absolute inset-0 flex items-center justify-center",
+          size === "xs" ? "translate-y-[0.18rem]" : "translate-y-[0.35rem]",
+          ICON_TEXT[size],
+          outline
+            ? "text-muted-foreground"
+            : cn(ICON_COLOR[colorKey], "opacity-100"),
+        )}
+      >
+        <i className={cn("fa-solid", icon)} aria-hidden="true" />
+      </span>
+    </div>
+  )
+}

package/template/components/folder-details-shell.tsx

@@ -0,0 +1,230 @@
+"use client"
+
+/**
+ * Folder details panel — OsFolderGlyph header + aggregates (`question-bank-inspector` helpers today).
+ * Reusable across list hubs that share `QuestionBankFolder` / `QuestionBankItem` shapes or adapters.
+ */
+
+import * as React from "react"
+import { ChevronRightIcon, X } from "lucide-react"
+import { OsFolderGlyph } from "@/components/data-views/os-folder-glyph"
+import { Button } from "@/components/ui/button"
+import { Separator } from "@/components/ui/separator"
+import { Tip } from "@/components/ui/tip"
+import { cn } from "@/lib/utils"
+import type { QuestionBankItem } from "@/lib/mock/question-bank"
+import type { QuestionBankFolder } from "@/lib/mock/question-bank-folders"
+import {
+  aggregateFolderQuestions,
+  BLOOM_LEVEL_ORDER,
+  questionsInFolderSubtree,
+} from "@/lib/mock/question-bank-inspector"
+
+function DetailBreadcrumbNav({ segments }: { segments: { id: string; label: string }[] }) {
+  if (segments.length === 0) return null
+  return (
+    <nav aria-label="Path in folder tree" className="flex min-w-0 flex-wrap items-center gap-1 text-xs text-muted-foreground">
+      {segments.map((seg, idx) => (
+        <React.Fragment key={seg.id}>
+          {idx > 0 && <ChevronRightIcon className="size-3 shrink-0 opacity-40" aria-hidden />}
+          <span
+            className={cn(
+              "min-w-0 truncate",
+              idx === segments.length - 1 ? "font-medium text-foreground" : "text-muted-foreground",
+            )}
+          >
+            {seg.label}
+          </span>
+        </React.Fragment>
+      ))}
+    </nav>
+  )
+}
+
+function DetailSection({
+  title,
+  children,
+  className,
+}: {
+  title: string
+  children: React.ReactNode
+  className?: string
+}) {
+  return (
+    <section className={cn("min-w-0", className)}>
+      <h3 className="mb-2 text-xs font-medium text-muted-foreground">{title}</h3>
+      {children}
+    </section>
+  )
+}
+
+function InspectorSectionTitle({ children, id }: { children: React.ReactNode; id?: string }) {
+  return (
+    <p
+      id={id}
+      className="mb-2 text-[11px] font-semibold uppercase tracking-wide text-muted-foreground"
+    >
+      {children}
+    </p>
+  )
+}
+
+export interface FolderDetailsShellProps {
+  folder: QuestionBankFolder
+  folders: QuestionBankFolder[]
+  questions: QuestionBankItem[]
+  /** Clears selection (tree inspector dismiss). */
+  onClearSelection?: () => void
+}
+
+export function FolderDetailsShell({
+  folder,
+  folders,
+  questions,
+  onClearSelection,
+}: FolderDetailsShellProps) {
+  const subtreeQuestions = questionsInFolderSubtree(folders, questions, folder.id)
+  const agg = aggregateFolderQuestions(subtreeQuestions)
+  const { totalQuestions, difficulty: diffAgg, bloom, avgPbi, scoredCount } = agg
+  const diffSum = diffAgg.easy + diffAgg.medium + diffAgg.hard
+  const maxBloomCount = Math.max(1, ...BLOOM_LEVEL_ORDER.map(level => bloom[level] ?? 0))
+
+  const breadcrumbs: QuestionBankFolder[] = []
+  let cur: QuestionBankFolder | undefined = folder
+  while (cur) {
+    breadcrumbs.unshift(cur)
+    cur = folders.find(f => f.id === cur?.parentId)
+  }
+  const pathSegments = breadcrumbs.map(f => ({ id: f.id, label: f.name }))
+
+  const diffHeadingId = `folder-details-difficulty-${folder.id}`
+  const bloomHeadingId = `folder-details-bloom-${folder.id}`
+
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden bg-card">
+      <header className="shrink-0 border-b border-border/60 bg-muted/10 px-4 pb-4 pt-4">
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex min-w-0 flex-1 items-start gap-3">
+            <OsFolderGlyph
+              colorKey={folder.colorKey}
+              icon={folder.icon}
+              size="xs"
+              className="shrink-0"
+            />
+            <div className="min-w-0 flex-1">
+              <h2 className="text-base font-semibold leading-tight tracking-tight text-foreground">
+                <span className="truncate">{folder.name}</span>
+                <span className="font-normal text-muted-foreground"> · Question Bank</span>
+              </h2>
+              <p className="mt-1 text-sm font-semibold tabular-nums text-foreground">
+                {totalQuestions} question{totalQuestions !== 1 ? "s" : ""}
+              </p>
+            </div>
+          </div>
+          {onClearSelection ? (
+            <Tip label="Close details" side="bottom">
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-sm"
+                className="shrink-0 text-muted-foreground hover:text-foreground"
+                onClick={onClearSelection}
+                aria-label="Close details"
+              >
+                <X className="size-4" aria-hidden />
+              </Button>
+            </Tip>
+          ) : null}
+        </div>
+      </header>
+
+      <div className="flex min-h-0 flex-1 flex-col gap-0 overflow-y-auto">
+        <div className="space-y-5 px-4 py-4">
+          <section aria-labelledby={diffHeadingId}>
+            <InspectorSectionTitle id={diffHeadingId}>Difficulty</InspectorSectionTitle>
+            <div
+              className="flex h-2 w-full overflow-hidden rounded-full bg-muted"
+              role="img"
+              aria-label={`Difficulty mix: ${diffAgg.easy} easy, ${diffAgg.medium} medium, ${diffAgg.hard} hard of ${diffSum || 0} questions`}
+            >
+              {diffSum === 0 ? (
+                <div className="h-full w-full bg-muted" />
+              ) : (
+                <>
+                  <div
+                    className="h-full bg-emerald-400/85 dark:bg-emerald-500/70"
+                    style={{ width: `${(diffAgg.easy / diffSum) * 100}%` }}
+                  />
+                  <div
+                    className="h-full bg-amber-400/90 dark:bg-amber-500/75"
+                    style={{ width: `${(diffAgg.medium / diffSum) * 100}%` }}
+                  />
+                  <div className="h-full bg-slate-500 dark:bg-slate-600" style={{ width: `${(diffAgg.hard / diffSum) * 100}%` }} />
+                </>
+              )}
+            </div>
+            <div className="mt-2 flex flex-wrap gap-x-4 gap-y-1.5 text-xs text-foreground">
+              <span className="inline-flex items-center gap-1.5">
+                <span className="size-2 shrink-0 rounded-sm bg-emerald-400/85 dark:bg-emerald-500/70" aria-hidden />
+                Easy: <span className="tabular-nums font-medium">{diffAgg.easy}</span>
+              </span>
+              <span className="inline-flex items-center gap-1.5">
+                <span className="size-2 shrink-0 rounded-sm bg-amber-400/90 dark:bg-amber-500/75" aria-hidden />
+                Medium: <span className="tabular-nums font-medium">{diffAgg.medium}</span>
+              </span>
+              <span className="inline-flex items-center gap-1.5">
+                <span className="size-2 shrink-0 rounded-sm bg-slate-500 dark:bg-slate-600" aria-hidden />
+                Hard: <span className="tabular-nums font-medium">{diffAgg.hard}</span>
+              </span>
+            </div>
+          </section>
+
+          <Separator className="bg-border/60" />
+
+          <section aria-labelledby={bloomHeadingId}>
+            <InspectorSectionTitle id={bloomHeadingId}>Bloom&apos;s</InspectorSectionTitle>
+            <ul className="flex flex-col gap-2.5" aria-label="Bloom taxonomy counts">
+              {BLOOM_LEVEL_ORDER.map(level => {
+                const count = bloom[level] ?? 0
+                const barPct = maxBloomCount ? (count / maxBloomCount) * 100 : 0
+                return (
+                  <li key={level} className="grid grid-cols-[minmax(5.5rem,auto)_1fr_auto] items-center gap-2 text-sm">
+                    <span className="text-muted-foreground">{level}</span>
+                    <div className="min-w-0">
+                      <div className="h-2 overflow-hidden rounded-full bg-muted">
+                        <div
+                          className="h-full rounded-full bg-pink-500/75 dark:bg-pink-500/65"
+                          style={{ width: `${barPct}%` }}
+                        />
+                      </div>
+                    </div>
+                    <span className="w-7 shrink-0 text-right tabular-nums font-medium text-foreground">{count}</span>
+                  </li>
+                )
+              })}
+            </ul>
+          </section>
+
+          <Separator className="bg-border/60" />
+
+          <p className="text-xs text-muted-foreground">
+            Avg. pBIS:{" "}
+            <span className="font-semibold text-foreground">{avgPbi != null ? avgPbi.toFixed(2) : "—"}</span>{" "}
+            <span className="tabular-nums">
+              ({scoredCount} of {totalQuestions} scored)
+            </span>
+          </p>
+
+          {pathSegments.length > 0 ? (
+            <>
+              <Separator className="bg-border/60" />
+              <DetailSection title="Location">
+                <DetailBreadcrumbNav segments={pathSegments} />
+              </DetailSection>
+            </>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  )
+}