@dowel-ui/react 0.4.0 → 0.5.0

package/src/components/sync-status/sync-status.tsx

@@ -0,0 +1,217 @@
+"use client";
+
+import { useState, useSyncExternalStore, type ComponentPropsWithRef } from "react";
+
+import { Button } from "@/components/button";
+import { cn } from "@/lib/utils";
+
+/**
+ * "Offline — 3 changes will sync when you're back."
+ *
+ * Linear, Notion, Figma and Google Docs each built this, and nothing in a
+ * component library touches network state at all. It is small, and it is
+ * the difference between an app that loses work and one that says it is
+ * holding it: the moment a request fails, the reader needs to know whether
+ * to keep typing, and whether what they typed a minute ago is anywhere.
+ *
+ * Two things this gets right that the obvious version gets wrong.
+ *
+ * `navigator.onLine` is believed in one direction only. False is reliable —
+ * the interface is down. True means only that there is an interface, not
+ * that the server is reachable, so an application's own failed request is
+ * the real signal and takes precedence. The hook is exported for the rest
+ * of the app to share the same reading.
+ *
+ * Announcements are for transitions, not states. Every save flips
+ * "Saving…" to "Saved", and a live region on that text narrates the whole
+ * session. So the visible text is not live; a separate region says something
+ * only when the situation changes — went offline, came back, could not sync —
+ * which is when a reader who is typing needs to be told.
+ */
+
+export type SyncState = "synced" | "pending" | "syncing" | "offline" | "error";
+
+export interface SyncInput {
+  /** From `useOnlineStatus`, or your own reading. */
+  online: boolean;
+  /** Changes waiting to be sent. */
+  pending?: number;
+  /** A send is in flight. */
+  syncing?: boolean;
+  /** The last send failed, in the reader's language. Takes precedence over `online`. */
+  error?: string | null;
+}
+
+/**
+ * Which state the inputs amount to. Error beats offline beats syncing beats
+ * pending beats synced: each one is the thing the reader most needs to know
+ * given the others.
+ */
+export function syncState({
+  online,
+  pending = 0,
+  syncing = false,
+  error,
+}: SyncInput): SyncState {
+  if (error) return "error";
+  if (!online) return "offline";
+  if (syncing) return "syncing";
+  if (pending > 0) return "pending";
+  return "synced";
+}
+
+const changes = (n: number) => `${String(n)} ${n === 1 ? "change" : "changes"}`;
+
+/** The state as a sentence. Used for the visible text and the announcement. */
+export function describeSyncState(
+  state: SyncState,
+  pending = 0,
+  error?: string | null,
+): string {
+  switch (state) {
+    case "synced":
+      return "All changes saved";
+    case "pending":
+      return `${changes(pending)} waiting to save`;
+    case "syncing":
+      return pending > 0 ? `Saving ${changes(pending)}…` : "Saving…";
+    case "offline":
+      return pending > 0
+        ? `Offline. ${changes(pending)} will save when you're back online.`
+        : "Offline. Changes will save when you're back online.";
+    case "error":
+      return pending > 0
+        ? `Could not save ${changes(pending)}. ${error ?? ""}`.trim()
+        : `Could not save. ${error ?? ""}`.trim();
+  }
+}
+
+/* The browser's reading of the network, as an external store. The server
+   snapshot is "online": a page rendered on the server has no interface to
+   report, and rendering "offline" into HTML would be a lie until hydration. */
+function subscribeOnline(callback: () => void) {
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+}
+const readOnline = () => navigator.onLine;
+const readOnlineOnServer = () => true;
+
+/** Whether the browser believes it has a network. False is reliable; true is not. */
+export function useOnlineStatus(): boolean {
+  return useSyncExternalStore(subscribeOnline, readOnline, readOnlineOnServer);
+}
+
+export interface SyncStatusProps
+  extends Omit<ComponentPropsWithRef<"div">, "children">, Omit<SyncInput, "online"> {
+  /** Omit to read the browser's own status. */
+  online?: boolean;
+  /** When the last save succeeded. Shown as a time, not a relative phrase, so no clock is needed. */
+  lastSyncedAt?: Date;
+  locale?: string;
+  /** Offered when a save failed. */
+  onRetry?: () => void;
+  /**
+   * Announce transitions. On by default, because going offline is the one
+   * thing a reader who is typing has to be told; syncing itself never
+   * announces, whichever way this is set.
+   */
+  announce?: boolean;
+}
+
+export function SyncStatus({
+  className,
+  online: onlineProp,
+  pending = 0,
+  syncing = false,
+  error,
+  lastSyncedAt,
+  locale,
+  onRetry,
+  announce = true,
+  ...props
+}: SyncStatusProps) {
+  const browserOnline = useOnlineStatus();
+  const online = onlineProp ?? browserOnline;
+  const state = syncState({ online, pending, syncing, error });
+  const text = describeSyncState(state, pending, error);
+
+  // Said once, when the situation changes. Adjusted during render so the
+  // announcement lands in the same commit as the state it describes. Syncing
+  // and pending are the ordinary churn of saving and are never announced.
+  const [seen, setSeen] = useState(state);
+  const [announcement, setAnnouncement] = useState("");
+  // A failure is over when a save lands, not when the retry starts, so the
+  // recovery is remembered across the syncing in between.
+  const [recovering, setRecovering] = useState(false);
+  if (seen !== state) {
+    const from = seen;
+    setSeen(state);
+    if (state === "offline" || state === "error") {
+      setAnnouncement(text);
+      setRecovering(false);
+    } else if (from === "offline") {
+      setAnnouncement(
+        pending > 0 ? `Back online. Saving ${changes(pending)}.` : "Back online.",
+      );
+    } else if ((from === "error" || recovering) && state === "synced") {
+      setAnnouncement("Saved.");
+      setRecovering(false);
+    } else if (from === "error") {
+      setRecovering(true);
+    }
+  }
+
+  const savedAt =
+    lastSyncedAt !== undefined
+      ? new Intl.DateTimeFormat(locale, { timeStyle: "short" }).format(lastSyncedAt)
+      : null;
+
+  return (
+    <div
+      data-slot="sync-status"
+      data-state={state}
+      className={cn("flex flex-wrap items-center gap-x-2 gap-y-1 text-xs", className)}
+      {...props}
+    >
+      {/* The dot is decoration. The word is the status. */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "size-2 shrink-0 rounded-full",
+          state === "synced" && "bg-success",
+          state === "pending" && "bg-muted-foreground",
+          state === "syncing" && "animate-pulse-soft bg-info",
+          state === "offline" && "bg-warning",
+          state === "error" && "bg-destructive",
+        )}
+      />
+      <span
+        data-slot="sync-status-text"
+        className={cn(
+          state === "offline" && "text-warning",
+          state === "error" && "text-destructive",
+          (state === "synced" || state === "pending" || state === "syncing") &&
+            "text-muted-foreground",
+        )}
+      >
+        {text}
+        {savedAt && state === "synced" ? ` at ${savedAt}` : null}
+      </span>
+
+      {state === "error" && onRetry ? (
+        <Button variant="outline" size="sm" className="h-6 px-2 text-xs" onClick={onRetry}>
+          Retry
+        </Button>
+      ) : null}
+
+      {/* Present from the start, so the first transition is heard. */}
+      <span role="status" aria-live={announce ? "polite" : "off"} className="sr-only">
+        {announce ? announcement : ""}
+      </span>
+    </div>
+  );
+}

package/src/index.ts

@@ -8,12 +8,14 @@ export * from "./components/ai-agent-status";
 export * from "./components/ai-approval-request";
 export * from "./components/ai-conversation";
 export * from "./components/ai-disclosure";
+export * from "./components/ai-extraction-review";
 export * from "./components/ai-message";
 export * from "./components/ai-model-selector";
 export * from "./components/ai-prompt-input";
 export * from "./components/ai-reasoning";
 export * from "./components/ai-response";
 export * from "./components/ai-sources";
+export * from "./components/ai-suggested-value";
 export * from "./components/ai-token-usage";
 export * from "./components/ai-tool";
 export * from "./components/alert";
@@ -26,10 +28,13 @@ export * from "./components/checkbox";
 export * from "./components/code-block";
 export * from "./components/combobox";
 export * from "./components/command";
+export * from "./components/confirm-typed";
+export * from "./components/cron-editor";
 export * from "./components/data-table";
 export * from "./components/date-picker";
 export * from "./components/dialog";
 export * from "./components/diff-viewer";
+export * from "./components/dns-record";
 export * from "./components/drawer";
 export * from "./components/dropdown-menu";
 export * from "./components/empty-state";
@@ -42,16 +47,21 @@ export * from "./components/meter";
 export * from "./components/metric-delta";
 export * from "./components/record-diff";
 export * from "./components/pagination";
+export * from "./components/permission-matrix";
 export * from "./components/popover";
 export * from "./components/progress";
 export * from "./components/radio-group";
+export * from "./components/secret-field";
 export * from "./components/select";
 export * from "./components/separator";
+export * from "./components/session-expiry";
 export * from "./components/sheet";
+export * from "./components/shortcut-recorder";
 export * from "./components/skeleton";
 export * from "./components/slider";
 export * from "./components/spinner";
 export * from "./components/switch";
+export * from "./components/sync-status";
 export * from "./components/table";
 export * from "./components/tabs";
 export * from "./components/tags-input";

package/src/registry/components.ts

@@ -8,6 +8,7 @@ import { meta as aiAgentStatusMeta } from "@/components/ai-agent-status/meta";
 import { meta as aiApprovalRequestMeta } from "@/components/ai-approval-request/meta";
 import { meta as aiConversationMeta } from "@/components/ai-conversation/meta";
 import { meta as aiDisclosureMeta } from "@/components/ai-disclosure/meta";
+import { meta as aiExtractionReviewMeta } from "@/components/ai-extraction-review/meta";
 import { meta as aiInlineCompletionMeta } from "@/components/ai-inline-completion/meta";
 import { meta as aiMessageMeta } from "@/components/ai-message/meta";
 import { meta as aiModelSelectorMeta } from "@/components/ai-model-selector/meta";
@@ -16,6 +17,7 @@ import { meta as aiReasoningMeta } from "@/components/ai-reasoning/meta";
 import { meta as aiResponseMeta } from "@/components/ai-response/meta";
 import { meta as aiSourcesMeta } from "@/components/ai-sources/meta";
 import { meta as aiStructuredOutputMeta } from "@/components/ai-structured-output/meta";
+import { meta as aiSuggestedValueMeta } from "@/components/ai-suggested-value/meta";
 import { meta as aiTokenUsageMeta } from "@/components/ai-token-usage/meta";
 import { meta as aiToolMeta } from "@/components/ai-tool/meta";
 import { meta as alertMeta } from "@/components/alert/meta";
@@ -28,10 +30,13 @@ import { meta as checkboxMeta } from "@/components/checkbox/meta";
 import { meta as codeBlockMeta } from "@/components/code-block/meta";
 import { meta as comboboxMeta } from "@/components/combobox/meta";
 import { meta as commandMeta } from "@/components/command/meta";
+import { meta as confirmTypedMeta } from "@/components/confirm-typed/meta";
+import { meta as cronEditorMeta } from "@/components/cron-editor/meta";
 import { meta as dataTableMeta } from "@/components/data-table/meta";
 import { meta as datePickerMeta } from "@/components/date-picker/meta";
 import { meta as dialogMeta } from "@/components/dialog/meta";
 import { meta as diffViewerMeta } from "@/components/diff-viewer/meta";
+import { meta as dnsRecordMeta } from "@/components/dns-record/meta";
 import { meta as drawerMeta } from "@/components/drawer/meta";
 import { meta as dropdownMenuMeta } from "@/components/dropdown-menu/meta";
 import { meta as emptyStateMeta } from "@/components/empty-state/meta";
@@ -43,17 +48,22 @@ import { meta as logViewerMeta } from "@/components/log-viewer/meta";
 import { meta as meterMeta } from "@/components/meter/meta";
 import { meta as metricDeltaMeta } from "@/components/metric-delta/meta";
 import { meta as paginationMeta } from "@/components/pagination/meta";
+import { meta as permissionMatrixMeta } from "@/components/permission-matrix/meta";
 import { meta as popoverMeta } from "@/components/popover/meta";
 import { meta as progressMeta } from "@/components/progress/meta";
 import { meta as radioGroupMeta } from "@/components/radio-group/meta";
 import { meta as recordDiffMeta } from "@/components/record-diff/meta";
+import { meta as secretFieldMeta } from "@/components/secret-field/meta";
 import { meta as selectMeta } from "@/components/select/meta";
 import { meta as separatorMeta } from "@/components/separator/meta";
+import { meta as sessionExpiryMeta } from "@/components/session-expiry/meta";
 import { meta as sheetMeta } from "@/components/sheet/meta";
+import { meta as shortcutRecorderMeta } from "@/components/shortcut-recorder/meta";
 import { meta as skeletonMeta } from "@/components/skeleton/meta";
 import { meta as sliderMeta } from "@/components/slider/meta";
 import { meta as spinnerMeta } from "@/components/spinner/meta";
 import { meta as switchMeta } from "@/components/switch/meta";
+import { meta as syncStatusMeta } from "@/components/sync-status/meta";
 import { meta as tableMeta } from "@/components/table/meta";
 import { meta as tabsMeta } from "@/components/tabs/meta";
 import { meta as tagsInputMeta } from "@/components/tags-input/meta";
@@ -81,6 +91,7 @@ export const componentMetas: ComponentMeta[] = [
   aiApprovalRequestMeta,
   aiConversationMeta,
   aiDisclosureMeta,
+  aiExtractionReviewMeta,
   aiInlineCompletionMeta,
   aiMessageMeta,
   aiModelSelectorMeta,
@@ -89,6 +100,7 @@ export const componentMetas: ComponentMeta[] = [
   aiResponseMeta,
   aiSourcesMeta,
   aiStructuredOutputMeta,
+  aiSuggestedValueMeta,
   aiTokenUsageMeta,
   aiToolMeta,
   alertMeta,
@@ -101,10 +113,13 @@ export const componentMetas: ComponentMeta[] = [
   codeBlockMeta,
   comboboxMeta,
   commandMeta,
+  confirmTypedMeta,
+  cronEditorMeta,
   dataTableMeta,
   datePickerMeta,
   dialogMeta,
   diffViewerMeta,
+  dnsRecordMeta,
   drawerMeta,
   dropdownMenuMeta,
   emptyStateMeta,
@@ -116,17 +131,22 @@ export const componentMetas: ComponentMeta[] = [
   meterMeta,
   metricDeltaMeta,
   paginationMeta,
+  permissionMatrixMeta,
   popoverMeta,
   progressMeta,
   radioGroupMeta,
   recordDiffMeta,
+  secretFieldMeta,
   selectMeta,
   separatorMeta,
+  sessionExpiryMeta,
   sheetMeta,
+  shortcutRecorderMeta,
   skeletonMeta,
   sliderMeta,
   spinnerMeta,
   switchMeta,
+  syncStatusMeta,
   tableMeta,
   tabsMeta,
   tagsInputMeta,