@mks2508/mks-ui 0.2.1 → 0.3.1

package/dist/react-ui/ui/TextFlow/index.js

@@ -0,0 +1,187 @@
+"use client";
+
+import { cn } from "../../lib/utils.js";
+import { SlidingText } from "../../primitives/waapi/SlidingText/index.js";
+import { ReorderRoot } from "../../primitives/waapi/Reorder/index.js";
+import { useListFormat } from "../../hooks/Formatting/UseListFormat.js";
+import React, { useCallback, useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/ui/TextFlow/index.tsx
+const DEFAULT_SEPARATOR = {
+	listType: "conjunction",
+	listStyle: "long",
+	transition: "none",
+	duration: 200
+};
+const DEFAULT_OVERFLOW = {
+	prefix: "+",
+	label: " more",
+	showSeparator: true
+};
+const DEFAULT_ANIMATION = {
+	mode: "character",
+	direction: "vertical",
+	stagger: 15,
+	duration: 200,
+	blur: true,
+	widthAnimation: false
+};
+/**
+* TextFlow - Locale-aware animated token list component
+*
+* Built on the Reorder primitive, provides smooth FLIP animations for token lists
+* with proper locale-aware separators using Intl.ListFormat.
+*
+* @example
+* ```tsx
+* // Basic usage
+* <TextFlow tokens={tokens} />
+*
+* // Spanish multiselect with transition
+* <TextFlow
+*   tokens={tokens}
+*   maxVisible={2}
+*   inline
+*   separator={{ locale: 'es', transition: 'fade' }}
+*   overflow={{ prefix: '+', label: ' más' }}
+* />
+* ```
+*/
+const TextFlow = ({ tokens, placeholder = "No tokens", maxVisible, separator: separatorConfig, overflow: overflowConfig, animation: animationConfig, inline = false, className = "", tokenClassName = "", placeholderClassName = "" }) => {
+	const separator = {
+		...DEFAULT_SEPARATOR,
+		...separatorConfig
+	};
+	const overflow = {
+		...DEFAULT_OVERFLOW,
+		...overflowConfig
+	};
+	const animation = {
+		...DEFAULT_ANIMATION,
+		...animationConfig
+	};
+	const exitingIdsRef = React.useRef(/* @__PURE__ */ new Set());
+	const visibleTokens = useMemo(() => maxVisible ? tokens.slice(0, maxVisible) : tokens, [tokens, maxVisible]);
+	const overflowCount = useMemo(() => maxVisible ? Math.max(0, tokens.length - maxVisible) : 0, [tokens.length, maxVisible]);
+	const listParts = useListFormat(visibleTokens.map((t) => t.text), {
+		locale: separator.locale,
+		type: separator.listType,
+		style: separator.listStyle,
+		separator: separator.value,
+		hasOverflow: overflowCount > 0
+	});
+	const shouldShowSeparator = useCallback((tokenIndex) => {
+		return !(tokenIndex >= visibleTokens.length - 1);
+	}, [visibleTokens.length]);
+	const handleItemExit = useCallback((id) => {
+		exitingIdsRef.current.add(id);
+	}, []);
+	const handleItemEnter = useCallback((id) => {}, []);
+	const showPlaceholder = tokens.length === 0 && !!placeholder;
+	const tokenElements = useMemo(() => {
+		let elementIndex = 0;
+		return listParts.map((part, partIndex) => {
+			if (part.type === "element") {
+				const token = visibleTokens[part.index];
+				if (!token) return null;
+				const isExiting = exitingIdsRef.current.has(token.id);
+				elementIndex++;
+				return /* @__PURE__ */ jsx("span", {
+					className: cn("waapi-token-wrapper", tokenClassName),
+					"data-reorder-id": token.id,
+					children: /* @__PURE__ */ jsx(SlidingText, {
+						text: token.text,
+						mode: isExiting ? "none" : animation.mode,
+						direction: animation.direction,
+						staggerDelay: animation.stagger,
+						duration: animation.duration,
+						blur: animation.blur,
+						widthAnimation: !isExiting && animation.widthAnimation,
+						initial: isExiting ? false : "initial",
+						animate: "animate"
+					})
+				}, token.id);
+			}
+			const prevToken = visibleTokens[part.index];
+			if (!prevToken) return null;
+			const tokenIndex = part.index;
+			if (!shouldShowSeparator(tokenIndex)) return null;
+			const separatorKey = `sep-${prevToken.id}`;
+			return /* @__PURE__ */ jsx("span", {
+				className: cn("waapi-token-separator", separator.className ?? ""),
+				children: part.value
+			}, separatorKey);
+		}).filter(Boolean);
+	}, [
+		listParts,
+		visibleTokens,
+		tokenClassName,
+		animation,
+		separator,
+		shouldShowSeparator
+	]);
+	const overflowElement = useMemo(() => {
+		if (overflowCount === 0) return null;
+		return /* @__PURE__ */ jsxs("div", {
+			"data-reorder-id": "overflow-counter",
+			className: cn("waapi-token-overflow", overflow.className ?? ""),
+			children: [
+				overflow.showSeparator && overflow.separator && /* @__PURE__ */ jsx("span", {
+					className: cn("waapi-token-separator", separator.className ?? ""),
+					children: overflow.separator
+				}),
+				overflow.prefix !== "" && /* @__PURE__ */ jsx("span", {
+					className: cn("waapi-token-separator", separator.className ?? ""),
+					children: overflow.prefix
+				}),
+				/* @__PURE__ */ jsx(SlidingText, {
+					text: String(overflowCount),
+					mode: "character",
+					duration: animation.duration,
+					blur: animation.blur,
+					initial: "initial",
+					animate: "animate"
+				}),
+				overflow.label && overflow.label !== "" && /* @__PURE__ */ jsx(SlidingText, {
+					text: overflow.label,
+					mode: animation.mode,
+					direction: animation.direction,
+					staggerDelay: animation.stagger,
+					duration: animation.duration,
+					blur: animation.blur,
+					initial: "initial",
+					animate: "animate"
+				})
+			]
+		}, "overflow-counter");
+	}, [
+		overflowCount,
+		overflow,
+		separator,
+		animation
+	]);
+	return /* @__PURE__ */ jsxs("div", {
+		role: "text",
+		className: cn("waapi-animated-tokens-container", inline && "waapi-animated-tokens-container--inline", className),
+		children: [showPlaceholder && /* @__PURE__ */ jsx(SlidingText, {
+			text: placeholder,
+			mode: "word",
+			direction: "vertical",
+			blur: true,
+			duration: 150,
+			initial: "initial",
+			animate: "animate",
+			className: cn("waapi-token-placeholder", placeholderClassName)
+		}, "placeholder"), /* @__PURE__ */ jsxs(ReorderRoot, {
+			layout: inline ? "inline-horizontal" : "horizontal",
+			onItemExit: handleItemExit,
+			onItemEnter: handleItemEnter,
+			children: [tokenElements, overflowElement]
+		})]
+	});
+};
+TextFlow.displayName = "TextFlow";
+
+//#endregion
+export { TextFlow };

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

@@ -27,5 +27,6 @@ export * from './InputGroup';
 export * from './Label';
 export * from './Select';
 export * from './Separator';
-export * from './Textarea';
+export * from './DataCard';
+export * from './TextFlow';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react-ui/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAG1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react-ui/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAG1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAG3B,cAAc,YAAY,CAAC"}

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

@@ -23,7 +23,6 @@ import { Button } from "./Button/index.js";
 import { cardVariants } from "./Card/Card.styles.js";
 import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./Card/index.js";
 import { Input } from "./Input/index.js";
-import { Textarea } from "./Textarea/index.js";
 import { inputGroupAddonVariants, inputGroupButtonVariants } from "./InputGroup/InputGroup.styles.js";
 import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea } from "./InputGroup/index.js";
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList, ComboboxSeparator, ComboboxTrigger, ComboboxValue, useComboboxAnchor } from "./Combobox/index.js";
@@ -35,3 +34,6 @@ import { Separator } from "./Separator/index.js";
 import { fieldVariants } from "./Field/Field.styles.js";
 import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle } from "./Field/index.js";
 import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from "./Select/index.js";
+import { dataCardStyles, dataCardVariants } from "./DataCard/DataCard.styles.js";
+import { DataCard, DataCardActions, DataCardBracket, DataCardLabel, DataCardToggle, DataCardValue, useDataCard } from "./DataCard/index.js";
+import { TextFlow } from "./TextFlow/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mks2508/mks-ui",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "UI component library - Shadcn/Animate UI based with DevEnv components",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,11 @@
     "./react/ui/*": "./src/react-ui/ui/*/index.tsx",
     "./react/primitives/*": "./src/react-ui/primitives/*/index.tsx",
     "./react/components/*": "./src/react-ui/components/*/index.tsx",
-    "./react/hooks/*": "./src/react-ui/hooks/*.tsx",
+    "./react/hooks/*": "./src/react-ui/hooks/*/*.ts",
+    "./react/hooks/Animation/*": "./src/react-ui/hooks/Animation/*.tsx",
+    "./react/hooks/DOM/*": "./src/react-ui/hooks/DOM/*.tsx",
+    "./react/hooks/State/*": "./src/react-ui/hooks/State/*.tsx",
+    "./react/hooks/Formatting/*": "./src/react-ui/hooks/Formatting/*.ts",
     "./react/icons/*": "./src/react-ui/icons/*.tsx",
     "./react/lib/*": "./src/react-ui/lib/*.ts"
   },

package/src/react-ui/hooks/Formatting/UseListFormat.ts

@@ -0,0 +1,134 @@
+import { useMemo } from 'react';
+
+/** 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;
+}
+
+const getDefaultLocale = (): string => {
+  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"
+ * ```
+ */
+export function useListFormat(
+  items: string[],
+  options: IUseListFormatOptions = {}
+): IListPart[] {
+  const {
+    locale,
+    type = 'conjunction',
+    style = 'long',
+    separator,
+    hasOverflow
+  } = options;
+
+  return useMemo(() => {
+    if (items.length === 0) return [];
+
+    // Manual override mode: use fixed separator
+    if (separator !== undefined) {
+      const parts: IListPart[] = [];
+      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;
+    }
+
+    // Use Intl.ListFormat for locale-aware formatting
+    const resolvedLocale = locale ?? getDefaultLocale();
+
+    try {
+      const formatter = new Intl.ListFormat(resolvedLocale, { type, style });
+
+      // If hasOverflow, add a placeholder to make Intl.ListFormat use commas
+      // instead of "and" before the overflow counter
+      const itemsToFormat = (hasOverflow && items.length > 1)
+        ? [...items, '']
+        : items;
+
+      const formatted = formatter.formatToParts(itemsToFormat);
+
+      // If hasOverflow, remove the last part (placeholder and its separator)
+      const partsToProcess = hasOverflow
+        ? formatted.slice(0, -2)
+        : formatted;
+
+      let elementIndex = 0;
+      return partsToProcess.map((part): IListPart => {
+        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 {
+      // Fallback if Intl.ListFormat fails
+      const parts: IListPart[] = [];
+      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]);
+}

package/src/react-ui/hooks/index.ts

@@ -15,3 +15,6 @@ export type { DataStateValue } from './State/UseDataState';
 
 export { useIsInView } from './DOM/UseIsInView';
 export type { IUseIsInViewOptions } from './DOM/UseIsInView';
+
+export { useListFormat } from './Formatting/UseListFormat';
+export type { IUseListFormatOptions, IListPart, ListFormatType, ListFormatStyle } from './Formatting/UseListFormat';

package/src/react-ui/primitives/index.ts

@@ -11,3 +11,6 @@ export * from './Slot';
 export * from './Highlight';
 export * from './AutoHeight';
 export * from './CountingNumber';
+
+// WAAPI Animation Primitives
+export * from './waapi';

package/src/react-ui/primitives/waapi/Morph/Morph.types.ts

@@ -0,0 +1,106 @@
+import type { ReactNode, RefObject } from 'react';
+
+/**
+ * Available morphing techniques.
+ */
+export type MorphTechnique = 'flip-clip-path' | 'css-grid' | 'view-transitions';
+
+// =============================================================================
+// FLIP + clip-path
+// =============================================================================
+
+/** Options for the FLIP + clip-path morphing technique */
+export interface IFLIPClipPathOptions {
+  duration?: number;
+  easing?: string;
+  clipPathStart?: string;
+  clipPathEnd?: string;
+}
+
+/** API returned by useFLIPClipPath */
+export interface IFLIPClipPathAPI {
+  isMorphing: boolean;
+  morph: (fromElement: HTMLElement, toElement: HTMLElement) => Promise<void>;
+  cancel: () => void;
+}
+
+// =============================================================================
+// CSS Grid
+// =============================================================================
+
+/** Options for the CSS Grid expand/collapse technique */
+export interface ICSSGridMorphOptions {
+  duration?: number;
+  easing?: string;
+}
+
+/** API returned by useCSSGridMorph */
+export interface ICSSGridMorphAPI {
+  isExpanded: boolean;
+  expand: () => void;
+  collapse: () => void;
+  toggle: () => void;
+  containerRef: RefObject<HTMLElement | null>;
+}
+
+// =============================================================================
+// View Transitions
+// =============================================================================
+
+/** Options for the View Transitions API wrapper */
+export interface IViewTransitionsOptions {
+  name?: string;
+  types?: string[];
+}
+
+/** API returned by useViewTransitions */
+export interface IViewTransitionsAPI {
+  isSupported: boolean;
+  startTransition: (callback: () => void | Promise<void>) => Promise<void>;
+  setTypes: (types: string[]) => void;
+}
+
+// =============================================================================
+// Unified Morph
+// =============================================================================
+
+/** Configuration for useMorph hook */
+export interface IUseMorphConfig {
+  technique?: MorphTechnique;
+  duration?: number;
+  easing?: string;
+  onMorphStart?: () => void;
+  onMorphEnd?: () => void;
+}
+
+/** Return type for useMorph hook */
+export interface IUseMorphReturn {
+  isMorphing: boolean;
+  technique: MorphTechnique;
+  isViewTransitionsSupported: boolean;
+  morph: (fromElement: HTMLElement, toElement: HTMLElement) => Promise<void>;
+  cancel: () => void;
+  flipClipPath: IFLIPClipPathAPI;
+  cssGrid: ICSSGridMorphAPI;
+  viewTransitions: IViewTransitionsAPI;
+}
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/** Props for Morph container component */
+export interface IMorphProps {
+  children: ReactNode;
+  technique?: MorphTechnique;
+  duration?: number;
+  easing?: string;
+  className?: string;
+  onMorphStart?: () => void;
+  onMorphEnd?: () => void;
+}
+
+/** Context value for Morph components */
+export interface IMorphContextValue {
+  morph: IUseMorphReturn;
+}

package/src/react-ui/primitives/waapi/Morph/MorphContext.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import React, { createContext, useContext } from 'react';
+import type { IMorphContextValue } from './Morph.types';
+
+const MorphContext = createContext<IMorphContextValue | null>(null);
+
+/**
+ * Hook to access morph context
+ *
+ * @throws Error if used outside of Morph provider
+ */
+export function useMorphContext(): IMorphContextValue {
+  const context = useContext(MorphContext);
+  if (!context) {
+    throw new Error('useMorphContext must be used within a Morph component');
+  }
+  return context;
+}
+
+export { MorphContext };

package/src/react-ui/primitives/waapi/Morph/index.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import React, { useMemo, type ReactNode } from 'react';
+import { MorphContext } from './MorphContext';
+import { useMorph } from './useMorph';
+import type { IMorphProps, IMorphContextValue } from './Morph.types';
+import { cn } from '@/react-ui/lib/utils';
+
+/**
+ * Morph - Container component for morphable elements.
+ *
+ * Provides morphing capabilities to child components through context.
+ * Supports FLIP + clip-path, CSS Grid, and View Transitions techniques.
+ *
+ * @example
+ * ```tsx
+ * <Morph technique="flip-clip-path" duration={300}>
+ *   <button onClick={() => morph(fromRef.current, toRef.current)}>
+ *     Morph
+ *   </button>
+ * </Morph>
+ * ```
+ */
+export function Morph({
+  children,
+  technique = 'flip-clip-path',
+  duration,
+  easing,
+  className = '',
+  onMorphStart,
+  onMorphEnd
+}: IMorphProps): ReactNode {
+  const morph = useMorph({
+    technique,
+    duration,
+    easing,
+    onMorphStart,
+    onMorphEnd
+  });
+
+  const contextValue = useMemo<IMorphContextValue>(() => ({
+    morph
+  }), [morph]);
+
+  return (
+    <MorphContext.Provider value={contextValue}>
+      <div className={cn('morph-container', className)}>
+        {children}
+      </div>
+    </MorphContext.Provider>
+  );
+}
+
+Morph.displayName = 'Morph';
+
+export type { IMorphProps, IMorphContextValue };

package/src/react-ui/primitives/waapi/Morph/techniques/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Morph techniques.
+ *
+ * Individual morphing implementations that can be used
+ * standalone or composed through useMorph.
+ *
+ * @module primitives/waapi/Morph/techniques
+ */
+
+export { useFLIPClipPath } from './useFLIPClipPath';
+export { useCSSGridMorph } from './useCSSGridMorph';
+export { useViewTransitions } from './useViewTransitions';

package/src/react-ui/primitives/waapi/Morph/techniques/useCSSGridMorph.ts

@@ -0,0 +1,88 @@
+import { useRef, useCallback, useState } from 'react';
+import { TIMING, EASINGS } from '../../core/animationConstants';
+import type { ICSSGridMorphOptions, ICSSGridMorphAPI } from '../Morph.types';
+
+const DEFAULT_DURATION = TIMING.FLIP_DURATION;
+const DEFAULT_EASING = EASINGS.MATERIAL_STANDARD;
+
+/**
+ * Hook for CSS Grid-based expand/collapse animations.
+ *
+ * Uses the `grid-template-rows: 0fr/1fr` technique for smooth height
+ * animations without needing to know the content height in advance.
+ *
+ * CSS required on container:
+ * ```css
+ * .morph-container {
+ *   display: grid;
+ *   grid-template-rows: 0fr;
+ *   transition: grid-template-rows 300ms ease;
+ * }
+ * .morph-container.expanded {
+ *   grid-template-rows: 1fr;
+ * }
+ * .morph-content {
+ *   overflow: hidden;
+ * }
+ * ```
+ *
+ * @param options - Duration and easing overrides
+ * @returns Grid morph API with expand, collapse, toggle, and container ref
+ *
+ * @example
+ * ```tsx
+ * const { isExpanded, toggle, containerRef } = useCSSGridMorph();
+ *
+ * return (
+ *   <div ref={containerRef} className={isExpanded ? 'expanded' : ''}>
+ *     <div className="morph-content">Collapsible content</div>
+ *   </div>
+ * );
+ * ```
+ */
+export function useCSSGridMorph(options?: ICSSGridMorphOptions): ICSSGridMorphAPI {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const containerRef = useRef<HTMLElement | null>(null);
+  const optionsRef = useRef(options);
+
+  const duration = optionsRef.current?.duration ?? DEFAULT_DURATION;
+  const easing = optionsRef.current?.easing ?? DEFAULT_EASING;
+
+  const applyTransition = useCallback(() => {
+    if (containerRef.current) {
+      containerRef.current.style.transition = `grid-template-rows ${duration}ms ${easing}`;
+    }
+  }, [duration, easing]);
+
+  const expand = useCallback(() => {
+    applyTransition();
+    if (containerRef.current) {
+      containerRef.current.style.gridTemplateRows = '1fr';
+    }
+    setIsExpanded(true);
+  }, [applyTransition]);
+
+  const collapse = useCallback(() => {
+    applyTransition();
+    if (containerRef.current) {
+      containerRef.current.style.gridTemplateRows = '0fr';
+    }
+    setIsExpanded(false);
+  }, [applyTransition]);
+
+  const toggle = useCallback(() => {
+    if (isExpanded) {
+      collapse();
+    } else {
+      expand();
+    }
+  }, [isExpanded, expand, collapse]);
+
+  return {
+    isExpanded,
+    expand,
+    collapse,
+    toggle,
+    containerRef
+  };
+}