@dowel-ui/react 0.4.0 → 0.7.0

package/src/components/sidebar/sidebar.tsx

@@ -0,0 +1,374 @@
+"use client";
+
+import { Slot } from "radix-ui";
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { Sheet, SheetContent, SheetTitle } from "@/components/sheet";
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * The application's own navigation.
+ *
+ * Two states, not one. On a wide screen it collapses to a rail of icons and
+ * stays in the page; on a narrow one it is an overlay, which needs a focus trap
+ * and an Escape key and is therefore a Sheet rather than a div with a
+ * transform. Building one behaviour and hiding it at a breakpoint gets the
+ * mobile case wrong every time — the page behind stays reachable by Tab while
+ * the menu covers it.
+ *
+ * The collapsed rail is where these usually fail. Hiding the label leaves a
+ * button whose only content is an icon, and an icon has no accessible name. The
+ * label here is not removed but visually hidden, so the control keeps its name
+ * whether or not the text is on screen.
+ *
+ * The overlay is mounted only on a narrow screen, and it has its own open
+ * state. Mounting it always and hiding it with CSS was the first version, and
+ * it was wrong in a way no visual check catches: a modal dialog that is
+ * `display: none` is still modal. It marks the rest of the page `aria-hidden`,
+ * traps focus in an element nothing can focus, and turns pointer events off on
+ * the body — so on a desktop the whole application was invisible to a screen
+ * reader and unclickable the moment the sidebar was open, which is its default.
+ */
+
+/** Below Tailwind's `md` breakpoint, which is where the rail gives way to the overlay. */
+const NARROW_QUERY = "(max-width: 767px)";
+
+function subscribeToNarrow(callback: () => void): () => void {
+  const query = window.matchMedia(NARROW_QUERY);
+  query.addEventListener("change", callback);
+  return () => {
+    query.removeEventListener("change", callback);
+  };
+}
+
+/**
+ * Whether the viewport is narrow enough for the overlay.
+ *
+ * The server snapshot says "wide": the rail renders in the HTML and CSS hides
+ * it below the breakpoint, so a narrow screen shows nothing wrong before
+ * hydration and the sheet mounts, closed, straight after.
+ */
+function useIsNarrow(): boolean {
+  return useSyncExternalStore(
+    subscribeToNarrow,
+    () => window.matchMedia(NARROW_QUERY).matches,
+    () => false,
+  );
+}
+
+interface SidebarContextValue {
+  /** The rail is expanded rather than collapsed. */
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** The viewport is narrow, so the navigation is an overlay. */
+  narrow: boolean;
+  /** The overlay is showing. Only meaningful when `narrow`. */
+  overlayOpen: boolean;
+  setOverlayOpen: (open: boolean) => void;
+  /** Whichever of the two states applies on this viewport. */
+  toggle: () => void;
+  /** Id of the sidebar element, for the trigger's aria-controls. */
+  sidebarId: string;
+}
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+function useSidebar(component: string): SidebarContextValue {
+  const context = useContext(SidebarContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <SidebarProvider>.`);
+  }
+  return context;
+}
+
+export interface SidebarProviderProps {
+  /** Controlled open state. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+export function SidebarProvider({
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  children,
+}: SidebarProviderProps) {
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+  const open = openProp ?? uncontrolled;
+  // Separate from `open`, and never true to begin with: "expanded by default"
+  // is a fact about the rail. An overlay that covers the page on first load is
+  // a menu nobody asked for.
+  const [overlayOpen, setOverlayOpen] = useState(false);
+  const narrow = useIsNarrow();
+  const sidebarId = useId();
+
+  const value = useMemo<SidebarContextValue>(() => {
+    const setOpen = (next: boolean) => {
+      if (openProp === undefined) setUncontrolled(next);
+      onOpenChange?.(next);
+    };
+
+    return {
+      open,
+      setOpen,
+      narrow,
+      overlayOpen,
+      setOverlayOpen,
+      toggle: () => {
+        if (narrow) setOverlayOpen(!overlayOpen);
+        else setOpen(!open);
+      },
+      sidebarId,
+    };
+  }, [open, openProp, onOpenChange, narrow, overlayOpen, sidebarId]);
+
+  return <SidebarContext.Provider value={value}>{children}</SidebarContext.Provider>;
+}
+
+export interface SidebarProps extends ComponentPropsWithRef<"aside"> {
+  /**
+   * Names the navigation landmark.
+   *
+   * Required, not optional. A page has more than one navigation region — this,
+   * a breadcrumb, a footer — and three landmarks all called "navigation" is a
+   * list a screen reader user cannot choose from.
+   */
+  label: string;
+  /** Title for the overlay on a narrow screen, where it is a dialog. */
+  mobileTitle?: string;
+}
+
+export function Sidebar({ className, label, mobileTitle, children, ...props }: SidebarProps) {
+  const { open, narrow, overlayOpen, setOverlayOpen, sidebarId } = useSidebar("Sidebar");
+
+  return (
+    <>
+      {/*
+        The overlay, on a narrow screen. A Sheet rather than a styled div: it
+        traps focus, closes on Escape and marks the rest of the page inert,
+        none of which a transform does — and without them the page behind stays
+        reachable by Tab while the menu covers it.
+
+        Mounted only when the screen is narrow. Those three behaviours are
+        exactly why it must not exist on a wide one: see the note at the top.
+      */}
+      {narrow ? (
+        <Sheet open={overlayOpen} onOpenChange={setOverlayOpen}>
+          <SheetContent side="left" className="w-72 p-0">
+            <SheetTitle className="sr-only">{mobileTitle ?? label}</SheetTitle>
+            <nav aria-label={label} className="flex h-full flex-col gap-2 p-3">
+              {children}
+            </nav>
+          </SheetContent>
+        </Sheet>
+      ) : null}
+
+      <aside
+        id={sidebarId}
+        data-slot="sidebar"
+        data-state={open ? "expanded" : "collapsed"}
+        className={cn(
+          "hidden shrink-0 border-e border-border bg-background md:block",
+          "transition-[width] duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]",
+          open ? "w-60" : "w-14",
+          className,
+        )}
+        {...props}
+      >
+        <nav aria-label={label} className="flex h-full flex-col gap-2 p-3">
+          {children}
+        </nav>
+      </aside>
+    </>
+  );
+}
+
+export function SidebarHeader({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="sidebar-header"
+      className={cn("flex min-h-9 items-center gap-2 px-1", className)}
+      {...props}
+    />
+  );
+}
+
+export function SidebarContent({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="sidebar-content"
+      className={cn("flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto", className)}
+      {...props}
+    />
+  );
+}
+
+export function SidebarFooter({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return <div data-slot="sidebar-footer" className={cn("mt-auto", className)} {...props} />;
+}
+
+export function SidebarGroup({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return <div data-slot="sidebar-group" className={cn("grid gap-1", className)} {...props} />;
+}
+
+/**
+ * A heading for a group of links.
+ *
+ * Hidden rather than removed when the rail is collapsed, so the grouping
+ * survives for anyone not reading the layout visually.
+ */
+export function SidebarGroupLabel({ className, ...props }: ComponentPropsWithRef<"div">) {
+  const { open, narrow } = useSidebar("SidebarGroupLabel");
+
+  return (
+    <div
+      data-slot="sidebar-group-label"
+      className={cn(
+        "px-2 text-xs font-medium tracking-wide text-muted-foreground uppercase",
+        // The rail's collapsed state is not the overlay's: a sheet is always
+        // wide enough for its labels.
+        !open && !narrow && "sr-only",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function SidebarMenu({ className, ...props }: ComponentPropsWithRef<"ul">) {
+  return <ul data-slot="sidebar-menu" className={cn("grid gap-0.5", className)} {...props} />;
+}
+
+export function SidebarMenuItem({ className, ...props }: ComponentPropsWithRef<"li">) {
+  return <li data-slot="sidebar-menu-item" className={cn("min-w-0", className)} {...props} />;
+}
+
+export interface SidebarMenuButtonProps extends ComponentPropsWithRef<"a"> {
+  /** Render the child as the control, for a router's own link or a button. */
+  asChild?: boolean;
+  /** The page currently being shown. */
+  isActive?: boolean;
+}
+
+/**
+ * One entry in the navigation.
+ *
+ * `aria-current="page"` when active, not merely a background colour: which page
+ * you are on is information, and a highlight conveys it to exactly one kind of
+ * reader.
+ */
+export function SidebarMenuButton({
+  className,
+  asChild = false,
+  isActive = false,
+  children,
+  ...props
+}: SidebarMenuButtonProps) {
+  const Component = asChild ? Slot.Root : "a";
+
+  return (
+    <Component
+      data-slot="sidebar-menu-button"
+      data-active={isActive || undefined}
+      aria-current={isActive ? "page" : undefined}
+      className={cn(
+        "flex h-9 w-full items-center gap-2.5 rounded-md px-2 text-sm",
+        "transition-colors duration-[var(--duration-fast)]",
+        "[&>svg]:size-4 [&>svg]:shrink-0",
+        isActive
+          ? "bg-accent font-medium text-accent-foreground"
+          : "text-muted-foreground hover:bg-accent/60 hover:text-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Component>
+  );
+}
+
+/**
+ * The text of a menu entry.
+ *
+ * Visually hidden rather than removed when the rail is collapsed. Removing it
+ * leaves a control whose only content is an icon, and an icon has no accessible
+ * name — which is how a collapsed sidebar becomes a column of buttons all
+ * announced as "link".
+ */
+export function SidebarMenuLabel({ className, ...props }: ComponentPropsWithRef<"span">) {
+  const { open, narrow } = useSidebar("SidebarMenuLabel");
+
+  return (
+    <span
+      data-slot="sidebar-menu-label"
+      className={cn("min-w-0 truncate", !open && !narrow && "sr-only", className)}
+      {...props}
+    />
+  );
+}
+
+export interface SidebarTriggerProps extends ComponentPropsWithRef<"button"> {
+  /** Overrides the label, which otherwise says what pressing it will do. */
+  label?: string;
+}
+
+export function SidebarTrigger({ className, label, ...props }: SidebarTriggerProps) {
+  const { open, narrow, overlayOpen, toggle, sidebarId } = useSidebar("SidebarTrigger");
+
+  const expanded = narrow ? overlayOpen : open;
+  const fallback = narrow
+    ? overlayOpen
+      ? "Close navigation"
+      : "Open navigation"
+    : open
+      ? "Collapse navigation"
+      : "Expand navigation";
+
+  return (
+    <button
+      type="button"
+      data-slot="sidebar-trigger"
+      aria-expanded={expanded}
+      // The rail is what this controls. The overlay is a dialog that names
+      // itself, and pointing at an element CSS has hidden helps nobody.
+      aria-controls={narrow ? undefined : sidebarId}
+      // Says what pressing it does, not what the state currently is. "Collapse
+      // navigation" while it is expanded is the useful half.
+      aria-label={label ?? fallback}
+      onClick={toggle}
+      className={cn(
+        "grid size-9 shrink-0 place-items-center rounded-md text-muted-foreground",
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-foreground",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      <svg viewBox="0 0 24 24" fill="none" aria-hidden className="size-4">
+        <rect x="3" y="4" width="18" height="16" rx="2" stroke="currentColor" strokeWidth="2" />
+        <path d="M9 4v16" stroke="currentColor" strokeWidth="2" />
+      </svg>
+    </button>
+  );
+}
+
+/** The region the sidebar sits beside. */
+export function SidebarInset({ className, ...props }: ComponentPropsWithRef<"main">) {
+  return (
+    <main data-slot="sidebar-inset" className={cn("min-w-0 flex-1", className)} {...props} />
+  );
+}

package/src/components/sync-status/index.ts

@@ -0,0 +1,9 @@
+export {
+  SyncStatus,
+  describeSyncState,
+  syncState,
+  useOnlineStatus,
+  type SyncInput,
+  type SyncState,
+  type SyncStatusProps,
+} from "./sync-status";

package/src/components/sync-status/meta.ts

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "sync-status",
+  title: "Sync Status",
+  description: "Offline, saving, saved or failed — with the count of changes being held.",
+  category: "feedback",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: ["button"],
+  files: ["sync-status.tsx"],
+  a11y:
+    "The word is the status and the coloured dot is decoration, hidden from assistive " +
+    "technology. The visible text is not a live region: every save flips it and a region on it " +
+    "would narrate the whole session. A separate region, present from the first render, " +
+    "announces transitions only — went offline with what will happen to the changes, came back " +
+    "with what is being saved, could not save, saved after a failure — and never the churn of " +
+    "saving itself. Announcing is on by default because going offline is the one thing a reader " +
+    "who is typing has to be told, and it can be turned off. The server render assumes online, " +
+    "since a page with no interface to report has no business saying offline.",
+});

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/components/table/table.tsx

@@ -98,8 +98,8 @@ export function TableHead({ className, ...props }: ComponentPropsWithRef<"th">)
     <th
       data-slot="table-head"
       className={cn(
-        "h-10 px-3 text-left align-middle text-xs font-medium whitespace-nowrap text-muted-foreground",
-        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pr-0",
+        "h-10 px-3 text-start align-middle text-xs font-medium whitespace-nowrap text-muted-foreground",
+        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pe-0",
         className,
       )}
       {...props}
@@ -113,7 +113,7 @@ export function TableCell({ className, ...props }: ComponentPropsWithRef<"td">)
       data-slot="table-cell"
       className={cn(
         "px-3 py-2.5 align-middle",
-        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pr-0",
+        "[&:has([role=checkbox])]:w-px [&:has([role=checkbox])]:pe-0",
         className,
       )}
       {...props}

package/src/components/tags-input/tags-input.tsx

@@ -232,7 +232,7 @@ export function TagsInput({
                       removeAt(index);
                     }}
                     className={cn(
-                      "-mr-0.5 grid size-4 place-items-center rounded-full",
+                      "-me-0.5 grid size-4 place-items-center rounded-full",
                       "transition-colors hover:bg-foreground/10",
                       focusRing,
                       disabledStyles,

package/src/components/textarea/index.ts

@@ -0,0 +1 @@
+export { Textarea, textareaVariants, type TextareaProps } from "./textarea";

package/src/components/textarea/meta.ts

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "textarea",
+  title: "Textarea",
+  description:
+    "A multi-line text field, with optional auto-resize and a character count that knows when to stay quiet.",
+  category: "form",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["textarea.tsx"],
+  a11y:
+    "Pair with a Label via htmlFor/id. The error state is driven by aria-invalid, so assistive " +
+    "technology and styling stay in sync. The character count is described by the field rather " +
+    "than announced on every keystroke — a permanently live counter reads the remaining number " +
+    "between every letter typed, which is unusable — so it goes live only once the limit is " +
+    "close, and states the remainder in words rather than as a bare ratio that is read aloud as " +
+    "two unlabelled numbers. Horizontal resizing is off by default, because a field dragged " +
+    "wider than its container is a broken layout.",
+});