@vjdesigns/vjdesigns-ui 0.0.0-stage → 2.0.0

package/dist/components/data-display/List/List.d.ts

@@ -0,0 +1,195 @@
+import { ComponentPropsWithRef, CSSProperties, ReactNode, Ref } from 'react';
+import { Size, Space } from '../../../types/common';
+/**
+ * Visual style of a list.
+ * - `plain`: no markers.
+ * - `bulleted`: small accent dots.
+ * - `numbered`: bold display-font numbers in soft circles (renders an `<ol>` by default).
+ * - `divided`: hairline dividers between items.
+ * - `card`: an inset, rounded card with dividers, like a settings list.
+ */
+export type ListVariant = "plain" | "bulleted" | "numbered" | "divided" | "card";
+/** The list element. */
+export type ListElement = "ul" | "ol";
+/** Tokens accepted by `current`; each becomes the item's `aria-current` value. */
+export type ListItemCurrent = "page" | "step" | "location" | "date" | "time" | "true";
+/** Heading level (or a plain `div`) for `List.Subheader`. */
+export type ListSubheaderElement = "h2" | "h3" | "h4" | "h5" | "h6" | "div";
+export interface ListOwnProps {
+    /** Visual style. @default "plain" */
+    variant?: ListVariant;
+    /** List element. Defaults to `"ol"` for `variant="numbered"` or `ordered`, otherwise `"ul"`. */
+    as?: ListElement;
+    /** Shortcut for `as="ol"`: the items have a meaningful order. @default false */
+    ordered?: boolean;
+    /** Type size, marker size, and item padding. @default "md" */
+    size?: Size;
+    /**
+     * Space between items, as a `--space-*` step. For `plain`, `bulleted`, and
+     * `numbered` it is the gap between items; for `divided` and `card` (where
+     * a gap would break the dividers) it is each item's block padding.
+     * Defaults to a step that scales with `size`.
+     */
+    spacing?: Space;
+    /**
+     * A custom marker for every item, such as `<CheckIcon />` for a feature
+     * list. Replaces the variant's dot or number. Decorative: hidden from
+     * assistive technology, so the item text must carry the meaning.
+     */
+    marker?: ReactNode;
+    /** For ordered lists: the number of the first item. @default 1 */
+    start?: number;
+    /** The items: `List.Item`, `List.ItemButton`, or `List.ItemLink`. */
+    children?: ReactNode;
+    /** Ref to the `<ul>` or `<ol>`. */
+    ref?: Ref<HTMLUListElement | HTMLOListElement>;
+}
+export type ListProps = ListOwnProps & Omit<ComponentPropsWithRef<"ol">, keyof ListOwnProps | "reversed" | "type">;
+/**
+ * A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.
+ *
+ * Every variant draws its own markers, so the browser's markers are removed
+ * with CSS; `role="list"` is added so Safari and VoiceOver keep announcing
+ * the list and its item count.
+ *
+ * This is a list, not a listbox: items are not selectable options and there
+ * is no roving focus. Interactive items (`List.ItemButton`, `List.ItemLink`)
+ * are ordinary Tab stops. For choosing among options, use a Listbox,
+ * Combobox, or Select instead.
+ *
+ * Grouping: put a `List.Subheader` (a real heading by default) before each
+ * list and point the list at it with `aria-labelledby`, so screen readers
+ * announce "Account, list, 3 items".
+ */
+export declare const List: {
+    ({ variant, as, ordered, size, spacing, marker, start, className, style, children, ref, ...rest }: ListProps): import("react").JSX.Element;
+    Item: {
+        (props: ListItemProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    ItemButton: {
+        (props: ListItemButtonProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    ItemLink: {
+        (props: ListItemLinkProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    Subheader: {
+        ({ as: Element, size, className, children, ...rest }: ListSubheaderProps): import("react").JSX.Element;
+        displayName: string;
+    };
+};
+/** Content slots shared by `List.Item`, `List.ItemButton`, and `List.ItemLink`. */
+export interface ListItemSlotProps {
+    /** Leading visual: an `Avatar`, an `Icon`, or a thumbnail. */
+    start?: ReactNode;
+    /** Primary text, in bold display type. */
+    title?: ReactNode;
+    /** Secondary text under the title, in muted body type. */
+    description?: ReactNode;
+    /** End-aligned secondary text, such as a timestamp or a count. */
+    meta?: ReactNode;
+    /**
+     * Trailing content: actions (`IconButton`, `Switch`), `Badge`s, or a
+     * chevron. On `ItemButton` and `ItemLink` these stay independently
+     * clickable and focusable; they sit above the stretched main action.
+     */
+    end?: ReactNode;
+    /**
+     * Overrides the list's marker for this item. `undefined` inherits the
+     * list's marker; `false` removes the marker. Decorative and hidden from
+     * assistive technology.
+     */
+    marker?: ReactNode;
+    /**
+     * Highlights the item with a tinted fill and a leading bar (shape plus
+     * color). Also sets `aria-current` (`"page"` on links, `"true"` otherwise)
+     * so the state is announced, not only seen. @default false
+     */
+    selected?: boolean;
+    /** Sets a specific `aria-current` token (e.g. `"step"`). Implies `selected`. */
+    current?: ListItemCurrent;
+    /** Plain content. Renders after the title and description, or alone when no slots are used. */
+    children?: ReactNode;
+}
+export type ListItemProps = ListItemSlotProps & Omit<ComponentPropsWithRef<"li">, keyof ListItemSlotProps>;
+/**
+ * A static list item (`<li>`) with optional `start`, `title`, `description`,
+ * `meta`, and `end` slots, or plain `children`. For a clickable row, use
+ * `List.ItemButton` or `List.ItemLink`.
+ */
+declare const ListItem: {
+    (props: ListItemProps): import("react").JSX.Element;
+    displayName: string;
+};
+export interface ListItemInteractiveProps extends ListItemSlotProps {
+    /** Disables the main action. `end` actions keep their own `disabled` state. @default false */
+    disabled?: boolean;
+    /** Class for the row (`<li>`). Other props go to the `<button>` or `<a>`. */
+    className?: string;
+    /** Style for the row (`<li>`). */
+    style?: CSSProperties;
+    /** Extra props for the row `<li>`, such as `data-*` attributes or an `id`. */
+    itemProps?: Omit<ComponentPropsWithRef<"li">, "children">;
+}
+export type ListItemButtonProps = ListItemInteractiveProps & Omit<ComponentPropsWithRef<"button">, keyof ListItemInteractiveProps>;
+/**
+ * A list item whose main area is a real `<button>`. The button wraps the
+ * title (or `children` when there is no title) and its hit area is
+ * stretched over the whole row, so the row is clickable, while `end`
+ * actions sit above it and stay independently clickable. Never nest
+ * interactive elements in `title` or `description`.
+ *
+ * `className` and `style` go on the row `<li>`; `ref`, `onClick`, `type`,
+ * `aria-*`, and every other prop go on the `<button>`. The description and
+ * meta become the button's accessible description.
+ */
+declare const ListItemButton: {
+    (props: ListItemButtonProps): import("react").JSX.Element;
+    displayName: string;
+};
+export type ListItemLinkProps = ListItemInteractiveProps & Omit<ComponentPropsWithRef<"a">, keyof ListItemInteractiveProps>;
+/**
+ * A list item whose main area is a real `<a>`, stretched over the whole row
+ * like `List.ItemButton`. `selected` sets `aria-current="page"` (override
+ * with `current`). When `disabled`, the link loses its `href` and is marked
+ * `aria-disabled`, so it can't be followed or focused.
+ *
+ * `className` and `style` go on the row `<li>`; everything else, including
+ * `ref` and `href`, goes on the `<a>`.
+ */
+declare const ListItemLink: {
+    (props: ListItemLinkProps): import("react").JSX.Element;
+    displayName: string;
+};
+export interface ListSubheaderOwnProps {
+    /**
+     * Element to render. A heading (default `h3`) so grouped lists show up in
+     * the screen reader's headings list; pick the level that fits the page
+     * outline, or `div` when a heading would be out of place.
+     * @default "h3"
+     */
+    as?: ListSubheaderElement;
+    /** Type size, matching the list's `size`. @default "md" */
+    size?: Size;
+    /** The group label. */
+    children?: ReactNode;
+}
+export type ListSubheaderProps = ListSubheaderOwnProps & Omit<ComponentPropsWithRef<"h3">, keyof ListSubheaderOwnProps>;
+/**
+ * An uppercase label for a group of items. Render it before (outside) a
+ * `List`, give it an `id`, and pass that id to the list's
+ * `aria-labelledby`. It must not go inside the `<ul>`, where it would be
+ * counted as an item.
+ *
+ * ```tsx
+ * <List.Subheader id="acct">Account</List.Subheader>
+ * <List aria-labelledby="acct">...</List>
+ * ```
+ */
+declare const ListSubheader: {
+    ({ as: Element, size, className, children, ...rest }: ListSubheaderProps): import("react").JSX.Element;
+    displayName: string;
+};
+export { ListItem, ListItemButton, ListItemLink, ListSubheader };

package/dist/components/data-display/List/List.mjs

@@ -0,0 +1,200 @@
+import { cx as e } from "../../../utils/cx.mjs";
+import t from "./List.module.css.mjs";
+import { createContext as n, useContext as r, useId as i } from "react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/components/data-display/List/List.tsx
+var s = {
+	plain: t.plain,
+	bulleted: t.bulleted,
+	numbered: t.numbered,
+	divided: t.divided,
+	card: t.card
+}, c = {
+	sm: t.sm,
+	md: t.md,
+	lg: t.lg
+}, l = n({
+	variant: "plain",
+	marker: void 0
+}), u = ({ variant: n = "plain", as: r, ordered: i = !1, size: o = "md", spacing: u, marker: d, start: f, className: p, style: m, children: h, ref: g, ..._ }) => {
+	let v = r ?? (i || n === "numbered" ? "ol" : "ul"), y = f === void 0 ? m : {
+		counterReset: `dh-list-item ${f - 1}`,
+		...m
+	};
+	return /* @__PURE__ */ a(l.Provider, {
+		value: {
+			variant: n,
+			marker: d
+		},
+		children: /* @__PURE__ */ a(v, {
+			role: "list",
+			..._,
+			ref: g,
+			start: v === "ol" ? f : void 0,
+			"data-spacing": u,
+			className: e(t.root, s[n], c[o], p),
+			style: y,
+			children: h
+		})
+	});
+}, d = ({ marker: n }) => {
+	let { variant: i, marker: o } = r(l), s = n ?? o;
+	return s === !1 ? null : s != null && s !== !0 ? /* @__PURE__ */ a("span", {
+		className: e(t.marker, t.customMarker),
+		"aria-hidden": "true",
+		children: s
+	}) : i === "bulleted" ? /* @__PURE__ */ a("span", {
+		className: e(t.marker, t.bulletMarker),
+		"aria-hidden": "true",
+		children: /* @__PURE__ */ a("span", { className: t.dot })
+	}) : i === "numbered" ? /* @__PURE__ */ a("span", {
+		className: e(t.marker, t.numberMarker),
+		"aria-hidden": "true",
+		children: /* @__PURE__ */ a("span", { className: t.number })
+	}) : null;
+}, f = (e) => e != null && e !== !1 && e !== "", p = (...e) => e.filter(Boolean).join(" ") || void 0, m = ({ slots: n, main: r, descriptionId: i, metaId: s, interactive: c, disabled: l, liProps: u, ariaCurrent: p }) => {
+	let { start: m, description: h, meta: g, end: _, marker: v } = n, y = !!(n.selected || n.current), { className: b, ...x } = u;
+	return /* @__PURE__ */ o("li", {
+		"aria-current": c ? void 0 : p,
+		"aria-disabled": l || void 0,
+		...x,
+		className: e(t.item, c && t.interactive, y && t.selected, l && t.disabled, b),
+		children: [
+			/* @__PURE__ */ a(d, { marker: v }),
+			f(m) && /* @__PURE__ */ a("span", {
+				className: t.start,
+				children: m
+			}),
+			/* @__PURE__ */ o("div", {
+				className: t.content,
+				children: [
+					r,
+					f(h) && /* @__PURE__ */ a("span", {
+						id: i,
+						className: t.description,
+						children: h
+					}),
+					n.title !== void 0 && f(n.children) && /* @__PURE__ */ a("div", {
+						className: t.body,
+						children: n.children
+					})
+				]
+			}),
+			f(g) && /* @__PURE__ */ a("span", {
+				id: s,
+				className: t.meta,
+				children: g
+			}),
+			f(_) && /* @__PURE__ */ a("div", {
+				className: t.end,
+				children: _
+			})
+		]
+	});
+};
+function h(e) {
+	let { start: t, title: n, description: r, meta: i, end: a, marker: o, selected: s, current: c, children: l, ...u } = e;
+	return {
+		slots: {
+			start: t,
+			title: n,
+			description: r,
+			meta: i,
+			end: a,
+			marker: o,
+			selected: s,
+			current: c,
+			children: l
+		},
+		rest: u
+	};
+}
+var g = (e) => {
+	let { slots: n, rest: r } = h(e), i = !!(n.selected || n.current), o = n.title === void 0 ? f(n.children) && /* @__PURE__ */ a("div", {
+		className: t.body,
+		children: n.children
+	}) : /* @__PURE__ */ a("span", {
+		className: t.title,
+		children: n.title
+	});
+	return /* @__PURE__ */ a(m, {
+		slots: n,
+		main: o,
+		interactive: !1,
+		liProps: r,
+		ariaCurrent: n.current ?? (i ? "true" : void 0)
+	});
+};
+g.displayName = "List.Item";
+var _ = (n) => {
+	let { slots: r, rest: o } = h(n), { disabled: s = !1, className: c, style: l, itemProps: u, type: d = "button", "aria-describedby": g, "aria-current": _, ...v } = o, y = i(), b = `${y}-description`, x = `${y}-meta`, S = !!(r.selected || r.current), C = /* @__PURE__ */ a("button", {
+		...v,
+		type: d,
+		disabled: s,
+		className: t.action,
+		"aria-current": _ ?? r.current ?? (S ? "true" : void 0),
+		"aria-describedby": p(g, f(r.description) && b, f(r.meta) && x),
+		children: /* @__PURE__ */ a("span", {
+			className: t.title,
+			children: r.title ?? r.children
+		})
+	});
+	return /* @__PURE__ */ a(m, {
+		slots: r,
+		main: C,
+		descriptionId: b,
+		metaId: x,
+		interactive: !0,
+		disabled: s,
+		liProps: {
+			...u,
+			className: e(u?.className, c),
+			style: {
+				...u?.style,
+				...l
+			}
+		}
+	});
+};
+_.displayName = "List.ItemButton";
+var v = (n) => {
+	let { slots: r, rest: o } = h(n), { disabled: s = !1, className: c, style: l, itemProps: u, href: d, onClick: g, "aria-describedby": _, "aria-current": v, ...y } = o, b = i(), x = `${b}-description`, S = `${b}-meta`, C = !!(r.selected || r.current), w = /* @__PURE__ */ a("a", {
+		...y,
+		href: s ? void 0 : d,
+		role: s ? "link" : void 0,
+		"aria-disabled": s || void 0,
+		onClick: s ? (e) => e.preventDefault() : g,
+		className: t.action,
+		"aria-current": v ?? r.current ?? (C ? "page" : void 0),
+		"aria-describedby": p(_, f(r.description) && x, f(r.meta) && S),
+		children: /* @__PURE__ */ a("span", {
+			className: t.title,
+			children: r.title ?? r.children
+		})
+	});
+	return /* @__PURE__ */ a(m, {
+		slots: r,
+		main: w,
+		descriptionId: x,
+		metaId: S,
+		interactive: !0,
+		disabled: s,
+		liProps: {
+			...u,
+			className: e(u?.className, c),
+			style: {
+				...u?.style,
+				...l
+			}
+		}
+	});
+};
+v.displayName = "List.ItemLink";
+var y = ({ as: n = "h3", size: r = "md", className: i, children: o, ...s }) => /* @__PURE__ */ a(n, {
+	...s,
+	className: e(t.subheader, c[r], i),
+	children: o
+});
+y.displayName = "List.Subheader", u.Item = g, u.ItemButton = _, u.ItemLink = v, u.Subheader = y;
+//#endregion
+export { u as List, g as ListItem, _ as ListItemButton, v as ListItemLink, y as ListSubheader };

package/dist/components/data-display/List/List.module.css.cjs.js

@@ -0,0 +1 @@
+var e=`_root_8n7jz_27`,t=`_sm_8n7jz_29`,n=`_md_8n7jz_29`,r=`_lg_8n7jz_29`,i=`_plain_8n7jz_207`,a=`_bulleted_8n7jz_209`,o=`_numbered_8n7jz_211`,s=`_divided_8n7jz_221`,c=`_card_8n7jz_223`,l=`_item_8n7jz_241`,u=`_start_8n7jz_329`,d=`_content_8n7jz_341`,f=`_title_8n7jz_357`,p=`_description_8n7jz_377`,m=`_body_8n7jz_393`,h=`_meta_8n7jz_411`,g=`_end_8n7jz_431`,_=`_marker_8n7jz_455`,v=`_bulletMarker_8n7jz_485`,y=`_dot_8n7jz_493`,b=`_numberMarker_8n7jz_513`,x=`_number_8n7jz_211`,S=`_customMarker_8n7jz_565`,C=`_interactive_8n7jz_593`,w=`_action_8n7jz_627`,T=`_disabled_8n7jz_729`,E=`_selected_8n7jz_763`,D=`_subheader_8n7jz_875`,O={root:e,sm:t,md:n,lg:r,plain:i,bulleted:a,numbered:o,divided:s,card:c,item:l,start:u,content:d,title:f,description:p,body:m,meta:h,end:g,marker:_,bulletMarker:v,dot:y,numberMarker:b,number:x,customMarker:S,interactive:C,action:w,disabled:T,selected:E,subheader:D};exports.action=w,exports.body=m,exports.bulletMarker=v,exports.bulleted=a,exports.card=c,exports.content=d,exports.customMarker=S,exports.default=O,exports.description=p,exports.disabled=T,exports.divided=s,exports.dot=y,exports.end=g,exports.interactive=C,exports.item=l,exports.lg=r,exports.marker=_,exports.md=n,exports.meta=h,exports.number=x,exports.numberMarker=b,exports.numbered=o,exports.plain=i,exports.root=e,exports.selected=E,exports.sm=t,exports.start=u,exports.subheader=D,exports.title=f;

package/dist/components/data-display/List/List.module.css.mjs

@@ -0,0 +1,33 @@
+//#region src/components/data-display/List/List.module.css
+var e = "_root_8n7jz_27", t = "_sm_8n7jz_29", n = "_md_8n7jz_29", r = "_lg_8n7jz_29", i = "_plain_8n7jz_207", a = "_bulleted_8n7jz_209", o = "_numbered_8n7jz_211", s = "_divided_8n7jz_221", c = "_card_8n7jz_223", l = "_item_8n7jz_241", u = "_start_8n7jz_329", d = "_content_8n7jz_341", f = "_title_8n7jz_357", p = "_description_8n7jz_377", m = "_body_8n7jz_393", h = "_meta_8n7jz_411", g = "_end_8n7jz_431", _ = "_marker_8n7jz_455", v = "_bulletMarker_8n7jz_485", y = "_dot_8n7jz_493", b = "_numberMarker_8n7jz_513", x = "_number_8n7jz_211", S = "_customMarker_8n7jz_565", C = "_interactive_8n7jz_593", w = "_action_8n7jz_627", T = "_disabled_8n7jz_729", E = "_selected_8n7jz_763", D = "_subheader_8n7jz_875", O = {
+	root: e,
+	sm: t,
+	md: n,
+	lg: r,
+	plain: i,
+	bulleted: a,
+	numbered: o,
+	divided: s,
+	card: c,
+	item: l,
+	start: u,
+	content: d,
+	title: f,
+	description: p,
+	body: m,
+	meta: h,
+	end: g,
+	marker: _,
+	bulletMarker: v,
+	dot: y,
+	numberMarker: b,
+	number: x,
+	customMarker: S,
+	interactive: C,
+	action: w,
+	disabled: T,
+	selected: E,
+	subheader: D
+};
+//#endregion
+export { w as action, m as body, v as bulletMarker, a as bulleted, c as card, d as content, S as customMarker, O as default, p as description, T as disabled, s as divided, y as dot, g as end, C as interactive, l as item, r as lg, _ as marker, n as md, h as meta, x as number, b as numberMarker, o as numbered, i as plain, e as root, E as selected, t as sm, u as start, D as subheader, f as title };

package/dist/components/data-display/List/index.d.ts

@@ -0,0 +1 @@
+export * from './List';

package/dist/components/data-display/Stat/Stat.cjs.js

@@ -0,0 +1 @@
+const e=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),t=require("../../../hooks/useMergedRef.cjs.js"),n=require("../../../utils/cx.cjs.js"),r=require("../../utilities/VisuallyHidden/VisuallyHidden.cjs.js"),i=require("../../primitives/Icon/icons.cjs.js"),a=require("../../feedback/Progress/Progress.cjs.js"),o=require("./Stat.module.css.cjs.js");let s=require("react"),c=require("react/jsx-runtime");var l={sm:o.default.sm,md:o.default.md,lg:o.default.lg,xl:o.default.xl},u={start:o.default.alignStart,center:o.default.alignCenter,end:o.default.alignEnd},d={plain:o.default.plain,card:o.default.card,accent:o.default.accent},f={start:o.default.accentStart,top:o.default.accentTop},p={neutral:o.default.toneNeutral,primary:o.default.tonePrimary,accent:o.default.toneAccent,success:o.default.toneSuccess,warning:o.default.toneWarning,danger:o.default.toneDanger,info:o.default.toneInfo},ee={neutral:o.default.barNeutral,primary:o.default.barPrimary,accent:o.default.barAccent,success:o.default.barSuccess,warning:o.default.barWarning,danger:o.default.barDanger,info:o.default.barInfo},te={increase:i.ArrowUpIcon,decrease:i.ArrowDownIcon,neutral:i.MinusIcon},m={style:`percent`,maximumFractionDigits:1},h=1200,g=e=>1-(1-e)**3,_=()=>typeof window<`u`&&typeof window.matchMedia==`function`&&window.matchMedia(`(prefers-reduced-motion: reduce)`).matches,v=e=>{if(!Number.isFinite(e))return 0;let[,t=``]=String(e).split(`.`);return Math.min(4,t.replace(/e.*$/,``).length)};function y(e){return e>0?`increase`:e<0?`decrease`:`neutral`}function ne(e,t,n){let r=t&&e!==void 0,[i,a]=(0,s.useState)(()=>r&&!_()?0:e),o=(0,s.useRef)(i);return o.current=i,(0,s.useEffect)(()=>{if(!r||_()){a(e);return}if(!n)return;let t=o.current??0,i=e,s=10**v(i),c=0,l,u=e=>{l??=e;let n=Math.min(1,(e-l)/h),r=t+(i-t)*g(n);a(n>=1?i:Math.round(r*s)/s),n<1&&(c=requestAnimationFrame(u))},d=()=>{c=requestAnimationFrame(u)};if(typeof IntersectionObserver>`u`)return d(),()=>cancelAnimationFrame(c);let f=new IntersectionObserver(e=>{e.some(e=>e.isIntersecting)&&(f.disconnect(),d())},{threshold:.25});return f.observe(n),()=>{f.disconnect(),cancelAnimationFrame(c)}},[r,e,n]),i}var b=(0,s.createContext)(!1),x=({label:i,value:h,format:g,locale:_,prefix:v,suffix:x,unit:S,helpText:C,icon:w,size:T=`md`,align:E=`start`,variant:D=`plain`,accentPosition:re=`start`,tone:O,change:k,changeType:ie,positiveIsGood:A=!0,changeFormat:j=m,comparisonLabel:ae,changeLabel:oe,progress:M,sparkline:N,animate:P=!1,loading:F=!1,loadingLabel:I,className:L,ref:R,...z})=>{let{messages:B,locale:V}=e.useLocale(),H=_??V,U=I??B.stat.loading,W=(0,s.useContext)(b),[G,K]=(0,s.useState)(null),se=t.useMergedRef(K,R),q=typeof h==`number`,J=(0,s.useMemo)(()=>new Intl.NumberFormat(H,g),[H,g]),ce=(0,s.useMemo)(()=>new Intl.NumberFormat(H,j),[H,j]),Y=ne(q?h:void 0,P&&q&&!F,G),X=q?J.format(h):void 0,le=q&&Y!==void 0?J.format(Y):X,ue=P&&q,Z=k!==void 0&&Number.isFinite(k),Q=ie??(Z?y(k):`neutral`),de=Q===`neutral`?`neutral`:Q===`increase`===A?`positive`:`negative`,$=Z?ce.format(Math.abs(k)):``,fe=Z?Q===`neutral`?$:`${Q===`increase`?`+`:`−`}${$}`:``,pe=oe??[Q===`increase`?B.stat.increased($):Q===`decrease`?B.stat.decreased($):k===0?B.stat.noChange:B.stat.changed($),ae].filter(Boolean).join(` `),me=te[Q],he=typeof i==`string`||typeof i==`number`?B.stat.progressNamed(String(i)):B.stat.progress,ge=W?`div`:`dl`,_e=O??`accent`;return(0,c.jsxs)(ge,{...z,ref:se,"aria-busy":F||void 0,"data-variant":D,className:n.cx(o.default.root,l[T],u[E],d[D],D===`accent`&&f[re],D===`accent`&&ee[_e],p[O??`primary`],N!=null&&o.default.hasSparkline,L),children:[(0,c.jsxs)(`dt`,{className:o.default.labelRow,children:[w!=null&&(0,c.jsx)(`span`,{className:o.default.icon,"aria-hidden":`true`,children:w}),(0,c.jsx)(`span`,{className:o.default.label,children:i})]}),(0,c.jsx)(`dd`,{className:o.default.valueRow,children:F?(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(`span`,{className:n.cx(o.default.skeleton,o.default.skeletonValue),"aria-hidden":`true`}),Z&&(0,c.jsx)(`span`,{className:n.cx(o.default.skeleton,o.default.skeletonChange),"aria-hidden":`true`}),(0,c.jsx)(r.VisuallyHidden,{children:U})]}):(0,c.jsxs)(c.Fragment,{children:[(0,c.jsxs)(`span`,{className:o.default.value,children:[v!=null&&(0,c.jsx)(`span`,{className:o.default.affix,children:v}),ue?(0,c.jsxs)(`span`,{className:o.default.counter,children:[(0,c.jsx)(`span`,{className:o.default.counterGhost,"aria-hidden":`true`,children:X}),(0,c.jsx)(`span`,{className:o.default.counterLive,"aria-hidden":`true`,children:le}),(0,c.jsx)(r.VisuallyHidden,{children:X})]}):(0,c.jsx)(`span`,{className:o.default.number,children:q?X:h}),x!=null&&(0,c.jsx)(`span`,{className:o.default.affix,children:x}),S!=null&&(0,c.jsx)(`span`,{className:o.default.unit,children:S})]}),Z&&(0,c.jsxs)(`span`,{className:o.default.change,"data-trend":Q,"data-sentiment":de,children:[(0,c.jsxs)(`span`,{className:o.default.changeVisible,"aria-hidden":`true`,children:[(0,c.jsx)(me,{className:o.default.changeIcon,strokeWidth:2.5}),fe]}),(0,c.jsx)(r.VisuallyHidden,{children:`, ${pe}`})]})]})}),N!=null&&(0,c.jsx)(`dd`,{className:o.default.sparkline,children:N}),C!=null&&(0,c.jsx)(`dd`,{className:o.default.helpText,children:C}),M&&(0,c.jsx)(`dd`,{className:o.default.progress,children:(0,c.jsx)(a.Progress,{size:`sm`,value:F?null:M.value,max:M.max??100,tone:M.tone??O??`primary`,label:M.label,showValue:M.showValue,valueText:M.valueText,"aria-label":M.label?void 0:he})})]})},S=[`base`,`sm`,`md`,`lg`,`xl`,`2xl`],C={plain:o.default.groupPlain,card:o.default.groupCard},w=({children:e,columns:t,divided:r=!1,variant:i=`plain`,className:a,style:s,...l})=>{let u;if(t!==void 0){let e={},n;for(let r of S){let i=typeof t==`number`?r===`base`?t:void 0:t[r];i!==void 0&&(n=Math.max(1,Math.round(i))),n!==void 0&&(e[`--_cols-${r}`]=n)}u=e}return(0,c.jsx)(b.Provider,{value:!0,children:(0,c.jsx)(`dl`,{...l,className:n.cx(o.default.group,C[i],t===void 0?o.default.groupAuto:o.default.groupColumns,r&&o.default.groupDivided,a),style:u?{...u,...s}:s,children:e})})};exports.Stat=x,exports.StatGroup=w,exports.getStatChangeType=y;

package/dist/components/data-display/Stat/Stat.d.ts

@@ -0,0 +1,149 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { Responsive, Tone } from '../../../types/common';
+/** Stat size. Adds `xl` to the shared scale for hero, scoreboard-style numbers. */
+export type StatSize = "sm" | "md" | "lg" | "xl";
+/** Horizontal alignment of the stat's content. */
+export type StatAlign = "start" | "center" | "end";
+/**
+ * Surface style.
+ * - `plain`: no surface, just the numbers.
+ * - `card`: a rounded (`--radius-xl`) raised card with a soft shadow.
+ * - `accent`: a bold bar on one edge (the accent by default, or the `tone` color).
+ */
+export type StatVariant = "plain" | "card" | "accent";
+/** Edge the `accent` variant's bar sits on. `start` is logical (flips in RTL). */
+export type StatAccentPosition = "start" | "top";
+/** Direction of a change. Inferred from the sign of `change` when not set. */
+export type StatChangeType = "increase" | "decrease" | "neutral";
+/** Options for the optional progress bar under the value. */
+export interface StatProgress {
+    /** Current amount, e.g. `412` points. */
+    value: number;
+    /** Goal or capacity. @default 100 */
+    max?: number;
+    /** Visible caption above the bar, e.g. `"68% of season goal"`. Also its accessible name. */
+    label?: ReactNode;
+    /** Show the formatted percentage next to the caption. @default false */
+    showValue?: boolean;
+    /** Fill color. @default the stat's `tone`, or `"primary"` */
+    tone?: Tone;
+    /** Text screen readers announce instead of the percentage, e.g. `"412 of 600 points"`. */
+    valueText?: string;
+}
+/** Infers a change direction from the sign of `change`. */
+export declare function getStatChangeType(change: number): StatChangeType;
+export interface StatOwnProps {
+    /** Eyebrow label above the value, shown in uppercase display type (e.g. `"Points"`). Rendered as the `<dt>`. */
+    label: ReactNode;
+    /**
+     * The headline value. Numbers are formatted with `format` and `locale`,
+     * and can count up with `animate`. Any other node is rendered as is.
+     */
+    value: ReactNode;
+    /**
+     * `Intl.NumberFormat` options for a numeric `value`, e.g.
+     * `{ notation: "compact" }` (12.4K), `{ style: "percent" }` (pass a
+     * fraction, 0.48 shows 48%), or `{ style: "currency", currency: "USD" }`.
+     */
+    format?: Intl.NumberFormatOptions;
+    /** Locale(s) for number formatting. @default the user's locale */
+    locale?: string | string[];
+    /** Text before the value, at a smaller size (e.g. `"#"` or `"$"` when not using currency format). */
+    prefix?: ReactNode;
+    /** Text right after the value, at a smaller size (e.g. `"%"` or `"+"`). */
+    suffix?: ReactNode;
+    /** Unit after the value in small caps type, e.g. `"PPG"` or `"MIN"`. */
+    unit?: ReactNode;
+    /** Muted supporting text under the value, e.g. `"vs. last 5 games"`. */
+    helpText?: ReactNode;
+    /** Decorative icon next to the label, in a soft tone-tinted circle. Hidden from assistive technology. */
+    icon?: ReactNode;
+    /** Type and spacing scale. `xl` is for hero, scoreboard numbers. @default "md" */
+    size?: StatSize;
+    /** Horizontal alignment. @default "start" */
+    align?: StatAlign;
+    /** Surface style. @default "plain" */
+    variant?: StatVariant;
+    /** Edge the `accent` bar sits on. @default "start" */
+    accentPosition?: StatAccentPosition;
+    /**
+     * Tints the icon circle, the accent bar, and the progress fill.
+     * @default "primary" for the icon and progress; the accent bar defaults to `"accent"`
+     */
+    tone?: Tone;
+    /**
+     * Change since the comparison period, formatted with `changeFormat`. With the
+     * default percent format, pass a fraction: `0.042` shows `+4.2%`.
+     */
+    change?: number;
+    /** Direction of the change. @default inferred from the sign of `change` */
+    changeType?: StatChangeType;
+    /**
+     * Whether an increase is good news. Set `false` for stats like turnovers or
+     * fouls, so an increase shows in the danger tone and a decrease in success.
+     * @default true
+     */
+    positiveIsGood?: boolean;
+    /** `Intl.NumberFormat` options for `change`. @default { style: "percent", maximumFractionDigits: 1 } */
+    changeFormat?: Intl.NumberFormatOptions;
+    /**
+     * The comparison period, appended to the screen-reader change text, e.g.
+     * `"from last week"` reads as "increased by 4.2% from last week".
+     */
+    comparisonLabel?: string;
+    /** Replaces the whole generated screen-reader change text. */
+    changeLabel?: string;
+    /** Thin progress bar under the value, e.g. toward a season goal. */
+    progress?: StatProgress;
+    /** Slot for a small chart (e.g. a sparkline), shown beside the value. Give it its own text alternative. */
+    sparkline?: ReactNode;
+    /**
+     * Counts a numeric `value` up from 0 when the stat scrolls into view (and
+     * from the old value when it changes). Skipped under
+     * `prefers-reduced-motion`. Screen readers always get the final value.
+     * @default false
+     */
+    animate?: boolean;
+    /** Shows placeholder blocks instead of the value and change, and sets `aria-busy`. @default false */
+    loading?: boolean;
+    /** Screen-reader text while `loading`. @default "Loading" */
+    loadingLabel?: string;
+}
+export type StatProps = StatOwnProps & Omit<ComponentPropsWithRef<"div">, keyof StatOwnProps | "children">;
+/**
+ * A big, bold number with a label, for dashboards and box scores: points,
+ * revenue, completion rates. Optional trend, progress, icon, and sparkline.
+ *
+ * Semantics: a description list. Standalone, the root is a `<dl>`; inside a
+ * `StatGroup` (itself a `<dl>`), the root is a `<div>` grouping one `<dt>`
+ * (the label) with its `<dd>`s (value and change, help text, progress,
+ * sparkline). Screen readers read it as "Points: 24.3, increased by 4.2%
+ * from last week". Trends are never color- or arrow-only: the sign is in
+ * the visible text and the direction is spelled out in hidden text.
+ */
+export declare const Stat: ({ label, value, format, locale: localeProp, prefix, suffix, unit, helpText, icon, size, align, variant, accentPosition, tone, change, changeType, positiveIsGood, changeFormat, comparisonLabel, changeLabel, progress, sparkline, animate, loading, loadingLabel: loadingLabelProp, className, ref, ...rest }: StatProps) => import("react").JSX.Element;
+/** Surface style of a `StatGroup`. `card` wraps every stat in one raised card (a box-score panel). */
+export type StatGroupVariant = "plain" | "card";
+export interface StatGroupOwnProps {
+    /** `Stat` elements. Each renders as a `<div>` group of `<dt>` and `<dd>`s inside this `<dl>`. */
+    children?: ReactNode;
+    /**
+     * Number of columns, fixed or per breakpoint (mobile first), e.g.
+     * `{ base: 2, md: 5 }`. When not set, stats fill the row and wrap
+     * automatically.
+     */
+    columns?: Responsive<number>;
+    /** Draws hairline dividers between stats, across wrapped rows too. @default false */
+    divided?: boolean;
+    /** Surface style. @default "plain" */
+    variant?: StatGroupVariant;
+}
+export type StatGroupProps = StatGroupOwnProps & Omit<ComponentPropsWithRef<"dl">, keyof StatGroupOwnProps>;
+/**
+ * A responsive row or grid of `Stat`s, such as a player's box-score line.
+ * Renders one `<dl>`, so the whole group is a single description list.
+ *
+ * With `divided`, stats sit edge to edge with hairline dividers; give the
+ * stats `variant="plain"` there (a `card` stat's shadow would be clipped).
+ */
+export declare const StatGroup: ({ children, columns, divided, variant, className, style, ...rest }: StatGroupProps) => import("react").JSX.Element;