@zedtech/zedkit-ui 0.1.1 → 0.3.0

package/src/card-skeleton.tsx

@@ -0,0 +1,31 @@
+import { Skeleton } from "./skeleton.js";
+import { cn } from "./utils.js";
+
+export interface CardSkeletonProps {
+  label?: string;
+  className?: string;
+}
+
+/**
+ * Faithful loading shape of Card: header block plus three text lines
+ * in the same bordered box, so content lands without shifting.
+ */
+export function CardSkeleton({ label = "Loading", className }: CardSkeletonProps) {
+  return (
+    <div
+      role="status"
+      aria-label={label}
+      className={cn("rounded-xl border bg-card p-6 shadow", className)}
+    >
+      <div className="space-y-1.5">
+        <Skeleton className="h-5 w-1/3" />
+        <Skeleton className="h-4 w-2/3" />
+      </div>
+      <div className="mt-4 space-y-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-4/5" />
+      </div>
+    </div>
+  );
+}

package/src/card.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (card) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 import * as React from "react";
 
 import { cn } from "./utils.js";

package/src/checkbox.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (checkbox) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";

package/src/checkmark.tsx

@@ -0,0 +1,34 @@
+import { cn } from "./utils.js";
+
+export interface CheckmarkProps {
+  /** Accessible name; omitted means decorative (pair with visible text). */
+  label?: string;
+  className?: string;
+}
+
+/**
+ * Success check that draws itself once (static full check under
+ * reduced motion — see `zk-check-draw` in styles.css).
+ */
+export function Checkmark({ label, className }: CheckmarkProps) {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      {...(label === undefined
+        ? { "aria-hidden": true as const }
+        : { role: "img" as const, "aria-label": label })}
+      className={cn("size-4 text-success", className)}
+    >
+      <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="1.5" />
+      <path
+        d="M5.5 8.2 7.2 9.9 10.6 6.3"
+        stroke="currentColor"
+        strokeWidth="1.8"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="[stroke-dasharray:8] motion-safe:animate-[zk-check-draw_0.45s_ease-out_forwards]"
+      />
+    </svg>
+  );
+}

package/src/data-table-skeleton.tsx

@@ -0,0 +1,53 @@
+import { Skeleton } from "./skeleton.js";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "./table.js";
+import { cn } from "./utils.js";
+
+export interface DataTableSkeletonProps {
+  label?: string;
+  columns?: number;
+  rows?: number;
+  filter?: boolean;
+  className?: string;
+}
+
+/**
+ * Standalone loading shape of DataTable for Suspense fallbacks: filter
+ * slot plus a headed table of skeleton rows. (DataTable's own inline
+ * loading state stays untouched inside the table body.)
+ */
+export function DataTableSkeleton({
+  label = "Loading",
+  columns = 4,
+  rows = 3,
+  filter = true,
+  className,
+}: DataTableSkeletonProps) {
+  return (
+    <div role="status" aria-label={label} className={cn("space-y-4", className)}>
+      {filter ? <Skeleton className="h-9 max-w-sm" /> : null}
+      {/* Decorative shape only — the zone label above carries the meaning. */}
+      <Table aria-hidden>
+        <TableHeader>
+          <TableRow>
+            {Array.from({ length: columns }, (_, index) => (
+              <TableHead key={index}>
+                <Skeleton className="h-4 w-2/3" />
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {Array.from({ length: rows }, (_, row) => (
+            <TableRow key={row}>
+              {Array.from({ length: columns }, (_, column) => (
+                <TableCell key={column}>
+                  <Skeleton className="h-4 w-full" />
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

package/src/detail-panel-skeleton.tsx

@@ -0,0 +1,29 @@
+import { Skeleton } from "./skeleton.js";
+import { cn } from "./utils.js";
+
+export interface DetailPanelSkeletonProps {
+  label?: string;
+  rows?: number;
+  className?: string;
+}
+
+/**
+ * Faithful loading shape of DetailPanel: label/value skeleton pairs
+ * in the same divided box, so rows land without shifting.
+ */
+export function DetailPanelSkeleton({ label = "Loading", rows = 4, className }: DetailPanelSkeletonProps) {
+  return (
+    <div
+      role="status"
+      aria-label={label}
+      className={cn("divide-y divide-border rounded-lg border", className)}
+    >
+      {Array.from({ length: rows }, (_, index) => (
+        <div key={index} className="grid grid-cols-3 gap-4 px-4 py-3">
+          <Skeleton className="h-4 w-20" />
+          <Skeleton className="col-span-2 h-4 w-2/3" />
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/dialog.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (dialog) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";
@@ -16,7 +17,12 @@ const DialogOverlay = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <DialogPrimitive.Overlay
     ref={ref}
-    className={cn("fixed inset-0 z-50 bg-overlay/80", className)}
+    className={cn(
+      "fixed inset-0 z-50 bg-overlay/80",
+      "motion-safe:data-[state=open]:animate-[zk-fade-in_var(--motion-base)_var(--ease-enter)]",
+      "motion-safe:data-[state=closed]:animate-[zk-fade-out_var(--motion-base)_var(--ease-exit)]",
+      className,
+    )}
     {...props}
   />
 ));
@@ -32,6 +38,8 @@ const DialogContent = React.forwardRef<
       ref={ref}
       className={cn(
         "fixed top-[50%] left-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg sm:rounded-lg",
+        "motion-safe:data-[state=open]:animate-[zk-zoom-in_var(--motion-base)_var(--ease-enter)]",
+        "motion-safe:data-[state=closed]:animate-[zk-zoom-out_var(--motion-base)_var(--ease-exit)]",
         className,
       )}
       {...props}

package/src/drawer.tsx

@@ -0,0 +1,140 @@
+// Derived from shadcn/ui (drawer) — see Provenance in packages/ui/README.md. Adapted: direction-aware
+// positioning via data variants (vaul sets data-vaul-drawer-direction on the content), drag handle and
+// close left to the consumer to compose, ref-as-prop (React 19). Vaul injects its own base CSS
+// (drag transitions, open/close keyframes) at import; the kit adds no drawer CSS.
+"use client";
+
+import * as React from "react";
+import { Drawer as DrawerPrimitive } from "vaul";
+import { cn } from "./utils.js";
+
+const Drawer = DrawerPrimitive.Root;
+const DrawerTrigger = DrawerPrimitive.Trigger;
+const DrawerClose = DrawerPrimitive.Close;
+const DrawerPortal = DrawerPrimitive.Portal;
+
+function DrawerOverlay({
+  className,
+  ref,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Overlay> & {
+  ref?: React.Ref<HTMLDivElement>;
+}) {
+  return (
+    <DrawerPrimitive.Overlay
+      ref={ref}
+      className={cn("fixed inset-0 z-50 bg-overlay/80", className)}
+      {...props}
+    />
+  );
+}
+
+function DrawerContent({
+  className,
+  children,
+  ref,
+  modal = true,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content> & {
+  ref?: React.Ref<HTMLDivElement>;
+  /**
+   * Mirror of the `Drawer` root `modal` prop: `false` renders no
+   * overlay so the background stays interactive. Defaults to `true`.
+   */
+  modal?: boolean;
+}) {
+  return (
+    <DrawerPortal>
+      {modal ? <DrawerOverlay /> : null}
+      <DrawerPrimitive.Content
+        ref={ref}
+        className={cn(
+          "fixed z-50 flex flex-col border bg-background",
+          "data-[vaul-drawer-direction=bottom]:inset-x-0 data-[vaul-drawer-direction=bottom]:bottom-0 data-[vaul-drawer-direction=bottom]:max-h-[96dvh] data-[vaul-drawer-direction=bottom]:rounded-t-xl",
+          "data-[vaul-drawer-direction=top]:inset-x-0 data-[vaul-drawer-direction=top]:top-0 data-[vaul-drawer-direction=top]:max-h-[96dvh] data-[vaul-drawer-direction=top]:rounded-b-xl",
+          "data-[vaul-drawer-direction=right]:inset-y-0 data-[vaul-drawer-direction=right]:right-0 data-[vaul-drawer-direction=right]:w-full data-[vaul-drawer-direction=right]:sm:max-w-md",
+          "data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-full data-[vaul-drawer-direction=left]:sm:max-w-md",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </DrawerPrimitive.Content>
+    </DrawerPortal>
+  );
+}
+
+function DrawerHandle({
+  className,
+  ref,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Handle> & {
+  ref?: React.Ref<HTMLDivElement>;
+}) {
+  return (
+    <DrawerPrimitive.Handle
+      ref={ref}
+      className={cn("mx-auto mt-4 h-1.5 w-12 shrink-0 rounded-full bg-muted", className)}
+      {...props}
+    />
+  );
+}
+
+function DrawerHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("flex flex-col gap-1.5 p-4 text-center sm:text-left", className)}
+      {...props}
+    />
+  );
+}
+
+function DrawerFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("mt-auto flex flex-col gap-2 p-4", className)} {...props} />;
+}
+
+function DrawerTitle({
+  className,
+  ref,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Title> & {
+  ref?: React.Ref<HTMLHeadingElement>;
+}) {
+  return (
+    <DrawerPrimitive.Title
+      ref={ref}
+      className={cn("text-lg leading-none font-semibold tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+
+function DrawerDescription({
+  className,
+  ref,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Description> & {
+  ref?: React.Ref<HTMLParagraphElement>;
+}) {
+  return (
+    <DrawerPrimitive.Description
+      ref={ref}
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerHeader,
+  DrawerOverlay,
+  DrawerPortal,
+  DrawerTitle,
+  DrawerTrigger,
+};

package/src/field.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (field) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import type * as React from "react";

package/src/form.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (form) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";

package/src/index.ts

@@ -24,6 +24,19 @@ export {
   DialogTrigger,
 } from "./dialog.js";
 export { DetailPanel, type DetailItem, type DetailPanelProps } from "./detail-panel.js";
+export {
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerHeader,
+  DrawerOverlay,
+  DrawerPortal,
+  DrawerTitle,
+  DrawerTrigger,
+} from "./drawer.js";
 export {
   Field,
   FieldContent,
@@ -52,6 +65,11 @@ export { Input } from "./input.js";
 export { Label } from "./label.js";
 export { Section, Stack, stackVariants, type SectionProps, type StackProps } from "./layout.js";
 export { LivePulse, type LivePulseProps } from "./live-pulse.js";
+export { StatusDot, type StatusDotProps, type StatusDotTone } from "./status-dot.js";
+export { ProgressBar, type ProgressBarProps } from "./progress-bar.js";
+export { Checkmark, type CheckmarkProps } from "./checkmark.js";
+export { StatusLabel, type StatusLabelProps, type StatusLabelTone } from "./status-label.js";
+export { UpdatedAgo, type UpdatedAgoProps } from "./updated-ago.js";
 export { OptionCards, type OptionCard, type OptionCardsProps } from "./option-cards.js";
 export { PageHeader, type PageHeaderProps } from "./page-header.js";
 export { SecretField, type SecretFieldProps } from "./secret-field.js";
@@ -93,3 +111,7 @@ export {
   type TextProps,
 } from "./typography.js";
 export { cn } from "./utils.js";
+export { CardSkeleton, type CardSkeletonProps } from "./card-skeleton.js";
+export { DataTableSkeleton, type DataTableSkeletonProps } from "./data-table-skeleton.js";
+export { DetailPanelSkeleton, type DetailPanelSkeletonProps } from "./detail-panel-skeleton.js";
+export { PageHeaderSkeleton, type PageHeaderSkeletonProps } from "./page-header-skeleton.js";

package/src/input.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (input) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 import * as React from "react";
 import { cn } from "./utils.js";
 

package/src/label.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (label) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";

package/src/live-pulse.tsx

@@ -1,3 +1,4 @@
+import { StatusDot } from "./status-dot.js";
 import { cn } from "./utils.js";
 
 export interface LivePulseProps {
@@ -13,14 +14,7 @@ export function LivePulse({ active = true, label = "Live", className }: LivePuls
       aria-label={active ? label : "Idle"}
       className={cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className)}
     >
-      <span className="relative flex size-2">
-        {active ? (
-          <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-success opacity-60" />
-        ) : null}
-        <span
-          className={cn("relative inline-flex size-2 rounded-full", active ? "bg-success" : "bg-muted-foreground/40")}
-        />
-      </span>
+      <StatusDot tone={active ? "success" : "idle"} pulse={active} />
       {active ? label : "Idle"}
     </span>
   );

package/src/page-header-skeleton.tsx

@@ -0,0 +1,39 @@
+import { Skeleton } from "./skeleton.js";
+import { cn } from "./utils.js";
+
+export interface PageHeaderSkeletonProps {
+  label?: string;
+  description?: boolean;
+  actions?: boolean;
+  className?: string;
+}
+
+/**
+ * Faithful loading shape of PageHeader: title, optional description
+ * and action slots. Same box, no layout shift when content lands.
+ */
+export function PageHeaderSkeleton({
+  label = "Loading",
+  description = true,
+  actions = true,
+  className,
+}: PageHeaderSkeletonProps) {
+  return (
+    <div
+      role="status"
+      aria-label={label}
+      className={cn("mb-6 flex flex-wrap items-start justify-between gap-4", className)}
+    >
+      <div className="space-y-1">
+        <Skeleton className="h-7 w-48" />
+        {description ? <Skeleton className="h-4 w-64" /> : null}
+      </div>
+      {actions ? (
+        <div className="flex items-center gap-2">
+          <Skeleton className="h-9 w-24" />
+          <Skeleton className="h-9 w-24" />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/progress-bar.tsx

@@ -0,0 +1,45 @@
+import { cn } from "./utils.js";
+
+export interface ProgressBarProps {
+  /** Current value, clamped to 0..max (`NaN` reads as empty). */
+  value: number;
+  max?: number;
+  /** Accessible name (kept screen-only — pair with visible text). */
+  label: string;
+  className?: string;
+}
+
+const SEGMENTS = 10;
+
+/**
+ * Determinate progress as filled segments (exact value stays in
+ * `aria-valuenow`). No animation, so nothing to disable for reduced
+ * motion. Announce the operation with visible text (e.g. StatusLabel)
+ * next to it — the label here stays screen-only.
+ */
+export function ProgressBar({ value, max = 100, label, className }: ProgressBarProps) {
+  const safeMax = Number.isFinite(max) && max > 0 ? max : 100;
+  const safeValue = Number.isFinite(value) ? Math.min(Math.max(value, 0), safeMax) : 0;
+  const filled = Math.round((safeValue / safeMax) * SEGMENTS);
+  return (
+    <div
+      role="progressbar"
+      aria-label={label}
+      aria-valuemin={0}
+      aria-valuemax={safeMax}
+      aria-valuenow={Math.round(safeValue)}
+      className={cn("flex w-full gap-0.5", className)}
+    >
+      {Array.from({ length: SEGMENTS }, (_, index) => (
+        <span
+          key={index}
+          aria-hidden
+          className={cn(
+            "h-1.5 flex-1 rounded-full motion-safe:transition-colors",
+            index < filled ? "bg-primary" : "bg-muted",
+          )}
+        />
+      ))}
+    </div>
+  );
+}

package/src/select.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (select) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";

package/src/separator.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (separator) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import * as React from "react";

package/src/skeleton.tsx

@@ -1,7 +1,8 @@
+// Derived from shadcn/ui (skeleton) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 import { cn } from "./utils.js";
 
 function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("animate-pulse rounded-md bg-muted", className)} {...props} />;
+  return <div className={cn("rounded-md bg-muted motion-safe:animate-pulse", className)} {...props} />;
 }
 
 export { Skeleton };

package/src/sonner.tsx

@@ -1,3 +1,4 @@
+// Derived from shadcn/ui (sonner) — see Provenance in packages/ui/README.md. Tolerated exception: migrated to custom code only when customization needs it.
 "use client";
 
 import { Toaster as Sonner, type ToasterProps } from "sonner";

package/src/status-dot.tsx

@@ -0,0 +1,42 @@
+import { cn } from "./utils.js";
+
+export type StatusDotTone = "active" | "idle" | "success" | "warning" | "danger";
+
+export interface StatusDotProps {
+  tone?: StatusDotTone;
+  /** Override the default ping (ongoing tones ping, others stay static). */
+  pulse?: boolean;
+  className?: string;
+}
+
+const TONE_COLOR: Record<StatusDotTone, string> = {
+  active: "bg-primary",
+  idle: "bg-muted-foreground/40",
+  success: "bg-success",
+  warning: "bg-warning",
+  danger: "bg-destructive",
+};
+
+const PING_TONES: ReadonlySet<StatusDotTone> = new Set(["active", "warning", "danger"]);
+
+/**
+ * Decorative status dot: pings for ongoing tones (motion-safe), static
+ * otherwise. Pair with visible text (e.g. StatusLabel) — never alone.
+ */
+export function StatusDot({ tone = "active", pulse, className }: StatusDotProps) {
+  const color = TONE_COLOR[tone];
+  const ping = pulse ?? PING_TONES.has(tone);
+  return (
+    <span aria-hidden className={cn("relative flex size-2", className)}>
+      {ping ? (
+        <span
+          className={cn(
+            "absolute inline-flex h-full w-full rounded-full opacity-60 motion-safe:animate-ping",
+            color,
+          )}
+        />
+      ) : null}
+      <span className={cn("relative inline-flex size-2 rounded-full", color)} />
+    </span>
+  );
+}

package/src/status-label.tsx

@@ -0,0 +1,53 @@
+import { WifiOff } from "lucide-react";
+
+import { Checkmark } from "./checkmark.js";
+import { StatusDot } from "./status-dot.js";
+import { cn } from "./utils.js";
+
+export type StatusLabelTone = "loading" | "updating" | "syncing" | "saved" | "retry" | "error" | "offline";
+
+export interface StatusLabelProps {
+  tone: StatusLabelTone;
+  children: React.ReactNode;
+  className?: string;
+}
+
+function ToneIcon({ tone }: { tone: StatusLabelTone }) {
+  switch (tone) {
+    case "saved":
+      return <Checkmark />;
+    case "retry":
+      return <StatusDot tone="warning" />;
+    case "error":
+      return <StatusDot tone="danger" />;
+    case "offline":
+      return <WifiOff aria-hidden className="size-3.5 text-muted-foreground" />;
+    case "loading":
+    case "updating":
+    case "syncing":
+      return <StatusDot tone="active" />;
+  }
+}
+
+/**
+ * Named inline status: icon + text, announced politely (`role=status`).
+ * Name the operation ("Saving report…", not "Loading…") so a worried
+ * user always knows what is happening and where.
+ */
+export function StatusLabel({ tone, children, className }: StatusLabelProps) {
+  return (
+    <span
+      role="status"
+      className={cn(
+        "inline-flex items-center gap-1.5 text-xs",
+        tone === "error" ? "text-destructive" : "text-muted-foreground",
+        className,
+      )}
+    >
+      <span className="flex size-4 shrink-0 items-center justify-center">
+        <ToneIcon tone={tone} />
+      </span>
+      {children}
+    </span>
+  );
+}