@cube-dev/ui-kit 0.121.0 → 0.121.1

package/docs/components/form/FormInstance.md

@@ -0,0 +1,307 @@
+# FormInstance
+
+The `CubeFormInstance` is the core form management class that provides programmatic control over form state, validation, and data handling. It serves as the central API for interacting with form fields, managing validation states, and handling form submission workflows.
+
+## Creation
+
+Form instances are typically created using the `useForm` hook:
+
+```tsx
+import { Form } from '@cube-dev/ui-kit';
+
+function MyComponent() {
+  const [form] = Form.useForm();
+  
+  return <Form form={form}>{/* form fields */}</Form>;
+}
+```
+
+Alternatively, you can create an instance directly:
+
+```tsx
+import { CubeFormInstance } from '@cube-dev/ui-kit';
+
+const formInstance = new CubeFormInstance();
+```
+
+## Field Management
+
+### Field Values
+
+Access and modify individual field values:
+
+```tsx
+// Get a field value
+const email = form.getFieldValue('email');
+
+// Set a field value
+form.setFieldValue('email', 'user@example.com');
+
+// Get all field values (flat structure)
+const allValues = form.getFieldsValue();
+
+// Get form data (respects dot notation for nested objects)
+const formData = form.getFormData();
+```
+
+### Batch Operations
+
+Update multiple fields at once:
+
+```tsx
+// Set multiple field values
+form.setFieldsValue({
+  email: 'user@example.com',
+  name: 'John Doe',
+  'profile.age': 25
+});
+
+// Reset specific fields to default values
+form.resetFields(['email', 'name']);
+
+// Reset all fields
+form.resetFields();
+```
+
+## Validation
+
+### Individual Field Validation
+
+```tsx
+// Validate a single field
+try {
+  await form.validateField('email');
+  console.log('Field is valid');
+} catch (error) {
+  console.log('Validation failed:', error);
+}
+
+// Check validation state
+const isValid = form.isFieldValid('email');
+const isInvalid = form.isFieldInvalid('email');
+const errors = form.getFieldError('email');
+```
+
+### Form-wide Validation
+
+```tsx
+// Validate all fields
+try {
+  const validData = await form.validateFields();
+  console.log('All fields valid:', validData);
+} catch (errors) {
+  console.log('Validation errors:', errors);
+}
+
+// Check overall form state
+const allValid = form.isValid;
+const hasErrors = form.isInvalid;
+```
+
+### Manual Error Handling
+
+```tsx
+// Set custom error for a field
+form.setFieldError('email', 'This email is already taken');
+
+// Clear validation errors
+form.resetFieldsValidation(['email']);
+```
+
+## Form State
+
+### Touch State
+
+Track user interaction with fields:
+
+```tsx
+// Check if field was touched
+const wasTouched = form.isFieldTouched('email');
+
+// Check if any field was touched
+const formTouched = form.isTouched;
+```
+
+### Dirty State
+
+Detect changes from initial values:
+
+```tsx
+// Check if form has unsaved changes
+const hasChanges = form.isDirty;
+```
+
+### Initial Values
+
+Manage default form state:
+
+```tsx
+// Set initial values during setup
+form.setInitialFieldsValue({
+  email: 'default@example.com',
+  name: 'Default Name'
+});
+
+// Update initial values (useful for edit forms)
+form.updateInitialFieldsValue({
+  'profile.age': 30
+});
+```
+
+## Submission
+
+### Basic Submission
+
+```tsx
+// Submit the form (calls the onSubmit handler)
+await form.submit();
+
+// Check submission state
+const isSubmitting = form.isSubmitting;
+
+// Control submission state manually
+form.setSubmitting(true);
+```
+
+### Submission Errors
+
+```tsx
+// Access submission errors
+const submitError = form.submitError;
+```
+
+## Advanced Usage
+
+### Dot Notation Support
+
+The form instance supports dot notation for nested object structures:
+
+```tsx
+// Set nested value
+form.setFieldValue('user.profile.name', 'John');
+
+// This creates the structure:
+// {
+//   user: {
+//     profile: {
+//       name: 'John'
+//     }
+//   }
+// }
+```
+
+### Field Instance Access
+
+Access the internal field data structure:
+
+```tsx
+const fieldInstance = form.getFieldInstance('email');
+// Returns: {
+//   name: 'email',
+//   value: '...',
+//   errors: [...],
+//   touched: boolean,
+//   validating: boolean,
+//   status: 'valid' | 'invalid' | undefined
+// }
+```
+
+## Event Handlers
+
+Form instances support event callbacks:
+
+```tsx
+const [form] = Form.useForm(undefined, undefined, {
+  onSubmit: async (data) => {
+    // Handle form submission
+    await apiCall(data);
+  },
+  onValuesChange: (data) => {
+    // Handle value changes
+    console.log('Form data changed:', data);
+  }
+});
+```
+
+## API Reference
+
+### Properties
+
+- **`isSubmitting`** `boolean` — Whether the form is currently being submitted
+- **`submitError`** `unknown` — Error from the last submission attempt
+- **`isTouched`** `boolean` — Whether any field has been interacted with
+- **`isDirty`** `boolean` — Whether any field value differs from initial values
+- **`isValid`** `boolean` — Whether all fields are validated and valid
+- **`isInvalid`** `boolean` — Whether any field is validated and invalid
+
+### Methods
+
+#### Field Value Management
+
+- **`getFieldValue`** `<Name>(name: Name) => T[Name]` — Get the value of a specific field
+- **`setFieldValue`** `<Name>(name: Name, value: T[Name], isTouched?, skipRender?) => void` — Set the value of a specific field
+- **`getFieldsValue`** `() => PartialString<T>` — Get all field values as a flat object
+- **`setFieldsValue`** `(newData: PartialString<T>, touched?, skipRender?) => void` — Set multiple field values
+- **`getFormData`** `() => T` — Get form data with dot notation converted to nested objects
+
+#### Initial Values
+
+- **`setInitialFieldsValue`** `(values: PartialString<T>) => void` — Set initial values for fields
+- **`updateInitialFieldsValue`** `(values: FieldTypes) => void` — Update initial values (merge with existing)
+- **`resetFields`** `(names?: string[], skipRender?) => void` — Reset fields to initial values
+
+#### Validation
+
+- **`validateField`** `<Name>(name: Name) => Promise<any>` — Validate a single field
+- **`validateFields`** `<Names>(names?: Names) => Promise<any>` — Validate multiple or all fields
+- **`isFieldValid`** `<Name>(name: Name) => boolean` — Check if a field is valid
+- **`isFieldInvalid`** `<Name>(name: Name) => boolean` — Check if a field is invalid
+- **`getFieldError`** `<Name>(name: Name) => ReactNode[]` — Get validation errors for a field
+- **`setFieldError`** `(name: string, error: ReactNode, skipRender?) => void` — Set a custom error for a field
+- **`resetFieldsValidation`** `(names?: string[], skipRender?) => void` — Clear validation errors
+
+#### State Checking
+
+- **`isFieldTouched`** `<Name>(name: Name) => boolean` — Check if a field has been interacted with
+- **`getFieldInstance`** `<Name>(name: Name) => TFormData[Name]` — Get the internal field instance
+
+#### Submission
+
+- **`submit`** `() => Promise<void>` — Submit the form
+- **`setSubmitting`** `(isSubmitting: boolean) => void` — Set the submission state
+
+## Type Definitions
+
+```tsx
+type FieldTypes = {
+  [key: string]: any;
+};
+
+type CubeFormData<T extends FieldTypes> = {
+  [K in keyof T & string]?: CubeFieldData<K, T[K]>;
+};
+
+type CubeFieldData<Name extends string, Value> = {
+  readonly name: Name;
+  errors: ReactNode[];
+  value?: Value;
+  touched?: boolean;
+  rules?: any[];
+  validating?: boolean;
+  validationId?: number;
+  status?: 'valid' | 'invalid';
+};
+```
+
+## Best Practices
+
+1. **Always use the `useForm` hook** in React components rather than creating instances manually
+2. **Handle async validation errors** appropriately using try-catch blocks
+3. **Set initial values early** in the component lifecycle to avoid field state inconsistencies
+4. **Use dot notation** for nested object structures instead of managing complex object hierarchies manually
+5. **Check validation state** before allowing form submission in complex workflows
+6. **Reset fields appropriately** when switching between different data sets (e.g., edit vs. create modes)
+
+## Integration with Forms
+
+Form instances are designed to work seamlessly with the `Form` component and field components. The instance automatically manages field registration, validation triggers, and re-rendering optimization.

package/docs/components/helpers/DisplayTransition.md

@@ -0,0 +1,268 @@
+# DisplayTransition
+
+A headless helper component that manages enter and exit animation states for showing and hiding content. It provides phase information through a render prop, allowing you to apply appropriate CSS transitions or animations based on the current transition state.
+
+## When to Use
+
+- When you need to animate content appearing and disappearing with full control over timing
+- When you want to coordinate CSS transitions with component mount/unmount
+- When you need to delay unmounting until exit animations complete
+- When building custom animated overlays, modals, or dropdowns
+
+## Component
+
+---
+
+### Properties
+
+- **`isShown`** `boolean` — Desired visibility state (driver for the transition)
+- **`duration`** `number` — Transition duration in milliseconds. If `0`, transitions are instant. If `undefined`, uses native CSS transition events for timing.
+- **`animateOnMount`** `boolean` (default: `true`) — Whether to animate on first mount. Set to `false` to skip the initial enter animation
+- **`respectReducedMotion`** `boolean` (default: `true`) — Respect the user's `prefers-reduced-motion` setting by collapsing duration to 0
+- **`preserveContent`** `boolean` (default: `true`) — Preserve children content during exit transition. When true, uses stored children from when content was visible
+- **`exposeUnmounted`** `boolean` (default: `false`) — Keep calling children during the `unmounted` phase instead of returning `null`
+- **`onRest`** `(transition: 'enter' | 'exit') => void` — Fires after enter settles or after exit completes (unmount)
+- **`onPhaseChange`** `(phase: ReportedPhase) => void` — Fires when the transition phase changes
+- **`onToggle`** `(isShown: boolean) => void` — Fires when the derived `isShown` value changes
+- **`children`** `(props: { phase, isShown, ref }) => ReactNode` — Render prop receiving the current phase, visibility state, and a ref callback to bind to the transitioned element
+
+### Base Properties
+
+This is a headless component and does not support base properties.
+
+## Transition Phases
+
+The component manages four distinct phases:
+
+- **`unmounted`** — Content is not mounted (isShown: `false`)
+- **`enter`** — Content is mounting, enter animation should start (isShown: `false`)
+- **`entered`** — Enter animation complete, content is visible (isShown: `true`)
+- **`exit`** — Content is exiting, exit animation should start (isShown: `false`)
+
+The render prop receives an object `{ phase, isShown }` where `isShown` is only `true` during the `entered` phase.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import { Block } from '@cube-dev/ui-kit';
+
+<DisplayTransition isShown={isVisible} duration={150}>
+  {({ phase, isShown }) => (
+    <Block 
+      data-phase={phase}
+      mods={{ entered: phase === 'entered' }}
+      styles={{
+        transition: 'fade',
+        opacity: {
+          '': '0',
+          'entered': '1',
+        },
+        '$transition': '150ms'
+      }}
+    >
+      Content
+    </Block>
+  )}
+</DisplayTransition>
+```
+
+### With Tasty Styles
+
+```jsx
+const AnimatedCard = tasty(Card, {
+  styles: {
+    '$transition': '150ms',
+    transition: 'fade, translate',
+    opacity: {
+      '': '0',
+      'entered': '1',
+    },
+    transform: {
+      '': 'translateY(-8px)',
+      'entered': 'translateY(0)',
+      'exit': 'translateY(8px)',
+    },
+  },
+});
+
+<DisplayTransition isShown={isVisible}>
+  {({ phase }) => (
+    <AnimatedCard mods={{ entered: phase === 'entered', exit: phase === 'exit' }}>
+      Content
+    </AnimatedCard>
+  )}
+</DisplayTransition>
+```
+
+### Instant Transitions
+
+Set `duration={0}` for instant show/hide without animation.
+
+### Skip Mount Animation
+
+Set `animateOnMount={false}` to skip the initial enter animation when the component mounts with `isShown={true}`. Useful for server-side rendering or preventing layout shift.
+
+### Slow Transition
+
+Longer durations can be used for more dramatic entrance and exit effects.
+
+### With Callbacks
+
+```jsx
+<DisplayTransition 
+  isShown={isVisible}
+  onRest={(transition) => {
+    console.log(`${transition} transition completed`);
+  }}
+>
+  {({ phase, isShown }) => (
+    <Block 
+      data-phase={phase}
+      mods={{ entered: phase === 'entered' }}
+    >
+      Content
+    </Block>
+  )}
+</DisplayTransition>
+```
+
+The `onRest` callback fires after the enter animation settles (when reaching `entered` phase) or after the exit animation completes (when reaching `unmounted` phase).
+
+## Advanced Features
+
+### Exposing Unmounted Phase
+
+By default, the component returns `null` when in the `unmounted` phase. Set `exposeUnmounted={true}` to continue calling the render prop even when unmounted:
+
+```jsx
+<DisplayTransition isShown={isVisible} exposeUnmounted>
+  {({ phase, isShown }) => {
+    if (phase === 'unmounted') {
+      return <Block>Custom unmounted state</Block>;
+    }
+    return <Block data-phase={phase}>Content</Block>;
+  }}
+</DisplayTransition>
+```
+
+### Reduced Motion Support
+
+The component automatically respects the `prefers-reduced-motion` media query when `respectReducedMotion={true}` (default). When the user has requested reduced motion, the internal duration is collapsed to 0, resulting in instant transitions.
+
+### Preserve Content During Exit
+
+By default (`preserveContent={true}`), the component stores the children render function when content is visible and uses the stored version during exit transitions. This ensures the exiting content remains consistent even if the parent stops providing content immediately after hiding.
+
+```jsx
+<DisplayTransition isShown={isVisible} preserveContent>
+  {({ phase }) => (
+    <Block mods={{ entered: phase === 'entered' }}>
+      {/* This content will be preserved during exit animation */}
+      {isVisible ? dynamicContent : null}
+    </Block>
+  )}
+</DisplayTransition>
+```
+
+Set `preserveContent={false}` if you need the exit animation to reflect real-time children changes:
+
+```jsx
+<DisplayTransition isShown={isVisible} preserveContent={false}>
+  {({ phase }) => (
+    <Block mods={{ entered: phase === 'entered' }}>
+      {/* Content updates during exit will be reflected */}
+      {currentContent}
+    </Block>
+  )}
+</DisplayTransition>
+```
+
+## Animation Flow
+
+### Enter Flow
+1. `isShown` changes from `false` to `true`
+2. Phase changes to `enter` (isShown = false)
+3. After next paint, phase changes to `entered` (isShown = true)
+4. After `duration` milliseconds, `onRest('enter')` fires
+
+### Exit Flow
+1. `isShown` changes from `true` to `false`
+2. Phase changes to `exit` (isShown = false)
+3. After `duration` milliseconds, phase changes to `unmounted` and `onRest('exit')` fires
+4. Component returns `null` (unless `exposeUnmounted={true}`)
+
+## Best Practices
+
+1. **Match CSS duration with duration prop**: Ensure your CSS transition/animation duration matches the `duration` prop for proper timing
+   ```jsx
+   <DisplayTransition duration={300}>
+     {({ phase }) => (
+       <Block 
+         data-phase={phase}
+         mods={{ entered: phase === 'entered' }}
+         styles={{
+           transition: 'fade',
+           opacity: { '': '0', 'entered': '1' },
+           '$transition': '300ms',
+         }}
+       >
+         ...
+       </Block>
+     )}
+   </DisplayTransition>
+   ```
+
+2. **Use stable callbacks**: The component uses `useEvent` internally, but you should still avoid recreating callbacks on every render when possible
+
+3. **Animate on mount thoughtfully**: Set `animateOnMount={false}` for content that should appear immediately on SSR or first paint
+   ```jsx
+   <DisplayTransition isShown={true} animateOnMount={false}>
+     {({ phase }) => (
+       <Block 
+         data-phase={phase}
+         mods={{ entered: phase === 'entered' }}
+       >
+         Initially visible content
+       </Block>
+     )}
+   </DisplayTransition>
+   ```
+
+4. **Respect reduced motion**: Keep the default `respectReducedMotion={true}` to provide a better experience for users with motion sensitivity
+
+5. **Don't use for list items**: This component is designed for single element show/hide. For animating lists, consider using React Aria's built-in list animation features or a dedicated list animation library
+
+## Performance Considerations
+
+- The component uses `requestAnimationFrame` and `setTimeout` for efficient animation scheduling
+- Rapid toggles are handled gracefully with automatic cancellation of pending timers
+- React Strict Mode compatible with versioned flow control
+- Zero additional DOM nodes (headless component)
+
+## Accessibility
+
+### Reduced Motion
+
+The component automatically respects the user's motion preferences when `respectReducedMotion={true}`. Users who have enabled "Reduce motion" in their OS settings will see instant transitions instead of animations.
+
+### Screen Reader Considerations
+
+Since this is a purely visual transition component, ensure that:
+- Content changes are announced appropriately (use `aria-live` if needed)
+- Focus management is handled by parent components
+- Critical state changes aren't communicated only through animations
+
+## Suggested Improvements
+
+- `onPhaseChange` - Callback that fires on every phase change with (newPhase, oldPhase)
+- `onEnter` / `onExit` - Separate callbacks instead of combined `onRest`
+- `skipAnimation` - Runtime prop to skip animations without changing duration
+
+## Related Components
+
+- [Modal](/components/Modal) - Uses DisplayTransition internally for overlay animations
+- [Popover](/components/Popover) - Can use DisplayTransition for custom entrance animations
+- [OverlayWrapper](/components/OverlayWrapper) - Another component that may benefit from transition management
+