@exxatdesignux/ui 0.2.18 → 0.2.19

package/template/components/data-views/list-page-folder-columns-panel.tsx

@@ -0,0 +1,345 @@
+"use client"
+
+/**
+ * Finder-style multi-column folder + item explorer for **panel** view tabs.
+ * Generic over folder and item shapes; hubs supply labels, icons, and detail renderers.
+ */
+
+import * as React from "react"
+import { Button } from "@/components/ui/button"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable"
+import { cn } from "@/lib/utils"
+import { ListPageTreeColumnHeader } from "@/components/data-views/list-page-tree-column-header"
+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 ListPageFolderColumnsPanelProps<
+  TFolder extends { id: string },
+  TItem extends { id: string },
+> {
+  folders: TFolder[]
+  items: TItem[]
+  isFolder: (item: TFolder | TItem) => item is TFolder
+  getFolderParentId: (folder: TFolder) => string | null
+  getFolderName: (folder: TFolder) => string
+  getItemFolderId: (item: TItem) => string | null
+  getItemLabel: (item: TItem) => string
+  renderItemDetail: (item: TItem) => React.ReactNode
+  renderFolderDetail?: (
+    folder: TFolder,
+    ctx: { folders: TFolder[]; items: TItem[] },
+  ) => React.ReactNode
+  renderItemMeta?: (item: TItem, ctx: { isSelected: boolean }) => React.ReactNode
+  renderFolderIcon?: (
+    folder: TFolder,
+    ctx: { isSelected: boolean; depth: number },
+  ) => React.ReactNode
+  renderItemIcon?: (item: TItem, ctx: { isSelected: boolean }) => React.ReactNode
+  renderFolderRowClassName?: (
+    folder: TFolder,
+    ctx: { isSelected: boolean; depth: number },
+  ) => string | undefined
+  renderFolderActions?: (folder: TFolder) => React.ReactNode
+  onAddFolder: (parentId: string | null) => void
+  onAddItem?: (parentId: string | null) => void
+  rootColumnTitle?: string
+  addFolderAriaLabel?: string
+  addItemAriaLabel?: string
+}
+
+export function ListPageFolderColumnsPanel<
+  TFolder extends { id: string },
+  TItem extends { id: string },
+>({
+  folders,
+  items,
+  isFolder,
+  getFolderParentId,
+  getFolderName,
+  getItemFolderId,
+  getItemLabel,
+  renderItemDetail,
+  renderFolderDetail,
+  renderItemMeta,
+  renderFolderIcon,
+  renderItemIcon,
+  renderFolderRowClassName,
+  renderFolderActions,
+  onAddFolder,
+  onAddItem,
+  rootColumnTitle = "Categories",
+  addFolderAriaLabel = "Add folder",
+  addItemAriaLabel = "Add item",
+}: ListPageFolderColumnsPanelProps<TFolder, TItem>) {
+  type HierarchyItem = TFolder | TItem
+
+  const [selectedPath, setSelectedPath] = React.useState<HierarchyItem[]>(() => {
+    const roots = folders
+      .filter(f => getFolderParentId(f) === null)
+      .sort((a, b) => getFolderName(a).localeCompare(getFolderName(b)))
+    return roots.length > 0 ? [roots[0]] : []
+  })
+
+  const isFirstRenderRef = React.useRef(true)
+
+  const rootFolders = React.useMemo(() => {
+    return folders
+      .filter(f => getFolderParentId(f) === null)
+      .sort((a, b) => getFolderName(a).localeCompare(getFolderName(b)))
+  }, [folders, getFolderParentId, getFolderName])
+
+  const handleSelect = (item: HierarchyItem, depth: number) => {
+    setSelectedPath(prev => [...prev.slice(0, depth), item])
+  }
+
+  React.useEffect(() => {
+    if (isFirstRenderRef.current && selectedPath.length > 0) {
+      const lastItem = selectedPath[selectedPath.length - 1]
+      if (isFolder(lastItem)) {
+        const subfolders = folders
+          .filter(f => getFolderParentId(f) === lastItem.id)
+          .sort((a, b) => getFolderName(a).localeCompare(getFolderName(b)))
+        const childItems = items.filter(i => getItemFolderId(i) === lastItem.id)
+        const next: HierarchyItem[] = [...subfolders, ...childItems]
+
+        if (next.length > 0 && !selectedPath[selectedPath.length + 1]) {
+          setSelectedPath(prev => [...prev, next[0]])
+          isFirstRenderRef.current = false
+        }
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const columns: Array<{ items: HierarchyItem[]; depth: number; parentId?: string | null }> =
+    React.useMemo(() => {
+      const cols: Array<{ items: HierarchyItem[]; depth: number; parentId?: string | null }> = [
+        { items: rootFolders, depth: 0, parentId: null },
+      ]
+
+      for (let i = 0; i < selectedPath.length; i++) {
+        const item = selectedPath[i]
+        if (isFolder(item)) {
+          const subfolders = folders
+            .filter(f => getFolderParentId(f) === item.id)
+            .sort((a, b) => getFolderName(a).localeCompare(getFolderName(b)))
+          const childItems = items.filter(i => getItemFolderId(i) === item.id)
+          const columnItems: HierarchyItem[] = [...subfolders, ...childItems]
+
+          if (columnItems.length > 0) {
+            cols.push({ items: columnItems, depth: i + 1, parentId: item.id })
+          }
+        }
+      }
+
+      return cols
+    }, [selectedPath, rootFolders, folders, items, isFolder, getFolderParentId, getFolderName, getItemFolderId])
+
+  const selectedLeaf = selectedPath.length > 0 ? selectedPath.at(-1)! : null
+  const selectedItem =
+    selectedLeaf && !isFolder(selectedLeaf) ? (selectedLeaf as TItem) : null
+  const selectedFolderLeaf =
+    selectedLeaf && isFolder(selectedLeaf) ? (selectedLeaf as TFolder) : null
+
+  const defaultFolderIcon = (selected: boolean) => (
+    <i
+      className={cn("fa-folder shrink-0 text-sm", selected ? "fa-solid" : "fa-light")}
+      aria-hidden="true"
+    />
+  )
+
+  const defaultItemIcon = (selected: boolean) => (
+    <i
+      className={cn("fa-file shrink-0 text-sm", selected ? "fa-solid" : "fa-light")}
+      aria-hidden="true"
+    />
+  )
+
+  return (
+    <ResizablePanelGroup
+      direction="horizontal"
+      className="flex h-full min-h-0 w-full flex-1 overflow-hidden"
+    >
+      {columns.map(({ items: columnItems, depth, parentId }, columnIdx) => (
+        <React.Fragment key={`col-${depth}`}>
+          {columnIdx > 0 && (
+            <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+          )}
+          <ResizablePanel
+            id={`col-${depth}`}
+            defaultSize={columnIdx === 0 ? 35 : columnIdx === 1 ? 35 : 30}
+            minSize={15}
+            className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+          >
+            <ListPageTreeColumnHeader
+              title={
+                depth === 0
+                  ? rootColumnTitle
+                  : selectedPath[depth - 1] && isFolder(selectedPath[depth - 1])
+                    ? getFolderName(selectedPath[depth - 1] as TFolder)
+                    : "Items"
+              }
+              trailing={
+                <>
+                  <span className="shrink-0 text-xs font-medium text-muted-foreground tabular-nums">
+                    {columnItems.length}
+                  </span>
+                  {depth < columns.length - 1 && columnItems.length > 0 ? (
+                    <div className="flex shrink-0 items-center gap-0.5">
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <Button
+                            size="icon-sm"
+                            variant="ghost"
+                            onClick={() => onAddFolder(parentId ?? null)}
+                            aria-label={addFolderAriaLabel}
+                          >
+                            <i className="fa-light fa-folder-plus text-xs" aria-hidden="true" />
+                          </Button>
+                        </TooltipTrigger>
+                        <TooltipContent side="top" sideOffset={4}>
+                          {addFolderAriaLabel}
+                        </TooltipContent>
+                      </Tooltip>
+                      {onAddItem ? (
+                        <Tooltip>
+                          <TooltipTrigger asChild>
+                            <Button
+                              size="icon-sm"
+                              variant="ghost"
+                              onClick={() => onAddItem(parentId ?? null)}
+                              aria-label={addItemAriaLabel}
+                            >
+                              <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+                            </Button>
+                          </TooltipTrigger>
+                          <TooltipContent side="top" sideOffset={4}>
+                            {addItemAriaLabel}
+                          </TooltipContent>
+                        </Tooltip>
+                      ) : null}
+                    </div>
+                  ) : null}
+                </>
+              }
+            />
+
+            <div className="min-h-0 flex-1 overflow-y-auto py-1">
+              {columnItems.map(item => {
+                const isSelected = selectedPath[depth]?.id === item.id
+                const isFolderRow = isFolder(item)
+                const folder = isFolderRow ? item : null
+                const rowItem = isFolderRow ? null : (item as TItem)
+
+                const subfolderCount = isFolderRow
+                  ? folders.filter(f => getFolderParentId(f) === item.id).length
+                  : 0
+                const childItemCount = isFolderRow
+                  ? items.filter(i => getItemFolderId(i) === item.id).length
+                  : 0
+                const itemCount = subfolderCount + childItemCount
+
+                return (
+                  <div
+                    key={item.id}
+                    className="group flex items-center hover:bg-muted/50"
+                  >
+                    <button
+                      type="button"
+                      onClick={() => handleSelect(item, depth)}
+                      className={cn(
+                        "flex 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 text-accent-foreground"
+                          : "text-foreground",
+                        isFolderRow && folder
+                          ? renderFolderRowClassName?.(folder, { isSelected, depth })
+                          : undefined,
+                      )}
+                      aria-selected={isSelected}
+                      role="option"
+                    >
+                      {isFolderRow && folder ? (
+                        renderFolderIcon?.(folder, { isSelected, depth }) ??
+                        defaultFolderIcon(isSelected)
+                      ) : rowItem ? (
+                        renderItemIcon?.(rowItem, { isSelected }) ??
+                        defaultItemIcon(isSelected)
+                      ) : null}
+
+                      <span
+                        className={cn(
+                          "min-w-0 flex-1 truncate leading-tight",
+                          isSelected && "font-medium",
+                        )}
+                      >
+                        {isFolderRow && folder
+                          ? getFolderName(folder)
+                          : rowItem
+                            ? getItemLabel(rowItem)
+                            : ""}
+                      </span>
+
+                      <span
+                        className={cn(
+                          "ml-auto shrink-0 text-xs tabular-nums",
+                          isSelected ? "text-accent-foreground/70" : "text-muted-foreground",
+                        )}
+                      >
+                        {isFolderRow
+                          ? itemCount
+                          : rowItem
+                            ? (renderItemMeta?.(rowItem, { isSelected }) ?? null)
+                            : null}
+                      </span>
+                    </button>
+
+                    {isFolderRow && folder && renderFolderActions?.(folder)}
+                  </div>
+                )
+              })}
+            </div>
+          </ResizablePanel>
+        </React.Fragment>
+      ))}
+
+      {(selectedItem || selectedFolderLeaf) && (
+        <>
+          <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+          <ResizablePanel
+            id="col-detail"
+            defaultSize={30}
+            minSize={20}
+            className={LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS}
+          >
+            {selectedItem ? (
+              <>
+                <ListPageTreeColumnHeader title="Details" className="px-4" />
+                <div className="min-h-0 flex-1 overflow-y-auto px-4 py-4">
+                  {renderItemDetail(selectedItem)}
+                </div>
+              </>
+            ) : selectedFolderLeaf && renderFolderDetail ? (
+              <div className="min-h-0 flex-1 overflow-hidden">
+                {renderFolderDetail(selectedFolderLeaf, { folders, items })}
+              </div>
+            ) : null}
+          </ResizablePanel>
+        </>
+      )}
+    </ResizablePanelGroup>
+  )
+}

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

@@ -21,6 +21,14 @@ export const LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE: React.CSSProperties = {
   minHeight: 420,
 }
 
+/**
+ * Viewport band for calendar under `ListPageTemplate` + hub toolbar (+ optional metrics).
+ * Uses a fixed height (not min-height) so the week strip scrolls inside the card, not the page.
+ */
+export const LIST_PAGE_CALENDAR_HEIGHT_STYLE: React.CSSProperties = {
+  height: "clamp(420px, calc(100dvh - 22rem), 880px)",
+}
+
 const SURFACE_CLASS =
   "flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-border bg-card"
 

package/template/components/examples/focused-workflow-showcase.tsx

@@ -0,0 +1,183 @@
+"use client"
+
+/**
+ * Patterns / examples — `FocusedWorkflowPageTemplate` layout variants.
+ */
+
+import * as React from "react"
+import Link from "next/link"
+
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { ViewSegmentedControl } from "@/components/ui/view-segmented-control"
+import {
+  FocusedWorkflowEmptyState,
+  FocusedWorkflowSingleColumn,
+  FocusedWorkflowStepForm,
+  FocusedWorkflowSidebarSections,
+  FocusedWorkflowWizardFooter,
+  type FocusedWorkflowStep,
+} from "@/components/templates/focused-workflow-layouts"
+import {
+  FocusedWorkflowPageTemplate,
+  FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS,
+} from "@/components/templates/focused-workflow-page-template"
+
+const DEMO_STEPS: FocusedWorkflowStep[] = [
+  {
+    id: "basics",
+    label: "Basics",
+    description: "Name, owner, and schedule for this record.",
+  },
+  {
+    id: "details",
+    label: "Details",
+    description: "Optional fields and attachments.",
+  },
+  {
+    id: "review",
+    label: "Review",
+    description: "Confirm before you submit.",
+  },
+]
+
+const DEMO_SECTIONS = [
+  { id: "general", label: "General" },
+  { id: "notifications", label: "Notifications" },
+  { id: "security", label: "Security" },
+] as const
+
+type DemoVariant = "empty" | "steps" | "sidebar"
+
+const VARIANT_OPTIONS: { value: DemoVariant; label: string }[] = [
+  { value: "empty", label: "Empty" },
+  { value: "steps", label: "Steps" },
+  { value: "sidebar", label: "Sidebar" },
+]
+
+export function FocusedWorkflowShowcase() {
+  const [variant, setVariant] = React.useState<DemoVariant>("steps")
+  const [stepIndex, setStepIndex] = React.useState(0)
+  const [activeSection, setActiveSection] = React.useState<string>("general")
+
+  const siteHeader = {
+    back: { label: "Patterns", href: "/examples" },
+    title: "Focused workflow layouts",
+  }
+
+  const shell = (body: React.ReactNode, maxWidth: "md" | "lg" = "lg") => (
+    <FocusedWorkflowPageTemplate
+      siteHeader={siteHeader}
+      maxWidth={maxWidth}
+      contentClassName={FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS}
+    >
+      <FocusedWorkflowSingleColumn>
+        <PageHeader
+          title="Focused workflow"
+          subtitle="Dedicated routes for large forms and multi-step actions — not list hubs or split-column explorers."
+          actions={
+            <ViewSegmentedControl
+              value={variant}
+              onValueChange={v => setVariant(v as DemoVariant)}
+              options={VARIANT_OPTIONS}
+              aria-label="Layout variant"
+            />
+          }
+        />
+        {body}
+      </FocusedWorkflowSingleColumn>
+    </FocusedWorkflowPageTemplate>
+  )
+
+  if (variant === "empty") {
+    return shell(
+      <FocusedWorkflowEmptyState
+        title="No draft yet"
+        description="Start a new record from the hub, or pick a template to pre-fill common fields."
+        action={
+          <Button type="button" size="lg">
+            Create record
+          </Button>
+        }
+      />,
+    )
+  }
+
+  if (variant === "sidebar") {
+    return shell(
+      <FocusedWorkflowSidebarSections
+        sections={DEMO_SECTIONS}
+        activeSectionId={activeSection}
+        onSectionSelect={id => {
+          setActiveSection(id)
+          document.getElementById(id)?.scrollIntoView({ behavior: "smooth", block: "start" })
+        }}
+      >
+        <section id="general" className="scroll-mt-20 space-y-4">
+          <header className="space-y-1">
+            <h2 className="text-lg font-semibold text-foreground">General</h2>
+            <p className="text-sm text-muted-foreground">
+              Settings-style section nav — same shell as long preference forms.
+            </p>
+          </header>
+          <div className="space-y-2">
+            <Label htmlFor="fw-name">Display name</Label>
+            <Input id="fw-name" defaultValue="Clinical education workspace" />
+          </div>
+        </section>
+        <section id="notifications" className="scroll-mt-20 space-y-4">
+          <header className="space-y-1">
+            <h2 className="text-lg font-semibold text-foreground">Notifications</h2>
+            <p className="text-sm text-muted-foreground">Email and in-app alerts.</p>
+          </header>
+          <p className="text-sm text-muted-foreground">Wire toggles and checkboxes here.</p>
+        </section>
+        <section id="security" className="scroll-mt-20 space-y-4">
+          <header className="space-y-1">
+            <h2 className="text-lg font-semibold text-foreground">Security</h2>
+            <p className="text-sm text-muted-foreground">Sessions and access.</p>
+          </header>
+          <Button type="button" variant="outline" asChild>
+            <Link href="/settings">Open full settings</Link>
+          </Button>
+        </section>
+      </FocusedWorkflowSidebarSections>,
+      "lg",
+    )
+  }
+
+  return shell(
+    <FocusedWorkflowStepForm
+      steps={DEMO_STEPS}
+      currentIndex={stepIndex}
+      onStepSelect={setStepIndex}
+      footer={
+        <FocusedWorkflowWizardFooter
+          stepIndex={stepIndex}
+          stepCount={DEMO_STEPS.length}
+          onBack={() => setStepIndex(i => Math.max(0, i - 1))}
+          onCancel={() => setStepIndex(0)}
+          onNext={() => setStepIndex(i => Math.min(DEMO_STEPS.length - 1, i + 1))}
+          onSubmit={() => setStepIndex(0)}
+          submitLabel="Create record"
+        />
+      }
+    >
+      <div className="rounded-lg border border-border bg-card p-6">
+        <h2 className="text-base font-semibold text-foreground">
+          {DEMO_STEPS[stepIndex]?.label}
+        </h2>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {DEMO_STEPS[stepIndex]?.description} Replace this panel with your step fields.
+        </p>
+        <div className="mt-6 space-y-2">
+          <Label htmlFor="fw-demo-field">Example field</Label>
+          <Input id="fw-demo-field" placeholder="Required on this step" />
+        </div>
+      </div>
+    </FocusedWorkflowStepForm>,
+    "md",
+  )
+}

package/template/components/list-hub-board-view.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from "react"
+import type { ListHubRecord } from "@/lib/mock/list-hub-directory"
+import { formatDateUS } from "@/lib/date-filter"
+import { BoardCardIconRow, BoardCardTwoLineBlock } from "@/components/data-views/board-card-primitives"
+import {
+  HubRecordCard,
+  ListPageBoardCardBody,
+  ListPageBoardCardHeader,
+  ListPageBoardCardTitleRow,
+} from "@/components/data-views/list-page-board-card"
+import {
+  ListPageBoardTemplate,
+  type ListPageBoardColumnDef,
+} from "@/components/data-views/list-page-board-template"
+
+const CATEGORY_COUNT_BADGE = "bg-muted/90 text-foreground"
+
+function ListHubBoardCard({ row }: { row: ListHubRecord }) {
+  return (
+    <HubRecordCard interactive className="h-full w-full">
+      <ListPageBoardCardHeader>
+        <ListPageBoardCardTitleRow title={row.title} titleClassName="truncate" />
+        <ListPageBoardCardBody>
+          <BoardCardTwoLineBlock
+            iconClass="fa-tag"
+            line1={row.category}
+            line2={formatDateUS(row.eventDate)}
+          />
+          <BoardCardIconRow iconClass="fa-hashtag">
+            <span className="font-mono tabular-nums">{row.id}</span>
+          </BoardCardIconRow>
+        </ListPageBoardCardBody>
+      </ListPageBoardCardHeader>
+    </HubRecordCard>
+  )
+}
+
+function useListHubBoardColumns(rows: ListHubRecord[]) {
+  return React.useMemo(() => {
+    const categories = [...new Set(rows.map(r => r.category))].sort((a, b) => a.localeCompare(b))
+    const columns: ListPageBoardColumnDef<ListHubRecord>[] = categories.map(category => ({
+      id: category,
+      label: category,
+      filter: (r: ListHubRecord) => r.category === category,
+    }))
+    const badgeMap = Object.fromEntries(
+      categories.map(c => [c, CATEGORY_COUNT_BADGE]),
+    )
+    return { columns, badgeMap }
+  }, [rows])
+}
+
+export function ListHubCardGrid({ rows }: { rows: ListHubRecord[] }) {
+  const { columns, badgeMap } = useListHubBoardColumns(rows)
+
+  return (
+    <ListPageBoardTemplate
+      columns={columns}
+      rows={rows}
+      getRowKey={r => r.id}
+      columnCountBadgeClassName={badgeMap}
+      emptyColumnLabel="No records"
+      renderCard={row => <ListHubBoardCard row={row} />}
+    />
+  )
+}