@exxatdesignux/ui 0.2.18 → 0.2.19

package/template/components/templates/focused-workflow-layouts.tsx

@@ -0,0 +1,448 @@
+"use client"
+
+/**
+ * Body layouts for `FocusedWorkflowPageTemplate` — single column, stepped wizard,
+ * sectioned sidebar (settings-style), and empty placeholder.
+ */
+
+import * as React from "react"
+
+import { Button } from "@/components/ui/button"
+import { Kbd, KbdGroup } from "@/components/ui/kbd"
+import { Shortcut } from "@/components/ui/dropdown-menu"
+import { cn } from "@/lib/utils"
+import { useModKeyLabel } from "@/hooks/use-mod-key-label"
+import { useAltKeyLabel } from "@/hooks/use-mod-key-label"
+
+export interface FocusedWorkflowStep {
+  id: string
+  label: string
+  description?: string
+}
+
+export interface FocusedWorkflowSingleColumnProps {
+  children: React.ReactNode
+  className?: string
+}
+
+/** Default body — stack header, form sections, and actions in one column. */
+export function FocusedWorkflowSingleColumn({
+  children,
+  className,
+}: FocusedWorkflowSingleColumnProps) {
+  return <div className={cn("flex min-h-0 flex-1 flex-col gap-6", className)}>{children}</div>
+}
+
+export interface FocusedWorkflowStepIndicatorProps {
+  steps: readonly FocusedWorkflowStep[]
+  currentIndex: number
+  className?: string
+  /** When set, step buttons call this instead of being decorative only. */
+  onStepSelect?: (index: number) => void
+}
+
+export function FocusedWorkflowStepIndicator({
+  steps,
+  currentIndex,
+  className,
+  onStepSelect,
+}: FocusedWorkflowStepIndicatorProps) {
+  const progress =
+    steps.length > 0 ? ((currentIndex + 1) / steps.length) * 100 : 0
+
+  return (
+    <nav
+      className={cn("flex flex-col gap-3", className)}
+      aria-label="Workflow progress"
+    >
+      <div className="flex flex-col gap-1">
+        <p className="text-xs font-medium text-muted-foreground">
+          Step{" "}
+          <span className="tabular-nums text-foreground">{currentIndex + 1}</span>{" "}
+          of <span className="tabular-nums">{steps.length}</span>
+        </p>
+        <div
+          className="h-2 w-full overflow-hidden rounded-full bg-muted"
+          aria-hidden="true"
+        >
+          <div
+            className="h-full rounded-full transition-all duration-300"
+            style={{ width: `${progress}%`, background: "var(--brand-color)" }}
+          />
+        </div>
+      </div>
+      <ol className="flex flex-col gap-2 sm:gap-1.5">
+        {steps.map((step, index) => {
+          const isComplete = index < currentIndex
+          const isCurrent = index === currentIndex
+          const rowClass = cn(
+            "flex w-full items-start gap-3 rounded-lg border px-3 py-2.5 text-left transition-colors",
+            isCurrent
+              ? "border-[var(--brand-color)]/40 bg-muted/50"
+              : "border-border bg-card",
+            onStepSelect && !isCurrent && "hover:bg-muted/30",
+          )
+          const inner = (
+            <>
+              {isComplete ? (
+                <span
+                  className="mt-0.5 inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-emerald-300/70 bg-emerald-50 text-emerald-700 dark:border-emerald-500/40 dark:bg-emerald-500/15 dark:text-emerald-300"
+                  aria-hidden="true"
+                >
+                  <i className="fa-light fa-check text-xs" aria-hidden="true" />
+                </span>
+              ) : (
+                <span
+                  className={cn(
+                    "mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-full border text-xs font-semibold tabular-nums",
+                    isCurrent
+                      ? "border-transparent bg-[var(--brand-color)] text-primary-foreground"
+                      : "border-border bg-background text-muted-foreground",
+                  )}
+                  aria-hidden="true"
+                >
+                  {index + 1}
+                </span>
+              )}
+              <span className="min-w-0 flex-1">
+                <span className="block text-sm font-semibold text-foreground">
+                  {step.label}
+                </span>
+                {step.description && isCurrent ? (
+                  <span className="mt-1 block text-xs leading-snug text-muted-foreground sm:text-sm">
+                    {step.description}
+                  </span>
+                ) : null}
+              </span>
+            </>
+          )
+          return (
+            <li key={step.id} aria-current={isCurrent ? "step" : undefined}>
+              {onStepSelect ? (
+                <button
+                  type="button"
+                  onClick={() => onStepSelect(index)}
+                  className={cn(
+                    rowClass,
+                    "outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+                  )}
+                >
+                  {inner}
+                </button>
+              ) : (
+                <div className={rowClass}>{inner}</div>
+              )}
+            </li>
+          )
+        })}
+      </ol>
+    </nav>
+  )
+}
+
+export interface FocusedWorkflowStepFormProps {
+  steps: readonly FocusedWorkflowStep[]
+  currentIndex: number
+  onStepSelect?: (index: number) => void
+  children: React.ReactNode
+  footer: React.ReactNode
+  className?: string
+}
+
+/** Multi-step wizard body — step list, active panel, sticky action footer. */
+export function FocusedWorkflowStepForm({
+  steps,
+  currentIndex,
+  onStepSelect,
+  children,
+  footer,
+  className,
+}: FocusedWorkflowStepFormProps) {
+  return (
+    <div className={cn("flex min-h-0 flex-1 flex-col gap-8", className)}>
+      <FocusedWorkflowStepIndicator
+        steps={steps}
+        currentIndex={currentIndex}
+        onStepSelect={onStepSelect}
+      />
+      <div className="min-h-0 flex-1">{children}</div>
+      <div className="sticky bottom-0 z-10 -mx-4 border-t border-border bg-background/95 px-4 py-4 backdrop-blur-sm sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8">
+        {footer}
+      </div>
+    </div>
+  )
+}
+
+export interface FocusedWorkflowSidebarSection {
+  id: string
+  label: string
+}
+
+export interface FocusedWorkflowSidebarSectionsProps {
+  sections: readonly FocusedWorkflowSidebarSection[]
+  activeSectionId?: string
+  onSectionSelect?: (id: string) => void
+  /** Full-width block above the nav + content grid (e.g. `PageHeader`). */
+  header?: React.ReactNode
+  children: React.ReactNode
+  className?: string
+  navLabel?: string
+}
+
+/** Grid for settings-style section nav + body (shared with route loading skeleton). */
+export const FOCUSED_WORKFLOW_SIDEBAR_SECTIONS_GRID_CLASS =
+  "lg:grid lg:grid-cols-[minmax(10rem,12rem)_minmax(0,1fr)] lg:gap-x-12 lg:gap-y-8 lg:items-start"
+
+/**
+ * Sectioned form with a **left nav rail** (settings-style). Use `id` on each
+ * `<section>` in `children` matching `sections[].id` for in-page anchors.
+ */
+export function FocusedWorkflowSidebarSections({
+  sections,
+  activeSectionId,
+  onSectionSelect,
+  header,
+  children,
+  className,
+  navLabel = "Sections",
+}: FocusedWorkflowSidebarSectionsProps) {
+  return (
+    <div
+      className={cn(
+        "flex min-h-0 flex-1 flex-col gap-8",
+        FOCUSED_WORKFLOW_SIDEBAR_SECTIONS_GRID_CLASS,
+        className,
+      )}
+    >
+      {header ? <div className="min-w-0 lg:col-span-2">{header}</div> : null}
+      <nav
+        className="flex shrink-0 flex-col gap-0.5 lg:sticky lg:top-6 lg:self-start"
+        aria-label={navLabel}
+      >
+        {sections.map(section => {
+          const isActive = section.id === activeSectionId
+          return (
+            <button
+              key={section.id}
+              type="button"
+              onClick={() => onSectionSelect?.(section.id)}
+              className={cn(
+                "rounded-md py-2 text-left text-sm transition-colors",
+                "outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+                isActive
+                  ? "bg-muted font-medium text-foreground"
+                  : "text-muted-foreground hover:bg-muted/60 hover:text-foreground",
+              )}
+              aria-current={isActive ? "true" : undefined}
+            >
+              {section.label}
+            </button>
+          )
+        })}
+      </nav>
+      <div className="min-w-0 flex-1 flex flex-col gap-16">{children}</div>
+    </div>
+  )
+}
+
+export interface FocusedWorkflowEmptyStateProps {
+  iconClass?: string
+  title: string
+  description?: string
+  action?: React.ReactNode
+  className?: string
+}
+
+export function FocusedWorkflowEmptyState({
+  iconClass = "fa-layer-group",
+  title,
+  description,
+  action,
+  className,
+}: FocusedWorkflowEmptyStateProps) {
+  return (
+    <div
+      className={cn(
+        "flex min-h-[min(24rem,50vh)] flex-col items-center justify-center gap-4 px-4 text-center",
+        className,
+      )}
+      role="status"
+    >
+      <span
+        className="flex size-14 items-center justify-center rounded-xl bg-muted text-muted-foreground"
+        aria-hidden="true"
+      >
+        <i className={cn("fa-light text-xl", iconClass)} aria-hidden="true" />
+      </span>
+      <div className="max-w-md space-y-2">
+        <h2 className="text-lg font-semibold text-foreground">{title}</h2>
+        {description ? (
+          <p className="text-sm text-muted-foreground">{description}</p>
+        ) : null}
+      </div>
+      {action}
+    </div>
+  )
+}
+
+export interface FocusedWorkflowActionFooterProps {
+  onCancel: () => void
+  cancelLabel?: string
+  cancelDisabled?: boolean
+  primary: React.ReactNode
+  secondary?: React.ReactNode
+  className?: string
+}
+
+/** Workflow footer — Cancel (Esc) + primary slot (usually submit with ⏎ Kbd). */
+export function FocusedWorkflowActionFooter({
+  onCancel,
+  cancelLabel = "Cancel",
+  cancelDisabled,
+  primary,
+  secondary,
+  className,
+}: FocusedWorkflowActionFooterProps) {
+  return (
+    <>
+      <Shortcut keys="Escape" disabled={cancelDisabled} onInvoke={onCancel} />
+      <div className={cn("flex flex-wrap items-center gap-2", className)}>
+        <Button
+          type="button"
+          variant="outline"
+          className="flex-1 min-w-[8rem] sm:flex-none"
+          disabled={cancelDisabled}
+          onClick={onCancel}
+        >
+          {cancelLabel}
+          <KbdGroup className="ml-1.5">
+            <Kbd variant="bare">Esc</Kbd>
+          </KbdGroup>
+        </Button>
+        {secondary}
+        <div className="flex flex-1 min-w-[8rem] justify-end sm:flex-none">{primary}</div>
+      </div>
+    </>
+  )
+}
+
+export interface FocusedWorkflowWizardFooterProps {
+  stepIndex: number
+  stepCount: number
+  onBack: () => void
+  onCancel: () => void
+  onNext: () => void
+  onSubmit?: () => void
+  isFirstStep?: boolean
+  isLastStep?: boolean
+  nextLabel?: string
+  submitLabel?: string
+  cancelLabel?: string
+  disabled?: boolean
+  submitting?: boolean
+}
+
+/** Step wizard footer — Back (⌘⌥←), Cancel (Esc), Next (⌘⏎) or Submit (⏎). */
+export function FocusedWorkflowWizardFooter({
+  stepIndex,
+  stepCount,
+  onBack,
+  onCancel,
+  onNext,
+  onSubmit,
+  isFirstStep,
+  isLastStep,
+  nextLabel = "Next",
+  submitLabel = "Submit",
+  cancelLabel = "Cancel",
+  disabled,
+  submitting,
+}: FocusedWorkflowWizardFooterProps) {
+  const mod = useModKeyLabel()
+  const alt = useAltKeyLabel()
+  const first = isFirstStep ?? stepIndex === 0
+  const last = isLastStep ?? stepIndex >= stepCount - 1
+
+  return (
+    <>
+      <Shortcut keys="Escape" disabled={disabled || submitting} onInvoke={onCancel} />
+      {!first ? (
+        <Shortcut
+          keys={`${mod}${alt}←`}
+          disabled={disabled || submitting}
+          onInvoke={onBack}
+        />
+      ) : null}
+      {last ? (
+        <Shortcut keys="Enter" disabled={disabled || submitting} onInvoke={() => onSubmit?.()} />
+      ) : (
+        <Shortcut keys={`${mod}Enter`} disabled={disabled || submitting} onInvoke={onNext} />
+      )}
+      <div className="flex flex-wrap items-center gap-2">
+        <Button
+          type="button"
+          variant="outline"
+          disabled={disabled || submitting}
+          onClick={onCancel}
+        >
+          {cancelLabel}
+          <KbdGroup className="ml-1.5">
+            <Kbd variant="bare">Esc</Kbd>
+          </KbdGroup>
+        </Button>
+        {!first ? (
+          <Button
+            type="button"
+            variant="outline"
+            disabled={disabled || submitting}
+            onClick={onBack}
+          >
+            Back
+            <KbdGroup className="ml-1.5">
+              <Kbd variant="bare">
+                {mod}
+                {alt}←
+              </Kbd>
+            </KbdGroup>
+          </Button>
+        ) : null}
+        <div className="ms-auto flex flex-1 min-w-[8rem] justify-end sm:flex-none">
+          {last ? (
+            <Button
+              type="button"
+              disabled={disabled || submitting}
+              aria-busy={submitting}
+              onClick={() => onSubmit?.()}
+            >
+              {submitting ? (
+                <>
+                  <i
+                    className="fa-light fa-spinner-third fa-spin text-[13px]"
+                    aria-hidden="true"
+                  />
+                  Saving…
+                </>
+              ) : (
+                <>
+                  {submitLabel}
+                  <KbdGroup className="ml-1.5">
+                    <Kbd variant="bare">⏎</Kbd>
+                  </KbdGroup>
+                </>
+              )}
+            </Button>
+          ) : (
+            <Button type="button" disabled={disabled || submitting} onClick={onNext}>
+              {nextLabel}
+              <KbdGroup className="ml-1.5">
+                <Kbd variant="bare">
+                  {mod}⏎
+                </Kbd>
+              </KbdGroup>
+            </Button>
+          )}
+        </div>
+      </div>
+    </>
+  )
+}

package/template/components/templates/focused-workflow-page-template.tsx

@@ -0,0 +1,69 @@
+import * as React from "react"
+
+import { SiteHeader, type SiteHeaderProps } from "@/components/site-header"
+import { SidebarInset } from "@/components/ui/sidebar"
+import { cn } from "@/lib/utils"
+
+/** Default horizontal padding for focused workflow routes (forms, wizards, authoring). */
+export const FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS =
+  "px-4 pt-6 pb-32 sm:px-6 lg:px-8"
+
+/** Max-width presets — narrower than primary list hubs (`max-w-[1440px]`). */
+export const FOCUSED_WORKFLOW_MAX_WIDTH = {
+  md: "max-w-3xl",
+  lg: "max-w-4xl",
+  xl: "max-w-5xl",
+} as const
+
+export type FocusedWorkflowMaxWidth = keyof typeof FOCUSED_WORKFLOW_MAX_WIDTH
+
+export interface FocusedWorkflowPageTemplateProps {
+  /** e.g. `SidebarAutoCollapse` on long-form routes. */
+  beforeSiteHeader?: React.ReactNode
+  /** Breadcrumb back link + title; parent context stays in `SiteHeader`. */
+  siteHeader: SiteHeaderProps
+  children: React.ReactNode
+  maxWidth?: FocusedWorkflowMaxWidth
+  /** Merged with default content padding. */
+  contentClassName?: string
+  bodyClassName?: string
+}
+
+/**
+ * Dedicated-route shell for **large or multi-step work** — create/edit flows, wizards,
+ * and sectioned settings. **Not** for list hubs (use `PrimaryPageTemplate`) and **not**
+ * for Miller-column / split-panel explorers (use `ListPageSplitHubChrome`).
+ *
+ * Pair body layouts with `FocusedWorkflowSingleColumn`, `FocusedWorkflowStepForm`,
+ * `FocusedWorkflowSidebarSections`, or `FocusedWorkflowEmptyState`.
+ *
+ * @see `docs/focused-workflow-page-pattern.md`
+ */
+export function FocusedWorkflowPageTemplate({
+  beforeSiteHeader,
+  siteHeader,
+  children,
+  maxWidth = "md",
+  contentClassName,
+  bodyClassName,
+}: FocusedWorkflowPageTemplateProps) {
+  return (
+    <SidebarInset id="main-content" tabIndex={-1}>
+      {beforeSiteHeader}
+      <SiteHeader {...siteHeader} />
+      <div className={cn("flex min-h-0 flex-1 flex-col outline-none", bodyClassName)}>
+        <div
+          className={cn(
+            "@container/main mx-auto flex min-h-0 w-full min-w-0 flex-1 flex-col",
+            FOCUSED_WORKFLOW_MAX_WIDTH[maxWidth],
+            FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS,
+            contentClassName,
+          )}
+        >
+          {children}
+        </div>
+      </div>
+    </SidebarInset>
+  )
+}
+

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

@@ -47,6 +47,10 @@ import {
   Shortcut,
 } from "@/components/ui/dropdown-menu"
 import type { DataListViewType } from "@/lib/data-list-view"
+import {
+  dataListViewTilesForHub,
+  showsListPageHubMetricsStrip,
+} from "@/lib/data-list-view-registry"
 import { DATA_LIST_VIEW_TILES, dataListViewAddShortcut } from "@/lib/data-list-view"
 import {
   createListPageEditViewHandler,
@@ -126,6 +130,11 @@ export interface ListPageTemplateProps {
   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
+  /**
+   * View types this hub can render. Limits **Add view** and documents intent; table components
+   * should still implement each kind via `ListPageConnectedViewBody`. Defaults to all registry views.
+   */
+  supportedViewTypes?: readonly DataListViewType[]
 }
 
 /** Collision-proof id for a dynamically-added tab. Module-level counters reset
@@ -180,6 +189,7 @@ export function ListPageTemplate({
   onEditView,
   tablePropertiesRef,
   hideViewsToolbar = false,
+  supportedViewTypes,
 }: ListPageTemplateProps) {
   const controlled =
     tabsProp !== undefined &&
@@ -212,6 +222,20 @@ export function ListPageTemplate({
 
   const activeTab = tabs.find(t => t.id === activeTabId) ?? tabs[0]
 
+  const addableViewTypes = React.useMemo(
+    () =>
+      supportedViewTypes != null
+        ? dataListViewTilesForHub(supportedViewTypes)
+        : VIEW_TYPES,
+    [supportedViewTypes],
+  )
+
+  const metricsVisible =
+    showMetrics
+    && metrics != null
+    && activeTab != null
+    && showsListPageHubMetricsStrip(activeTab.viewType)
+
   const editViewFromRef = React.useMemo(
     () => (tablePropertiesRef ? createListPageEditViewHandler(tablePropertiesRef) : undefined),
     [tablePropertiesRef]
@@ -272,8 +296,8 @@ export function ListPageTemplate({
   }
 
   return (
-    <>
-      {!hideViewsToolbar && VIEW_TYPES.slice(0, 9).map((v, i) => {
+    <div className="flex min-h-0 w-full min-w-0 flex-1 flex-col">
+      {!hideViewsToolbar && addableViewTypes.slice(0, 9).map((v, i) => {
         const keys = dataListViewAddShortcut(i)
         return keys ? (
           <Shortcut
@@ -302,7 +326,7 @@ export function ListPageTemplate({
       )}
       {header}
 
-      {showMetrics && metrics}
+      {metricsVisible ? metrics : null}
 
       {/* ── Views toolbar (not tablist: settings/close are not tabs — WCAG 1.3.1 / ARIA) ── */}
       {!hideViewsToolbar && (
@@ -480,7 +504,7 @@ export function ListPageTemplate({
             <DropdownMenuContent align="start">
               <DropdownMenuLabel className="text-xs">Add a view</DropdownMenuLabel>
               <DropdownMenuSeparator />
-              {VIEW_TYPES.map((v, i) => (
+              {addableViewTypes.map((v, i) => (
                 <DropdownMenuItem
                   key={v.type}
                   shortcut={dataListViewAddShortcut(i)}
@@ -579,6 +603,6 @@ export function ListPageTemplate({
           </DialogFooter>
         </DialogContent>
       </Dialog>
-    </>
+    </div>
   )
 }

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

@@ -27,6 +27,7 @@ export function NestedSecondaryPanelShell({
   return (
     <nav
       aria-label={ariaLabel}
+      data-slot="secondary-panel"
       data-state={open ? "open" : "closed"}
       data-layout={open ? (compact ? "icon" : "expanded") : "closed"}
       className={cn(
@@ -40,7 +41,7 @@ export function NestedSecondaryPanelShell({
               // 2rem on mobile where the panel scrolls inline and we leave
               // a little more breathing room). No upper cap so tall screens
               // get a fully-extended rail.
-              "shrink-0 m-2 mx-2 rounded-xl ring-1 ring-sidebar-border shadow-sm relative md:sticky md:top-2 bg-[var(--secondary-panel-bg)]",
+              "shrink-0 m-2 mx-2 rounded-xl border border-sidebar-border bg-secondary-panel-bg shadow-sm relative md:sticky md:top-2",
               compact
                 ? "w-12 min-w-12 max-w-12 h-[calc(100svh-2rem)] md:h-[calc(100svh-1rem)]"
                 : "w-64 min-w-64 max-w-64 h-[calc(100svh-2rem)] md:h-[calc(100svh-1rem)]",