@giddaa-housing/ui 3.3.0 → 3.4.0

package/css/theme.css

@@ -141,6 +141,7 @@
 	--animate-accordion-up: accordion-up 0.2s ease-out;
 	--animate-sonar-glow: sonar-glow 1.5s cubic-bezier(0, 0, 0.2, 1) infinite;
 	--animate-round-sonar-glow: round-sonar-glow 1.5s ease-out infinite;
+	--animate-sonar-wave: sonar-wave 1.5s cubic-bezier(0, 0, 0.2, 1) infinite;
 	--animate-spin-slow: spin 3s linear infinite;
 }
 
@@ -175,6 +176,7 @@
 		--animate-bouncing-loader: none;
 		--animate-sonar-glow: none;
 		--animate-round-sonar-glow: none;
+		--animate-sonar-wave: none;
 		--animate-spin-slow: none;
 	}
 }
@@ -280,3 +282,21 @@
 		opacity: 0;
 	}
 }
+
+/* Drives `Sonar`. Spread rather than `transform: scale()` on purpose: spread
+   grows the ring by the same number of pixels on every side and traces the
+   element's own border-radius, so one keyframe fits a 8px dot and a wide
+   button alike. Scaling would expand a wide element far more horizontally
+   than vertically — which is why sonar-glow above needs its per-axis
+   --sonar-glow-scale-x/y knobs. */
+@keyframes sonar-wave {
+	from {
+		box-shadow: 0 0 0 0 currentColor;
+		opacity: 0.55;
+	}
+
+	to {
+		box-shadow: 0 0 0 var(--sonar-spread, 0.625rem) currentColor;
+		opacity: 0;
+	}
+}

package/dist/badge.js

@@ -36,6 +36,11 @@ const badgeVariants = cva("group/badge inline-flex w-fit shrink-0 items-center j
 			false: ""
 		}
 	},
+	compoundVariants: [{
+		variant: "outline",
+		border: false,
+		class: "border-line"
+	}],
 	defaultVariants: {
 		variant: "default",
 		size: "md",

package/dist/price-tag.d.ts

@@ -3,32 +3,100 @@ import * as React from "react";
 //#region src/price-tag.d.ts
 declare const priceTagVariants: (props?: ({
   size?: "lg" | "md" | "sm" | "xs" | "xxs" | null | undefined;
+  hasDescription?: boolean | null | undefined;
   hasMonthlyPayment?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 type PriceTagSize = NonNullable<VariantProps<typeof priceTagVariants>["size"]>;
+/**
+ * A currency in the dropdown.
+ *
+ * `currency`, `value` and `description` are all PriceTag needs, and none of
+ * them are interpreted — `description` in particular is printed as given, so
+ * the wording is yours. The rest are legacy and go in the next major.
+ */
 type PriceTagCurrencyOption = {
-  code: string;
-  amount: string;
+  /** Shown at the leading edge, and matched against `selectedCurrency`. */
+  currency?: string;
+  /** The price, exactly as it should read. */
+  value?: React.ReactNode;
+  /** A second line under the price. Your words, printed as given. */
+  description?: React.ReactNode;
+  /** @deprecated Use `currency`. Removed in the next major. */
+  code?: string;
+  /** @deprecated Use `value`. Removed in the next major. */
+  amount?: string;
+  /** @deprecated Format before you pass it. Removed in the next major. */
   shortAmount?: string;
+  /** @deprecated Use `description`. Removed in the next major. */
   monthlyPayment?: string;
+  /** @deprecated Use `description`. Removed in the next major. */
   monthlyPaymentLabel?: string;
 };
+/**
+ * A currency option after the legacy fields have been folded in — what
+ * `onCurrencyChange` and `renderMenuOption` receive. The original object is
+ * spread in, so code still reading `code` or `amount` off it keeps working.
+ *
+ * Generic over your own option type, which `PriceTag` infers from `currencies`.
+ * Anything extra you hang on an option — a rate, an id, a flag — arrives here
+ * typed, so `renderMenuOption` can use it without a cast.
+ */
+type PriceTagMenuOption<TOption extends PriceTagCurrencyOption = PriceTagCurrencyOption> = TOption & {
+  currency: string;
+  value: React.ReactNode;
+  description?: React.ReactNode;
+  /** Whether this is the row `selectedCurrency` points at. */
+  selected: boolean;
+};
+/** @deprecated Format before you pass it. Removed in the next major. */
 type PriceTagFormat = "full" | "shortened";
-type PriceTagProps = Omit<React.ComponentProps<"button">, "children"> & {
-  amount: string;
-  shortAmount?: string;
-  format?: PriceTagFormat;
+type PriceTagProps<TOption extends PriceTagCurrencyOption = PriceTagCurrencyOption> = Omit<React.ComponentProps<"button">, "children" | "value"> & {
+  /** The price, exactly as it should read. */
+  value?: React.ReactNode;
+  /** A second line under the price. Your words, printed as given. */
+  description?: React.ReactNode;
   size?: PriceTagSize;
-  monthlyPayment?: string;
-  monthlyPaymentLabel?: string;
-  currencies?: PriceTagCurrencyOption[];
+  /**
+   * Providing this turns the tag into a dropdown trigger. Options carry
+   * whatever else you need — `TOption` is inferred from here, and the
+   * callbacks below receive it intact.
+   */
+  currencies?: TOption[];
   selectedCurrency?: string;
-  onCurrencyChange?: (currency: PriceTagCurrencyOption) => void;
+  onCurrencyChange?: (option: PriceTagMenuOption<NoInfer<TOption>>) => void;
+  /**
+   * Replace a row's contents. PriceTag keeps the button, its selected state
+   * and its keyboard behaviour, so a custom row can't quietly lose them.
+   */
+  renderMenuOption?: (option: PriceTagMenuOption<NoInfer<TOption>>) => React.ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
   onOpenChange?: (open: boolean) => void;
   popoverClassName?: string;
+  /** @deprecated Use `value`. Removed in the next major. */
+  amount?: string;
+  /** @deprecated Format before you pass it. Removed in the next major. */
+  shortAmount?: string;
+  /** @deprecated Format before you pass it. Removed in the next major. */
+  format?: PriceTagFormat;
+  /** @deprecated Use `description`. Removed in the next major. */
+  monthlyPayment?: string;
+  /** @deprecated Use `description`. Removed in the next major. */
+  monthlyPaymentLabel?: string;
 };
-declare function PriceTag({ amount, shortAmount, format, size, monthlyPayment, monthlyPaymentLabel, currencies, selectedCurrency, onCurrencyChange, open, defaultOpen, onOpenChange, className, popoverClassName, type, ...props }: PriceTagProps): React.JSX.Element;
+/**
+ * Pill-shaped price display, optionally a trigger for a currency dropdown.
+ *
+ * Display only: it prints `value` and `description` as given and never
+ * composes a sentence, picks a format, or decides that a line is too small to
+ * be worth showing. Wording, currency conversion and number formatting all
+ * belong to the app, which is the only place that knows the locale, the
+ * product's voice, and what the second line is actually for.
+ *
+ * The legacy `amount` / `shortAmount` / `format` / `monthlyPayment` props still
+ * work and keep their old behaviour exactly, including the size threshold that
+ * hid the monthly line below `md`. They go in the next major.
+ */
+declare function PriceTag<TOption extends PriceTagCurrencyOption = PriceTagCurrencyOption>({ value, description, size, currencies, selectedCurrency, onCurrencyChange, renderMenuOption, open, defaultOpen, onOpenChange, className, popoverClassName, type, amount, shortAmount, format, monthlyPayment, monthlyPaymentLabel, ...props }: PriceTagProps<TOption>): React.JSX.Element;
 //#endregion
-export { PriceTag, type PriceTagCurrencyOption, type PriceTagFormat, type PriceTagProps, type PriceTagSize, priceTagVariants };
+export { PriceTag, type PriceTagCurrencyOption, type PriceTagFormat, type PriceTagMenuOption, type PriceTagProps, type PriceTagSize, priceTagVariants };

package/dist/price-tag.js

@@ -1,7 +1,7 @@
 "use client";
 import { Check, ChevronDown } from "./icons.js";
 import { t as cn } from "./cn-BI_4DMBf.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
 import { Popover } from "@base-ui/react/popover";
 //#region src/price-tag.tsx
@@ -14,6 +14,12 @@ const priceTagVariants = cva("group/price-tag inline-flex w-fit shrink-0 items-c
 			md: "min-h-10.5 gap-1.5 px-5 py-2 text-gdt-md [&>svg]:size-4",
 			lg: "min-h-13 gap-2 px-7 py-3 text-gdt-lg [&>svg]:size-4.5"
 		},
+		/** Two lines sit top-aligned against the chevron rather than centred. */
+		hasDescription: {
+			true: "items-start",
+			false: ""
+		},
+		/** @deprecated Use `hasDescription`. Removed in the next major. */
 		hasMonthlyPayment: {
 			true: "items-start",
 			false: ""
@@ -21,37 +27,102 @@ const priceTagVariants = cva("group/price-tag inline-flex w-fit shrink-0 items-c
 	},
 	defaultVariants: {
 		size: "md",
-		hasMonthlyPayment: false
+		hasDescription: false
 	}
 });
+/** The description is quieter than the price, and quietest at the largest size. */
+const descriptionSizeClassName = {
+	xxs: "text-gdt-subtext",
+	xs: "text-gdt-subtext",
+	sm: "text-gdt-subtext",
+	md: "text-gdt-subtext",
+	lg: "text-gdt-xs"
+};
 function getDisplayAmount({ amount, shortAmount, format }) {
 	return format === "shortened" && shortAmount ? shortAmount : amount;
 }
-function PriceTag({ amount, shortAmount, format = "full", size = "md", monthlyPayment, monthlyPaymentLabel = "Low as", currencies, selectedCurrency, onCurrencyChange, open, defaultOpen, onOpenChange, className, popoverClassName, type = "button", ...props }) {
+/**
+* Folds the legacy fields into the current three. New fields win outright, so
+* an option can be migrated one at a time.
+*/
+function resolveMenuOption(option, format, selectedCurrency) {
+	const currency = option.currency ?? option.code ?? "";
+	const value = option.value ?? getDisplayAmount({
+		amount: option.amount,
+		shortAmount: option.shortAmount,
+		format
+	});
+	const description = option.description ?? (option.monthlyPayment ? `${option.monthlyPaymentLabel ?? "As low as"} ${option.monthlyPayment} per month` : void 0);
+	return {
+		...option,
+		currency,
+		value,
+		description,
+		selected: currency === selectedCurrency
+	};
+}
+function DefaultMenuOption({ option }) {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx("span", {
+			className: "min-w-10 text-gdt-sm font-semibold text-fg-brand",
+			children: option.currency
+		}),
+		/* @__PURE__ */ jsxs("span", {
+			className: "ml-auto flex min-w-0 flex-col items-end",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "text-gdt-sm font-bold text-fg-primary",
+				children: option.value
+			}), option.description ? /* @__PURE__ */ jsx("span", {
+				className: "text-gdt-xs text-fg-secondary",
+				children: option.description
+			}) : null]
+		}),
+		option.selected ? /* @__PURE__ */ jsx(Check, {
+			"aria-hidden": "true",
+			className: "size-4 shrink-0 text-fg-brand"
+		}) : null
+	] });
+}
+/**
+* Pill-shaped price display, optionally a trigger for a currency dropdown.
+*
+* Display only: it prints `value` and `description` as given and never
+* composes a sentence, picks a format, or decides that a line is too small to
+* be worth showing. Wording, currency conversion and number formatting all
+* belong to the app, which is the only place that knows the locale, the
+* product's voice, and what the second line is actually for.
+*
+* The legacy `amount` / `shortAmount` / `format` / `monthlyPayment` props still
+* work and keep their old behaviour exactly, including the size threshold that
+* hid the monthly line below `md`. They go in the next major.
+*/
+function PriceTag({ value, description, size = "md", currencies, selectedCurrency, onCurrencyChange, renderMenuOption, open, defaultOpen, onOpenChange, className, popoverClassName, type = "button", amount, shortAmount, format = "full", monthlyPayment, monthlyPaymentLabel = "Low as", ...props }) {
 	const hasDropdown = Boolean(currencies?.length);
-	const displayMonthlyPayment = (size === "md" || size === "lg") && monthlyPayment ? `${monthlyPaymentLabel} ${monthlyPayment} monthly` : void 0;
+	const resolvedValue = value ?? getDisplayAmount({
+		amount,
+		shortAmount,
+		format
+	});
+	const legacyDescription = monthlyPayment && (size === "md" || size === "lg") ? `${monthlyPaymentLabel} ${monthlyPayment} monthly` : void 0;
+	const resolvedDescription = description ?? legacyDescription;
 	const pill = /* @__PURE__ */ jsxs("span", {
 		className: "flex min-w-0 flex-col gap-1",
-		children: [/* @__PURE__ */ jsx("span", { children: getDisplayAmount({
-			amount,
-			shortAmount,
-			format
-		}) }), displayMonthlyPayment ? /* @__PURE__ */ jsx("span", {
-			className: cn("hidden text-gdt-subtext font-medium leading-none opacity-90", {
-				"inline-block": size === "md",
-				"inline-block text-gdt-xs": size === "lg"
-			}),
-			children: displayMonthlyPayment
+		children: [/* @__PURE__ */ jsx("span", { children: resolvedValue }), resolvedDescription ? /* @__PURE__ */ jsx("span", {
+			className: cn("font-medium leading-none opacity-90", descriptionSizeClassName[size]),
+			children: resolvedDescription
 		}) : null]
 	});
+	const pillClassName = cn(priceTagVariants({
+		size,
+		hasDescription: Boolean(resolvedDescription)
+	}), className);
 	if (!hasDropdown) return /* @__PURE__ */ jsx("span", {
 		"data-slot": "price-tag",
-		className: cn(priceTagVariants({
-			size,
-			hasMonthlyPayment: Boolean(displayMonthlyPayment)
-		}), className),
+		className: pillClassName,
+		...props,
 		children: pill
 	});
+	const options = (currencies ?? []).map((currency) => resolveMenuOption(currency, format, selectedCurrency));
 	return /* @__PURE__ */ jsxs(Popover.Root, {
 		open,
 		defaultOpen,
@@ -60,10 +131,7 @@ function PriceTag({ amount, shortAmount, format = "full", size = "md", monthlyPa
 			"data-slot": "price-tag",
 			"data-interactive": "true",
 			type,
-			className: cn(priceTagVariants({
-				size,
-				hasMonthlyPayment: Boolean(displayMonthlyPayment)
-			}), className),
+			className: pillClassName,
 			...props,
 			children: [pill, /* @__PURE__ */ jsx(ChevronDown, {
 				"aria-hidden": "true",
@@ -75,41 +143,14 @@ function PriceTag({ amount, shortAmount, format = "full", size = "md", monthlyPa
 			children: /* @__PURE__ */ jsx(Popover.Popup, {
 				"data-slot": "price-tag-popover",
 				className: cn("z-50 flex w-[17.25rem] max-w-[calc(100vw-2rem)] origin-(--transform-origin) flex-col rounded-xl border border-line-subtle bg-surface-overlay p-2 text-fg-primary shadow-3 outline-hidden transition-[opacity,scale,translate] duration-[var(--duration-motion-popup)] ease-gdt-out data-starting-style:opacity-0 data-starting-style:scale-95 data-ending-style:opacity-0 data-ending-style:scale-95 data-[side=bottom]:data-starting-style:translate-y-2 data-[side=bottom]:data-ending-style:translate-y-2 data-[side=top]:data-starting-style:-translate-y-2 data-[side=top]:data-ending-style:-translate-y-2 motion-reduce:data-starting-style:scale-100 motion-reduce:data-ending-style:scale-100 motion-reduce:data-[side=bottom]:data-starting-style:translate-y-0 motion-reduce:data-[side=bottom]:data-ending-style:translate-y-0 motion-reduce:data-[side=top]:data-starting-style:translate-y-0 motion-reduce:data-[side=top]:data-ending-style:translate-y-0", popoverClassName),
-				children: currencies?.map((currency) => {
-					const active = currency.code === selectedCurrency;
-					const optionAmount = getDisplayAmount({
-						amount: currency.amount,
-						shortAmount: currency.shortAmount,
-						format
-					});
-					const optionMonthlyPayment = currency.monthlyPayment ? `${currency.monthlyPaymentLabel ?? "As low as"} ${currency.monthlyPayment} per month` : void 0;
-					return /* @__PURE__ */ jsxs("button", {
-						type: "button",
-						"data-active": active ? "true" : void 0,
-						className: "flex min-h-14 w-full items-center gap-3 rounded-lg px-3 text-start outline-none transition-colors hover:bg-surface-brand-subtle focus-visible:bg-surface-brand-subtle focus-visible:shadow-[0px_0px_0px_2px_var(--color-line-focus)] data-[active=true]:bg-surface-brand-subtle",
-						onClick: () => onCurrencyChange?.(currency),
-						children: [
-							/* @__PURE__ */ jsx("span", {
-								className: "min-w-10 text-gdt-sm font-semibold text-fg-brand",
-								children: currency.code
-							}),
-							/* @__PURE__ */ jsxs("span", {
-								className: "ml-auto flex min-w-0 flex-col items-end",
-								children: [/* @__PURE__ */ jsx("span", {
-									className: "text-gdt-sm font-bold text-fg-primary",
-									children: optionAmount
-								}), optionMonthlyPayment ? /* @__PURE__ */ jsx("span", {
-									className: "text-gdt-xs text-fg-secondary",
-									children: optionMonthlyPayment
-								}) : null]
-							}),
-							active ? /* @__PURE__ */ jsx(Check, {
-								"aria-hidden": "true",
-								className: "size-4 shrink-0 text-fg-brand"
-							}) : null
-						]
-					}, currency.code);
-				})
+				children: options.map((option) => /* @__PURE__ */ jsx("button", {
+					type: "button",
+					"data-slot": "price-tag-option",
+					"data-active": option.selected ? "true" : void 0,
+					className: "flex min-h-14 w-full items-center gap-3 rounded-lg px-3 text-start outline-none transition-colors hover:bg-surface-brand-subtle focus-visible:bg-surface-brand-subtle focus-visible:shadow-[0px_0px_0px_2px_var(--color-line-focus)] data-[active=true]:bg-surface-brand-subtle",
+					onClick: () => onCurrencyChange?.(option),
+					children: renderMenuOption ? renderMenuOption(option) : /* @__PURE__ */ jsx(DefaultMenuOption, { option })
+				}, option.currency))
 			})
 		}) })]
 	});

package/dist/scroll-spy.d.ts

@@ -2,6 +2,21 @@ import { t as ComponentSize } from "./size-context-BX6kAdVj.js";
 import { TabsListVariant } from "./tabs.js";
 import * as React from "react";
 //#region src/scroll-spy.d.ts
+/**
+ * Read and drive the spy from anywhere inside a `ScrollSpy` — an overflow
+ * "More" menu, a floating progress rail, a heading that echoes the section
+ * being read.
+ *
+ * Context reaches through portals, so a consumer inside an open `DropdownMenu`
+ * or `Popover` works without threading anything down by hand. `registerSection`
+ * is deliberately not exposed: sections are `ScrollSpyContent`'s to own.
+ */
+declare function useScrollSpy(): {
+  activeValue: string | undefined;
+  getSectionId: (value: string) => string;
+  getTriggerId: (value: string) => string;
+  scrollToSection: (value: string) => void;
+};
 type ScrollSpyProps = Omit<React.ComponentProps<"div">, "onChange"> & {
   orientation?: "horizontal" | "vertical";
   /** Controlled active section. */
@@ -58,4 +73,4 @@ type ScrollSpyContentProps = Omit<React.ComponentProps<"section">, "value"> & {
 };
 declare function ScrollSpyContent({ className, value, style, tabIndex, ...props }: ScrollSpyContentProps): React.JSX.Element;
 //#endregion
-export { ScrollSpy, ScrollSpyContent, type ScrollSpyContentProps, ScrollSpyList, type ScrollSpyListProps, type ScrollSpyProps, ScrollSpyTrigger, type ScrollSpyTriggerProps, scrollSpyTriggerClassName };
+export { ScrollSpy, ScrollSpyContent, type ScrollSpyContentProps, ScrollSpyList, type ScrollSpyListProps, type ScrollSpyProps, ScrollSpyTrigger, type ScrollSpyTriggerProps, scrollSpyTriggerClassName, useScrollSpy };

package/dist/scroll-spy.js

@@ -37,10 +37,33 @@ function getScrollport(element) {
 }
 function useScrollSpyContext(part) {
 	const context = React.useContext(ScrollSpyContext);
-	if (!context) throw new Error(`\`${part}\` must be rendered inside \`ScrollSpy\`.`);
+	if (!context) throw new Error(`\`${part}\` must be used inside \`ScrollSpy\`.`);
 	return context;
 }
 /**
+* Read and drive the spy from anywhere inside a `ScrollSpy` — an overflow
+* "More" menu, a floating progress rail, a heading that echoes the section
+* being read.
+*
+* Context reaches through portals, so a consumer inside an open `DropdownMenu`
+* or `Popover` works without threading anything down by hand. `registerSection`
+* is deliberately not exposed: sections are `ScrollSpyContent`'s to own.
+*/
+function useScrollSpy() {
+	const { activeValue, getSectionId, getTriggerId, scrollToSection } = useScrollSpyContext("useScrollSpy");
+	return React.useMemo(() => ({
+		activeValue,
+		getSectionId,
+		getTriggerId,
+		scrollToSection
+	}), [
+		activeValue,
+		getSectionId,
+		getTriggerId,
+		scrollToSection
+	]);
+}
+/**
 * `Tabs` for a page that shows everything at once: every section stays mounted
 * and visible, the triggers scroll to their section, and the active trigger
 * tracks whichever section the reader is currently on.
@@ -292,4 +315,4 @@ function ScrollSpyContent({ className, value, style, tabIndex = -1, ...props })
 	});
 }
 //#endregion
-export { ScrollSpy, ScrollSpyContent, ScrollSpyList, ScrollSpyTrigger, scrollSpyTriggerClassName };
+export { ScrollSpy, ScrollSpyContent, ScrollSpyList, ScrollSpyTrigger, scrollSpyTriggerClassName, useScrollSpy };

package/dist/sonar.d.ts

@@ -0,0 +1,51 @@
+import { t as ComponentSize } from "./size-context-BX6kAdVj.js";
+import { VariantProps } from "class-variance-authority";
+import * as React from "react";
+//#region src/sonar.d.ts
+/**
+ * Kept in step with `--animate-sonar-wave` in `css/theme.css`; the waves are
+ * staggered by a fraction of one cycle, which only reads as a continuous sonar
+ * if this matches the keyframe's duration. `sonar.test.tsx` asserts they agree.
+ */
+declare const SONAR_DURATION_MS = 1500;
+/**
+ * Colour rides on `currentColor` so the keyframe stays tone-agnostic: one set
+ * of keyframes, one class per tone.
+ */
+declare const sonarWaveVariants: (props?: ({
+  tone?: "brand" | "danger" | "info" | "success" | "warning" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type SonarProps = React.ComponentProps<"span"> & VariantProps<typeof sonarWaveVariants> & {
+  /** Stop pulsing without unmounting — the child renders on its own. */
+  active?: boolean;
+  /** Overlapping rings. More reads as a faster, more urgent sonar. */
+  waves?: 1 | 2 | 3;
+  /** How far each ring travels. Inherits from `SizeProvider`. */
+  size?: ComponentSize;
+  /**
+   * Skip measurement and use this `border-radius` verbatim. Only needed
+   * when the child's shape can't be read off the DOM — an SVG using
+   * geometry rather than CSS, say.
+   */
+  radius?: string;
+};
+/**
+ * Draws attention to a dot, badge or button by pulsing rings outward from it.
+ *
+ * The rings trace the child's own shape: `Sonar` reads the child's computed
+ * `border-radius` and hands it to the rings, so a pill badge pulses a pill and
+ * a rounded button pulses a rounded rectangle, with nothing to keep in sync by
+ * hand. That matters because radii in this library are often size-dependent —
+ * `Tag` alone moves through `rounded-md`/`lg`/`xl` across its three sizes.
+ *
+ * Purely decorative: the rings are `aria-hidden` and the child is untouched, so
+ * whatever the child announces is what assistive tech hears. A pulse is not a
+ * label — if the attention it draws carries meaning, put that meaning in the
+ * child.
+ *
+ * The rings are painted with `box-shadow` spread, which lives outside the
+ * element's box, so an ancestor with `overflow: hidden` will clip them.
+ */
+declare function Sonar({ className, children, active, waves, size, tone, radius, style, ...props }: SonarProps): React.JSX.Element;
+//#endregion
+export { SONAR_DURATION_MS, Sonar, type SonarProps, sonarWaveVariants };

package/dist/sonar.js

@@ -0,0 +1,117 @@
+"use client";
+import { t as cn } from "./cn-BI_4DMBf.js";
+import { useComponentSize } from "./size-context.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cva } from "class-variance-authority";
+import * as React from "react";
+//#region src/sonar.tsx
+/**
+* Kept in step with `--animate-sonar-wave` in `css/theme.css`; the waves are
+* staggered by a fraction of one cycle, which only reads as a continuous sonar
+* if this matches the keyframe's duration. `sonar.test.tsx` asserts they agree.
+*/
+const SONAR_DURATION_MS = 1500;
+const SQUARE = {
+	borderTopLeftRadius: "0px",
+	borderTopRightRadius: "0px",
+	borderBottomRightRadius: "0px",
+	borderBottomLeftRadius: "0px"
+};
+function sameCorners(a, b) {
+	return a !== null && a.borderTopLeftRadius === b.borderTopLeftRadius && a.borderTopRightRadius === b.borderTopRightRadius && a.borderBottomRightRadius === b.borderBottomRightRadius && a.borderBottomLeftRadius === b.borderBottomLeftRadius;
+}
+/**
+* Colour rides on `currentColor` so the keyframe stays tone-agnostic: one set
+* of keyframes, one class per tone.
+*/
+const sonarWaveVariants = cva(cn("pointer-events-none absolute inset-0 animate-sonar-wave", "motion-reduce:animate-none motion-reduce:opacity-40 motion-reduce:shadow-[0_0_0_2px_currentColor]"), {
+	variants: { tone: {
+		brand: "text-fg-brand",
+		info: "text-status-info",
+		success: "text-status-success",
+		warning: "text-status-warning",
+		danger: "text-status-danger"
+	} },
+	defaultVariants: { tone: "brand" }
+});
+/**
+* Rings evenly spaced across one cycle, so the last finishes just as the first
+* comes round again. Doubles as each ring's key — the offsets are distinct by
+* construction, which an index would only pretend to be.
+*/
+function waveDelays(waves) {
+	return Array.from({ length: waves }, (_, index) => Math.round(index * SONAR_DURATION_MS / waves));
+}
+/** How far the ring travels before it fades out. */
+const sonarSpread = {
+	sm: "[--sonar-spread:0.375rem]",
+	md: "[--sonar-spread:0.625rem]",
+	lg: "[--sonar-spread:0.875rem]"
+};
+/**
+* Draws attention to a dot, badge or button by pulsing rings outward from it.
+*
+* The rings trace the child's own shape: `Sonar` reads the child's computed
+* `border-radius` and hands it to the rings, so a pill badge pulses a pill and
+* a rounded button pulses a rounded rectangle, with nothing to keep in sync by
+* hand. That matters because radii in this library are often size-dependent —
+* `Tag` alone moves through `rounded-md`/`lg`/`xl` across its three sizes.
+*
+* Purely decorative: the rings are `aria-hidden` and the child is untouched, so
+* whatever the child announces is what assistive tech hears. A pulse is not a
+* label — if the attention it draws carries meaning, put that meaning in the
+* child.
+*
+* The rings are painted with `box-shadow` spread, which lives outside the
+* element's box, so an ancestor with `overflow: hidden` will clip them.
+*/
+function Sonar({ className, children, active = true, waves = 2, size, tone, radius, style, ...props }) {
+	const resolvedSize = useComponentSize(size);
+	const ref = React.useRef(null);
+	const [corners, setCorners] = React.useState(null);
+	React.useEffect(() => {
+		if (radius !== void 0 || !active) return;
+		const target = ref.current?.querySelector(":scope > :not([data-slot=\"sonar-wave\"])");
+		if (!target) {
+			setCorners(SQUARE);
+			return;
+		}
+		const measure = () => {
+			const computed = getComputedStyle(target);
+			const next = {
+				borderTopLeftRadius: computed.borderTopLeftRadius,
+				borderTopRightRadius: computed.borderTopRightRadius,
+				borderBottomRightRadius: computed.borderBottomRightRadius,
+				borderBottomLeftRadius: computed.borderBottomLeftRadius
+			};
+			setCorners((current) => sameCorners(current, next) ? current : next);
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(target);
+		return () => observer.disconnect();
+	}, [active, radius]);
+	const shape = radius !== void 0 ? { borderRadius: radius } : corners;
+	return /* @__PURE__ */ jsxs("span", {
+		ref,
+		"data-slot": "sonar",
+		"data-tone": tone ?? "brand",
+		"data-size": resolvedSize,
+		"data-active": active ? "" : void 0,
+		className: cn("relative inline-flex w-fit shrink-0", sonarSpread[resolvedSize], className),
+		style,
+		...props,
+		children: [children, active && shape ? waveDelays(waves).map((delay) => /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "sonar-wave",
+			style: {
+				...shape,
+				animationDelay: delay === 0 ? void 0 : `${delay}ms`
+			},
+			className: cn(sonarWaveVariants({ tone }), delay > 0 && "motion-reduce:hidden")
+		}, `sonar-wave-${delay}`)) : null]
+	});
+}
+//#endregion
+export { SONAR_DURATION_MS, Sonar, sonarWaveVariants };