@dowel-ui/react 0.4.0 → 0.7.0

package/dist/components/sidebar/meta.js

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/sidebar/meta.ts
+const meta = defineMeta({
+	name: "sidebar",
+	title: "Sidebar",
+	description: "The application's own navigation: a collapsible rail on a wide screen, an overlay on a narrow one.",
+	category: "navigation",
+	status: "stable",
+	dependencies: ["radix-ui"],
+	registryDependencies: ["sheet"],
+	files: ["sidebar.tsx"],
+	a11y: "The navigation landmark must be named — a page has several, and three regions all called \"navigation\" is a list nobody can choose from. The active entry carries aria-current=\"page\" rather than only a background colour. On a narrow screen it is a Sheet, not a styled div: an overlay needs a focus trap and an Escape key, and without them the page behind stays reachable by Tab while the menu covers it. When the rail collapses, labels are visually hidden rather than removed — removing them leaves controls whose only content is an icon, which is how a collapsed sidebar becomes a column of links all announced as \"link\". The trigger says what pressing it will do, not what the state currently is. The overlay is mounted only on a narrow screen and has its own open state: a modal dialog that CSS hides is still modal, and mounting it always made every wide screen aria-hidden and unclickable whenever the rail was open."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/sidebar/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/sidebar/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"sidebar\",\n  title: \"Sidebar\",\n  description:\n    \"The application's own navigation: a collapsible rail on a wide screen, an overlay on a narrow one.\",\n  category: \"navigation\",\n  status: \"stable\",\n  dependencies: [\"radix-ui\"],\n  registryDependencies: [\"sheet\"],\n  files: [\"sidebar.tsx\"],\n  a11y:\n    \"The navigation landmark must be named — a page has several, and three regions all called \" +\n    '\"navigation\" is a list nobody can choose from. The active entry carries aria-current=' +\n    '\"page\" rather than only a background colour. On a narrow screen it is a Sheet, not a ' +\n    \"styled div: an overlay needs a focus trap and an Escape key, and without them the page \" +\n    \"behind stays reachable by Tab while the menu covers it. When the rail collapses, labels \" +\n    \"are visually hidden rather than removed — removing them leaves controls whose only content \" +\n    \"is an icon, which is how a collapsed sidebar becomes a column of links all announced as \" +\n    '\"link\". The trigger says what pressing it will do, not what the state currently is. The ' +\n    \"overlay is mounted only on a narrow screen and has its own open state: a modal dialog that \" +\n    \"CSS hides is still modal, and mounting it always made every wide screen aria-hidden and \" +\n    \"unclickable whenever the rail was open.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aACE;CACF,UAAU;CACV,QAAQ;CACR,cAAc,CAAC,UAAU;CACzB,sBAAsB,CAAC,OAAO;CAC9B,OAAO,CAAC,aAAa;CACrB,MACE;AAWJ,CAAC"}

package/dist/components/sidebar/sidebar.d.ts

@@ -0,0 +1,69 @@
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/components/sidebar/sidebar.d.ts
+interface SidebarProviderProps {
+  /** Controlled open state. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+}
+declare function SidebarProvider({ open: openProp, defaultOpen, onOpenChange, children }: SidebarProviderProps): import("react").JSX.Element;
+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;
+}
+declare function Sidebar({ className, label, mobileTitle, children, ...props }: SidebarProps): import("react").JSX.Element;
+declare function SidebarHeader({ className, ...props }: ComponentPropsWithRef<"div">): import("react").JSX.Element;
+declare function SidebarContent({ className, ...props }: ComponentPropsWithRef<"div">): import("react").JSX.Element;
+declare function SidebarFooter({ className, ...props }: ComponentPropsWithRef<"div">): import("react").JSX.Element;
+declare function SidebarGroup({ className, ...props }: ComponentPropsWithRef<"div">): import("react").JSX.Element;
+/**
+ * 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.
+ */
+declare function SidebarGroupLabel({ className, ...props }: ComponentPropsWithRef<"div">): import("react").JSX.Element;
+declare function SidebarMenu({ className, ...props }: ComponentPropsWithRef<"ul">): import("react").JSX.Element;
+declare function SidebarMenuItem({ className, ...props }: ComponentPropsWithRef<"li">): import("react").JSX.Element;
+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.
+ */
+declare function SidebarMenuButton({ className, asChild, isActive, children, ...props }: SidebarMenuButtonProps): import("react").JSX.Element;
+/**
+ * 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".
+ */
+declare function SidebarMenuLabel({ className, ...props }: ComponentPropsWithRef<"span">): import("react").JSX.Element;
+interface SidebarTriggerProps extends ComponentPropsWithRef<"button"> {
+  /** Overrides the label, which otherwise says what pressing it will do. */
+  label?: string;
+}
+declare function SidebarTrigger({ className, label, ...props }: SidebarTriggerProps): import("react").JSX.Element;
+/** The region the sidebar sits beside. */
+declare function SidebarInset({ className, ...props }: ComponentPropsWithRef<"main">): import("react").JSX.Element;
+//#endregion
+export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuButtonProps, SidebarMenuItem, SidebarMenuLabel, SidebarProps, SidebarProvider, SidebarProviderProps, SidebarTrigger, SidebarTriggerProps };
+//# sourceMappingURL=sidebar.d.ts.map

package/dist/components/sidebar/sidebar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar.d.ts","names":[],"sources":["../../../src/components/sidebar/sidebar.tsx"],"mappings":";;UA6FiB;;EAEf;EACA;EACA,gBAAgB;EAChB,WAAW;;iBAGG,kBACd,MAAM,UACN,aACA,cACA,YACC,uCAAoB,IAAA;UAiCN,qBAAqB;;;;;;;;EAQpC;;EAEA;;iBAGc,UAAU,WAAW,OAAO,aAAa,aAAa,SAAS,+BAAY,IAAA;iBA6C3E,gBAAgB,cAAc,SAAS,+CAA4B,IAAA;iBAUnE,iBAAiB,cAAc,SAAS,+CAA4B,IAAA;iBAUpE,gBAAgB,cAAc,SAAS,+CAA4B,IAAA;iBAInE,eAAe,cAAc,SAAS,+CAA4B,IAAA;;;;;;;iBAUlE,oBAAoB,cAAc,SAAS,+CAA4B,IAAA;iBAkBvE,cAAc,cAAc,SAAS,8CAA2B,IAAA;iBAIhE,kBAAkB,cAAc,SAAS,8CAA2B,IAAA;UAInE,+BAA+B;;EAE9C;;EAEA;;;;;;;;;iBAUc,oBACd,WACA,SACA,UACA,aACG,SACF,yCAAsB,IAAA;;;;;;;;;iBAkCT,mBAAmB,cAAc,SAAS,gDAA6B,IAAA;UAYtE,4BAA4B;;EAE3C;;iBAGc,iBAAiB,WAAW,UAAU,SAAS,sCAAmB,IAAA;;iBAyClE,eAAe,cAAc,SAAS,gDAA6B,IAAA"}

package/dist/components/sidebar/sidebar.js

@@ -0,0 +1,256 @@
+"use client";
+import { disabledStyles, focusRing } from "../../lib/styles.js";
+import { cn } from "../../lib/utils.js";
+import { Sheet, SheetContent, SheetTitle } from "../sheet/sheet.js";
+import { Slot } from "radix-ui";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useId, useMemo, useState, useSyncExternalStore } from "react";
+//#region src/components/sidebar/sidebar.tsx
+/**
+* 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) {
+	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() {
+	return useSyncExternalStore(subscribeToNarrow, () => window.matchMedia(NARROW_QUERY).matches, () => false);
+}
+const SidebarContext = createContext(null);
+function useSidebar(component) {
+	const context = useContext(SidebarContext);
+	if (!context) throw new Error(`${component} must be rendered inside <SidebarProvider>.`);
+	return context;
+}
+function SidebarProvider({ open: openProp, defaultOpen = true, onOpenChange, children }) {
+	const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+	const open = openProp ?? uncontrolled;
+	const [overlayOpen, setOverlayOpen] = useState(false);
+	const narrow = useIsNarrow();
+	const sidebarId = useId();
+	const value = useMemo(() => {
+		const setOpen = (next) => {
+			if (openProp === void 0) 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 /* @__PURE__ */ jsx(SidebarContext.Provider, {
+		value,
+		children
+	});
+}
+function Sidebar({ className, label, mobileTitle, children, ...props }) {
+	const { open, narrow, overlayOpen, setOverlayOpen, sidebarId } = useSidebar("Sidebar");
+	return /* @__PURE__ */ jsxs(Fragment, { children: [narrow ? /* @__PURE__ */ jsx(Sheet, {
+		open: overlayOpen,
+		onOpenChange: setOverlayOpen,
+		children: /* @__PURE__ */ jsxs(SheetContent, {
+			side: "left",
+			className: "w-72 p-0",
+			children: [/* @__PURE__ */ jsx(SheetTitle, {
+				className: "sr-only",
+				children: mobileTitle ?? label
+			}), /* @__PURE__ */ jsx("nav", {
+				"aria-label": label,
+				className: "flex h-full flex-col gap-2 p-3",
+				children
+			})]
+		})
+	}) : null, /* @__PURE__ */ jsx("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,
+		children: /* @__PURE__ */ jsx("nav", {
+			"aria-label": label,
+			className: "flex h-full flex-col gap-2 p-3",
+			children
+		})
+	})] });
+}
+function SidebarHeader({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "sidebar-header",
+		className: cn("flex min-h-9 items-center gap-2 px-1", className),
+		...props
+	});
+}
+function SidebarContent({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "sidebar-content",
+		className: cn("flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto", className),
+		...props
+	});
+}
+function SidebarFooter({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "sidebar-footer",
+		className: cn("mt-auto", className),
+		...props
+	});
+}
+function SidebarGroup({ className, ...props }) {
+	return /* @__PURE__ */ jsx("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.
+*/
+function SidebarGroupLabel({ className, ...props }) {
+	const { open, narrow } = useSidebar("SidebarGroupLabel");
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "sidebar-group-label",
+		className: cn("px-2 text-xs font-medium tracking-wide text-muted-foreground uppercase", !open && !narrow && "sr-only", className),
+		...props
+	});
+}
+function SidebarMenu({ className, ...props }) {
+	return /* @__PURE__ */ jsx("ul", {
+		"data-slot": "sidebar-menu",
+		className: cn("grid gap-0.5", className),
+		...props
+	});
+}
+function SidebarMenuItem({ className, ...props }) {
+	return /* @__PURE__ */ jsx("li", {
+		"data-slot": "sidebar-menu-item",
+		className: cn("min-w-0", className),
+		...props
+	});
+}
+/**
+* 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.
+*/
+function SidebarMenuButton({ className, asChild = false, isActive = false, children, ...props }) {
+	const Component = asChild ? Slot.Root : "a";
+	return /* @__PURE__ */ jsx(Component, {
+		"data-slot": "sidebar-menu-button",
+		"data-active": isActive || void 0,
+		"aria-current": isActive ? "page" : void 0,
+		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
+	});
+}
+/**
+* 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".
+*/
+function SidebarMenuLabel({ className, ...props }) {
+	const { open, narrow } = useSidebar("SidebarMenuLabel");
+	return /* @__PURE__ */ jsx("span", {
+		"data-slot": "sidebar-menu-label",
+		className: cn("min-w-0 truncate", !open && !narrow && "sr-only", className),
+		...props
+	});
+}
+function SidebarTrigger({ className, label, ...props }) {
+	const { open, narrow, overlayOpen, toggle, sidebarId } = useSidebar("SidebarTrigger");
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-slot": "sidebar-trigger",
+		"aria-expanded": narrow ? overlayOpen : open,
+		"aria-controls": narrow ? void 0 : sidebarId,
+		"aria-label": label ?? (narrow ? overlayOpen ? "Close navigation" : "Open navigation" : open ? "Collapse navigation" : "Expand navigation"),
+		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,
+		children: /* @__PURE__ */ jsxs("svg", {
+			viewBox: "0 0 24 24",
+			fill: "none",
+			"aria-hidden": true,
+			className: "size-4",
+			children: [/* @__PURE__ */ jsx("rect", {
+				x: "3",
+				y: "4",
+				width: "18",
+				height: "16",
+				rx: "2",
+				stroke: "currentColor",
+				strokeWidth: "2"
+			}), /* @__PURE__ */ jsx("path", {
+				d: "M9 4v16",
+				stroke: "currentColor",
+				strokeWidth: "2"
+			})]
+		})
+	});
+}
+/** The region the sidebar sits beside. */
+function SidebarInset({ className, ...props }) {
+	return /* @__PURE__ */ jsx("main", {
+		"data-slot": "sidebar-inset",
+		className: cn("min-w-0 flex-1", className),
+		...props
+	});
+}
+//#endregion
+export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuLabel, SidebarProvider, SidebarTrigger };
+
+//# sourceMappingURL=sidebar.js.map

package/dist/components/sidebar/sidebar.js.map

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

package/dist/components/sync-status/index.d.ts

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

package/dist/components/sync-status/index.js

@@ -0,0 +1,2 @@
+import { SyncStatus, describeSyncState, syncState, useOnlineStatus } from "./sync-status.js";
+export { SyncStatus, describeSyncState, syncState, useOnlineStatus };

package/dist/components/sync-status/meta.js

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/sync-status/meta.ts
+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."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/sync-status/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/sync-status/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"sync-status\",\n  title: \"Sync Status\",\n  description: \"Offline, saving, saved or failed — with the count of changes being held.\",\n  category: \"feedback\",\n  status: \"stable\",\n  dependencies: [],\n  registryDependencies: [\"button\"],\n  files: [\"sync-status.tsx\"],\n  a11y:\n    \"The word is the status and the coloured dot is decoration, hidden from assistive \" +\n    \"technology. The visible text is not a live region: every save flips it and a region on it \" +\n    \"would narrate the whole session. A separate region, present from the first render, \" +\n    \"announces transitions only — went offline with what will happen to the changes, came back \" +\n    \"with what is being saved, could not save, saved after a failure — and never the churn of \" +\n    \"saving itself. Announcing is on by default because going offline is the one thing a reader \" +\n    \"who is typing has to be told, and it can be turned off. The server render assumes online, \" +\n    \"since a page with no interface to report has no business saying offline.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aAAa;CACb,UAAU;CACV,QAAQ;CACR,cAAc,CAAC;CACf,sBAAsB,CAAC,QAAQ;CAC/B,OAAO,CAAC,iBAAiB;CACzB,MACE;AAQJ,CAAC"}

package/dist/components/sync-status/sync-status.d.ts

@@ -0,0 +1,65 @@
+import { ComponentPropsWithRef } from "react";
+//#region src/components/sync-status/sync-status.d.ts
+/**
+ * "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.
+ */
+type SyncState = "synced" | "pending" | "syncing" | "offline" | "error";
+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.
+ */
+declare function syncState({ online, pending, syncing, error }: SyncInput): SyncState;
+/** The state as a sentence. Used for the visible text and the announcement. */
+declare function describeSyncState(state: SyncState, pending?: number, error?: string | null): string;
+/** Whether the browser believes it has a network. False is reliable; true is not. */
+declare function useOnlineStatus(): boolean;
+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;
+}
+declare function SyncStatus({ className, online: onlineProp, pending, syncing, error, lastSyncedAt, locale, onRetry, announce, ...props }: SyncStatusProps): import("react").JSX.Element;
+//#endregion
+export { SyncInput, SyncState, SyncStatus, SyncStatusProps, describeSyncState, syncState, useOnlineStatus };
+//# sourceMappingURL=sync-status.d.ts.map

package/dist/components/sync-status/sync-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-status.d.ts","names":[],"sources":["../../../src/components/sync-status/sync-status.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;KA+BY;UAEK;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;iBAQc,YACd,QACA,SACA,SACA,SACC,YAAY;;iBAWC,kBACd,OAAO,WACP,kBACA;;iBAmCc;UAIC,wBACP,KAAK,2CAA2C,KAAK;;EAE7D;;EAEA,eAAe;EACf;;EAEA;;;;;;EAMA;;iBAGc,aACd,WACA,QAAQ,YACR,SACA,SACA,OACA,cACA,QACA,SACA,aACG,SACF,kCAAe,IAAA"}

package/dist/components/sync-status/sync-status.js

@@ -0,0 +1,103 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { Button } from "../button/button.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState, useSyncExternalStore } from "react";
+//#region src/components/sync-status/sync-status.tsx
+/**
+* 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.
+*/
+function syncState({ online, pending = 0, syncing = false, error }) {
+	if (error) return "error";
+	if (!online) return "offline";
+	if (syncing) return "syncing";
+	if (pending > 0) return "pending";
+	return "synced";
+}
+const changes = (n) => `${String(n)} ${n === 1 ? "change" : "changes"}`;
+/** The state as a sentence. Used for the visible text and the announcement. */
+function describeSyncState(state, pending = 0, error) {
+	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();
+	}
+}
+function subscribeOnline(callback) {
+	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. */
+function useOnlineStatus() {
+	return useSyncExternalStore(subscribeOnline, readOnline, readOnlineOnServer);
+}
+function SyncStatus({ className, online: onlineProp, pending = 0, syncing = false, error, lastSyncedAt, locale, onRetry, announce = true, ...props }) {
+	const browserOnline = useOnlineStatus();
+	const state = syncState({
+		online: onlineProp ?? browserOnline,
+		pending,
+		syncing,
+		error
+	});
+	const text = describeSyncState(state, pending, error);
+	const [seen, setSeen] = useState(state);
+	const [announcement, setAnnouncement] = useState("");
+	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 !== void 0 ? new Intl.DateTimeFormat(locale, { timeStyle: "short" }).format(lastSyncedAt) : null;
+	return /* @__PURE__ */ jsxs("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,
+		children: [
+			/* @__PURE__ */ jsx("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")
+			}),
+			/* @__PURE__ */ jsxs("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"),
+				children: [text, savedAt && state === "synced" ? ` at ${savedAt}` : null]
+			}),
+			state === "error" && onRetry ? /* @__PURE__ */ jsx(Button, {
+				variant: "outline",
+				size: "sm",
+				className: "h-6 px-2 text-xs",
+				onClick: onRetry,
+				children: "Retry"
+			}) : null,
+			/* @__PURE__ */ jsx("span", {
+				role: "status",
+				"aria-live": announce ? "polite" : "off",
+				className: "sr-only",
+				children: announce ? announcement : ""
+			})
+		]
+	});
+}
+//#endregion
+export { SyncStatus, describeSyncState, syncState, useOnlineStatus };
+
+//# sourceMappingURL=sync-status.js.map

package/dist/components/sync-status/sync-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-status.js","names":[],"sources":["../../../src/components/sync-status/sync-status.tsx"],"sourcesContent":["\"use client\";\n\nimport { useState, useSyncExternalStore, type ComponentPropsWithRef } from \"react\";\n\nimport { Button } from \"@/components/button\";\nimport { cn } from \"@/lib/utils\";\n\n/**\n * \"Offline — 3 changes will sync when you're back.\"\n *\n * Linear, Notion, Figma and Google Docs each built this, and nothing in a\n * component library touches network state at all. It is small, and it is\n * the difference between an app that loses work and one that says it is\n * holding it: the moment a request fails, the reader needs to know whether\n * to keep typing, and whether what they typed a minute ago is anywhere.\n *\n * Two things this gets right that the obvious version gets wrong.\n *\n * `navigator.onLine` is believed in one direction only. False is reliable —\n * the interface is down. True means only that there is an interface, not\n * that the server is reachable, so an application's own failed request is\n * the real signal and takes precedence. The hook is exported for the rest\n * of the app to share the same reading.\n *\n * Announcements are for transitions, not states. Every save flips\n * \"Saving…\" to \"Saved\", and a live region on that text narrates the whole\n * session. So the visible text is not live; a separate region says something\n * only when the situation changes — went offline, came back, could not sync —\n * which is when a reader who is typing needs to be told.\n */\n\nexport type SyncState = \"synced\" | \"pending\" | \"syncing\" | \"offline\" | \"error\";\n\nexport interface SyncInput {\n  /** From `useOnlineStatus`, or your own reading. */\n  online: boolean;\n  /** Changes waiting to be sent. */\n  pending?: number;\n  /** A send is in flight. */\n  syncing?: boolean;\n  /** The last send failed, in the reader's language. Takes precedence over `online`. */\n  error?: string | null;\n}\n\n/**\n * Which state the inputs amount to. Error beats offline beats syncing beats\n * pending beats synced: each one is the thing the reader most needs to know\n * given the others.\n */\nexport function syncState({\n  online,\n  pending = 0,\n  syncing = false,\n  error,\n}: SyncInput): SyncState {\n  if (error) return \"error\";\n  if (!online) return \"offline\";\n  if (syncing) return \"syncing\";\n  if (pending > 0) return \"pending\";\n  return \"synced\";\n}\n\nconst changes = (n: number) => `${String(n)} ${n === 1 ? \"change\" : \"changes\"}`;\n\n/** The state as a sentence. Used for the visible text and the announcement. */\nexport function describeSyncState(\n  state: SyncState,\n  pending = 0,\n  error?: string | null,\n): string {\n  switch (state) {\n    case \"synced\":\n      return \"All changes saved\";\n    case \"pending\":\n      return `${changes(pending)} waiting to save`;\n    case \"syncing\":\n      return pending > 0 ? `Saving ${changes(pending)}…` : \"Saving…\";\n    case \"offline\":\n      return pending > 0\n        ? `Offline. ${changes(pending)} will save when you're back online.`\n        : \"Offline. Changes will save when you're back online.\";\n    case \"error\":\n      return pending > 0\n        ? `Could not save ${changes(pending)}. ${error ?? \"\"}`.trim()\n        : `Could not save. ${error ?? \"\"}`.trim();\n  }\n}\n\n/* The browser's reading of the network, as an external store. The server\n   snapshot is \"online\": a page rendered on the server has no interface to\n   report, and rendering \"offline\" into HTML would be a lie until hydration. */\nfunction subscribeOnline(callback: () => void) {\n  window.addEventListener(\"online\", callback);\n  window.addEventListener(\"offline\", callback);\n  return () => {\n    window.removeEventListener(\"online\", callback);\n    window.removeEventListener(\"offline\", callback);\n  };\n}\nconst readOnline = () => navigator.onLine;\nconst readOnlineOnServer = () => true;\n\n/** Whether the browser believes it has a network. False is reliable; true is not. */\nexport function useOnlineStatus(): boolean {\n  return useSyncExternalStore(subscribeOnline, readOnline, readOnlineOnServer);\n}\n\nexport interface SyncStatusProps\n  extends Omit<ComponentPropsWithRef<\"div\">, \"children\">, Omit<SyncInput, \"online\"> {\n  /** Omit to read the browser's own status. */\n  online?: boolean;\n  /** When the last save succeeded. Shown as a time, not a relative phrase, so no clock is needed. */\n  lastSyncedAt?: Date;\n  locale?: string;\n  /** Offered when a save failed. */\n  onRetry?: () => void;\n  /**\n   * Announce transitions. On by default, because going offline is the one\n   * thing a reader who is typing has to be told; syncing itself never\n   * announces, whichever way this is set.\n   */\n  announce?: boolean;\n}\n\nexport function SyncStatus({\n  className,\n  online: onlineProp,\n  pending = 0,\n  syncing = false,\n  error,\n  lastSyncedAt,\n  locale,\n  onRetry,\n  announce = true,\n  ...props\n}: SyncStatusProps) {\n  const browserOnline = useOnlineStatus();\n  const online = onlineProp ?? browserOnline;\n  const state = syncState({ online, pending, syncing, error });\n  const text = describeSyncState(state, pending, error);\n\n  // Said once, when the situation changes. Adjusted during render so the\n  // announcement lands in the same commit as the state it describes. Syncing\n  // and pending are the ordinary churn of saving and are never announced.\n  const [seen, setSeen] = useState(state);\n  const [announcement, setAnnouncement] = useState(\"\");\n  // A failure is over when a save lands, not when the retry starts, so the\n  // recovery is remembered across the syncing in between.\n  const [recovering, setRecovering] = useState(false);\n  if (seen !== state) {\n    const from = seen;\n    setSeen(state);\n    if (state === \"offline\" || state === \"error\") {\n      setAnnouncement(text);\n      setRecovering(false);\n    } else if (from === \"offline\") {\n      setAnnouncement(\n        pending > 0 ? `Back online. Saving ${changes(pending)}.` : \"Back online.\",\n      );\n    } else if ((from === \"error\" || recovering) && state === \"synced\") {\n      setAnnouncement(\"Saved.\");\n      setRecovering(false);\n    } else if (from === \"error\") {\n      setRecovering(true);\n    }\n  }\n\n  const savedAt =\n    lastSyncedAt !== undefined\n      ? new Intl.DateTimeFormat(locale, { timeStyle: \"short\" }).format(lastSyncedAt)\n      : null;\n\n  return (\n    <div\n      data-slot=\"sync-status\"\n      data-state={state}\n      className={cn(\"flex flex-wrap items-center gap-x-2 gap-y-1 text-xs\", className)}\n      {...props}\n    >\n      {/* The dot is decoration. The word is the status. */}\n      <span\n        aria-hidden=\"true\"\n        className={cn(\n          \"size-2 shrink-0 rounded-full\",\n          state === \"synced\" && \"bg-success\",\n          state === \"pending\" && \"bg-muted-foreground\",\n          state === \"syncing\" && \"animate-pulse-soft bg-info\",\n          state === \"offline\" && \"bg-warning\",\n          state === \"error\" && \"bg-destructive\",\n        )}\n      />\n      <span\n        data-slot=\"sync-status-text\"\n        className={cn(\n          state === \"offline\" && \"text-warning\",\n          state === \"error\" && \"text-destructive\",\n          (state === \"synced\" || state === \"pending\" || state === \"syncing\") &&\n            \"text-muted-foreground\",\n        )}\n      >\n        {text}\n        {savedAt && state === \"synced\" ? ` at ${savedAt}` : null}\n      </span>\n\n      {state === \"error\" && onRetry ? (\n        <Button variant=\"outline\" size=\"sm\" className=\"h-6 px-2 text-xs\" onClick={onRetry}>\n          Retry\n        </Button>\n      ) : null}\n\n      {/* Present from the start, so the first transition is heard. */}\n      <span role=\"status\" aria-live={announce ? \"polite\" : \"off\"} className=\"sr-only\">\n        {announce ? announcement : \"\"}\n      </span>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;AAiDA,SAAgB,UAAU,EACxB,QACA,UAAU,GACV,UAAU,OACV,SACuB;CACvB,IAAI,OAAO,OAAO;CAClB,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,SAAS,OAAO;CACpB,IAAI,UAAU,GAAG,OAAO;CACxB,OAAO;AACT;AAEA,MAAM,WAAW,MAAc,GAAG,OAAO,CAAC,EAAE,GAAG,MAAM,IAAI,WAAW;;AAGpE,SAAgB,kBACd,OACA,UAAU,GACV,OACQ;CACR,QAAQ,OAAR;EACE,KAAK,UACH,OAAO;EACT,KAAK,WACH,OAAO,GAAG,QAAQ,OAAO,EAAE;EAC7B,KAAK,WACH,OAAO,UAAU,IAAI,UAAU,QAAQ,OAAO,EAAE,KAAK;EACvD,KAAK,WACH,OAAO,UAAU,IACb,YAAY,QAAQ,OAAO,EAAE,uCAC7B;EACN,KAAK,SACH,OAAO,UAAU,IACb,kBAAkB,QAAQ,OAAO,EAAE,IAAI,SAAS,KAAK,KAAK,IAC1D,mBAAmB,SAAS,KAAK,KAAK;CAC9C;AACF;AAKA,SAAS,gBAAgB,UAAsB;CAC7C,OAAO,iBAAiB,UAAU,QAAQ;CAC1C,OAAO,iBAAiB,WAAW,QAAQ;CAC3C,aAAa;EACX,OAAO,oBAAoB,UAAU,QAAQ;EAC7C,OAAO,oBAAoB,WAAW,QAAQ;CAChD;AACF;AACA,MAAM,mBAAmB,UAAU;AACnC,MAAM,2BAA2B;;AAGjC,SAAgB,kBAA2B;CACzC,OAAO,qBAAqB,iBAAiB,YAAY,kBAAkB;AAC7E;AAmBA,SAAgB,WAAW,EACzB,WACA,QAAQ,YACR,UAAU,GACV,UAAU,OACV,OACA,cACA,QACA,SACA,WAAW,MACX,GAAG,SACe;CAClB,MAAM,gBAAgB,gBAAgB;CAEtC,MAAM,QAAQ,UAAU;EAAE,QADX,cAAc;EACK;EAAS;EAAS;CAAM,CAAC;CAC3D,MAAM,OAAO,kBAAkB,OAAO,SAAS,KAAK;CAKpD,MAAM,CAAC,MAAM,WAAW,SAAS,KAAK;CACtC,MAAM,CAAC,cAAc,mBAAmB,SAAS,EAAE;CAGnD,MAAM,CAAC,YAAY,iBAAiB,SAAS,KAAK;CAClD,IAAI,SAAS,OAAO;EAClB,MAAM,OAAO;EACb,QAAQ,KAAK;EACb,IAAI,UAAU,aAAa,UAAU,SAAS;GAC5C,gBAAgB,IAAI;GACpB,cAAc,KAAK;EACrB,OAAO,IAAI,SAAS,WAClB,gBACE,UAAU,IAAI,uBAAuB,QAAQ,OAAO,EAAE,KAAK,cAC7D;OACK,KAAK,SAAS,WAAW,eAAe,UAAU,UAAU;GACjE,gBAAgB,QAAQ;GACxB,cAAc,KAAK;EACrB,OAAO,IAAI,SAAS,SAClB,cAAc,IAAI;CAEtB;CAEA,MAAM,UACJ,iBAAiB,KAAA,IACb,IAAI,KAAK,eAAe,QAAQ,EAAE,WAAW,QAAQ,CAAC,CAAC,CAAC,OAAO,YAAY,IAC3E;CAEN,OACE,qBAAC,OAAD;EACE,aAAU;EACV,cAAY;EACZ,WAAW,GAAG,uDAAuD,SAAS;EAC9E,GAAI;EAJN,UAAA;GAOE,oBAAC,QAAD;IACE,eAAY;IACZ,WAAW,GACT,gCACA,UAAU,YAAY,cACtB,UAAU,aAAa,uBACvB,UAAU,aAAa,8BACvB,UAAU,aAAa,cACvB,UAAU,WAAW,gBACvB;GACD,CAAA;GACD,qBAAC,QAAD;IACE,aAAU;IACV,WAAW,GACT,UAAU,aAAa,gBACvB,UAAU,WAAW,qBACpB,UAAU,YAAY,UAAU,aAAa,UAAU,cACtD,uBACJ;IAPF,UAAA,CASG,MACA,WAAW,UAAU,WAAW,OAAO,YAAY,IAChD;;GAEL,UAAU,WAAW,UACpB,oBAAC,QAAD;IAAQ,SAAQ;IAAU,MAAK;IAAK,WAAU;IAAmB,SAAS;IAAS,UAAA;GAE3E,CAAA,IACN;GAGJ,oBAAC,QAAD;IAAM,MAAK;IAAS,aAAW,WAAW,WAAW;IAAO,WAAU;IACnE,UAAA,WAAW,eAAe;GACvB,CAAA;EACH;;AAET"}