@vjdesigns/vjdesigns-ui 0.0.0-stage → 1.5.0

package/dist/components/feedback/Toast/toastStore.mjs

@@ -0,0 +1,86 @@
+import { isValidElement as e } from "react";
+//#region src/components/feedback/Toast/toastStore.ts
+var t = [], n = 0;
+function r() {
+	let e = t, r = /* @__PURE__ */ new Set(), i = (t) => {
+		e = t, r.forEach((e) => e());
+	}, a = (t, n) => {
+		e.some((e) => e.id === t) && i(e.map((e) => e.id === t ? {
+			...e,
+			...n,
+			id: t,
+			version: e.version + 1,
+			status: "open"
+		} : e));
+	};
+	return {
+		subscribe: (e) => (r.add(e), () => r.delete(e)),
+		getSnapshot: () => e,
+		getServerSnapshot: () => t,
+		add: ({ id: t, ...r }) => {
+			if (t && e.some((e) => e.id === t)) return a(t, r), t;
+			n += 1;
+			let o = t ?? `toast-${n}`;
+			return i([...e, {
+				...r,
+				id: o,
+				version: 0,
+				status: "open"
+			}]), o;
+		},
+		update: a,
+		dismiss: (t, n = "dismiss") => {
+			let r = e.filter((e) => (t === void 0 || e.id === t) && e.status === "open");
+			if (r.length === 0) return;
+			r.forEach((e) => n === "auto" ? e.onAutoClose?.(e.id) : e.onDismiss?.(e.id));
+			let a = new Set(r.map((e) => e.id));
+			i(e.map((e) => a.has(e.id) ? {
+				...e,
+				status: "closing"
+			} : e));
+		},
+		remove: (t) => {
+			e.some((e) => e.id === t) && i(e.filter((e) => e.id !== t));
+		}
+	};
+}
+function i(t) {
+	return typeof t == "object" && !!t && !Array.isArray(t) && !e(t);
+}
+function a(e) {
+	return i(e) ? e : { title: e };
+}
+function o(e, t) {
+	return a(typeof e == "function" ? e(t) : e);
+}
+function s(e) {
+	let t = (t) => (n, r) => e.add({
+		title: n,
+		...r,
+		tone: t
+	}), n = ((t) => e.add(t));
+	return n.success = t("success"), n.error = t("danger"), n.warning = t("warning"), n.info = t("info"), n.loading = t("loading"), n.dismiss = (t) => e.dismiss(t), n.update = (t, n) => e.update(t, n), n.promise = (t, n, r) => {
+		let i = e.add({
+			...r,
+			...a(n.loading),
+			tone: "loading",
+			dismissible: r?.dismissible ?? !0
+		}), s = typeof t == "function" ? t() : t, c = {
+			description: void 0,
+			duration: r?.duration,
+			icon: void 0
+		};
+		return s.then((t) => e.update(i, {
+			...c,
+			...o(n.success, t),
+			tone: "success"
+		}), (t) => e.update(i, {
+			...c,
+			...o(n.error, t),
+			tone: "danger"
+		})), i;
+	}, n;
+}
+var c = r(), l = s(c);
+//#endregion
+export { s as createToastApi, r as createToastStore, l as toast, c as toastStore };

package/dist/components/feedback/Toast/toastTiming.cjs.js

@@ -0,0 +1 @@
+let e=require("react");var t=4e3,n=250,r=1e4,i={neutral:``,info:`Info`,success:`Success`,warning:`Warning`,danger:`Error`,loading:`Loading`},a=e=>typeof e==`string`||typeof e==`number`?String(e):``,o=e=>e.split(/\s+/).filter(Boolean).length;function s(e,n){let{duration:i,tone:s,action:c}=e;if(i===1/0||i===void 0&&(s===`loading`||c))return 1/0;let l=o(`${a(e.title)} ${a(e.description)}`),u=Math.max(t+l*250,c?r:0);return Math.max(i??n,u)}function c(e,t){if(e.announcement!==void 0)return e.announcement;let n=[t,a(e.title),a(e.description)].filter(Boolean).join(`. `),r=e.action?.altText;return r?`${n}. ${r}`:n}function l(t,n,r,i){let a=(0,e.useRef)(t),o=(0,e.useRef)(i);o.current=i;let s=(0,e.useRef)(r),c=(0,e.useRef)(t);(s.current!==r||c.current!==t)&&(s.current=r,c.current=t,a.current=t),(0,e.useEffect)(()=>{if(n||!Number.isFinite(a.current))return;let e=Date.now(),i=window.setTimeout(()=>o.current(),Math.max(0,a.current));return()=>{window.clearTimeout(i),s.current===r&&c.current===t&&(a.current-=Date.now()-e)}},[n,r,t])}exports.TOAST_MIN_ACTION_DURATION=r,exports.TOAST_MIN_DURATION=t,exports.TOAST_MS_PER_WORD=n,exports.announcementOf=c,exports.defaultToneLabels=i,exports.resolveDuration=s,exports.textOf=a,exports.usePausableTimer=l;

package/dist/components/feedback/Toast/toastTiming.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { ToastRecord, ToastTone } from './toastTypes';
+/** Shortest time any auto-closing toast stays up (SC 2.2.1). */
+export declare const TOAST_MIN_DURATION = 4000;
+/** Extra reading time added per word of text. */
+export declare const TOAST_MS_PER_WORD = 250;
+/** Shortest time a toast with an action stays up when given a duration. */
+export declare const TOAST_MIN_ACTION_DURATION = 10000;
+/** Default screen reader labels for each tone, read before the message. */
+export declare const defaultToneLabels: Record<ToastTone, string>;
+/** Plain text of a node when it is a string or number. */
+export declare const textOf: (node: ReactNode) => string;
+/**
+ * The time a toast actually stays up:
+ * - `Infinity` when asked, for `loading`, and for toasts with an action and
+ *   no explicit duration.
+ * - Otherwise at least 4s plus 250ms per word of title and description
+ *   (10s for toasts with an action).
+ */
+export declare function resolveDuration(record: ToastRecord, fallback: number): number;
+/** Text sent to the live region for a toast. */
+export declare function announcementOf(record: ToastRecord, toneLabel: string): string;
+/**
+ * Runs `onExpire` after `duration` ms of un-paused time. Restarts whenever
+ * `resetKey` changes (e.g. the toast was updated).
+ */
+export declare function usePausableTimer(duration: number, paused: boolean, resetKey: unknown, onExpire: () => void): void;

package/dist/components/feedback/Toast/toastTiming.mjs

@@ -0,0 +1,43 @@
+import { useEffect as e, useRef as t } from "react";
+//#region src/components/feedback/Toast/toastTiming.ts
+var n = 4e3, r = 250, i = 1e4, a = {
+	neutral: "",
+	info: "Info",
+	success: "Success",
+	warning: "Warning",
+	danger: "Error",
+	loading: "Loading"
+}, o = (e) => typeof e == "string" || typeof e == "number" ? String(e) : "", s = (e) => e.split(/\s+/).filter(Boolean).length;
+function c(e, t) {
+	let { duration: r, tone: a, action: c } = e;
+	if (r === Infinity || r === void 0 && (a === "loading" || c)) return Infinity;
+	let l = s(`${o(e.title)} ${o(e.description)}`), u = Math.max(n + l * 250, c ? i : 0);
+	return Math.max(r ?? t, u);
+}
+function l(e, t) {
+	if (e.announcement !== void 0) return e.announcement;
+	let n = [
+		t,
+		o(e.title),
+		o(e.description)
+	].filter(Boolean).join(". "), r = e.action?.altText;
+	return r ? `${n}. ${r}` : n;
+}
+function u(n, r, i, a) {
+	let o = t(n), s = t(a);
+	s.current = a;
+	let c = t(i), l = t(n);
+	(c.current !== i || l.current !== n) && (c.current = i, l.current = n, o.current = n), e(() => {
+		if (r || !Number.isFinite(o.current)) return;
+		let e = Date.now(), t = window.setTimeout(() => s.current(), Math.max(0, o.current));
+		return () => {
+			window.clearTimeout(t), c.current === i && l.current === n && (o.current -= Date.now() - e);
+		};
+	}, [
+		r,
+		i,
+		n
+	]);
+}
+//#endregion
+export { i as TOAST_MIN_ACTION_DURATION, n as TOAST_MIN_DURATION, r as TOAST_MS_PER_WORD, l as announcementOf, a as defaultToneLabels, c as resolveDuration, o as textOf, u as usePausableTimer };

package/dist/components/feedback/Toast/toastTypes.d.ts

@@ -0,0 +1,136 @@
+import { MouseEvent, ReactNode } from 'react';
+import { StatusTone } from '../../../types/common';
+/**
+ * Semantic color and icon of a toast. The status tones match Alert;
+ * `neutral` is a plain message and `loading` shows a Spinner (and does not
+ * auto-dismiss until it is updated to another tone).
+ */
+export type ToastTone = StatusTone | "neutral" | "loading";
+/** Where the toast viewport sits on screen. Below 640px wide it is always full width at the bottom. */
+export type ToastPlacement = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end";
+/**
+ * How a toast is announced. `polite` uses the viewport's `role="status"`
+ * region, `assertive` its `role="alert"` region, and `off` skips it.
+ */
+export type ToastPoliteness = "polite" | "assertive" | "off";
+/** An action button inside a toast, such as "Undo". */
+export interface ToastAction {
+    /** Visible button label. Keep it short ("Undo", "View", "Retry"). */
+    label: ReactNode;
+    /**
+     * Called when the button is pressed. The toast then closes, unless you call
+     * `event.preventDefault()`.
+     */
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Required. Describes another way to do the same thing, for people who
+     * can't reach the toast before it closes, e.g. "Restore it from Trash".
+     * Included in the screen reader announcement after the message.
+     */
+    altText: string;
+}
+/** Options accepted by `toast()`, `update()`, and the tone shortcuts. */
+export interface ToastOptions {
+    /**
+     * Stable id. Calling `toast()` again with an id that is already showing
+     * updates that toast instead of adding a duplicate.
+     */
+    id?: string;
+    /** Bold display headline. */
+    title?: ReactNode;
+    /** Supporting text under the title. */
+    description?: ReactNode;
+    /** Semantic color and default icon. @default "neutral" */
+    tone?: ToastTone;
+    /** Replaces the tone's default icon. Decorative. Pass `null` for no icon. */
+    icon?: ReactNode;
+    /**
+     * Action button. A toast with an action stays until dismissed unless you
+     * pass a `duration`, which is then raised to at least 10 seconds.
+     */
+    action?: ToastAction;
+    /**
+     * Milliseconds before the toast closes on its own. `Infinity` keeps it
+     * until it is dismissed. Short values are raised to a readable minimum
+     * (4 seconds plus time per word). Timers pause while the viewport is
+     * hovered or focused and while the window is in the background.
+     * @default the provider's `duration` (5000); `Infinity` for `loading` and toasts with an action
+     */
+    duration?: number;
+    /** Shows the close button and lets Escape close the toast. @default true */
+    dismissible?: boolean;
+    /**
+     * Plain-text announcement for screen readers. Defaults to the tone label,
+     * title, and description when they are strings; set it when they are JSX.
+     */
+    announcement?: string;
+    /** Live region politeness. @default "assertive" for `danger`, otherwise "polite" */
+    politeness?: ToastPoliteness;
+    /** Shows a thin decorative bar for the remaining time. @default the provider's `showProgress` */
+    showProgress?: boolean;
+    /** Called when the toast is dismissed by the user or by `dismiss()`. */
+    onDismiss?: (id: string) => void;
+    /** Called when the toast closes because its time ran out. */
+    onAutoClose?: (id: string) => void;
+    /**
+     * Custom content. Return a `Toast` (or your own markup) to replace the
+     * default rendering; the viewport still handles timing, focus, and
+     * announcements.
+     */
+    render?: (context: ToastRenderContext) => ReactNode;
+}
+/** Passed to `ToastOptions.render`. */
+export interface ToastRenderContext {
+    /** The toast's id. */
+    id: string;
+    /** The toast's current options. */
+    toast: ToastRecord;
+    /** Closes this toast. */
+    dismiss: () => void;
+}
+/** A toast in the store. */
+export interface ToastRecord extends Omit<ToastOptions, "id"> {
+    /** Unique id. */
+    id: string;
+    /** Incremented on every update; restarts the timer and re-announces. */
+    version: number;
+    /** `closing` while the exit animation runs. */
+    status: "open" | "closing";
+}
+/** Content accepted by the `promise()` states. */
+export type ToastPromiseState<T> = ReactNode | ToastOptions | ((value: T) => ReactNode | ToastOptions);
+/** Messages for `promise()`. */
+export interface ToastPromiseMessages<T> {
+    /** Shown while pending, with the `loading` tone. */
+    loading: ReactNode | ToastOptions;
+    /** Shown when the promise resolves, with the `success` tone. */
+    success: ToastPromiseState<T>;
+    /** Shown when the promise rejects, with the `danger` tone. */
+    error: ToastPromiseState<unknown>;
+}
+/** Shortcut that sets the tone: `toast.success("Saved")`. */
+export type ToastShortcut = (title: ReactNode, options?: ToastOptions) => string;
+/** The `toast` function and its helpers. */
+export interface ToastApi {
+    /** Shows a toast and returns its id. */
+    (options: ToastOptions): string;
+    /** Shows a `success` toast. */
+    success: ToastShortcut;
+    /** Shows a `danger` toast, announced assertively. */
+    error: ToastShortcut;
+    /** Shows a `warning` toast. */
+    warning: ToastShortcut;
+    /** Shows an `info` toast. */
+    info: ToastShortcut;
+    /** Shows a `loading` toast that stays until updated or dismissed. */
+    loading: ToastShortcut;
+    /** Closes one toast, or every toast when no id is given. */
+    dismiss: (id?: string) => void;
+    /** Changes a toast in place (restarts its timer and re-announces it). */
+    update: (id: string, options: ToastOptions) => void;
+    /**
+     * Shows a loading toast, then updates it to success or error when the
+     * promise settles. Returns the toast id.
+     */
+    promise: <T>(promise: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>, options?: ToastOptions) => string;
+}

package/dist/components/feedback/Toast/useToast.cjs.js

@@ -0,0 +1 @@
+const e=require("./toastStore.cjs.js");let t=require("react");var n=(0,t.createContext)(null);function r(){let r=(0,t.useContext)(n),i=r?.store??e.toastStore,a=r?.api??e.toast,o=(0,t.useSyncExternalStore)(i.subscribe,i.getSnapshot,i.getServerSnapshot);return{toast:a,dismiss:a.dismiss,update:a.update,promise:a.promise,toasts:o}}exports.ToastContext=n,exports.useToast=r;

package/dist/components/feedback/Toast/useToast.d.ts

@@ -0,0 +1,32 @@
+import { ToastStore } from './toastStore';
+import { ToastApi, ToastRecord } from './toastTypes';
+/** @internal Shared by ToastProvider and useToast. */
+export interface ToastContextValue {
+    store: ToastStore;
+    api: ToastApi;
+}
+/** @internal */
+export declare const ToastContext: import('react').Context<ToastContextValue | null>;
+/** What `useToast()` returns. */
+export interface UseToastResult {
+    /** Shows a toast and returns its id. Also has `.success`, `.error`, `.warning`, `.info`, `.loading`. */
+    toast: ToastApi;
+    /** Closes one toast, or all of them when no id is given. */
+    dismiss: ToastApi["dismiss"];
+    /** Changes a toast in place. */
+    update: ToastApi["update"];
+    /** Loading toast that becomes success or error when the promise settles. */
+    promise: ToastApi["promise"];
+    /** Current toasts (including queued ones), oldest first. */
+    toasts: readonly ToastRecord[];
+}
+/**
+ * Shows toasts from a component. Uses the nearest `ToastProvider`'s store,
+ * or the default store (the one the exported `toast()` uses) without one.
+ *
+ * ```tsx
+ * const { toast } = useToast();
+ * toast.success("Roster saved");
+ * ```
+ */
+export declare function useToast(): UseToastResult;

package/dist/components/feedback/Toast/useToast.mjs

@@ -0,0 +1,16 @@
+import { toast as e, toastStore as t } from "./toastStore.mjs";
+import { createContext as n, useContext as r, useSyncExternalStore as i } from "react";
+//#region src/components/feedback/Toast/useToast.ts
+var a = n(null);
+function o() {
+	let n = r(a), o = n?.store ?? t, s = n?.api ?? e, c = i(o.subscribe, o.getSnapshot, o.getServerSnapshot);
+	return {
+		toast: s,
+		dismiss: s.dismiss,
+		update: s.update,
+		promise: s.promise,
+		toasts: c
+	};
+}
+//#endregion
+export { a as ToastContext, o as useToast };

package/dist/components/feedback/Toast/useToastAnnouncer.cjs.js

@@ -0,0 +1 @@
+const e=require("./toastTiming.cjs.js");let t=require("react");var n=150;function r(r,i){let[a,o]=(0,t.useState)([]),[s,c]=(0,t.useState)([]),l=(0,t.useRef)(new Map),u=(0,t.useRef)(new Set);return(0,t.useEffect)(()=>{let t=(e,t)=>{let n=window.setTimeout(()=>{u.current.delete(n),e()},t);u.current.add(n)},a=new Set(r.map(e=>e.id));for(let e of l.current.keys())a.has(e)||l.current.delete(e);for(let a of r){if(a.status!==`open`||l.current.get(a.id)===a.version)continue;l.current.set(a.id,a.version);let r=a.tone??`neutral`,s=a.politeness??(r===`danger`?`assertive`:`polite`);if(s===`off`)continue;let u=e.announcementOf(a,i[r]??e.defaultToneLabels[r]);if(!u)continue;let d={key:`${a.id}-${a.version}`,text:u},f=s===`assertive`?c:o;t(()=>f(e=>[...e,d]),n),t(()=>f(e=>e.filter(e=>e.key!==d.key)),7150)}},[r,i]),(0,t.useEffect)(()=>{let e=u.current,t=l.current;return()=>{e.forEach(e=>window.clearTimeout(e)),e.clear(),t.clear()}},[]),{polite:a,assertive:s}}exports.useToastAnnouncer=r;

package/dist/components/feedback/Toast/useToastAnnouncer.d.ts

@@ -0,0 +1,15 @@
+import { ToastRecord, ToastTone } from './toastTypes';
+/** @internal A message currently in one of the live regions. */
+export interface LiveMessage {
+    key: string;
+    text: string;
+}
+/**
+ * @internal Turns visible toasts into live region messages. Each new toast
+ * (and each update of one) appends a fresh node to the persistent polite or
+ * assertive region, which screen readers announce as an addition.
+ */
+export declare function useToastAnnouncer(visible: readonly ToastRecord[], toneLabels: Partial<Record<ToastTone, string>>): {
+    polite: LiveMessage[];
+    assertive: LiveMessage[];
+};

package/dist/components/feedback/Toast/useToastAnnouncer.mjs

@@ -0,0 +1,39 @@
+import { announcementOf as e, defaultToneLabels as t } from "./toastTiming.mjs";
+import { useEffect as n, useRef as r, useState as i } from "react";
+//#region src/components/feedback/Toast/useToastAnnouncer.ts
+var a = 150;
+function o(o, s) {
+	let [c, l] = i([]), [u, d] = i([]), f = r(/* @__PURE__ */ new Map()), p = r(/* @__PURE__ */ new Set());
+	return n(() => {
+		let n = (e, t) => {
+			let n = window.setTimeout(() => {
+				p.current.delete(n), e();
+			}, t);
+			p.current.add(n);
+		}, r = new Set(o.map((e) => e.id));
+		for (let e of f.current.keys()) r.has(e) || f.current.delete(e);
+		for (let r of o) {
+			if (r.status !== "open" || f.current.get(r.id) === r.version) continue;
+			f.current.set(r.id, r.version);
+			let i = r.tone ?? "neutral", o = r.politeness ?? (i === "danger" ? "assertive" : "polite");
+			if (o === "off") continue;
+			let c = e(r, s[i] ?? t[i]);
+			if (!c) continue;
+			let u = {
+				key: `${r.id}-${r.version}`,
+				text: c
+			}, p = o === "assertive" ? d : l;
+			n(() => p((e) => [...e, u]), a), n(() => p((e) => e.filter((e) => e.key !== u.key)), 7150);
+		}
+	}, [o, s]), n(() => {
+		let e = p.current, t = f.current;
+		return () => {
+			e.forEach((e) => window.clearTimeout(e)), e.clear(), t.clear();
+		};
+	}, []), {
+		polite: c,
+		assertive: u
+	};
+}
+//#endregion
+export { o as useToastAnnouncer };

package/dist/components/forms/CheckBox/CheckBox.cjs.js

@@ -0,0 +1 @@
+const e=require("../../../hooks/useControllableState.cjs.js"),t=require("../../../hooks/useFormReset.cjs.js"),n=require("../../../utils/cx.cjs.js"),r=require("../../primitives/Icon/icons.cjs.js"),i=require("../Field/FieldContext.cjs.js"),a=require("./CheckBox.module.css.cjs.js");let o=require("react"),s=require("react/jsx-runtime");var c={sm:a.default.sm,md:a.default.md,lg:a.default.lg},l={neutral:a.default.toneNeutral,primary:a.default.tonePrimary,accent:a.default.toneAccent,success:a.default.toneSuccess,warning:a.default.toneWarning,danger:a.default.toneDanger,info:a.default.toneInfo},u={end:a.default.labelEnd,start:a.default.labelStart},d={vertical:a.default.vertical,horizontal:a.default.horizontal},f=(0,o.createContext)(null);function p({checked:d,defaultChecked:p=!1,onCheckedChange:m,indeterminate:h=!1,label:g,description:_,size:v,tone:y,invalid:b,disabled:x,required:S,readOnly:C,labelPosition:w=`end`,value:T,name:E,id:D,className:O,style:k,ref:A,onChange:j,onClick:M,"aria-describedby":N,...P}){let F=(0,o.useContext)(f),I=(0,o.useId)(),L=(0,o.useId)(),R=i.useFieldControl({id:D??(F?I:void 0),invalid:b??F?.invalid,required:S,disabled:x??(F?.disabled||void 0),readOnly:C??(F?.readOnly||void 0),size:v??F?.size,"aria-describedby":[_?L:void 0,N].filter(Boolean).join(` `)||void 0}),z=R.id??I,B=R.size??`md`,V=y??F?.tone??`primary`,{disabled:H,readOnly:U,invalid:W}=R,G=F?[_?L:void 0,F.itemDescribedBy,N].filter(Boolean).join(` `)||void 0:R.ariaProps[`aria-describedby`],[K,q]=e.useControllableState({value:d,defaultValue:p,onChange:m});t.useFormReset(()=>X.current,()=>F?F.reset():q(p??!1),F?!0:d===void 0);let J=T??`on`,Y=F?F.value.includes(J):K,X=(0,o.useRef)(null);(0,o.useLayoutEffect)(()=>{X.current&&(X.current.indeterminate=h)});let Z=(0,o.useCallback)(e=>{if(X.current=e,typeof A==`function`)return A(e);A&&(A.current=e)},[A]),Q=e=>{M?.(e),U&&e.preventDefault()},$=e=>{if(j?.(e),U)return;let t=e.target.checked;F?(F.toggle(J,t),m?.(t)):q(t)};return(0,s.jsxs)(`div`,{className:n.cx(a.default.root,c[B],l[V],u[w],O),style:k,"data-disabled":H||void 0,"data-invalid":W||void 0,"data-readonly":U||void 0,children:[(0,s.jsxs)(`span`,{className:a.default.controlWrap,children:[(0,s.jsx)(`input`,{...P,ref:Z,type:`checkbox`,id:z,name:E??F?.name,value:J,checked:Y,disabled:H,required:F?void 0:R.required,"aria-describedby":G,"aria-invalid":R.ariaProps[`aria-invalid`],"aria-errormessage":F?void 0:R.ariaProps[`aria-errormessage`],"aria-readonly":U||void 0,className:a.default.input,onClick:Q,onChange:$}),(0,s.jsxs)(`span`,{className:a.default.control,"aria-hidden":`true`,children:[(0,s.jsx)(r.CheckIcon,{className:n.cx(a.default.mark,a.default.check),strokeWidth:3.5}),(0,s.jsx)(r.MinusIcon,{className:n.cx(a.default.mark,a.default.minus),strokeWidth:3.5})]})]}),(g||_)&&(0,s.jsxs)(`span`,{className:a.default.text,children:[g&&(0,s.jsx)(`label`,{htmlFor:z,className:a.default.label,children:g}),_&&(0,s.jsx)(`span`,{id:L,className:a.default.description,children:_})]})]})}function m({value:t,defaultValue:r=[],onValueChange:l,name:u,orientation:p=`vertical`,size:m,tone:h,disabled:g,readOnly:_,invalid:v,label:y,description:b,className:x,children:S,"aria-labelledby":C,"aria-describedby":w,...T}){let E=i.useFieldContext(),D=(0,o.useId)(),O=(0,o.useId)(),k=i.useFieldControl({invalid:v,disabled:g,readOnly:_,size:m,"aria-describedby":[b?O:void 0,w].filter(Boolean).join(` `)||void 0}),[A,j]=e.useControllableState({value:t,defaultValue:r,onChange:l}),M=(0,o.useCallback)((e,t)=>{j(n=>t?n.includes(e)?n:[...n,e]:n.filter(t=>t!==e))},[j]),N=E?.isGroup===!0&&!C&&!y,P=[C,y?D:void 0].filter(Boolean).join(` `)||void 0,F=[b?O:void 0,w].filter(Boolean).join(` `)||void 0,I={name:u,value:A,toggle:M,size:k.size,tone:h,disabled:k.disabled,readOnly:k.readOnly,invalid:k.invalid,reset:()=>{t===void 0&&j(r??[])},itemDescribedBy:N?F:void 0};return(0,s.jsxs)(`div`,{...T,role:N?void 0:`group`,"aria-labelledby":N?void 0:P,"aria-describedby":N?F:k.ariaProps[`aria-describedby`],className:n.cx(a.default.group,c[k.size??`md`],x),"data-disabled":k.disabled||void 0,"aria-disabled":k.disabled||void 0,children:[(y||b)&&(0,s.jsxs)(`div`,{className:a.default.groupHeader,children:[y&&(0,s.jsx)(`span`,{id:D,className:a.default.groupLabel,children:y}),b&&(0,s.jsx)(`span`,{id:O,className:a.default.description,children:b})]}),(0,s.jsx)(`div`,{className:n.cx(a.default.options,d[p]),children:(0,s.jsx)(f.Provider,{value:I,children:S})})]})}exports.CheckBox=p,exports.CheckBoxGroup=m;

package/dist/components/forms/CheckBox/CheckBox.d.ts

@@ -0,0 +1,79 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { Orientation, Size, Tone } from '../../../types/common';
+/** Which side of the box the label sits on. `end` (default) puts the label after the box. */
+export type CheckBoxLabelPosition = "start" | "end";
+/** Props for `CheckBox`. Native `<input type="checkbox">` props are forwarded to the input. */
+export interface CheckBoxProps extends Omit<ComponentPropsWithRef<"input">, "type" | "size" | "checked" | "defaultChecked" | "value"> {
+    /** Checked state (controlled). Ignored inside a `CheckBoxGroup`, which owns the state. */
+    checked?: boolean;
+    /** Initial checked state (uncontrolled). */
+    defaultChecked?: boolean;
+    /** Called with the next checked state when the user toggles the box. */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Shows a "mixed" state (a dash) and exposes `aria-checked="mixed"` via the
+     * native `indeterminate` property. Use for a parent "select all" box whose
+     * children are partly checked. Stays on until you set it to `false`.
+     */
+    indeterminate?: boolean;
+    /** Visible label. Clicking it toggles the box. Without it, pass `aria-label` or `aria-labelledby`. */
+    label?: ReactNode;
+    /** Supporting text below the label, linked with `aria-describedby`. */
+    description?: ReactNode;
+    /** Box and text size. Default `md` (20px box). Inherits from `Field` or `CheckBoxGroup`. */
+    size?: Size;
+    /** Fill color when checked. Default `primary`. Inherits from `CheckBoxGroup`. */
+    tone?: Tone;
+    /** Danger styling plus `aria-invalid`. Inherits from `Field`. */
+    invalid?: boolean;
+    /** Label placement. `end` (default) puts the label after the box, `start` before it. */
+    labelPosition?: CheckBoxLabelPosition;
+    /** Keeps the box focusable and announced but prevents toggling (`aria-readonly`). */
+    readOnly?: boolean;
+    /** Form value. Required inside a `CheckBoxGroup`, where it identifies the option. Default `"on"`. */
+    value?: string;
+    /** Class name for the root element (the input receives every other prop). */
+    className?: string;
+}
+/**
+ * A checkbox with a label and an optional description. It is a real native
+ * `<input type="checkbox">` (visually hidden but focusable) layered under a
+ * custom box, so keyboard, form submission, and screen readers work natively.
+ * Works standalone, inside `Field`, and as an option in `CheckBoxGroup`.
+ */
+export declare function CheckBox({ checked: checkedProp, defaultChecked, onCheckedChange, indeterminate, label, description, size: sizeProp, tone: toneProp, invalid: invalidProp, disabled: disabledProp, required: requiredProp, readOnly: readOnlyProp, labelPosition, value, name, id: idProp, className, style, ref, onChange, onClick, "aria-describedby": ariaDescribedBy, ...rest }: CheckBoxProps): import("react").JSX.Element;
+/** Props for `CheckBoxGroup`. */
+export interface CheckBoxGroupProps extends Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange"> {
+    /** Checked option values (controlled). */
+    value?: string[];
+    /** Initially checked option values (uncontrolled). */
+    defaultValue?: string[];
+    /** Called with the full list of checked values whenever an option is toggled. */
+    onValueChange?: (value: string[]) => void;
+    /** Form field name applied to every option. */
+    name?: string;
+    /** Stack options vertically (default) or in a wrapping row. */
+    orientation?: Orientation;
+    /** Size for every option. Inherits from `Field`. */
+    size?: Size;
+    /** Checked fill color for every option. */
+    tone?: Tone;
+    /** Disable every option. Inherits from `Field`. */
+    disabled?: boolean;
+    /** Make every option read-only. Inherits from `Field`. */
+    readOnly?: boolean;
+    /** Danger styling and `aria-invalid` on every option. Inherits from `Field`. */
+    invalid?: boolean;
+    /** Visible group label for standalone use. Inside a `Fieldset`, the legend labels the group instead. */
+    label?: ReactNode;
+    /** Supporting text below the group label, linked with `aria-describedby`. */
+    description?: ReactNode;
+    /** `CheckBox` options, each with a unique `value`. */
+    children?: ReactNode;
+}
+/**
+ * A labelled set of checkboxes sharing one `string[]` value. Renders
+ * `role="group"` labelled by its own `label`, by a surrounding `Fieldset`'s
+ * legend, or by `aria-label`/`aria-labelledby`.
+ */
+export declare function CheckBoxGroup({ value: valueProp, defaultValue, onValueChange, name, orientation, size: sizeProp, tone, disabled: disabledProp, readOnly: readOnlyProp, invalid: invalidProp, label, description, className, children, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: CheckBoxGroupProps): import("react").JSX.Element;