@exxatdesignux/ui 0.2.6 → 0.2.7

package/template/components/data-views/finder-panel-view.tsx

@@ -0,0 +1,405 @@
+"use client"
+
+/**
+ * FinderPanelView — Miller-style 3-column split for list-page hubs.
+ *
+ * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `bg-muted/15` columns,
+ * shared resizable handles) — see `list-page-split-hub-tokens.ts`.
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable"
+import { ListPageTreeColumnHeader } from "@/components/data-views/list-page-tree-column-header"
+import { ListPageSplitDetailsPlaceholder } from "@/components/data-views/list-page-split-details-placeholder"
+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"
+
+export interface FinderGroup {
+  id: string
+  label: string
+  icon?: string
+  accent?: string
+  count: number
+}
+
+export interface FinderPanelViewProps<T> {
+  groups: FinderGroup[]
+  rows: T[]
+  getRowId: (row: T) => string | number
+  getRowGroupId: (row: T) => string
+  renderListRow: (row: T, isSelected: boolean) => React.ReactNode
+  renderDetail: (row: T) => React.ReactNode
+  emptyDetail?: React.ReactNode
+  emptyList?: React.ReactNode
+  defaultGroupId?: string
+  ariaLabel?: string
+  autoSaveId?: string
+  className?: string
+  style?: React.CSSProperties
+  onAddItem?: () => void
+  /**
+   * When true, omit outer margin, border, and card fill so the grid fits inside
+   * `ListPageSplitHubChrome` (shared split surface across hubs).
+   */
+  embedded?: boolean
+  /** Left column title (Question bank: “Categories”). */
+  groupsColumnTitle?: string
+  /** Middle column title; defaults from the active group label. */
+  getListColumnTitle?: (activeGroup: FinderGroup | undefined) => string
+}
+
+export function GroupsColumn({
+  groups,
+  selectedGroupId,
+  onSelect,
+  columnTitle,
+}: {
+  groups: FinderGroup[]
+  selectedGroupId: string
+  onSelect: (id: string) => void
+  columnTitle: string
+}) {
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <ListPageTreeColumnHeader title={columnTitle} />
+      <div
+        className="min-h-0 flex-1 overflow-y-auto py-1"
+        role="listbox"
+        aria-label="Group navigation"
+        aria-multiselectable="false"
+      >
+        {groups.map(group => {
+          const isSelected = group.id === selectedGroupId
+          return (
+            <div key={group.id} className="group flex items-center hover:bg-muted/50">
+              <button
+                type="button"
+                role="option"
+                aria-selected={isSelected}
+                onClick={() => onSelect(group.id)}
+                className={cn(
+                  "flex w-full flex-1 items-center gap-2 px-3 py-2 text-left text-sm transition-colors duration-75",
+                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                  isSelected
+                    ? "bg-accent font-medium text-accent-foreground"
+                    : "text-foreground",
+                )}
+              >
+                {group.accent ? (
+                  <span className={cn("size-2 shrink-0 rounded-full", group.accent)} aria-hidden="true" />
+                ) : group.icon ? (
+                  <i
+                    className={cn(
+                      "fa-light shrink-0 text-xs",
+                      group.icon,
+                      isSelected ? "text-accent-foreground" : "text-muted-foreground",
+                    )}
+                    aria-hidden="true"
+                  />
+                ) : null}
+                <span className="min-w-0 flex-1 truncate leading-tight">{group.label}</span>
+                <span
+                  className={cn(
+                    "shrink-0 tabular-nums text-xs",
+                    isSelected ? "text-accent-foreground/80" : "text-muted-foreground",
+                  )}
+                >
+                  {group.count}
+                </span>
+              </button>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Horizontal scope strip (toolbar toggles). Optional: place above a hub body when you need
+ * status scope without consuming a Finder column.
+ */
+export function FinderGroupStrip({
+  groups,
+  selectedGroupId,
+  onSelect,
+  ariaLabel = "Scope",
+}: {
+  groups: FinderGroup[]
+  selectedGroupId: string
+  onSelect: (id: string) => void
+  ariaLabel?: string
+}) {
+  return (
+    <div
+      role="toolbar"
+      aria-label={ariaLabel}
+      className="flex min-h-10 flex-wrap items-center gap-1.5 border-b border-border bg-muted/15 px-2 py-2"
+    >
+      {groups.map(group => {
+        const isSelected = group.id === selectedGroupId
+        return (
+          <button
+            key={group.id}
+            type="button"
+            aria-pressed={isSelected}
+            onClick={() => onSelect(group.id)}
+            className={cn(
+              "inline-flex h-8 max-w-full min-w-0 shrink-0 items-center gap-1.5 rounded-lg border px-2.5 text-xs font-medium transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              isSelected
+                ? "border-brand/40 bg-accent text-accent-foreground"
+                : "border-transparent bg-background/80 text-foreground hover:bg-muted",
+            )}
+          >
+            {group.accent ? (
+              <span className={cn("size-2 shrink-0 rounded-full", group.accent)} aria-hidden="true" />
+            ) : group.icon ? (
+              <i
+                className={cn(
+                  "fa-light shrink-0 text-[11px]",
+                  group.icon,
+                  isSelected ? "text-accent-foreground" : "text-muted-foreground",
+                )}
+                aria-hidden="true"
+              />
+            ) : null}
+            <span className="min-w-0 truncate">{group.label}</span>
+            <span
+              className={cn(
+                "shrink-0 tabular-nums text-[11px]",
+                isSelected ? "text-accent-foreground/85" : "text-muted-foreground",
+              )}
+            >
+              {group.count}
+            </span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+function ListColumn<T>({
+  rows,
+  getRowId,
+  selectedId,
+  renderListRow,
+  onSelect,
+  emptyList,
+  groupLabel,
+  columnTitle,
+  onAddItem,
+}: {
+  rows: T[]
+  getRowId: (row: T) => string | number
+  selectedId: string | number | null
+  renderListRow: (row: T, isSelected: boolean) => React.ReactNode
+  onSelect: (id: string | number) => void
+  emptyList?: React.ReactNode
+  groupLabel: string
+  columnTitle: string
+  onAddItem?: () => void
+}) {
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <ListPageTreeColumnHeader title={columnTitle} />
+      <div className="flex min-h-0 flex-1 flex-col">
+        <div
+          className="min-h-0 flex-1 overflow-y-auto py-1"
+          role="listbox"
+          aria-label={`${groupLabel} items`}
+          aria-multiselectable="false"
+        >
+          {rows.length === 0 ? (
+            <div className="flex flex-col items-center justify-center px-4 py-12 text-center text-sm text-muted-foreground">
+              {emptyList ?? <p>No items in this group.</p>}
+            </div>
+          ) : (
+            rows.map(row => {
+              const id = getRowId(row)
+              const isSelected = id === selectedId
+              return (
+                <div key={id} className="group flex items-center hover:bg-muted/50">
+                  <button
+                    type="button"
+                    role="option"
+                    aria-selected={isSelected}
+                    onClick={() => onSelect(id)}
+                    className={cn(
+                      "flex w-full flex-1 items-center gap-3 px-3 py-2 text-left text-sm transition-colors duration-75",
+                      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                      isSelected
+                        ? "bg-accent font-medium text-accent-foreground"
+                        : "text-foreground",
+                    )}
+                  >
+                    {renderListRow(row, isSelected)}
+                  </button>
+                </div>
+              )
+            })
+          )}
+        </div>
+        {onAddItem ? (
+          <div className="flex shrink-0 items-center justify-center border-t border-border/50 px-2 py-1.5">
+            <button
+              type="button"
+              onClick={onAddItem}
+              className="flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              aria-label={`Add item to ${groupLabel}`}
+            >
+              <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+            </button>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+function DetailColumn({ children }: { children: React.ReactNode }) {
+  return (
+    <div className={cn(LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS, "overflow-hidden")}>
+      <ListPageTreeColumnHeader title="Details" />
+      <div className="flex min-h-0 flex-1 flex-col overflow-hidden">{children}</div>
+    </div>
+  )
+}
+
+function DefaultEmptyDetail() {
+  return (
+    <ListPageSplitDetailsPlaceholder title="Nothing selected" />
+  )
+}
+
+export function FinderPanelView<T>({
+  groups,
+  rows,
+  getRowId,
+  getRowGroupId,
+  renderListRow,
+  renderDetail,
+  emptyDetail,
+  emptyList,
+  defaultGroupId,
+  ariaLabel = "List and details",
+  autoSaveId = "finder-panel-view",
+  className,
+  style,
+  onAddItem,
+  embedded = false,
+  groupsColumnTitle = "Categories",
+  getListColumnTitle = g => g?.label ?? "Items",
+}: FinderPanelViewProps<T>) {
+  const mergedStyle = React.useMemo<React.CSSProperties>(() => {
+    if (embedded) {
+      return { height: "100%", minHeight: 0, ...style }
+    }
+    return {
+      height: "calc(100vh - 280px)",
+      minHeight: 420,
+      ...style,
+    }
+  }, [embedded, style])
+  const firstGroupId = defaultGroupId ?? groups[0]?.id ?? "all"
+  const [selectedGroupId, setSelectedGroupId] = React.useState(firstGroupId)
+  const [selectedRowId, setSelectedRowId] = React.useState<string | number | null>(null)
+
+  const visibleRows = React.useMemo(() => {
+    if (selectedGroupId === "all") return rows
+    return rows.filter(r => getRowGroupId(r) === selectedGroupId)
+  }, [rows, selectedGroupId, getRowGroupId])
+
+  React.useEffect(() => {
+    setSelectedRowId(visibleRows[0] ? getRowId(visibleRows[0]) : null)
+  }, [selectedGroupId, visibleRows, getRowId])
+
+  React.useEffect(() => {
+    if (selectedRowId !== null && !visibleRows.find(r => getRowId(r) === selectedRowId)) {
+      setSelectedRowId(visibleRows[0] ? getRowId(visibleRows[0]) : null)
+    }
+  }, [visibleRows, selectedRowId, getRowId])
+
+  const selectedRow =
+    selectedRowId !== null
+      ? (visibleRows.find(r => getRowId(r) === selectedRowId) ?? null)
+      : null
+
+  const selectedGroup = groups.find(g => g.id === selectedGroupId)
+  const listColumnTitle = getListColumnTitle(selectedGroup)
+
+  return (
+    <div
+      className={cn(
+        embedded
+          ? "flex h-full min-h-0 flex-col overflow-hidden"
+          : "mx-4 mb-6 overflow-hidden rounded-xl border border-border bg-card lg:mx-6",
+        className,
+      )}
+      style={mergedStyle}
+      aria-label={ariaLabel}
+    >
+      <ResizablePanelGroup
+        id={String(autoSaveId)}
+        direction="horizontal"
+        className="h-full min-h-0 w-full flex-1"
+      >
+        <ResizablePanel
+          id="groups"
+          defaultSize="22%"
+          minSize="16%"
+          maxSize="32%"
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          <GroupsColumn
+            columnTitle={groupsColumnTitle}
+            groups={groups}
+            selectedGroupId={selectedGroupId}
+            onSelect={id => setSelectedGroupId(id)}
+          />
+        </ResizablePanel>
+
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+
+        <ResizablePanel
+          id="list"
+          defaultSize="34%"
+          minSize="22%"
+          maxSize="48%"
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          <ListColumn
+            columnTitle={listColumnTitle}
+            rows={visibleRows}
+            getRowId={getRowId}
+            selectedId={selectedRowId}
+            renderListRow={renderListRow}
+            onSelect={id => setSelectedRowId(id)}
+            emptyList={emptyList}
+            groupLabel={selectedGroup?.label ?? "All"}
+            onAddItem={onAddItem}
+          />
+        </ResizablePanel>
+
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+
+        <ResizablePanel id="detail" defaultSize="44%" minSize="30%" className={LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS}>
+          <DetailColumn>
+            {selectedRow
+              ? renderDetail(selectedRow)
+              : (emptyDetail ?? <DefaultEmptyDetail />)}
+          </DetailColumn>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  )
+}

package/template/components/data-views/folder-grid-view.tsx

@@ -0,0 +1,86 @@
+"use client"
+
+/**
+ * FolderGridView — generic icon-grid layout for any list-page hub.
+ *
+ * Handles the responsive CSS grid shell, empty state, and accessibility list role.
+ * Pass a `renderTile` render-prop for domain-specific tile content
+ * (Placements, Team, Rotations, etc.).
+ *
+ * Usage:
+ * ```tsx
+ * <FolderGridView
+ *   rows={placements}
+ *   getRowId={r => r.id}
+ *   renderTile={row => <PlacementFolderTile row={row} onClick={…} />}
+ *   ariaLabel="Placements folder view"
+ * />
+ * ```
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import {
+  ListPageViewFrame,
+  LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID,
+} from "@/components/data-views/list-page-view-frame"
+
+export interface FolderGridViewProps<T> {
+  rows: T[]
+  getRowId: (row: T) => string | number
+  /** Render one tile — receives the row, returns a React node (typically a `<button>`). */
+  renderTile: (row: T) => React.ReactNode
+  /** Shown when `rows` is empty. */
+  emptyContent?: React.ReactNode
+  /** `aria-label` on the grid list. */
+  ariaLabel?: string
+  className?: string
+  /**
+   * When true, constrains the grid to a centered max width so folder tiles don’t stretch
+   * edge-to-edge on very wide viewports.
+   */
+  constrainWidth?: boolean
+}
+
+export function FolderGridView<T>({
+  rows,
+  getRowId,
+  renderTile,
+  emptyContent,
+  ariaLabel = "Folder view",
+  className,
+  constrainWidth = false,
+}: FolderGridViewProps<T>) {
+  if (rows.length === 0) {
+    return (
+      <ListPageViewFrame
+        maxWidthClassName={constrainWidth ? LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID : undefined}
+        className={cn(className)}
+      >
+        <div className="flex flex-col items-center justify-center rounded-xl border border-dashed border-border py-16 text-sm text-muted-foreground">
+          <i className="fa-solid fa-grid-2 mb-3 text-3xl opacity-40" aria-hidden="true" />
+          {emptyContent ?? <p>No records found.</p>}
+        </div>
+      </ListPageViewFrame>
+    )
+  }
+
+  return (
+    <ListPageViewFrame className={cn(className)}>
+      <div
+        className={cn(
+          "grid grid-cols-2 gap-3 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 2xl:grid-cols-8",
+          constrainWidth && "mx-auto max-w-6xl",
+        )}
+        role="list"
+        aria-label={ariaLabel}
+      >
+        {rows.map(row => (
+          <div key={getRowId(row)} role="listitem">
+            {renderTile(row)}
+          </div>
+        ))}
+      </div>
+    </ListPageViewFrame>
+  )
+}

package/template/components/data-views/index.ts

@@ -26,6 +26,65 @@ export {
   type ViewSegmentOption,
 } from "@/components/ui/view-segmented-control"
 
+/** Shared gutter + centered max-width for list view bodies (folder grid, OS explorer, etc.). */
+export {
+  ListPageViewFrame,
+  LIST_PAGE_VIEW_FRAME_GUTTER,
+  LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID,
+  LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+  type ListPageViewFrameProps,
+} from "@/components/data-views/list-page-view-frame"
+
+/** Centered bordered card + viewport height for finder / tree / multi-column split hubs. */
+export {
+  ListPageSplitHubChrome,
+  LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE,
+  type ListPageSplitHubChromeProps,
+} from "@/components/data-views/list-page-split-hub-chrome"
+
+export {
+  ListPageTreeColumnHeader,
+  type ListPageTreeColumnHeaderProps,
+} from "@/components/data-views/list-page-tree-column-header"
+
+export {
+  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"
+
+export {
+  ListPageSplitDetailsPlaceholder,
+  type ListPageSplitDetailsPlaceholderProps,
+} from "@/components/data-views/list-page-split-details-placeholder"
+
+/** Tree / outline + inspector — `ListPageTreePanelShell`; composed hub wiring (`HubTreePanelView`); folder metrics (`FolderDetailsShell`). */
+export {
+  FolderDetailsShell,
+  type FolderDetailsShellProps,
+} from "@/components/folder-details-shell"
+
+export {
+  HubTreePanelView,
+  type HubTreePanelViewProps,
+} from "@/components/hub-tree-panel-view"
+
+export {
+  ListPageTreePanelShell,
+  type ListPageTreePanelShellProps,
+} from "@/components/data-views/list-page-tree-panel-shell"
+
+/** Windows 11–style folder art (Icons8) + FA overlay for icon-folder hubs. */
+export {
+  OsFolderGlyph,
+  OS_FOLDER_GLYPH_SRC,
+  type OsFolderGlyphProps,
+} from "@/components/data-views/os-folder-glyph"
+
+/** Generic folder icon-grid — reusable across all list hubs. */
+export { FolderGridView, type FolderGridViewProps } from "@/components/data-views/folder-grid-view"
+
+
 /** Unified hub tile + list row surface — see `list-page-board-card.tsx`. */
 export {
   HubRecordCard,

package/template/components/data-views/list-page-split-details-placeholder.tsx

@@ -0,0 +1,39 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+export interface ListPageSplitDetailsPlaceholderProps {
+  title?: string
+  description?: React.ReactNode
+  className?: string
+}
+
+/**
+ * Empty right pane for split hubs — matches Question bank tree “Nothing selected”.
+ */
+export function ListPageSplitDetailsPlaceholder({
+  title = "Nothing selected",
+  description,
+  className,
+}: ListPageSplitDetailsPlaceholderProps) {
+  return (
+    <div
+      className={cn(
+        "flex h-full min-h-0 flex-col items-center justify-center bg-gradient-to-b from-muted/25 via-card to-card px-6 py-10 text-center",
+        className,
+      )}
+    >
+      <div className="mb-4 flex size-14 items-center justify-center rounded-2xl border border-dashed border-border/70 bg-muted/25">
+        <i
+          className="fa-light fa-sidebar text-[1.65rem] leading-none text-muted-foreground/70"
+          aria-hidden="true"
+        />
+      </div>
+      <p className="text-sm font-medium text-foreground">{title}</p>
+      {description ? (
+        <div className="mt-1.5 max-w-[16rem] text-xs leading-relaxed text-muted-foreground">{description}</div>
+      ) : null}
+    </div>
+  )
+}

package/template/components/data-views/list-page-split-hub-chrome.tsx

@@ -0,0 +1,60 @@
+"use client"
+
+/**
+ * Shared **centered** chrome for list-hub split surfaces (finder / tree / multi-column explorers).
+ *
+ * Composes `ListPageViewFrame` (gutter + max width) with a single bordered card + fixed viewport
+ * height so panel and tree views match across routes (`AGENTS.md` §4.5).
+ */
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import {
+  ListPageViewFrame,
+  LIST_PAGE_VIEW_FRAME_GUTTER,
+  LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+} from "@/components/data-views/list-page-view-frame"
+
+/** Default height band for split views under `ListPageTemplate` + toolbar. */
+export const LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE: React.CSSProperties = {
+  height: "calc(100vh - 280px)",
+  minHeight: 420,
+}
+
+const SURFACE_CLASS =
+  "flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-border bg-card"
+
+export interface ListPageSplitHubChromeProps {
+  children: React.ReactNode
+  "aria-label"?: string
+  gutterClassName?: string
+  maxWidthClassName?: string
+  /** Override default split viewport height / min-height */
+  surfaceStyle?: React.CSSProperties
+  surfaceClassName?: string
+}
+
+export function ListPageSplitHubChrome({
+  children,
+  "aria-label": ariaLabel,
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  maxWidthClassName = LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+  surfaceStyle,
+  surfaceClassName,
+}: ListPageSplitHubChromeProps) {
+  return (
+    <ListPageViewFrame
+      gutterClassName={gutterClassName}
+      maxWidthClassName={maxWidthClassName}
+      className="flex min-h-0 flex-1 flex-col"
+    >
+      <div
+        className={cn(SURFACE_CLASS, surfaceClassName)}
+        style={{ ...LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE, ...surfaceStyle }}
+        aria-label={ariaLabel}
+      >
+        {children}
+      </div>
+    </ListPageViewFrame>
+  )
+}

package/template/components/data-views/list-page-split-hub-tokens.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared layout tokens for list-hub split surfaces (Miller columns, tree + details).
+ * Keeps Question bank panel / tree and generic `FinderPanelView` visually aligned.
+ */
+
+/** `ResizableHandle` between miller / tree columns — matches Question bank panel. */
+export const LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS =
+  "w-1 bg-border/40 hover:bg-brand/20 transition-colors"
+
+/** Primary column stack (scope list, folder list, record list, …). */
+export const LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS =
+  "flex min-h-0 min-w-0 flex-col bg-muted/15"
+
+/** Right-hand inspector / detail column shell. */
+export const LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS =
+  "flex min-h-0 min-w-0 flex-col bg-card"