@ponti-studios/ui 0.1.2 → 0.4.0

package/src/components/feedback/file-upload-status.tsx

@@ -0,0 +1,152 @@
+import { XIcon } from "lucide-react";
+import { memo } from "react";
+
+import { cn } from "../../lib/utils";
+import { ProgressBar } from "./progress-bar";
+
+export interface FileUploadStats {
+  progress?: number;
+  processingTime?: number;
+  total?: number;
+  created?: number;
+  updated?: number;
+  skipped?: number;
+  merged?: number;
+  invalid?: number;
+  errors?: unknown[];
+}
+
+export interface FileUploadState {
+  status: "uploading" | "processing" | "queued" | "done" | "error" | (string & {});
+  error?: string;
+  stats?: FileUploadStats;
+}
+
+export const FileUploadStatus = memo(function FileUploadStatus({
+  uploadStatus,
+}: {
+  uploadStatus?: FileUploadState;
+}) {
+  if (!uploadStatus) return null;
+  const { status, error, stats } = uploadStatus;
+
+  if (status === "uploading" || status === "processing") {
+    const progress = stats?.progress;
+
+    return (
+      <output className="w-full">
+        <div className="mb-1.5 flex items-center justify-between">
+          <span className="text-muted-foreground text-sm font-medium">
+            {status === "uploading" ? "Uploading" : "Processing"}
+          </span>
+          <span className="text-foreground text-sm font-medium">
+            {progress !== undefined ? `${Math.round(progress)}%` : ""}
+          </span>
+        </div>
+        <div className="w-full">
+          {typeof progress === "number" ? (
+            <ProgressBar
+              progress={progress}
+              className={cn("bg-muted h-2", "before:bg-emphasis-high")}
+            />
+          ) : (
+            <div className="bg-muted h-2 overflow-hidden">
+              <div className="bg-emphasis-high void-anim-breezy-progress h-full" />
+            </div>
+          )}
+        </div>
+      </output>
+    );
+  }
+
+  if (status === "queued") {
+    return (
+      <output className="w-full">
+        <div className="mb-1.5 flex items-center justify-between">
+          <span className="text-muted-foreground text-sm font-medium">Queue position</span>
+        </div>
+        <div className="w-full">
+          <ProgressBar progress={0} className="bg-warning-subtle before:bg-warning h-2" />
+        </div>
+      </output>
+    );
+  }
+
+  if (status === "done") {
+    return (
+      <output className="space-y-3">
+        <div className="w-full">
+          <ProgressBar progress={100} className="bg-emphasis-minimal before:bg-emphasis-high h-2" />
+        </div>
+        {stats && <ProcessingStats stats={stats} />}
+      </output>
+    );
+  }
+
+  if (status === "error") {
+    return (
+      <output className="mt-2" role="alert">
+        <div className="bg-destructive/10 text-destructive flex items-start gap-2 p-3">
+          <XIcon className="mt-0.5 h-5 w-5 flex-shrink-0" aria-hidden="true" />
+          <span className="text-sm">{error}</span>
+        </div>
+      </output>
+    );
+  }
+
+  return <output className="text-muted-foreground text-sm">{status}</output>;
+});
+
+const ProcessingStats = memo(function ProcessingStats({ stats }: { stats: FileUploadStats }) {
+  if (!stats || typeof stats !== "object") return null;
+
+  return (
+    <dl className="divide-border mt-3 divide-y">
+      {stats.processingTime !== undefined && (
+        <div className="py-2 first:pt-0 last:pb-0">
+          <dt className="sr-only">Processing time</dt>
+          <dd className="text-foreground text-sm font-medium">
+            Completed in {(stats.processingTime / 1000).toFixed(1)}s
+          </dd>
+        </div>
+      )}
+      {stats.total !== undefined && Object.values(stats).length ? (
+        <>
+          <ProcessingStat label="Total" value={stats.total} />
+          <ProcessingStat label="Created" value={stats.created} />
+          <ProcessingStat label="Updated" value={stats.updated} />
+          <ProcessingStat label="Skipped" value={stats.skipped} />
+          <ProcessingStat label="Merged" value={stats.merged} />
+          <ProcessingStat label="Invalid" value={stats.invalid} />
+        </>
+      ) : null}
+
+      {stats.errors?.length && stats.errors.length > 0 ? (
+        <div className="py-2">
+          <dt className="text-foreground text-sm font-medium">Errors</dt>
+          <dd className="mt-1">
+            <span className="bg-destructive/10 text-destructive inline-flex items-center px-2 py-1 text-xs font-medium">
+              {stats.errors.length} error{stats.errors.length > 1 ? "s" : ""}
+            </span>
+          </dd>
+        </div>
+      ) : null}
+    </dl>
+  );
+});
+
+const ProcessingStat = memo(function ProcessingStat({
+  label,
+  value,
+}: {
+  label: string;
+  value?: number | undefined;
+}) {
+  if (value === undefined) return null;
+  return (
+    <div className="py-2">
+      <dt className="text-muted-foreground text-sm font-medium">{label}</dt>
+      <dd className="text-foreground mt-1 text-sm">{value.toLocaleString()}</dd>
+    </div>
+  );
+});

package/src/components/feedback/index.ts

@@ -1,6 +1,15 @@
 export { Alert, AlertDescription, AlertTitle } from "./alert";
 export { EmptyState } from "./empty-state";
 export type { EmptyStateProps } from "./empty-state";
+export { FileUploadStatus } from "./file-upload-status";
+export type { FileUploadState, FileUploadStats } from "./file-upload-status";
+export { FileUploadStatusBadge } from "./file-upload-status-badge";
+export type { FileUploadStatusValue } from "./file-upload-status-badge";
 export { Progress } from "./progress";
+export { ProgressBar } from "./progress-bar";
+export type { ProgressBarProps } from "./progress-bar";
+export { Skeleton } from "./skeleton";
 export { Spinner } from "./spinner";
 export type { SpinnerProps } from "./spinner";
+export { UpdateGuard } from "./update-guard";
+export type { UpdateGuardCopy, UpdateGuardProps } from "./update-guard";

package/src/components/feedback/progress-bar.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ProgressBar } from "./progress-bar";
+
+const meta = {
+  title: "Feedback/ProgressBar",
+  component: ProgressBar,
+  tags: ["autodocs"],
+} satisfies Meta<typeof ProgressBar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { progress: 60 },
+  render: (args) => (
+    <div className="w-64">
+      <ProgressBar {...args} />
+    </div>
+  ),
+};
+
+export const Empty: Story = {
+  args: { progress: 0 },
+  render: (args) => (
+    <div className="w-64">
+      <ProgressBar {...args} />
+    </div>
+  ),
+};
+
+export const Complete: Story = {
+  args: { progress: 100 },
+  render: (args) => (
+    <div className="w-64">
+      <ProgressBar {...args} />
+    </div>
+  ),
+};

package/src/components/feedback/progress-bar.tsx

@@ -0,0 +1,21 @@
+import { cn } from "../../lib/utils";
+
+export interface ProgressBarProps {
+  className?: string;
+  progress?: number;
+}
+
+/** Thin linear progress indicator, distinct from the Radix-backed `Progress`. */
+export function ProgressBar({ className, progress = 0 }: ProgressBarProps) {
+  return (
+    <div className={cn("border-border h-[2px] w-full overflow-hidden border-t", className)}>
+      <div
+        className={cn("border-warning h-full border-t")}
+        style={{
+          width: `${Math.min(100, Math.max(0, progress))}%`,
+          opacity: progress === 100 ? 0 : 0.8,
+        }}
+      />
+    </div>
+  );
+}

package/src/components/feedback/progress.stories.tsx

@@ -14,24 +14,26 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     value: 60,
+    "aria-label": "Upload progress",
   },
 };
 
 export const Empty: Story = {
-  args: { value: 0 },
+  args: { value: 0, "aria-label": "Upload progress" },
 };
 
 export const Complete: Story = {
-  args: { value: 100 },
+  args: { value: 100, "aria-label": "Upload progress" },
 };
 
 export const Partial: Story = {
+  args: { value: 60 },
   render: () => (
     <div className="flex w-64 flex-col gap-4">
-      <Progress value={10} />
-      <Progress value={33} />
-      <Progress value={66} />
-      <Progress value={90} />
+      <Progress value={10} aria-label="Upload progress" />
+      <Progress value={33} aria-label="Upload progress" />
+      <Progress value={66} aria-label="Upload progress" />
+      <Progress value={90} aria-label="Upload progress" />
     </div>
   ),
 };

package/src/components/feedback/progress.tsx

@@ -1,4 +1,4 @@
-import * as ProgressPrimitive from "@radix-ui/react-progress";
+import { Progress as ProgressPrimitive } from "@base-ui/react/progress";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
@@ -14,13 +14,13 @@ function Progress({
   return (
     <ProgressPrimitive.Root
       data-slot="progress"
-      className={cn("bg-accent/20 relative h-2 w-full overflow-hidden rounded-full", className)}
+      className={cn("bg-primary/20 relative h-2 w-full overflow-hidden rounded-full", className)}
       value={value}
       {...props}
     >
       <ProgressPrimitive.Indicator
         data-slot="progress-indicator"
-        className={cn("bg-accent h-full w-full flex-1 transition-all", indicatorClassName)}
+        className={cn("bg-primary h-full w-full flex-1 transition-all", indicatorClassName)}
         style={{ transform: `translateX(-${100 - (value ?? 0)}%)` }}
       />
     </ProgressPrimitive.Root>

package/src/components/feedback/skeleton.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Skeleton } from "./skeleton";
+
+const meta = {
+  title: "Feedback/Skeleton",
+  component: Skeleton,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Skeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <Skeleton className="h-4 w-48" />,
+};
+
+export const TextLines: Story = {
+  render: () => (
+    <div className="w-64 space-y-2">
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-5/6" />
+      <Skeleton className="h-4 w-2/3" />
+    </div>
+  ),
+};
+
+export const CardShape: Story = {
+  render: () => (
+    <div className="w-64 space-y-3">
+      <Skeleton className="h-32 w-full" />
+      <Skeleton className="h-4 w-3/4" />
+      <Skeleton className="h-4 w-1/2" />
+    </div>
+  ),
+};

package/src/components/feedback/skeleton.tsx

@@ -0,0 +1,7 @@
+import type { ComponentProps } from "react";
+
+import { cn } from "../../lib/utils";
+
+export function Skeleton({ className, ...props }: ComponentProps<"div">) {
+  return <div className={cn("bg-muted animate-pulse rounded-md", className)} {...props} />;
+}

package/src/components/feedback/spinner.tsx

@@ -37,12 +37,12 @@ export function Spinner({
     >
       <span
         className={cn(
-          "border-default border-t-accent rounded-full border-2 motion-safe:animate-spin",
+          "border-border border-t-primary rounded-full border-2 motion-safe:animate-spin",
           sizeClasses[size],
         )}
         aria-hidden="true"
       />
-      {label && <span className="text-secondary text-xs">{label}</span>}
+      {label && <span className="text-muted-foreground text-xs">{label}</span>}
     </div>
   );
 }

package/src/components/feedback/update-guard.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { UpdateGuard } from "./update-guard";
+
+const meta = {
+  title: "Feedback/UpdateGuard",
+  component: UpdateGuard,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Registers a service worker at `serviceWorkerPath` and surfaces offline/update-available prompts. In Storybook there is no service worker to register against, so the prompts stay hidden — this story documents the wrapper's pass-through behavior for `children`.",
+      },
+    },
+  },
+} satisfies Meta<typeof UpdateGuard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    hideInDev: false,
+    children: (
+      <div className="border-border bg-surface text-muted-foreground rounded-md border p-6 text-sm">
+        App content renders here. Offline/update prompts appear fixed to the bottom of the viewport
+        when the service worker reports a change.
+      </div>
+    ),
+  },
+};

package/src/components/feedback/update-guard.tsx

@@ -0,0 +1,280 @@
+import type { ReactNode } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+
+interface RegisterSWOptions {
+  onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void;
+  onRegisterError?: (error: Error) => void;
+  serviceWorkerPath?: string;
+}
+
+interface RegisterSWResult {
+  offlineReady: [boolean, (value: boolean) => void];
+  needRefresh: [boolean, (value: boolean) => void];
+  updateServiceWorker: (reload?: boolean) => void;
+}
+
+function useRegisterSW(options?: RegisterSWOptions): RegisterSWResult {
+  const [offlineReady, setOfflineReady] = useState(false);
+  const [needRefresh, setNeedRefresh] = useState(false);
+  const registrationRef = useRef<ServiceWorkerRegistration | undefined>(undefined);
+  const shouldReloadRef = useRef(false);
+  const hasReloadedRef = useRef(false);
+  const onRegisteredRef = useRef(options?.onRegistered);
+  const onRegisterErrorRef = useRef(options?.onRegisterError);
+  const serviceWorkerPathRef = useRef(options?.serviceWorkerPath ?? "/sw.js");
+
+  useEffect(() => {
+    onRegisteredRef.current = options?.onRegistered;
+    onRegisterErrorRef.current = options?.onRegisterError;
+    serviceWorkerPathRef.current = options?.serviceWorkerPath ?? "/sw.js";
+  }, [options?.onRegistered, options?.onRegisterError, options?.serviceWorkerPath]);
+
+  useEffect(() => {
+    if (
+      typeof window === "undefined" ||
+      !("serviceWorker" in navigator) ||
+      !window.isSecureContext
+    ) {
+      return;
+    }
+
+    let isMounted = true;
+
+    const handleControllerChange = () => {
+      if (!shouldReloadRef.current || hasReloadedRef.current) {
+        return;
+      }
+
+      hasReloadedRef.current = true;
+      window.location.reload();
+    };
+
+    navigator.serviceWorker.addEventListener("controllerchange", handleControllerChange);
+
+    const handleWaitingServiceWorker = (registration: ServiceWorkerRegistration) => {
+      registrationRef.current = registration;
+      if (!isMounted) {
+        return;
+      }
+
+      setNeedRefresh(true);
+      setOfflineReady(false);
+    };
+
+    const handleInstalledServiceWorker = (registration: ServiceWorkerRegistration) => {
+      registrationRef.current = registration;
+      if (!isMounted) {
+        return;
+      }
+
+      if (navigator.serviceWorker.controller) {
+        setNeedRefresh(true);
+        setOfflineReady(false);
+        return;
+      }
+
+      setOfflineReady(true);
+    };
+
+    const trackRegistration = (registration: ServiceWorkerRegistration) => {
+      registrationRef.current = registration;
+      onRegisteredRef.current?.(registration);
+
+      if (registration.waiting) {
+        handleWaitingServiceWorker(registration);
+      }
+
+      registration.addEventListener("updatefound", () => {
+        const installingWorker = registration.installing;
+        if (!installingWorker) {
+          return;
+        }
+
+        installingWorker.addEventListener("statechange", () => {
+          if (installingWorker.state === "installed") {
+            handleInstalledServiceWorker(registration);
+          }
+        });
+      });
+    };
+
+    void navigator.serviceWorker
+      .register(serviceWorkerPathRef.current)
+      .then((registration) => {
+        if (!isMounted) {
+          return;
+        }
+
+        trackRegistration(registration);
+        return navigator.serviceWorker.ready.then(() => {
+          if (!isMounted || navigator.serviceWorker.controller) {
+            return;
+          }
+
+          setOfflineReady(true);
+        });
+      })
+      .catch((error: Error) => {
+        if (isMounted) {
+          onRegisterErrorRef.current?.(error);
+        }
+      });
+
+    return () => {
+      isMounted = false;
+      navigator.serviceWorker.removeEventListener("controllerchange", handleControllerChange);
+    };
+  }, []);
+
+  return {
+    offlineReady: [offlineReady, setOfflineReady],
+    needRefresh: [needRefresh, setNeedRefresh],
+    updateServiceWorker: (reload = true) => {
+      shouldReloadRef.current = reload;
+      registrationRef.current?.waiting?.postMessage({ type: "SKIP_WAITING" });
+    },
+  };
+}
+
+function subscribeOnline(onStoreChange: () => void) {
+  if (typeof window === "undefined") {
+    return () => {};
+  }
+
+  window.addEventListener("online", onStoreChange);
+  window.addEventListener("offline", onStoreChange);
+
+  return () => {
+    window.removeEventListener("online", onStoreChange);
+    window.removeEventListener("offline", onStoreChange);
+  };
+}
+
+function getOnlineSnapshot() {
+  if (typeof navigator === "undefined") {
+    return true;
+  }
+
+  return navigator.onLine;
+}
+
+export interface UpdateGuardCopy {
+  offlineReady?: string;
+  newContentAvailable?: string;
+  refreshButton?: string;
+  closeButton?: string;
+  offlineMessage?: string;
+  offlineStaleMessage?: string;
+}
+
+export interface UpdateGuardProps {
+  children: ReactNode;
+  serviceWorkerPath?: string;
+  hasStaleData?: boolean;
+  hideInDev?: boolean;
+  copy?: UpdateGuardCopy;
+}
+
+function UpdateGuardClient({
+  serviceWorkerPath,
+  hasStaleData = false,
+  hideInDev = true,
+  copy,
+}: Omit<UpdateGuardProps, "children">) {
+  const isDev =
+    typeof import.meta !== "undefined" &&
+    typeof import.meta.env !== "undefined" &&
+    Boolean(import.meta.env.DEV);
+
+  const {
+    offlineReady: [offlineReady, setOfflineReady],
+    needRefresh: [needRefresh, setNeedRefresh],
+    updateServiceWorker,
+  } = useRegisterSW({ serviceWorkerPath });
+
+  const isOnline = useSyncExternalStore(subscribeOnline, getOnlineSnapshot, () => true);
+
+  const closePrompt = () => {
+    setOfflineReady(false);
+    setNeedRefresh(false);
+  };
+
+  const offlineMessage = useMemo(() => {
+    if (isOnline) {
+      return null;
+    }
+
+    return hasStaleData
+      ? (copy?.offlineStaleMessage ?? "Offline - showing cached data where available")
+      : (copy?.offlineMessage ?? "Offline - data may be unavailable");
+  }, [copy?.offlineMessage, copy?.offlineStaleMessage, hasStaleData, isOnline]);
+
+  if (hideInDev && isDev) {
+    return null;
+  }
+
+  return (
+    <>
+      {offlineMessage ? (
+        <div className="fixed inset-x-0 bottom-16 z-50 flex justify-center px-4">
+          <div className="border-border bg-surface flex items-center gap-3 rounded-md border px-4 py-2">
+            <span className="text-foreground text-sm">{offlineMessage}</span>
+          </div>
+        </div>
+      ) : null}
+
+      {offlineReady || needRefresh ? (
+        <div className="fixed inset-x-0 bottom-4 z-50 flex justify-center px-4">
+          <div className="border-border bg-surface flex items-center gap-3 rounded-md border px-4 py-2">
+            <span className="text-foreground text-sm">
+              {offlineReady
+                ? (copy?.offlineReady ?? "App ready to work offline")
+                : (copy?.newContentAvailable ?? "New content available")}
+            </span>
+            {needRefresh ? (
+              <button
+                type="button"
+                onClick={() => updateServiceWorker(true)}
+                className="text-accent text-sm font-semibold"
+              >
+                {copy?.refreshButton ?? "Refresh"}
+              </button>
+            ) : null}
+            <button type="button" onClick={closePrompt} className="text-muted-foreground text-sm">
+              {copy?.closeButton ?? "Close"}
+            </button>
+          </div>
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * Registers a service worker and surfaces "offline ready" / "update
+ * available" prompts around `children`. No-op (renders only `children`) when
+ * rendered on the server.
+ */
+export function UpdateGuard({
+  children,
+  serviceWorkerPath,
+  hasStaleData = false,
+  hideInDev = true,
+  copy,
+}: UpdateGuardProps) {
+  const isClient = typeof window !== "undefined";
+
+  return (
+    <>
+      {children}
+      {isClient ? (
+        <UpdateGuardClient
+          serviceWorkerPath={serviceWorkerPath}
+          hasStaleData={hasStaleData}
+          hideInDev={hideInDev}
+          copy={copy}
+        />
+      ) : null}
+    </>
+  );
+}