xertica-ui 2.2.1 → 2.4.0

package/docs/components/file-upload.md

@@ -1,189 +1,189 @@
-# File Upload
-
-## Overview
-
-A drag-and-drop file input component that accepts one or multiple files. Renders a dropzone area with visual feedback on drag, displays selected file names, and validates against allowed MIME types and file size limits.
-
-The package also exports a **headless `useFileUpload` hook** for building fully custom drop-zone UIs while reusing all the validation and drag-state logic.
-
----
-
-## Exports
-
-| Export                | Description                                     |
-| --------------------- | ----------------------------------------------- |
-| `FileUpload`          | Ready-to-use drag-and-drop file input component |
-| `useFileUpload`       | Headless hook — all logic, no UI                |
-| `UseFileUploadProps`  | TypeScript props type for the hook              |
-| `UseFileUploadReturn` | TypeScript return type for the hook             |
-
----
-
-## When to Use
-
-- Document upload forms
-- Avatar/profile image replacement
-- Data import (CSV, JSON uploads)
-- Any file selection where UX is important
-
----
-
-## `FileUpload` Component Props
-
-| Prop            | Type                      | Default | Required | Description                                  |
-| --------------- | ------------------------- | ------- | -------- | -------------------------------------------- |
-| `accept`        | `string`                  | `'*'`   | No       | Accepted MIME types (e.g., `'image/*,.pdf'`) |
-| `multiple`      | `boolean`                 | `false` | No       | Allow multiple file selection                |
-| `maxSize`       | `number`                  | —       | No       | Maximum file size in bytes                   |
-| `onFilesChange` | `(files: File[]) => void` | —       | No       | Called when selection changes                |
-| `disabled`      | `boolean`                 | `false` | No       | Disables the dropzone                        |
-| `className`     | `string`                  | —       | No       | Additional CSS classes                       |
-
----
-
-## Examples
-
-### Image Upload
-
-```tsx
-import { FileUpload } from 'xertica-ui/ui';
-
-<FileUpload
-  accept="image/*"
-  maxSize={5 * 1024 * 1024} // 5MB
-  onFilesChange={files => handleAvatarUpload(files[0])}
-/>;
-```
-
-### Multiple Document Upload
-
-```tsx
-<FileUpload
-  accept=".pdf,.doc,.docx"
-  multiple
-  onFilesChange={files => setSelectedDocuments(files)}
-/>
-```
-
-### Inside react-hook-form
-
-```tsx
-<FormField
-  control={form.control}
-  name="attachment"
-  render={({ field }) => (
-    <FormItem>
-      <FormLabel>Attachment</FormLabel>
-      <FormControl>
-        <FileUpload accept=".pdf" onFilesChange={files => field.onChange(files[0])} />
-      </FormControl>
-      <FormMessage />
-    </FormItem>
-  )}
-/>
-```
-
----
-
-## `useFileUpload` Hook
-
-A headless hook that encapsulates all file upload logic — drag state, file validation, error messaging, and the hidden input ref — without rendering any UI. Use it when the `<FileUpload>` component's visual design doesn't fit your needs.
-
-### Props
-
-| Prop            | Type                                                    | Default         | Description                                            |
-| --------------- | ------------------------------------------------------- | --------------- | ------------------------------------------------------ |
-| `maxFiles`      | `number`                                                | `1`             | Maximum number of files allowed                        |
-| `maxSize`       | `number`                                                | `5242880` (5MB) | Maximum file size in bytes                             |
-| `onFilesChange` | `(files: File[]) => void`                               | —               | Called with the accepted file list whenever it changes |
-| `onError`       | `(rejected: File[], reason: 'size' \| 'count') => void` | —               | Called when files are rejected                         |
-| `disabled`      | `boolean`                                               | `false`         | Whether the upload area is disabled                    |
-
-### Return Value
-
-| Property         | Type                                         | Description                                          |
-| ---------------- | -------------------------------------------- | ---------------------------------------------------- |
-| `files`          | `File[]`                                     | Currently accepted files                             |
-| `dragActive`     | `boolean`                                    | Whether a drag is active over the drop zone          |
-| `errorMessage`   | `string \| null`                             | Inline error message, or `null`                      |
-| `inputRef`       | `RefObject<HTMLInputElement>`                | Attach to the hidden `<input type="file">`           |
-| `handleFiles`    | `(files: FileList \| null) => void`          | Process a `FileList` from any source                 |
-| `handleDrag`     | `(e: DragEvent) => void`                     | Attach to `onDragEnter`, `onDragOver`, `onDragLeave` |
-| `handleDrop`     | `(e: DragEvent) => void`                     | Attach to `onDrop`                                   |
-| `handleChange`   | `(e: ChangeEvent<HTMLInputElement>) => void` | Attach to the hidden input's `onChange`              |
-| `removeFile`     | `(index: number) => void`                    | Remove a file by its index                           |
-| `openFileDialog` | `() => void`                                 | Programmatically open the native file picker         |
-
-### Custom Drop Zone Example
-
-```tsx
-import { useFileUpload } from 'xertica-ui/ui';
-import { UploadCloud } from 'lucide-react';
-
-function CustomDropZone() {
-  const {
-    files,
-    dragActive,
-    errorMessage,
-    inputRef,
-    handleDrag,
-    handleDrop,
-    handleChange,
-    removeFile,
-    openFileDialog,
-  } = useFileUpload({
-    maxFiles: 3,
-    maxSize: 10 * 1024 * 1024, // 10MB
-    onFilesChange: files => console.log('Files:', files),
-  });
-
-  return (
-    <div className="space-y-3">
-      <div
-        onDragEnter={handleDrag}
-        onDragOver={handleDrag}
-        onDragLeave={handleDrag}
-        onDrop={handleDrop}
-        onClick={openFileDialog}
-        className={cn(
-          'flex flex-col items-center justify-center rounded-xl border-2 border-dashed p-10 cursor-pointer transition-colors',
-          dragActive ? 'border-primary bg-primary/5' : 'border-border hover:border-primary/50'
-        )}
-      >
-        <UploadCloud className="size-8 text-muted-foreground mb-2" />
-        <p className="text-sm text-muted-foreground">
-          Drop files here or <span className="text-primary font-medium">browse</span>
-        </p>
-        <input ref={inputRef} type="file" multiple className="hidden" onChange={handleChange} />
-      </div>
-
-      {errorMessage && <p className="text-sm text-destructive">{errorMessage}</p>}
-
-      {files.length > 0 && (
-        <ul className="space-y-1">
-          {files.map((file, i) => (
-            <li key={i} className="flex items-center justify-between text-sm">
-              <span>{file.name}</span>
-              <Button size="sm" variant="ghost" onClick={() => removeFile(i)}>
-                Remove
-              </Button>
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}
-```
-
----
-
-## AI Rules
-
-- Do not use native `<input type="file">` — always use `<FileUpload>` or `useFileUpload` from `xertica-ui`.
-- `maxSize` is in bytes — calculate using `MB * 1024 * 1024`.
-- In forms, use `onFilesChange` to call `field.onChange` — not `{...field}`.
-- For avatar uploads, use `accept="image/*"` and `multiple={false}`.
-- When using `useFileUpload`, attach `handleDrag` to **all three** drag events: `onDragEnter`, `onDragOver`, and `onDragLeave`.
-- Always attach `inputRef` to a hidden `<input type="file">` element — `openFileDialog()` requires it.
-- `removeFile(index)` removes by array index, not by file name.
+# File Upload
+
+## Overview
+
+A drag-and-drop file input component that accepts one or multiple files. Renders a dropzone area with visual feedback on drag, displays selected file names, and validates against allowed MIME types and file size limits.
+
+The package also exports a **headless `useFileUpload` hook** for building fully custom drop-zone UIs while reusing all the validation and drag-state logic.
+
+---
+
+## Exports
+
+| Export                | Description                                     |
+| --------------------- | ----------------------------------------------- |
+| `FileUpload`          | Ready-to-use drag-and-drop file input component |
+| `useFileUpload`       | Headless hook — all logic, no UI                |
+| `UseFileUploadProps`  | TypeScript props type for the hook              |
+| `UseFileUploadReturn` | TypeScript return type for the hook             |
+
+---
+
+## When to Use
+
+- Document upload forms
+- Avatar/profile image replacement
+- Data import (CSV, JSON uploads)
+- Any file selection where UX is important
+
+---
+
+## `FileUpload` Component Props
+
+| Prop            | Type                      | Default | Required | Description                                  |
+| --------------- | ------------------------- | ------- | -------- | -------------------------------------------- |
+| `accept`        | `string`                  | `'*'`   | No       | Accepted MIME types (e.g., `'image/*,.pdf'`) |
+| `multiple`      | `boolean`                 | `false` | No       | Allow multiple file selection                |
+| `maxSize`       | `number`                  | —       | No       | Maximum file size in bytes                   |
+| `onFilesChange` | `(files: File[]) => void` | —       | No       | Called when selection changes                |
+| `disabled`      | `boolean`                 | `false` | No       | Disables the dropzone                        |
+| `className`     | `string`                  | —       | No       | Additional CSS classes                       |
+
+---
+
+## Examples
+
+### Image Upload
+
+```tsx
+import { FileUpload } from 'xertica-ui/ui';
+
+<FileUpload
+  accept="image/*"
+  maxSize={5 * 1024 * 1024} // 5MB
+  onFilesChange={files => handleAvatarUpload(files[0])}
+/>;
+```
+
+### Multiple Document Upload
+
+```tsx
+<FileUpload
+  accept=".pdf,.doc,.docx"
+  multiple
+  onFilesChange={files => setSelectedDocuments(files)}
+/>
+```
+
+### Inside react-hook-form
+
+```tsx
+<FormField
+  control={form.control}
+  name="attachment"
+  render={({ field }) => (
+    <FormItem>
+      <FormLabel>Attachment</FormLabel>
+      <FormControl>
+        <FileUpload accept=".pdf" onFilesChange={files => field.onChange(files[0])} />
+      </FormControl>
+      <FormMessage />
+    </FormItem>
+  )}
+/>
+```
+
+---
+
+## `useFileUpload` Hook
+
+A headless hook that encapsulates all file upload logic — drag state, file validation, error messaging, and the hidden input ref — without rendering any UI. Use it when the `<FileUpload>` component's visual design doesn't fit your needs.
+
+### Props
+
+| Prop            | Type                                                    | Default         | Description                                            |
+| --------------- | ------------------------------------------------------- | --------------- | ------------------------------------------------------ |
+| `maxFiles`      | `number`                                                | `1`             | Maximum number of files allowed                        |
+| `maxSize`       | `number`                                                | `5242880` (5MB) | Maximum file size in bytes                             |
+| `onFilesChange` | `(files: File[]) => void`                               | —               | Called with the accepted file list whenever it changes |
+| `onError`       | `(rejected: File[], reason: 'size' \| 'count') => void` | —               | Called when files are rejected                         |
+| `disabled`      | `boolean`                                               | `false`         | Whether the upload area is disabled                    |
+
+### Return Value
+
+| Property         | Type                                         | Description                                          |
+| ---------------- | -------------------------------------------- | ---------------------------------------------------- |
+| `files`          | `File[]`                                     | Currently accepted files                             |
+| `dragActive`     | `boolean`                                    | Whether a drag is active over the drop zone          |
+| `errorMessage`   | `string \| null`                             | Inline error message, or `null`                      |
+| `inputRef`       | `RefObject<HTMLInputElement>`                | Attach to the hidden `<input type="file">`           |
+| `handleFiles`    | `(files: FileList \| null) => void`          | Process a `FileList` from any source                 |
+| `handleDrag`     | `(e: DragEvent) => void`                     | Attach to `onDragEnter`, `onDragOver`, `onDragLeave` |
+| `handleDrop`     | `(e: DragEvent) => void`                     | Attach to `onDrop`                                   |
+| `handleChange`   | `(e: ChangeEvent<HTMLInputElement>) => void` | Attach to the hidden input's `onChange`              |
+| `removeFile`     | `(index: number) => void`                    | Remove a file by its index                           |
+| `openFileDialog` | `() => void`                                 | Programmatically open the native file picker         |
+
+### Custom Drop Zone Example
+
+```tsx
+import { useFileUpload } from 'xertica-ui/ui';
+import { UploadCloud } from 'lucide-react';
+
+function CustomDropZone() {
+  const {
+    files,
+    dragActive,
+    errorMessage,
+    inputRef,
+    handleDrag,
+    handleDrop,
+    handleChange,
+    removeFile,
+    openFileDialog,
+  } = useFileUpload({
+    maxFiles: 3,
+    maxSize: 10 * 1024 * 1024, // 10MB
+    onFilesChange: files => console.log('Files:', files),
+  });
+
+  return (
+    <div className="space-y-3">
+      <div
+        onDragEnter={handleDrag}
+        onDragOver={handleDrag}
+        onDragLeave={handleDrag}
+        onDrop={handleDrop}
+        onClick={openFileDialog}
+        className={cn(
+          'flex flex-col items-center justify-center rounded-xl border-2 border-dashed p-10 cursor-pointer transition-colors',
+          dragActive ? 'border-primary bg-primary/5' : 'border-border hover:border-primary/50'
+        )}
+      >
+        <UploadCloud className="size-8 text-muted-foreground mb-2" />
+        <p className="text-sm text-muted-foreground">
+          Drop files here or <span className="text-primary font-medium">browse</span>
+        </p>
+        <input ref={inputRef} type="file" multiple className="hidden" onChange={handleChange} />
+      </div>
+
+      {errorMessage && <p className="text-sm text-destructive">{errorMessage}</p>}
+
+      {files.length > 0 && (
+        <ul className="space-y-1">
+          {files.map((file, i) => (
+            <li key={i} className="flex items-center justify-between text-sm">
+              <span>{file.name}</span>
+              <Button size="sm" variant="ghost" onClick={() => removeFile(i)}>
+                Remove
+              </Button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+- Do not use native `<input type="file">` — always use `<FileUpload>` or `useFileUpload` from `xertica-ui`.
+- `maxSize` is in bytes — calculate using `MB * 1024 * 1024`.
+- In forms, use `onFilesChange` to call `field.onChange` — not `{...field}`.
+- For avatar uploads, use `accept="image/*"` and `multiple={false}`.
+- When using `useFileUpload`, attach `handleDrag` to **all three** drag events: `onDragEnter`, `onDragOver`, and `onDragLeave`.
+- Always attach `inputRef` to a hidden `<input type="file">` element — `openFileDialog()` requires it.
+- `removeFile(index)` removes by array index, not by file name.

package/docs/components/floating-media-wrapper.md

@@ -1,63 +1,63 @@
-# FloatingMediaWrapper
-
-A higher-level wrapper for media players (audio/video) that manages floating state, positioning, and transitions.
-
----
-
-## Overview
-
-The `FloatingMediaWrapper` is the engine behind the "auto-float" behavior of Xertica UI media components. It provides a draggable, resizable container that can follow the user across the application via portals, ensuring uninterrupted media consumption.
-
----
-
-## Features
-
-- **Draggable & Resizable**: Users can move and scale the media window as needed.
-- **Persistent State**: Remembers the last position and size in `localStorage` per `playerId`.
-- **Portal Rendering**: Mounts to `document.body` when floating to avoid CSS clipping and parent constraints.
-- **Responsive Placeholder**: Leaves a placeholder in the original document position when floating.
-
----
-
-## Props
-
-| Prop            | Type                     | Default     | Description                            |
-| --------------- | ------------------------ | ----------- | -------------------------------------- |
-| `isFloating`    | `boolean`                | —           | Controls the floating state.           |
-| `setIsFloating` | `(v: boolean) => void`   | —           | State setter for floating state.       |
-| `title`         | `string`                 | —           | Title shown in the floating header.    |
-| `aspectRatio`   | `number`                 | `16 / 9`    | Mantains the ratio during resize.      |
-| `minWidth`      | `number`                 | `320`       | Minimum width allowed.                 |
-| `colorVariant`  | `'default' \| 'primary'` | `'default'` | Visual style of the header.            |
-| `playerId`      | `string`                 | `'default'` | Unique key for storing position state. |
-
----
-
-## Examples
-
-### Basic Usage
-
-```tsx
-import { FloatingMediaWrapper } from 'xertica-ui/media';
-
-function MyPlayer() {
-  const [isFloating, setIsFloating] = useState(false);
-
-  return (
-    <FloatingMediaWrapper
-      isFloating={isFloating}
-      setIsFloating={setIsFloating}
-      title="Sample Media"
-    >
-      <video src="..." />
-    </FloatingMediaWrapper>
-  );
-}
-```
-
----
-
-## Related Components
-
-- [`VideoPlayer`](./video-player.md) — Uses this wrapper for its floating mode.
-- [`AudioPlayer`](./audio-player.md) — For system-level audio playback.
+# FloatingMediaWrapper
+
+A higher-level wrapper for media players (audio/video) that manages floating state, positioning, and transitions.
+
+---
+
+## Overview
+
+The `FloatingMediaWrapper` is the engine behind the "auto-float" behavior of Xertica UI media components. It provides a draggable, resizable container that can follow the user across the application via portals, ensuring uninterrupted media consumption.
+
+---
+
+## Features
+
+- **Draggable & Resizable**: Users can move and scale the media window as needed.
+- **Persistent State**: Remembers the last position and size in `localStorage` per `playerId`.
+- **Portal Rendering**: Mounts to `document.body` when floating to avoid CSS clipping and parent constraints.
+- **Responsive Placeholder**: Leaves a placeholder in the original document position when floating.
+
+---
+
+## Props
+
+| Prop            | Type                     | Default     | Description                            |
+| --------------- | ------------------------ | ----------- | -------------------------------------- |
+| `isFloating`    | `boolean`                | —           | Controls the floating state.           |
+| `setIsFloating` | `(v: boolean) => void`   | —           | State setter for floating state.       |
+| `title`         | `string`                 | —           | Title shown in the floating header.    |
+| `aspectRatio`   | `number`                 | `16 / 9`    | Mantains the ratio during resize.      |
+| `minWidth`      | `number`                 | `320`       | Minimum width allowed.                 |
+| `colorVariant`  | `'default' \| 'primary'` | `'default'` | Visual style of the header.            |
+| `playerId`      | `string`                 | `'default'` | Unique key for storing position state. |
+
+---
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { FloatingMediaWrapper } from 'xertica-ui/media';
+
+function MyPlayer() {
+  const [isFloating, setIsFloating] = useState(false);
+
+  return (
+    <FloatingMediaWrapper
+      isFloating={isFloating}
+      setIsFloating={setIsFloating}
+      title="Sample Media"
+    >
+      <video src="..." />
+    </FloatingMediaWrapper>
+  );
+}
+```
+
+---
+
+## Related Components
+
+- [`VideoPlayer`](./video-player.md) — Uses this wrapper for its floating mode.
+- [`AudioPlayer`](./audio-player.md) — For system-level audio playback.