@dowel-ui/react 0.3.0 → 0.5.0

package/dist/components/shortcut-recorder/shortcut-recorder.js

@@ -0,0 +1,212 @@
+"use client";
+import { disabledStyles, focusRing } from "../../lib/styles.js";
+import { cn } from "../../lib/utils.js";
+import { describeShortcut, detectPlatform, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual } from "./shortcut-model.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useId, useState, useSyncExternalStore } from "react";
+//#region src/components/shortcut-recorder/shortcut-recorder.tsx
+const subscribeToNothing = () => () => void 0;
+const readPlatform = () => detectPlatform();
+const readNeutralPlatform = () => "other";
+function ShortcutRecorder({ className, label, value: valueProp, defaultValue = null, onChange, taken = [], platform: platformProp, requireModifier = true, ...props }) {
+	const id = useId();
+	const detected = useSyncExternalStore(subscribeToNothing, readPlatform, readNeutralPlatform);
+	const platform = platformProp ?? detected;
+	const [uncontrolled, setUncontrolled] = useState(defaultValue);
+	const value = valueProp === void 0 ? uncontrolled : valueProp;
+	const current = value ? safeParse(value) : null;
+	const [recording, setRecording] = useState(false);
+	/** Modifiers held mid-chord, shown so the person sees the recorder listening. */
+	const [held, setHeld] = useState(null);
+	const [conflict, setConflict] = useState(null);
+	const [announcement, setAnnouncement] = useState("");
+	const commit = (next) => {
+		const serialized = next ? serializeShortcut(next) : null;
+		setUncontrolled(serialized);
+		onChange?.(serialized);
+	};
+	const stop = () => {
+		setRecording(false);
+		setHeld(null);
+	};
+	const onKeyDown = (event) => {
+		if (!recording) return;
+		if (event.key === "Tab") {
+			stop();
+			setAnnouncement("Cancelled.");
+			return;
+		}
+		event.preventDefault();
+		if (event.key === "Escape") {
+			stop();
+			setAnnouncement("Cancelled.");
+			return;
+		}
+		if ((event.key === "Backspace" || event.key === "Delete") && !hasModifier(event)) {
+			stop();
+			commit(null);
+			setAnnouncement("Cleared.");
+			return;
+		}
+		const chord = shortcutFromKey(event.nativeEvent, platform);
+		if (!chord) {
+			setHeld({
+				key: "",
+				mod: platform === "mac" ? event.metaKey : event.ctrlKey,
+				ctrl: platform === "mac" ? event.ctrlKey : false,
+				alt: event.altKey,
+				shift: event.shiftKey
+			});
+			return;
+		}
+		if (requireModifier && needsModifier(chord)) {
+			setAnnouncement(`${describeShortcut(chord, platform)} needs a modifier — it would fire while typing. Try again.`);
+			setHeld(null);
+			return;
+		}
+		const clash = taken.find((entry) => shortcutsEqual(safeParse(entry.shortcut) ?? chord, chord));
+		stop();
+		if (clash && !(current && shortcutsEqual(current, chord))) {
+			setConflict({
+				shortcut: chord,
+				with: clash
+			});
+			setAnnouncement(`${describeShortcut(chord, platform)} is already used by ${clash.label}.`);
+			return;
+		}
+		commit(chord);
+		setAnnouncement(`Recorded ${describeShortcut(chord, platform)}.`);
+	};
+	const onKeyUp = (event) => {
+		if (!recording || !held) return;
+		setHeld({
+			key: "",
+			mod: platform === "mac" ? event.metaKey : event.ctrlKey,
+			ctrl: platform === "mac" ? event.ctrlKey : false,
+			alt: event.altKey,
+			shift: event.shiftKey
+		});
+	};
+	const shown = recording ? held : current;
+	const description = recording ? "Press the keys you want. Escape cancels, Backspace clears." : current ? `${describeShortcut(current, platform)}. Press to change.` : "Not set. Press to record.";
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "shortcut-recorder",
+		"data-state": recording ? "recording" : conflict ? "conflict" : current ? "set" : "empty",
+		className: cn("flex flex-col gap-1.5", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				id: `${id}-label`,
+				className: "text-xs font-medium",
+				children: label
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-wrap items-center gap-2",
+				children: [/* @__PURE__ */ jsx("button", {
+					type: "button",
+					"aria-labelledby": `${id}-label`,
+					"aria-describedby": `${id}-description`,
+					"aria-pressed": recording,
+					className: cn("flex h-9 min-w-32 items-center justify-center gap-1 rounded-md border px-3 font-mono text-sm", recording ? "border-primary bg-primary/5 text-muted-foreground" : "border-input bg-background hover:bg-accent", focusRing, disabledStyles),
+					onClick: () => {
+						if (recording) return;
+						setConflict(null);
+						setRecording(true);
+						setAnnouncement("");
+					},
+					onKeyDown,
+					onKeyUp,
+					onBlur: () => {
+						if (recording) {
+							stop();
+							setAnnouncement("Cancelled.");
+						}
+					},
+					children: /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						className: "flex items-center gap-1",
+						children: shown && (shown.key || shown.mod || shown.ctrl || shown.alt || shown.shift) ? shortcutParts(shown, platform).filter(Boolean).map((part, index) => /* @__PURE__ */ jsx("kbd", {
+							className: "rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-xs",
+							children: part
+						}, index)) : recording ? /* @__PURE__ */ jsx("span", {
+							className: "text-xs",
+							children: "Press keys…"
+						}) : /* @__PURE__ */ jsx("span", {
+							className: "text-xs text-muted-foreground",
+							children: "Not set"
+						})
+					})
+				}), current && !recording ? /* @__PURE__ */ jsx("button", {
+					type: "button",
+					"aria-label": `Clear — ${label}`,
+					className: cn("rounded-md border border-input bg-background px-2.5 py-1 text-xs font-medium hover:bg-accent", focusRing),
+					onClick: () => {
+						commit(null);
+						setConflict(null);
+						setAnnouncement("Cleared.");
+					},
+					children: "Clear"
+				}) : null]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				id: `${id}-description`,
+				className: "text-xs text-muted-foreground",
+				children: description
+			}),
+			conflict ? /* @__PURE__ */ jsxs("div", {
+				"data-slot": "shortcut-conflict",
+				className: "flex flex-wrap items-center gap-2 rounded-md border border-warning/50 bg-warning/5 px-2.5 py-1.5 text-xs",
+				children: [
+					/* @__PURE__ */ jsxs("span", {
+						className: "flex-1 text-warning",
+						children: [
+							describeShortcut(conflict.shortcut, platform),
+							" is already used by",
+							" ",
+							/* @__PURE__ */ jsx("strong", { children: conflict.with.label }),
+							"."
+						]
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: cn("rounded-md border border-input bg-background px-2 py-0.5 font-medium hover:bg-accent", focusRing),
+						onClick: () => {
+							commit(conflict.shortcut);
+							setConflict(null);
+							setAnnouncement(`Recorded ${describeShortcut(conflict.shortcut, platform)}. ${conflict.with.label} no longer has a shortcut.`);
+						},
+						children: "Use anyway"
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: cn("rounded-md border border-input bg-background px-2 py-0.5 font-medium hover:bg-accent", focusRing),
+						onClick: () => {
+							setConflict(null);
+						},
+						children: "Keep the old one"
+					})
+				]
+			}) : null,
+			/* @__PURE__ */ jsx("span", {
+				role: "status",
+				"aria-live": "polite",
+				className: "sr-only",
+				children: announcement
+			})
+		]
+	});
+}
+function hasModifier(event) {
+	return event.metaKey || event.ctrlKey || event.altKey || event.shiftKey;
+}
+function safeParse(text) {
+	try {
+		return parseShortcut(text);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { ShortcutRecorder };
+
+//# sourceMappingURL=shortcut-recorder.js.map

package/dist/components/shortcut-recorder/shortcut-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut-recorder.js","names":[],"sources":["../../../src/components/shortcut-recorder/shortcut-recorder.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  useId,\n  useState,\n  useSyncExternalStore,\n  type ComponentPropsWithRef,\n  type KeyboardEvent,\n} from \"react\";\n\nimport { disabledStyles, focusRing } from \"@/lib/styles\";\nimport { cn } from \"@/lib/utils\";\n\nimport {\n  describeShortcut,\n  detectPlatform,\n  needsModifier,\n  parseShortcut,\n  serializeShortcut,\n  shortcutFromKey,\n  shortcutParts,\n  shortcutsEqual,\n  type Platform,\n  type Shortcut,\n} from \"./shortcut-model\";\n\n/**\n * Press the keys you want.\n *\n * Linear, Slack, VS Code, Figma and Superhuman each wrote one, and no\n * component library ships the recorder — only the `<kbd>` that displays the\n * result. The recorder is the hard part: a button that, when pressed, stops\n * being a button and starts being a keyboard listener, and has to come back.\n *\n * Three things it does that a listener bolted onto an input does not. It\n * reads letters from `code`, not `key`, so Option-K records as Option K and\n * not as the ˚ the Mac produced. It stores `Mod`, not Command or Control,\n * so a binding saved on one machine is right on the other. And it refuses a\n * bare printable key by saying so, because a shortcut that fires while\n * someone types a sentence is the bug every app that allowed it later fixed.\n *\n * Tab and Escape are never recorded: Tab leaves, Escape cancels, and a\n * recorder that captures both is a keyboard trap with a nice label. A\n * chord that another command already uses is said, with that command's\n * name, and applied only if the person says to use it anyway.\n */\n\nexport interface TakenShortcut {\n  /** Stored form: `Mod+K`. */\n  shortcut: string;\n  /** What it does: \"Search\". */\n  label: string;\n}\n\nexport interface ShortcutRecorderProps extends Omit<\n  ComponentPropsWithRef<\"div\">,\n  \"onChange\" | \"defaultValue\"\n> {\n  /** What the shortcut triggers: \"Open search\". Names the control. */\n  label: string;\n  /** Stored form, `Mod+Shift+K`, or null for none. Controlled. */\n  value?: string | null;\n  defaultValue?: string | null;\n  onChange?: (value: string | null) => void;\n  /** Shortcuts other commands already use. A clash is said, and applied only on request. */\n  taken?: TakenShortcut[];\n  /** Mac shows ⌘⇧K; everything else shows Ctrl+Shift+K. Detected if omitted. */\n  platform?: Platform;\n  /** Printable keys need a modifier. On by default, for the reason in the source. */\n  requireModifier?: boolean;\n}\n\n/* The platform, as an external store that never changes: a constant that the\n   server cannot know, so the server snapshot is the neutral one and the real\n   answer arrives after hydration without a mismatch. */\nconst subscribeToNothing = () => () => undefined;\nconst readPlatform = () => detectPlatform();\nconst readNeutralPlatform = (): Platform => \"other\";\n\nexport function ShortcutRecorder({\n  className,\n  label,\n  value: valueProp,\n  defaultValue = null,\n  onChange,\n  taken = [],\n  platform: platformProp,\n  requireModifier = true,\n  ...props\n}: ShortcutRecorderProps) {\n  const id = useId();\n  const detected = useSyncExternalStore(subscribeToNothing, readPlatform, readNeutralPlatform);\n  const platform = platformProp ?? detected;\n\n  const [uncontrolled, setUncontrolled] = useState<string | null>(defaultValue);\n  const value = valueProp === undefined ? uncontrolled : valueProp;\n  const current = value ? safeParse(value) : null;\n\n  const [recording, setRecording] = useState(false);\n  /** Modifiers held mid-chord, shown so the person sees the recorder listening. */\n  const [held, setHeld] = useState<Shortcut | null>(null);\n  const [conflict, setConflict] = useState<{ shortcut: Shortcut; with: TakenShortcut } | null>(\n    null,\n  );\n  const [announcement, setAnnouncement] = useState(\"\");\n\n  const commit = (next: Shortcut | null) => {\n    const serialized = next ? serializeShortcut(next) : null;\n    setUncontrolled(serialized);\n    onChange?.(serialized);\n  };\n\n  const stop = () => {\n    setRecording(false);\n    setHeld(null);\n  };\n\n  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {\n    if (!recording) return;\n    // Tab leaves. A recorder that keeps it is a keyboard trap.\n    if (event.key === \"Tab\") {\n      stop();\n      setAnnouncement(\"Cancelled.\");\n      return;\n    }\n    event.preventDefault();\n    if (event.key === \"Escape\") {\n      stop();\n      setAnnouncement(\"Cancelled.\");\n      return;\n    }\n    if ((event.key === \"Backspace\" || event.key === \"Delete\") && !hasModifier(event)) {\n      stop();\n      commit(null);\n      setAnnouncement(\"Cleared.\");\n      return;\n    }\n\n    const chord = shortcutFromKey(event.nativeEvent, platform);\n    if (!chord) {\n      // Only modifiers so far. Show them, keep listening.\n      setHeld({\n        key: \"\",\n        mod: platform === \"mac\" ? event.metaKey : event.ctrlKey,\n        ctrl: platform === \"mac\" ? event.ctrlKey : false,\n        alt: event.altKey,\n        shift: event.shiftKey,\n      });\n      return;\n    }\n\n    if (requireModifier && needsModifier(chord)) {\n      setAnnouncement(\n        `${describeShortcut(chord, platform)} needs a modifier — it would fire while typing. Try again.`,\n      );\n      setHeld(null);\n      return;\n    }\n\n    const clash = taken.find((entry) =>\n      shortcutsEqual(safeParse(entry.shortcut) ?? chord, chord),\n    );\n    stop();\n    if (clash && !(current && shortcutsEqual(current, chord))) {\n      setConflict({ shortcut: chord, with: clash });\n      setAnnouncement(\n        `${describeShortcut(chord, platform)} is already used by ${clash.label}.`,\n      );\n      return;\n    }\n    commit(chord);\n    setAnnouncement(`Recorded ${describeShortcut(chord, platform)}.`);\n  };\n\n  const onKeyUp = (event: KeyboardEvent<HTMLButtonElement>) => {\n    if (!recording || !held) return;\n    setHeld({\n      key: \"\",\n      mod: platform === \"mac\" ? event.metaKey : event.ctrlKey,\n      ctrl: platform === \"mac\" ? event.ctrlKey : false,\n      alt: event.altKey,\n      shift: event.shiftKey,\n    });\n  };\n\n  const shown = recording ? held : current;\n  const description = recording\n    ? \"Press the keys you want. Escape cancels, Backspace clears.\"\n    : current\n      ? `${describeShortcut(current, platform)}. Press to change.`\n      : \"Not set. Press to record.\";\n\n  return (\n    <div\n      data-slot=\"shortcut-recorder\"\n      data-state={recording ? \"recording\" : conflict ? \"conflict\" : current ? \"set\" : \"empty\"}\n      className={cn(\"flex flex-col gap-1.5\", className)}\n      {...props}\n    >\n      <span id={`${id}-label`} className=\"text-xs font-medium\">\n        {label}\n      </span>\n\n      <div className=\"flex flex-wrap items-center gap-2\">\n        <button\n          type=\"button\"\n          aria-labelledby={`${id}-label`}\n          aria-describedby={`${id}-description`}\n          aria-pressed={recording}\n          className={cn(\n            \"flex h-9 min-w-32 items-center justify-center gap-1 rounded-md border px-3 font-mono text-sm\",\n            recording\n              ? \"border-primary bg-primary/5 text-muted-foreground\"\n              : \"border-input bg-background hover:bg-accent\",\n            focusRing,\n            disabledStyles,\n          )}\n          onClick={() => {\n            if (recording) return;\n            setConflict(null);\n            setRecording(true);\n            setAnnouncement(\"\");\n          }}\n          onKeyDown={onKeyDown}\n          onKeyUp={onKeyUp}\n          onBlur={() => {\n            if (recording) {\n              stop();\n              setAnnouncement(\"Cancelled.\");\n            }\n          }}\n        >\n          {/* Symbols and key caps are for the eye; the description says the\n              same thing in words. */}\n          <span aria-hidden=\"true\" className=\"flex items-center gap-1\">\n            {shown && (shown.key || shown.mod || shown.ctrl || shown.alt || shown.shift) ? (\n              shortcutParts(shown, platform)\n                .filter(Boolean)\n                .map((part, index) => (\n                  <kbd\n                    key={index}\n                    className=\"rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-xs\"\n                  >\n                    {part}\n                  </kbd>\n                ))\n            ) : recording ? (\n              <span className=\"text-xs\">Press keys…</span>\n            ) : (\n              <span className=\"text-xs text-muted-foreground\">Not set</span>\n            )}\n          </span>\n        </button>\n\n        {current && !recording ? (\n          <button\n            type=\"button\"\n            aria-label={`Clear — ${label}`}\n            className={cn(\n              \"rounded-md border border-input bg-background px-2.5 py-1 text-xs font-medium hover:bg-accent\",\n              focusRing,\n            )}\n            onClick={() => {\n              commit(null);\n              setConflict(null);\n              setAnnouncement(\"Cleared.\");\n            }}\n          >\n            Clear\n          </button>\n        ) : null}\n      </div>\n\n      <p id={`${id}-description`} className=\"text-xs text-muted-foreground\">\n        {description}\n      </p>\n\n      {conflict ? (\n        <div\n          data-slot=\"shortcut-conflict\"\n          className=\"flex flex-wrap items-center gap-2 rounded-md border border-warning/50 bg-warning/5 px-2.5 py-1.5 text-xs\"\n        >\n          <span className=\"flex-1 text-warning\">\n            {describeShortcut(conflict.shortcut, platform)} is already used by{\" \"}\n            <strong>{conflict.with.label}</strong>.\n          </span>\n          <button\n            type=\"button\"\n            className={cn(\n              \"rounded-md border border-input bg-background px-2 py-0.5 font-medium hover:bg-accent\",\n              focusRing,\n            )}\n            onClick={() => {\n              commit(conflict.shortcut);\n              setConflict(null);\n              setAnnouncement(\n                `Recorded ${describeShortcut(conflict.shortcut, platform)}. ${conflict.with.label} no longer has a shortcut.`,\n              );\n            }}\n          >\n            Use anyway\n          </button>\n          <button\n            type=\"button\"\n            className={cn(\n              \"rounded-md border border-input bg-background px-2 py-0.5 font-medium hover:bg-accent\",\n              focusRing,\n            )}\n            onClick={() => {\n              setConflict(null);\n            }}\n          >\n            Keep the old one\n          </button>\n        </div>\n      ) : null}\n\n      {/* Present from the start, so the first outcome is heard. */}\n      <span role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n        {announcement}\n      </span>\n    </div>\n  );\n}\n\nfunction hasModifier(event: KeyboardEvent): boolean {\n  return event.metaKey || event.ctrlKey || event.altKey || event.shiftKey;\n}\n\nfunction safeParse(text: string): Shortcut | null {\n  try {\n    return parseShortcut(text);\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"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"}

package/dist/components/spinner/spinner.d.ts

@@ -2,7 +2,7 @@ import { VariantProps } from "class-variance-authority";
 import { ComponentPropsWithRef } from "react";
 //#region src/components/spinner/spinner.d.ts
 declare const spinnerVariants: (props?: ({
-  size?: "sm" | "md" | "lg" | "xs" | "xl" | null | undefined;
+  size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface SpinnerProps extends Omit<ComponentPropsWithRef<"svg">, "children">, VariantProps<typeof spinnerVariants> {
   /**

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":"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"}

package/dist/components/time-range-picker/index.d.ts

@@ -0,0 +1,3 @@
+import { DEFAULT_PRESETS, ResolveOptions, ResolvedRange, TimeExpressionError, TimeRangePreset, TimeUnit, absoluteExpression, describeTimeRange, formatResolvedRange, isValidTimeRange, resolveExpression, resolveTimeRange } from "./time-expression.js";
+import { TimeRange, TimeRangeCalendar, TimeRangeContent, TimeRangeContentProps, TimeRangeExpression, TimeRangePresets, TimeRangeProps, TimeRangeTrigger, TimeRangeTriggerProps } from "./time-range-picker.js";
+export { DEFAULT_PRESETS, type ResolveOptions, type ResolvedRange, TimeExpressionError, TimeRange, TimeRangeCalendar, TimeRangeContent, type TimeRangeContentProps, TimeRangeExpression, type TimeRangePreset, TimeRangePresets, type TimeRangeProps, TimeRangeTrigger, type TimeRangeTriggerProps, type TimeUnit, absoluteExpression, describeTimeRange, formatResolvedRange, isValidTimeRange, resolveExpression, resolveTimeRange };

package/dist/components/time-range-picker/index.js

@@ -0,0 +1,3 @@
+import { DEFAULT_PRESETS, TimeExpressionError, absoluteExpression, describeTimeRange, formatResolvedRange, isValidTimeRange, resolveExpression, resolveTimeRange } from "./time-expression.js";
+import { TimeRange, TimeRangeCalendar, TimeRangeContent, TimeRangeExpression, TimeRangePresets, TimeRangeTrigger } from "./time-range-picker.js";
+export { DEFAULT_PRESETS, TimeExpressionError, TimeRange, TimeRangeCalendar, TimeRangeContent, TimeRangeExpression, TimeRangePresets, TimeRangeTrigger, absoluteExpression, describeTimeRange, formatResolvedRange, isValidTimeRange, resolveExpression, resolveTimeRange };

package/dist/components/time-range-picker/meta.js

@@ -0,0 +1,22 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/time-range-picker/meta.ts
+const meta = defineMeta({
+	name: "time-range-picker",
+	title: "Time Range Picker",
+	description: "A time range whose value is an expression, so it stays relative across a reload.",
+	category: "form",
+	status: "stable",
+	dependencies: ["react-day-picker"],
+	registryDependencies: [
+		"button",
+		"calendar",
+		"input",
+		"popover"
+	],
+	files: ["time-expression.ts", "time-range-picker.tsx"],
+	a11y: "The trigger is named by the range it holds — \"Last 6 hours\" — and the window that resolves to is read after it, so the relative choice is not replaced by two timestamps. The popover carries role=\"dialog\" and is named. Presets are buttons rather than radios because choosing one both selects and dismisses, with aria-pressed carrying which matches the current expression. The expression field reports why an unparseable entry is invalid through one aria-describedby element that the preview and the error share, so a reader hears the error replace the preview rather than both at once; an invalid expression is never applied, because a chart silently re-scoping itself is worse than one that refuses."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/time-range-picker/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/time-range-picker/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"time-range-picker\",\n  title: \"Time Range Picker\",\n  description:\n    \"A time range whose value is an expression, so it stays relative across a reload.\",\n  category: \"form\",\n  status: \"stable\",\n  dependencies: [\"react-day-picker\"],\n  registryDependencies: [\"button\", \"calendar\", \"input\", \"popover\"],\n  files: [\"time-expression.ts\", \"time-range-picker.tsx\"],\n  a11y:\n    'The trigger is named by the range it holds — \"Last 6 hours\" — and the window that ' +\n    \"resolves to is read after it, so the relative choice is not replaced by two timestamps. \" +\n    'The popover carries role=\"dialog\" and is named. Presets are buttons rather than radios ' +\n    \"because choosing one both selects and dismisses, with aria-pressed carrying which matches \" +\n    \"the current expression. The expression field reports why an unparseable entry is invalid \" +\n    \"through one aria-describedby element that the preview and the error share, so a reader \" +\n    \"hears the error replace the preview rather than both at once; an invalid expression is \" +\n    \"never applied, because a chart silently re-scoping itself is worse than one that refuses.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aACE;CACF,UAAU;CACV,QAAQ;CACR,cAAc,CAAC,kBAAkB;CACjC,sBAAsB;EAAC;EAAU;EAAY;EAAS;CAAS;CAC/D,OAAO,CAAC,sBAAsB,uBAAuB;CACrD,MACE;AAQJ,CAAC"}

package/dist/components/time-range-picker/time-expression.d.ts

@@ -0,0 +1,88 @@
+//#region src/components/time-range-picker/time-expression.d.ts
+/**
+ * Time ranges as expressions, not as two frozen timestamps.
+ *
+ * `now-6h` is still the last six hours tomorrow; a resolved pair is six hours
+ * of last Tuesday forever. Storing the expression is what lets a dashboard URL
+ * survive being bookmarked and reloaded.
+ *
+ * The grammar is a deliberate subset of the one Grafana, Datadog and Kibana
+ * converged on, so the strings are already familiar:
+ *
+ *   range  := expr ".." expr
+ *   expr   := "now" offset* snap? | ISO-8601
+ *   offset := ("-" | "+") digits unit
+ *   snap   := "/" unit
+ *   unit   := s | m | h | d | w | M | y
+ *
+ *   now-6h..now          the last six hours
+ *   now-6h/h..now        the last six hours, starting on the hour
+ *   now/d..now/d         today, all of it
+ *   now-1d/d..now-1d/d   yesterday
+ *   2026-01-01..now      since a fixed instant
+ *
+ * Everything here is pure and takes `now` as an argument: reading the clock
+ * during render would disagree between the server and the browser.
+ */
+type TimeUnit = "s" | "m" | "h" | "d" | "w" | "M" | "y";
+interface ResolveOptions {
+  /** The instant `now` refers to. Required, so nothing here reads the clock. */
+  now: Date;
+  /**
+   * IANA zone the snapping happens in — "start of day" is a different instant
+   * in Auckland than in Denver. Defaults to the runtime zone.
+   */
+  timeZone?: string;
+}
+interface ResolvedRange {
+  from: Date;
+  to: Date;
+}
+/** Why an expression could not be resolved. Shown to the user verbatim. */
+declare class TimeExpressionError extends Error {
+  /** The part of the input at fault, for pointing at it. */
+  readonly input: string;
+  constructor(message: string,
+  /** The part of the input at fault, for pointing at it. */
+  input: string);
+}
+/** Resolves a single side of a range. Exported for the input's live feedback. */
+declare function resolveExpression(expression: string, edge: "start" | "end", options: ResolveOptions): Date;
+/**
+ * Turns a range expression into the two instants a query needs.
+ *
+ * Throws `TimeExpressionError` rather than returning a fallback range: a chart
+ * silently showing the wrong window is worse than one that says it cannot.
+ */
+declare function resolveTimeRange(expression: string, options: ResolveOptions): ResolvedRange;
+/** Whether an expression resolves, without the caller writing a try/catch. */
+declare function isValidTimeRange(expression: string, options: ResolveOptions): boolean;
+interface TimeRangePreset {
+  expression: string;
+  label: string;
+  /** Groups presets under a heading in the picker. */
+  group: string;
+}
+/** Relative windows first, for debugging; calendar periods after, for reporting. */
+declare const DEFAULT_PRESETS: TimeRangePreset[];
+/**
+ * A sentence for the trigger.
+ *
+ * An unnamed relative range is described in its own terms — "Last 90 minutes" —
+ * because showing it as two timestamps throws away what the user chose. Only an
+ * absolute range, which has no relative meaning left, is shown as dates.
+ */
+declare function describeTimeRange(expression: string, options: ResolveOptions & {
+  locale?: string;
+  presets?: TimeRangePreset[];
+}): string;
+/** The resolved window, spelled out. Pairs with the relative label, not replaces it. */
+declare function formatResolvedRange(range: ResolvedRange, options?: {
+  locale?: string;
+  timeZone?: string;
+}): string;
+/** Builds the expression for an absolute range chosen on a calendar. */
+declare function absoluteExpression(from: Date, to: Date): string;
+//#endregion
+export { DEFAULT_PRESETS, ResolveOptions, ResolvedRange, TimeExpressionError, TimeRangePreset, TimeUnit, absoluteExpression, describeTimeRange, formatResolvedRange, isValidTimeRange, resolveExpression, resolveTimeRange };
+//# sourceMappingURL=time-expression.d.ts.map

package/dist/components/time-range-picker/time-expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-expression.d.ts","names":[],"sources":["../../../src/components/time-range-picker/time-expression.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;KA0BY;UAEK;;EAEf,KAAK;;;;;EAKL;;UAGe;EACf,MAAM;EACN,IAAI;;;cAIO,4BAA4B;;WAI5B;EAFT,YAAA,iBAES;;EAAA;;;iBAwOG,kBACd,oBACA,uBACA,SAAS,iBACR;;;;;;;iBAwFa,iBAAiB,oBAAoB,SAAS,iBAAiB;;iBAoB/D,iBAAiB,oBAAoB,SAAS;UAa7C;EACf;EACA;;EAEA;;;cAIW,iBAAiB;;;;;;;;iBAyBd,kBACd,oBACA,SAAS;EAAmB;EAAiB,UAAU;;;iBA2BzC,oBACd,OAAO,eACP;EAAW;EAAiB;;;iBAWd,mBAAmB,MAAM,MAAM,IAAI"}