@exxatdesignux/ui 0.2.19 → 0.4.0

package/src/components/ui/export-drawer.tsx

@@ -0,0 +1,375 @@
+"use client"
+
+/**
+ * ExportDrawer — floating right-side drawer with export form.
+ *
+ * Uses the same Sheet pattern as TablePropertiesDrawer:
+ *  - showCloseButton={false}, showOverlay={false}
+ *  - Rounded, floating, inset from viewport edges
+ *  - Button + Tip from our own component library
+ *
+ * Form fields (shadcn Form + react-hook-form + zod):
+ *   • File format  CSV · Excel · PDF  (SelectionTileGrid radio)
+ *   • Date range   From / To          (FilterTextValueInput dateMDY — same as Settings / table filters)
+ *   • Columns      All · Visible only (radio)
+ *   • Apply active filters            (checkbox)
+ *
+ * WCAG 2.1 AA:
+ *   ✓ All inputs labelled via FormLabel linked to control id (1.3.1)
+ *   ✓ Error messages linked via aria-describedby (3.3.1)
+ *   ✓ Focus returns to trigger on close (2.4.3)
+ */
+
+import * as React from "react"
+import { useForm } from "react-hook-form"
+import { z } from "zod"
+import { zodResolver } from "@hookform/resolvers/zod"
+
+import { devLog } from "../../lib/dev-log"
+import { Button }   from "./button"
+import { Checkbox } from "./checkbox"
+import { Label } from "./label"
+import { Tip }      from "./tip"
+import { Kbd, KbdGroup } from "./kbd"
+import { Shortcut } from "./dropdown-menu"
+import { RadioGroup, RadioGroupItem, RadioGroupLabel } from "./radio-group"
+import { SelectionTileGrid } from "./selection-tile-grid"
+import { FilterTextValueInput } from "../data-table/filter-text-value-input"
+import type { SelectionTileOption } from "./selection-tile-grid"
+import {
+  Sheet,
+  SheetContent,
+  SheetTitle,
+} from "./sheet"
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "./form"
+
+/** Parse full MM/DD/YYYY from masked input; partial/invalid → undefined. */
+function parseMdyToDate(raw: string | undefined): Date | undefined {
+  if (!raw?.trim()) return undefined
+  const m = raw.trim().match(/^(\d{2})\/(\d{2})\/(\d{4})$/)
+  if (!m) return undefined
+  const month = Number(m[1])
+  const day = Number(m[2])
+  const year = Number(m[3])
+  if (month < 1 || month > 12 || day < 1 || day > 31) return undefined
+  const d = new Date(year, month - 1, day, 12, 0, 0, 0)
+  if (d.getFullYear() !== year || d.getMonth() !== month - 1 || d.getDate() !== day) return undefined
+  return d
+}
+
+// ── Validation schema ─────────────────────────────────────────────────────────
+
+const EXPORT_FORMAT_OPTIONS: SelectionTileOption<"csv" | "excel" | "pdf">[] = [
+  { value: "csv",   label: "CSV",   icon: "fa-file-csv" },
+  { value: "excel", label: "Excel", icon: "fa-file-excel" },
+  { value: "pdf",   label: "PDF",   icon: "fa-file-pdf" },
+]
+
+const exportSchema = z
+  .object({
+    format:         z.enum(["csv", "excel", "pdf"]),
+    columns:        z.enum(["all", "visible"]),
+    dateFrom:       z.string().optional(),
+    dateTo:         z.string().optional(),
+    includeFilters: z.boolean(),
+  })
+  .superRefine((data, ctx) => {
+    const from = parseMdyToDate(data.dateFrom)
+    const to = parseMdyToDate(data.dateTo)
+    if (data.dateFrom?.trim() && !from) {
+      ctx.addIssue({ code: "custom", message: "Enter a valid from date", path: ["dateFrom"] })
+    }
+    if (data.dateTo?.trim() && !to) {
+      ctx.addIssue({ code: "custom", message: "Enter a valid to date", path: ["dateTo"] })
+    }
+    if (from && to && to < from) {
+      ctx.addIssue({ code: "custom", message: "End date must be after start date", path: ["dateTo"] })
+    }
+  })
+
+type ExportForm = z.infer<typeof exportSchema>
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+export interface ExportDrawerProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  totalRows?: number
+  visibleColumns?: number
+}
+
+export function ExportDrawer({
+  open,
+  onOpenChange,
+  totalRows = 0,
+  visibleColumns,
+}: ExportDrawerProps) {
+  const form = useForm<ExportForm>({
+    resolver: zodResolver(exportSchema),
+    defaultValues: {
+      format:         "csv",
+      columns:        "visible",
+      dateFrom:       "",
+      dateTo:         "",
+      includeFilters: true,
+    },
+  })
+
+  const [isExporting, setIsExporting] = React.useState(false)
+
+  async function onSubmit(values: ExportForm) {
+    setIsExporting(true)
+    await new Promise(r => setTimeout(r, 1200))
+    devLog("Export:", {
+      ...values,
+      dateFrom: parseMdyToDate(values.dateFrom)?.toISOString(),
+      dateTo:   parseMdyToDate(values.dateTo)?.toISOString(),
+    })
+    setIsExporting(false)
+    onOpenChange(false)
+    form.reset()
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        data-slot="export-drawer"
+        side="right"
+        showCloseButton={false}
+        showOverlay={false}
+        className="z-[80] w-80 sm:max-w-80 p-0 gap-0 flex flex-col border border-border shadow-xl rounded-xl overflow-hidden"
+        style={{ top: "0.5rem", bottom: "0.5rem", right: "0.5rem", height: "calc(100vh - 1rem)" }}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between gap-3 px-4 pt-5 pb-3">
+          <SheetTitle className="text-base font-semibold leading-tight">Export data</SheetTitle>
+          <Tip label="Close" side="bottom">
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-sm"
+              aria-label="Close"
+              onClick={() => onOpenChange(false)}
+            >
+              <i className="fa-light fa-xmark text-[13px]" aria-hidden="true" />
+            </Button>
+          </Tip>
+        </div>
+
+        {/* Record count */}
+        <p className="px-4 pb-3 text-sm text-muted-foreground -mt-1">
+          {totalRows} record{totalRows !== 1 ? "s" : ""} available for export.
+        </p>
+
+        {/* Form body */}
+        <Form {...form}>
+          <form
+            id="export-form"
+            onSubmit={form.handleSubmit(onSubmit)}
+            className="flex-1 overflow-y-auto"
+          >
+            <div className="px-4 pb-4 space-y-5">
+
+              {/* File format */}
+              <FormField
+                control={form.control}
+                name="format"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormControl>
+                      <SelectionTileGrid
+                        sectionLabel="File format"
+                        options={EXPORT_FORMAT_OPTIONS}
+                        columns={3}
+                        value={field.value}
+                        onValueChange={field.onChange}
+                        interaction="radio"
+                        idPrefix="export-fmt"
+                        itemVariant="outline"
+                        itemMotion="pop"
+                      />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+              {/* Date range */}
+              <fieldset className="space-y-2">
+                <legend className="text-sm font-medium leading-none mb-2">
+                  Date range{" "}
+                  <span className="text-muted-foreground font-normal">(optional)</span>
+                </legend>
+                <div className="grid grid-cols-2 gap-3">
+                  <FormField
+                    control={form.control}
+                    name="dateFrom"
+                    render={({ field }) => (
+                      <FormItem className="gap-1">
+                        <FormLabel htmlFor="export-date-from" className="text-xs text-muted-foreground">
+                          From
+                        </FormLabel>
+                        <FormControl>
+                          <FilterTextValueInput
+                            id="export-date-from"
+                            mask="dateMDY"
+                            aria-label="Export from date (optional)"
+                            placeholder="MM/DD/YYYY"
+                            value={field.value ?? ""}
+                            onValueChange={field.onChange}
+                            className="h-8 text-sm"
+                          />
+                        </FormControl>
+                        <FormDescription className="text-[11px]">MM/DD/YYYY</FormDescription>
+                        <FormMessage />
+                      </FormItem>
+                    )}
+                  />
+                  <FormField
+                    control={form.control}
+                    name="dateTo"
+                    render={({ field }) => (
+                      <FormItem className="gap-1">
+                        <FormLabel htmlFor="export-date-to" className="text-xs text-muted-foreground">
+                          To
+                        </FormLabel>
+                        <FormControl>
+                          <FilterTextValueInput
+                            id="export-date-to"
+                            mask="dateMDY"
+                            aria-label="Export to date (optional)"
+                            placeholder="MM/DD/YYYY"
+                            value={field.value ?? ""}
+                            onValueChange={field.onChange}
+                            className="h-8 text-sm"
+                          />
+                        </FormControl>
+                        <FormDescription className="text-[11px]">MM/DD/YYYY</FormDescription>
+                        <FormMessage />
+                      </FormItem>
+                    )}
+                  />
+                </div>
+              </fieldset>
+
+              {/* Columns */}
+              <FormField
+                control={form.control}
+                name="columns"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel className="text-sm font-medium">Columns</FormLabel>
+                    <FormControl>
+                      <RadioGroup
+                        value={field.value}
+                        onValueChange={field.onChange}
+                        className="space-y-1.5 mt-1"
+                        itemVariant="outline"
+                        itemMotion="pop"
+                      >
+                        {([
+                          { value: "all",     label: "All columns",          sub: null },
+                          { value: "visible", label: "Visible columns only", sub: visibleColumns !== undefined ? `${visibleColumns} columns` : null },
+                        ] as const).map(opt => (
+                          <div
+                            key={opt.value}
+                            className="flex items-center gap-2.5 rounded-lg border border-border px-3 py-2.5 transition-colors hover:bg-interactive-hover has-[[data-state=checked]]:border-brand has-[[data-state=checked]]:bg-brand/10 cursor-pointer"
+                          >
+                            <RadioGroupItem value={opt.value} id={`col-${opt.value}`} />
+                            <RadioGroupLabel
+                              htmlFor={`col-${opt.value}`}
+                              className="min-h-0 flex-1 cursor-pointer py-0 text-sm font-normal leading-none"
+                            >
+                              {opt.label}
+                              {opt.sub && (
+                                <span className="text-muted-foreground ms-1.5 font-normal">({opt.sub})</span>
+                              )}
+                            </RadioGroupLabel>
+                          </div>
+                        ))}
+                      </RadioGroup>
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+              {/* Include filters */}
+              <FormField
+                control={form.control}
+                name="includeFilters"
+                render={({ field }) => (
+                  <FormItem>
+                    <div className="flex items-start gap-3 rounded-lg border border-border px-3 py-2.5 transition-colors hover:bg-interactive-hover has-[[data-state=checked]]:border-primary">
+                      <FormControl>
+                        <Checkbox
+                          id="include-filters"
+                          checked={field.value}
+                          onCheckedChange={field.onChange}
+                          className="mt-0.5 shrink-0"
+                        />
+                      </FormControl>
+                      <div className="min-w-0">
+                        <Label htmlFor="include-filters" className="text-sm cursor-pointer font-medium leading-none">
+                          Apply active filters
+                        </Label>
+                        <p className="text-xs text-muted-foreground mt-1">
+                          Export only rows matching current filters
+                        </p>
+                      </div>
+                    </div>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+            </div>
+          </form>
+        </Form>
+
+        {/* Global bindings — only active while the drawer is open (Sheet unmounts content on close) */}
+        <Shortcut keys="Enter" disabled={isExporting} onInvoke={() => form.handleSubmit(onSubmit)()} />
+
+        {/* Footer */}
+        <div className="flex items-center gap-2 px-4 py-3 border-t border-border">
+          <Button
+            type="button"
+            variant="outline"
+            className="flex-1"
+            onClick={() => onOpenChange(false)}
+          >
+            Cancel
+            <KbdGroup className="ms-1.5"><Kbd variant="bare">Esc</Kbd></KbdGroup>
+          </Button>
+          <Button
+            type="submit"
+            form="export-form"
+            className="flex-1"
+            disabled={isExporting}
+          >
+            {isExporting ? (
+              <>
+                <i className="fa-light fa-spinner-third fa-spin text-[13px]" aria-hidden="true" />
+                Exporting…
+              </>
+            ) : (
+              <>
+                <i className="fa-light fa-arrow-down-to-line text-[13px]" aria-hidden="true" />
+                Export
+                <KbdGroup className="ms-1.5"><Kbd variant="bare">⏎</Kbd></KbdGroup>
+              </>
+            )}
+          </Button>
+        </div>
+      </SheetContent>
+    </Sheet>
+  )
+}

package/src/components/ui/hover-card.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+/**
+ * HoverCard — richer, persistent hover surface for content too large or
+ * interactive for a `Tooltip` (avatars, link previews, user cards, glossary
+ * entries).
+ *
+ * When to choose `HoverCard` vs `Tooltip` vs `Popover`:
+ *  - **`Tooltip`** — short text label, no interaction, auto-dismiss on
+ *    mouseout / blur. Pairs with `Tip` for icon-only buttons.
+ *  - **`HoverCard`** — small interactive content (links, copy buttons,
+ *    avatars) shown on intentional hover; closes when the pointer leaves.
+ *    Not focusable / not announced by screen readers — pair with an
+ *    accessible alternative for keyboard users (visit profile link, etc.).
+ *  - **`Popover`** — keyboard- and screen-reader-accessible, opens on
+ *    explicit click. Use this when the surface holds primary content.
+ *
+ * Accessibility (per Radix):
+ *  - HoverCard is NOT exposed to screen readers — Radix intentionally
+ *    treats it as a sighted-mouse-user affordance. The trigger MUST also
+ *    convey its meaning through its own accessible name and behaviour
+ *    (e.g. a focusable `<a>` that links to the same content).
+ */
+
+import * as React from "react"
+import { HoverCard as HoverCardPrimitive } from "radix-ui"
+
+import { cn } from "../../lib/utils"
+
+function HoverCard({
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
+  return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />
+}
+
+function HoverCardTrigger({
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+  return (
+    <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+  )
+}
+
+function HoverCardContent({
+  className,
+  align = "center",
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
+  return (
+    <HoverCardPrimitive.Portal data-slot="hover-card-portal">
+      <HoverCardPrimitive.Content
+        data-slot="hover-card-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-lg bg-popover p-4 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className,
+        )}
+        {...props}
+      />
+    </HoverCardPrimitive.Portal>
+  )
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }

package/src/components/ui/key-metrics-context.tsx

@@ -0,0 +1,78 @@
+"use client"
+
+/**
+ * KeyMetricsProvider — host-app injection point for the design-system
+ * `KeyMetrics` component.
+ *
+ * `KeyMetrics` itself ships as a pure primitive: it knows how to render
+ * a KPI strip, an insight rail, and a default insight CTA, but it does
+ * NOT know anything about the host app's AI assistant, command palette,
+ * or keyboard-shortcut registry.
+ *
+ * Consumers (e.g. `apps/web`) mount a `KeyMetricsProvider` near the root
+ * of the app and supply two optional injection points:
+ *
+ *  - `defaultInsightAction` — fired when the user clicks the default
+ *    "Ask Leo about these metrics" button in the card-variant header,
+ *    and the default insight CTA when an individual `MetricInsight` did
+ *    not supply its own `onAction`. When omitted, the default button is
+ *    hidden entirely so the primitive stays useful in apps without an
+ *    AI assistant.
+ *
+ *  - `shortcutHint` — inline React node rendered inside the tooltip
+ *    alongside the action label (typically a keyboard chord such as
+ *    `<Kbd>⌘⌥K</Kbd>`). When omitted, the tooltip simply shows the
+ *    label.
+ *
+ *  - `defaultActionLabel` — visible label + accessible name for the
+ *    default action button. Defaults to "Ask Leo" so the existing
+ *    Exxat-DS layout reads identically without any consumer changes.
+ *
+ * This is the SAME injection shape used by Adobe Spectrum
+ * (`Provider`-based service injection) and Material UI (`Theme`
+ * context). It lets the design-system package ship product patterns
+ * without taking on a hard dependency on the host app's AI surface.
+ */
+
+import * as React from "react"
+
+export interface KeyMetricsContextValue {
+  /** Click handler for the default "Ask Leo about these metrics" CTA. */
+  defaultInsightAction?: () => void
+  /** Inline kbd chord (or any node) rendered next to the action label inside the tooltip. */
+  shortcutHint?: React.ReactNode
+  /** Label + aria-label for the default insight action button. Defaults to "Ask Leo". */
+  defaultActionLabel?: string
+}
+
+const KeyMetricsContext = React.createContext<KeyMetricsContextValue>({})
+
+/** Read the active `KeyMetricsProvider` value. Returns an empty object if no provider is mounted. */
+export function useKeyMetricsContext(): KeyMetricsContextValue {
+  return React.useContext(KeyMetricsContext)
+}
+
+export function KeyMetricsProvider({
+  value,
+  children,
+}: {
+  value: KeyMetricsContextValue
+  children: React.ReactNode
+}) {
+  // Memoize the wrapper so consumers passing fresh object identities
+  // (common in client components) do not invalidate every descendant
+  // that reads the context.
+  const memo = React.useMemo<KeyMetricsContextValue>(
+    () => ({
+      defaultInsightAction: value.defaultInsightAction,
+      shortcutHint: value.shortcutHint,
+      defaultActionLabel: value.defaultActionLabel,
+    }),
+    [value.defaultInsightAction, value.shortcutHint, value.defaultActionLabel],
+  )
+  return (
+    <KeyMetricsContext.Provider value={memo}>
+      {children}
+    </KeyMetricsContext.Provider>
+  )
+}