@mks2508/mks-ui 0.2.0 → 0.3.1

package/dist/react-ui/components/MorphingPopover/MorphingPopover.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MorphingPopover.types.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/components/MorphingPopover/MorphingPopover.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,UAAU,qBAAqB;IAC7B,qCAAqC;IACrC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,mCAAmC;IACnC,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,UAAU,oBACR,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;CAClD;AAED;;;;GAIG;AACH,UAAU,+BACR,SAAQ,IAAI,CAAC,qBAAqB,EAAE,WAAW,GAAG,YAAY,CAAC;IAC/D,gDAAgD;IAChD,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACxC,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,+BAA+B,GAChC,CAAC"}

package/dist/react-ui/components/MorphingPopover/index.d.ts

@@ -0,0 +1,46 @@
+import type { IMorphingPopoverProps, IMorphingPopoverWithTargetProps } from './MorphingPopover.types';
+/**
+ * MorphingPopover — animates from a circular trigger to an expanded popover.
+ *
+ * @param content - Content to display in the expanded popover
+ * @param trigger - Trigger button content (default: "...")
+ * @param targetSize - Expanded dimensions { width, height }
+ * @param onOpen - Callback when popover opens
+ * @param onClose - Callback when popover closes
+ *
+ * @example
+ * ```tsx
+ * <MorphingPopover
+ *   trigger="+"
+ *   content={<div>Expanded content</div>}
+ *   targetSize={{ width: 320, height: 200 }}
+ * />
+ * ```
+ */
+declare const MorphingPopover: import("react").ForwardRefExoticComponent<IMorphingPopoverProps & import("react").RefAttributes<HTMLButtonElement>>;
+/**
+ * MorphingPopoverWithTarget — variant that animates to a specific target element.
+ *
+ * The target element must have CSS `anchor-name: --target-anchor` set on it.
+ *
+ * @param targetRef - Reference to the target element to anchor to
+ * @param content - Content to display in the expanded popover
+ *
+ * @example
+ * ```tsx
+ * const targetRef = useRef<HTMLDivElement>(null);
+ *
+ * <div ref={targetRef} style={{ anchorName: '--target-anchor' }}>
+ *   Drag me around
+ * </div>
+ *
+ * <MorphingPopoverWithTarget
+ *   targetRef={targetRef}
+ *   content={<div>Content</div>}
+ * />
+ * ```
+ */
+declare const MorphingPopoverWithTarget: import("react").ForwardRefExoticComponent<IMorphingPopoverWithTargetProps & import("react").RefAttributes<HTMLButtonElement>>;
+export { MorphingPopover, MorphingPopoverWithTarget };
+export type { IMorphingPopoverProps, IMorphingPopoverWithTargetProps, } from './MorphingPopover.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/react-ui/components/MorphingPopover/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/components/MorphingPopover/index.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,qBAAqB,EAErB,+BAA+B,EAChC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,eAAe,qHAuDpB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,QAAA,MAAM,yBAAyB,+HAiD9B,CAAC;AAIF,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,+BAA+B,GAChC,MAAM,yBAAyB,CAAC"}

package/dist/react-ui/components/MorphingPopover/index.js

@@ -0,0 +1,119 @@
+'use client';
+
+import { cn } from "../../lib/utils.js";
+import morphing_popover_module_default from "./morphing-popover.module.js";
+import { forwardRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/components/MorphingPopover/index.tsx
+/**
+* MorphingPopover — a popover that animates from a trigger button to a target position.
+*
+* Uses CSS Anchor Positioning + Popover API + @starting-style for smooth morphing animations.
+*
+* @example
+* ```tsx
+* <MorphingPopover
+*   trigger="..."
+*   content={<div>Expanded content</div>}
+*   targetSize={{ width: 320, height: 200 }}
+* />
+* ```
+*/
+/**
+* MorphingPopover — animates from a circular trigger to an expanded popover.
+*
+* @param content - Content to display in the expanded popover
+* @param trigger - Trigger button content (default: "...")
+* @param targetSize - Expanded dimensions { width, height }
+* @param onOpen - Callback when popover opens
+* @param onClose - Callback when popover closes
+*
+* @example
+* ```tsx
+* <MorphingPopover
+*   trigger="+"
+*   content={<div>Expanded content</div>}
+*   targetSize={{ width: 320, height: 200 }}
+* />
+* ```
+*/
+const MorphingPopover = forwardRef(({ content, trigger = "⋯", triggerClassName, popoverClassName, targetSize = {
+	width: 220,
+	height: 120
+}, onOpen, onClose, popoverId = "morphing-popover" }, ref) => {
+	const containerStyle = {
+		"--target-width": `${targetSize.width}px`,
+		"--target-height": `${targetSize.height}px`
+	};
+	const handleToggle = (e) => {
+		if (e.target.matches(":popover-open")) onOpen?.();
+		else onClose?.();
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: morphing_popover_module_default.morphingPopoverContainer,
+		style: containerStyle,
+		children: [/* @__PURE__ */ jsx("button", {
+			ref,
+			popovertarget: popoverId,
+			popoverTargetAction: "toggle",
+			className: cn(morphing_popover_module_default.morphingTrigger, triggerClassName),
+			onClick: handleToggle,
+			children: trigger
+		}), /* @__PURE__ */ jsx("div", {
+			id: popoverId,
+			popover: "auto",
+			className: cn(morphing_popover_module_default.morphingPopover, popoverClassName),
+			children: content
+		})]
+	});
+});
+MorphingPopover.displayName = "MorphingPopover";
+/**
+* MorphingPopoverWithTarget — variant that animates to a specific target element.
+*
+* The target element must have CSS `anchor-name: --target-anchor` set on it.
+*
+* @param targetRef - Reference to the target element to anchor to
+* @param content - Content to display in the expanded popover
+*
+* @example
+* ```tsx
+* const targetRef = useRef<HTMLDivElement>(null);
+*
+* <div ref={targetRef} style={{ anchorName: '--target-anchor' }}>
+*   Drag me around
+* </div>
+*
+* <MorphingPopoverWithTarget
+*   targetRef={targetRef}
+*   content={<div>Content</div>}
+* />
+* ```
+*/
+const MorphingPopoverWithTarget = forwardRef(({ content, trigger = "⋯", triggerClassName, popoverClassName, onOpen, onClose, popoverId = "morphing-popover-target" }, ref) => {
+	const handleToggle = (e) => {
+		if (e.target.matches(":popover-open")) onOpen?.();
+		else onClose?.();
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: morphing_popover_module_default.morphingPopoverTargetContainer,
+		children: [/* @__PURE__ */ jsx("button", {
+			ref,
+			popovertarget: popoverId,
+			popoverTargetAction: "toggle",
+			className: cn(morphing_popover_module_default.morphingTrigger, triggerClassName),
+			onClick: handleToggle,
+			children: trigger
+		}), /* @__PURE__ */ jsx("div", {
+			id: popoverId,
+			popover: "auto",
+			className: cn(morphing_popover_module_default.morphingPopoverTarget, popoverClassName),
+			children: content
+		})]
+	});
+});
+MorphingPopoverWithTarget.displayName = "MorphingPopoverWithTarget";
+
+//#endregion
+export { MorphingPopover, MorphingPopoverWithTarget };

package/dist/react-ui/components/MorphingPopover/morphing-popover.module.js

@@ -0,0 +1,5 @@
+//#region src/react-ui/components/MorphingPopover/morphing-popover.module.css
+var morphing_popover_module_default = {};
+
+//#endregion
+export { morphing_popover_module_default as default };

package/dist/react-ui/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react-ui/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,mBAAmB,CAAC"}

package/dist/react-ui/hooks/Animation/UseAutoHeight.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+/**
+ * Options for the useAutoHeight hook.
+ */
+interface IAutoHeightOptions {
+    /** Include parent element box model (padding, border) in measurement. */
+    includeParentBox?: boolean;
+    /** Include self element box model in measurement. */
+    includeSelfBox?: boolean;
+}
+/**
+ * Hook that measures and tracks the height of an element with ResizeObserver.
+ * Returns a ref to attach and the current height value.
+ *
+ * @param deps - Dependency list to trigger re-measurement
+ * @param options - Configuration for box model inclusion
+ * @returns Object with ref and height
+ *
+ * @example
+ * ```tsx
+ * const { ref, height } = useAutoHeight<HTMLDivElement>([content]);
+ * <div style={{ height }}><div ref={ref}>{content}</div></div>
+ * ```
+ */
+export declare function useAutoHeight<T extends HTMLElement = HTMLDivElement>(deps?: React.DependencyList, options?: IAutoHeightOptions): {
+    readonly ref: React.RefObject<T | null>;
+    readonly height: number;
+};
+export type { IAutoHeightOptions };
+//# sourceMappingURL=UseAutoHeight.d.ts.map

package/dist/react-ui/hooks/Animation/UseAutoHeight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseAutoHeight.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/hooks/Animation/UseAutoHeight.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;GAEG;AACH,UAAU,kBAAkB;IAC1B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,GAAG,cAAc,EAClE,IAAI,GAAE,KAAK,CAAC,cAAmB,EAC/B,OAAO,GAAE,kBAGR;;;EAuFF;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/react-ui/hooks/Animation/UseAutoHeight.js

@@ -0,0 +1,80 @@
+'use client';
+
+import * as React$1 from "react";
+
+//#region src/react-ui/hooks/Animation/UseAutoHeight.tsx
+/**
+* Hook that measures and tracks the height of an element with ResizeObserver.
+* Returns a ref to attach and the current height value.
+*
+* @param deps - Dependency list to trigger re-measurement
+* @param options - Configuration for box model inclusion
+* @returns Object with ref and height
+*
+* @example
+* ```tsx
+* const { ref, height } = useAutoHeight<HTMLDivElement>([content]);
+* <div style={{ height }}><div ref={ref}>{content}</div></div>
+* ```
+*/
+function useAutoHeight(deps = [], options = {
+	includeParentBox: true,
+	includeSelfBox: false
+}) {
+	const ref = React$1.useRef(null);
+	const roRef = React$1.useRef(null);
+	const [height, setHeight] = React$1.useState(0);
+	const measure = React$1.useCallback(() => {
+		const el = ref.current;
+		if (!el) return 0;
+		const base = el.getBoundingClientRect().height || 0;
+		let extra = 0;
+		if (options.includeParentBox && el.parentElement) {
+			const cs = getComputedStyle(el.parentElement);
+			const paddingY = (parseFloat(cs.paddingTop || "0") || 0) + (parseFloat(cs.paddingBottom || "0") || 0);
+			const borderY = (parseFloat(cs.borderTopWidth || "0") || 0) + (parseFloat(cs.borderBottomWidth || "0") || 0);
+			if (cs.boxSizing === "border-box") extra += paddingY + borderY;
+		}
+		if (options.includeSelfBox) {
+			const cs = getComputedStyle(el);
+			const paddingY = (parseFloat(cs.paddingTop || "0") || 0) + (parseFloat(cs.paddingBottom || "0") || 0);
+			const borderY = (parseFloat(cs.borderTopWidth || "0") || 0) + (parseFloat(cs.borderBottomWidth || "0") || 0);
+			if (cs.boxSizing === "border-box") extra += paddingY + borderY;
+		}
+		const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+		return Math.ceil((base + extra) * dpr) / dpr;
+	}, [options.includeParentBox, options.includeSelfBox]);
+	React$1.useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		setHeight(measure());
+		if (roRef.current) {
+			roRef.current.disconnect();
+			roRef.current = null;
+		}
+		const ro = new ResizeObserver(() => {
+			const next = measure();
+			requestAnimationFrame(() => setHeight(next));
+		});
+		ro.observe(el);
+		if (options.includeParentBox && el.parentElement) ro.observe(el.parentElement);
+		roRef.current = ro;
+		return () => {
+			ro.disconnect();
+			roRef.current = null;
+		};
+	}, deps);
+	React$1.useLayoutEffect(() => {
+		if (height === 0) {
+			const next = measure();
+			if (next !== 0) setHeight(next);
+		}
+	}, [height, measure]);
+	return {
+		ref,
+		height
+	};
+}
+
+//#endregion
+export { useAutoHeight };

package/dist/react-ui/hooks/DOM/UseIsInView.d.ts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { type UseInViewOptions } from 'motion/react';
+/**
+ * Options for the useIsInView hook.
+ */
+interface IUseIsInViewOptions {
+    /** Enable intersection observer tracking. */
+    inView?: boolean;
+    /** Only trigger once when element enters viewport. */
+    inViewOnce?: boolean;
+    /** Root margin for intersection observer. */
+    inViewMargin?: UseInViewOptions['margin'];
+}
+/**
+ * Hook that tracks whether an element is visible in the viewport
+ * using the Intersection Observer API via motion/react.
+ *
+ * @param ref - Forwarded ref to merge with local ref
+ * @param options - InView configuration options
+ * @returns Object with local ref and isInView boolean
+ *
+ * @example
+ * ```tsx
+ * const { ref, isInView } = useIsInView(forwardedRef, { inView: true, inViewOnce: true });
+ * ```
+ */
+declare function useIsInView<T extends HTMLElement = HTMLElement>(ref: React.Ref<T>, options?: IUseIsInViewOptions): {
+    ref: React.RefObject<T | null>;
+    isInView: boolean;
+};
+export { useIsInView, type IUseIsInViewOptions };
+//# sourceMappingURL=UseIsInView.d.ts.map

package/dist/react-ui/hooks/DOM/UseIsInView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseIsInView.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/hooks/DOM/UseIsInView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,UAAU,mBAAmB;IAC3B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,WAAW,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtD,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,mBAAwB;;;EAWlC;AAED,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,CAAC"}

package/dist/react-ui/hooks/DOM/UseIsInView.js

@@ -0,0 +1,33 @@
+import * as React$1 from "react";
+import { useInView } from "motion/react";
+
+//#region src/react-ui/hooks/DOM/UseIsInView.tsx
+/**
+* Hook that tracks whether an element is visible in the viewport
+* using the Intersection Observer API via motion/react.
+*
+* @param ref - Forwarded ref to merge with local ref
+* @param options - InView configuration options
+* @returns Object with local ref and isInView boolean
+*
+* @example
+* ```tsx
+* const { ref, isInView } = useIsInView(forwardedRef, { inView: true, inViewOnce: true });
+* ```
+*/
+function useIsInView(ref, options = {}) {
+	const { inView, inViewOnce = false, inViewMargin = "0px" } = options;
+	const localRef = React$1.useRef(null);
+	React$1.useImperativeHandle(ref, () => localRef.current);
+	const inViewResult = useInView(localRef, {
+		once: inViewOnce,
+		margin: inViewMargin
+	});
+	return {
+		ref: localRef,
+		isInView: !inView || inViewResult
+	};
+}
+
+//#endregion
+export { useIsInView };

package/dist/react-ui/hooks/Formatting/UseListFormat.d.ts

@@ -0,0 +1,49 @@
+/** Intl.ListFormat conjunction/disjunction/unit type */
+export type ListFormatType = 'conjunction' | 'disjunction' | 'unit';
+/** Intl.ListFormat style: long, short, or narrow */
+export type ListFormatStyle = 'long' | 'short' | 'narrow';
+/** Options for useListFormat hook */
+export interface IUseListFormatOptions {
+    locale?: string;
+    type?: ListFormatType;
+    style?: ListFormatStyle;
+    separator?: string;
+    /** If true, format as if there's one more item (avoids "and" before overflow counter) */
+    hasOverflow?: boolean;
+}
+/** A single part of a formatted list (element or separator) */
+export interface IListPart {
+    type: 'element' | 'literal';
+    value: string;
+    index: number;
+}
+/**
+ * Hook for locale-aware list formatting using Intl.ListFormat.
+ *
+ * Provides parts that can be rendered individually with animations.
+ * Uses the browser's Intl.ListFormat API for proper locale handling.
+ *
+ * @param items - Array of strings to format
+ * @param options - Locale, type, style, separator override, overflow flag
+ * @returns Array of list parts (elements and literals)
+ *
+ * @example
+ * ```tsx
+ * // Automatic locale detection
+ * const parts = useListFormat(['Apple', 'Banana', 'Cherry']);
+ * // en: [{ type: 'element', value: 'Apple' }, { type: 'literal', value: ', ' }, ...]
+ *
+ * // Spanish
+ * const parts = useListFormat(['Apple', 'Banana'], { locale: 'es' });
+ *
+ * // Disjunction ("or")
+ * const parts = useListFormat(['A', 'B', 'C'], { type: 'disjunction' });
+ * // en: "A, B, or C"
+ *
+ * // Manual separator override
+ * const parts = useListFormat(['A', 'B', 'C'], { separator: ' | ' });
+ * // "A | B | C"
+ * ```
+ */
+export declare function useListFormat(items: string[], options?: IUseListFormatOptions): IListPart[];
+//# sourceMappingURL=UseListFormat.d.ts.map

package/dist/react-ui/hooks/Formatting/UseListFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseListFormat.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/hooks/Formatting/UseListFormat.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,CAAC;AAEpE,oDAAoD;AACpD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,qBAA0B,GAClC,SAAS,EAAE,CAsEb"}

package/dist/react-ui/hooks/Formatting/UseListFormat.js

@@ -0,0 +1,105 @@
+import { useMemo } from "react";
+
+//#region src/react-ui/hooks/Formatting/UseListFormat.ts
+const getDefaultLocale = () => {
+	if (typeof navigator !== "undefined" && navigator.language) return navigator.language;
+	return "en";
+};
+/**
+* Hook for locale-aware list formatting using Intl.ListFormat.
+*
+* Provides parts that can be rendered individually with animations.
+* Uses the browser's Intl.ListFormat API for proper locale handling.
+*
+* @param items - Array of strings to format
+* @param options - Locale, type, style, separator override, overflow flag
+* @returns Array of list parts (elements and literals)
+*
+* @example
+* ```tsx
+* // Automatic locale detection
+* const parts = useListFormat(['Apple', 'Banana', 'Cherry']);
+* // en: [{ type: 'element', value: 'Apple' }, { type: 'literal', value: ', ' }, ...]
+*
+* // Spanish
+* const parts = useListFormat(['Apple', 'Banana'], { locale: 'es' });
+*
+* // Disjunction ("or")
+* const parts = useListFormat(['A', 'B', 'C'], { type: 'disjunction' });
+* // en: "A, B, or C"
+*
+* // Manual separator override
+* const parts = useListFormat(['A', 'B', 'C'], { separator: ' | ' });
+* // "A | B | C"
+* ```
+*/
+function useListFormat(items, options = {}) {
+	const { locale, type = "conjunction", style = "long", separator, hasOverflow } = options;
+	return useMemo(() => {
+		if (items.length === 0) return [];
+		if (separator !== void 0) {
+			const parts = [];
+			items.forEach((item, i) => {
+				parts.push({
+					type: "element",
+					value: item,
+					index: i
+				});
+				if (i < items.length - 1) parts.push({
+					type: "literal",
+					value: separator,
+					index: i
+				});
+			});
+			return parts;
+		}
+		const resolvedLocale = locale ?? getDefaultLocale();
+		try {
+			const formatter = new Intl.ListFormat(resolvedLocale, {
+				type,
+				style
+			});
+			const itemsToFormat = hasOverflow && items.length > 1 ? [...items, ""] : items;
+			const formatted = formatter.formatToParts(itemsToFormat);
+			const partsToProcess = hasOverflow ? formatted.slice(0, -2) : formatted;
+			let elementIndex = 0;
+			return partsToProcess.map((part) => {
+				if (part.type === "element") return {
+					type: "element",
+					value: part.value,
+					index: elementIndex++
+				};
+				return {
+					type: "literal",
+					value: part.value,
+					index: Math.max(0, elementIndex - 1)
+				};
+			});
+		} catch {
+			const parts = [];
+			items.forEach((item, i) => {
+				parts.push({
+					type: "element",
+					value: item,
+					index: i
+				});
+				if (i < items.length - 1) parts.push({
+					type: "literal",
+					value: ", ",
+					index: i
+				});
+			});
+			return parts;
+		}
+	}, [
+		items,
+		locale,
+		type,
+		style,
+		separator,
+		hasOverflow
+	]);
+}
+
+//#endregion
+export { useListFormat };

package/dist/react-ui/hooks/State/UseControlledState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseControlledState.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/hooks/State/UseControlledState.tsx"],"names":[],"mappings":"AAEA;;GAEG;AACH,UAAU,qBAAqB,CAAC,CAAC;IAC/B,wBAAwB;IACxB,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,SAAS,GAAG,EAAE,GAAG,EAAE,EAC3D,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9C,GACA,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,CAoBhD;AAED,YAAY,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/react-ui/hooks/State/UseControlledState.js

@@ -0,0 +1,34 @@
+import * as React$1 from "react";
+
+//#region src/react-ui/hooks/State/UseControlledState.tsx
+/**
+* Hook for controlled/uncontrolled state management.
+* Supports both patterns seamlessly — when `value` is provided, it's controlled;
+* otherwise uses internal state initialized from `defaultValue`.
+*
+* @param props - Value, defaultValue, and onChange callback
+* @returns Tuple of [currentValue, setValue]
+*
+* @example
+* ```tsx
+* const [open, setOpen] = useControlledState({
+*   value: props.open,
+*   defaultValue: false,
+*   onChange: props.onOpenChange,
+* });
+* ```
+*/
+function useControlledState(props) {
+	const { value, defaultValue, onChange } = props;
+	const [state, setInternalState] = React$1.useState(value !== void 0 ? value : defaultValue);
+	React$1.useEffect(() => {
+		if (value !== void 0) setInternalState(value);
+	}, [value]);
+	return [state, React$1.useCallback((next, ...args) => {
+		setInternalState(next);
+		onChange?.(next, ...args);
+	}, [onChange])];
+}
+
+//#endregion
+export { useControlledState };

package/dist/react-ui/hooks/State/UseDataState.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+/** Possible values stored in a data-* attribute. */
+type DataStateValue = string | boolean | null;
+/**
+ * Hook that observes a `data-*` attribute on a DOM element via MutationObserver
+ * and returns the current value reactively.
+ *
+ * @param key - The data attribute key (without `data-` prefix)
+ * @param forwardedRef - Optional forwarded ref to merge
+ * @param onChange - Callback when value changes
+ * @returns Tuple of [currentValue, localRef]
+ *
+ * @example
+ * ```tsx
+ * const [state, ref] = useDataState<HTMLDivElement>('state');
+ * // Reacts to changes in `data-state` attribute on the element
+ * ```
+ */
+declare function useDataState<T extends HTMLElement = HTMLElement>(key: string, forwardedRef?: React.Ref<T | null>, onChange?: (value: DataStateValue) => void): [DataStateValue, React.RefObject<T | null>];
+export { useDataState, type DataStateValue };
+//# sourceMappingURL=UseDataState.d.ts.map

package/dist/react-ui/hooks/State/UseDataState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UseDataState.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/hooks/State/UseDataState.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,oDAAoD;AACpD,KAAK,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAe9C;;;;;;;;;;;;;;GAcG;AACH,iBAAS,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACvD,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAClC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACzC,CAAC,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAkC7C;AAED,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,CAAC"}

package/dist/react-ui/hooks/State/UseDataState.js

@@ -0,0 +1,63 @@
+'use client';
+
+import * as React$1 from "react";
+
+//#region src/react-ui/hooks/State/UseDataState.tsx
+/**
+* Parse a DOM dataset attribute string into a typed value.
+*
+* @param value - Raw attribute string
+* @returns Parsed DataStateValue
+*/
+function parseDatasetValue(value) {
+	if (value === null) return null;
+	if (value === "" || value === "true") return true;
+	if (value === "false") return false;
+	return value;
+}
+/**
+* Hook that observes a `data-*` attribute on a DOM element via MutationObserver
+* and returns the current value reactively.
+*
+* @param key - The data attribute key (without `data-` prefix)
+* @param forwardedRef - Optional forwarded ref to merge
+* @param onChange - Callback when value changes
+* @returns Tuple of [currentValue, localRef]
+*
+* @example
+* ```tsx
+* const [state, ref] = useDataState<HTMLDivElement>('state');
+* // Reacts to changes in `data-state` attribute on the element
+* ```
+*/
+function useDataState(key, forwardedRef, onChange) {
+	const localRef = React$1.useRef(null);
+	React$1.useImperativeHandle(forwardedRef, () => localRef.current);
+	const getSnapshot = () => {
+		const el = localRef.current;
+		return el ? parseDatasetValue(el.getAttribute(`data-${key}`)) : null;
+	};
+	const subscribe = (callback) => {
+		const el = localRef.current;
+		if (!el) return () => {};
+		const observer = new MutationObserver((records) => {
+			for (const record of records) if (record.attributeName === `data-${key}`) {
+				callback();
+				break;
+			}
+		});
+		observer.observe(el, {
+			attributes: true,
+			attributeFilter: [`data-${key}`]
+		});
+		return () => observer.disconnect();
+	};
+	const value = React$1.useSyncExternalStore(subscribe, getSnapshot);
+	React$1.useEffect(() => {
+		if (onChange) onChange(value);
+	}, [value, onChange]);
+	return [value, localRef];
+}
+
+//#endregion
+export { useDataState };