xertica-ui 2.2.1 → 2.4.0

package/docs/components/audio-player.md

@@ -1,167 +1,167 @@
-# AudioPlayer
-
-A unified, premium media player designed for both quick audio previews and long-form podcasts. It supports embedded (Card) and global (Bar) layouts, featuring fluid transitions and intelligent responsiveness.
-
----
-
-## Import
-
-```tsx
-import { AudioPlayer } from 'xertica-ui/media';
-```
-
----
-
-## Basic Usage
-
-### Embedded with Auto-Float (Card)
-
-Ideal for in-page content. The player automatically "floats" if the user scrolls away while listening.
-
-```tsx
-<AudioPlayer
-  src="url/to/audio.mp3"
-  title="Exclusive Interview"
-  artist="Xertica News"
-  variant="card"
-/>
-```
-
-### Global Bar (Bar)
-
-Ideal for continuous playback across the entire application.
-
-```tsx
-<AudioPlayer
-  src="url/to/audio.mp3"
-  title="Weekly Podcast"
-  variant="bar"
-  colorVariant="primary"
-  isOpen={true}
-  onClose={() => setOpen(false)}
-/>
-```
-
----
-
-## Props
-
-| Prop              | Type                     | Default     | Description                                                   |
-| ----------------- | ------------------------ | ----------- | ------------------------------------------------------------- |
-| `variant`         | `'card' \| 'bar'`        | `'card'`    | Determines if the player is an embedded card or a fixed bar.  |
-| `colorVariant`    | `'default' \| 'primary'` | `'default'` | Visual style (`primary` is ideal for brand-focused podcasts). |
-| `isOpen`          | `boolean`                | `true`      | (Bar only) Whether the player bar is open or closed.          |
-| `enableAutoFloat` | `boolean`                | `true`      | (Card only) Whether to float when scrolling out of viewport.  |
-| `title`           | `string`                 | —           | Track title.                                                  |
-| `artist`          | `string`                 | —           | Author or subtitle.                                           |
-| `src`             | `string`                 | —           | Audio file URL.                                               |
-| `duration`        | `number`                 | —           | Total duration in seconds.                                    |
-
----
-
-## Features and Behaviors
-
-### Dynamic Responsiveness
-
-The `AudioPlayer` doesn't just hide elements—it **reallocates** them. Depending on available screen space:
-
-- **Large Screens (Desktop)**: All controls (volume, speed, download) are visible on the bar.
-- **Medium/Small Screens**: Controls like volume and speed automatically move to the secondary options menu (`...`) to prevent visual clutter.
-
-### Playback Speed
-
-Supports speed adjustments: `0.5x`, `1x`, `1.5x`, and `2x`. The control adapts dynamically to the screen width.
-
-### Layout Integration
-
-The `bar` variant automatically detects the state of the **Sidebar** and **AI Assistant** via `LayoutContext`, adjusting its margins to ensure it never covers vital system elements.
-
----
-
-## Headless Hook: `useAudioPlayer`
-
-For advanced use cases where you need a fully custom player UI, use the `useAudioPlayer` headless hook directly:
-
-```tsx
-import { useAudioPlayer } from 'xertica-ui/hooks';
-
-function MyCustomPlayer({ src }: { src: string }) {
-  const {
-    audioRef,
-    containerRef,
-    isPlaying,
-    togglePlay,
-    currentTime,
-    duration,
-    formatTime,
-    onPlay,
-    onPause,
-    onEnded,
-    onTimeUpdate,
-    onLoadedMetadata,
-  } = useAudioPlayer({ src, variant: 'card' });
-
-  return (
-    <div ref={containerRef}>
-      <audio
-        ref={audioRef}
-        src={src}
-        onPlay={onPlay}
-        onPause={onPause}
-        onEnded={onEnded}
-        onTimeUpdate={onTimeUpdate}
-        onLoadedMetadata={onLoadedMetadata}
-      />
-      <button onClick={togglePlay}>{isPlaying ? 'Pause' : 'Play'}</button>
-      <span>
-        {formatTime(currentTime)} / {formatTime(duration)}
-      </span>
-    </div>
-  );
-}
-```
-
-See [`hooks.md`](./hooks.md#useaudioplayer) for the complete `useAudioPlayer` API reference.
-
----
-
-## Implementation Notes (v2.1.9+)
-
-### Latest-Ref Pattern in mode-switch effect
-
-The hook uses the **latest-ref pattern** to avoid stale closure problems when switching between floating and embedded modes:
-
-```ts
-const currentTimeRef = useRef(currentTime);
-const isPlayingRef = useRef(isPlaying);
-
-useEffect(() => {
-  currentTimeRef.current = currentTime;
-}, [currentTime]);
-useEffect(() => {
-  isPlayingRef.current = isPlaying;
-}, [isPlaying]);
-
-// mode-switch effect — reads from refs, not from state closure
-useEffect(() => {
-  const audio = audioRef.current;
-  if (audio) {
-    if (Math.abs(audio.currentTime - currentTimeRef.current) > 0.5)
-      audio.currentTime = currentTimeRef.current;
-    if (isPlayingRef.current) audio.play().catch(err => console.log('Playback interrupted:', err));
-  }
-}, [isFloating, variant]);
-```
-
-This eliminates the need for the `eslint-disable-next-line react-hooks/exhaustive-deps` comment that previously suppressed the stale-closure warning. When building a custom player with `useAudioPlayer`, you do not need to replicate this pattern — it is handled internally.
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
->
-> - **Branding Variants**: Use `colorVariant="primary"` for high-relevance or branded content (like Podcasts). Use the default style for utility audios.
-> - **Manual Floating**: In Card mode, users can click the "Maximize" icon to manually force floating mode.
-> - **Accessibility**: All buttons have appropriate ARIA labels. Always provide a descriptive `title` for each audio track.
-> - **Custom UI**: Use `useAudioPlayer` from `xertica-ui/hooks` only when you need a fully custom player interface. For standard playback, always use `<AudioPlayer>` directly.
+# AudioPlayer
+
+A unified, premium media player designed for both quick audio previews and long-form podcasts. It supports embedded (Card) and global (Bar) layouts, featuring fluid transitions and intelligent responsiveness.
+
+---
+
+## Import
+
+```tsx
+import { AudioPlayer } from 'xertica-ui/media';
+```
+
+---
+
+## Basic Usage
+
+### Embedded with Auto-Float (Card)
+
+Ideal for in-page content. The player automatically "floats" if the user scrolls away while listening.
+
+```tsx
+<AudioPlayer
+  src="url/to/audio.mp3"
+  title="Exclusive Interview"
+  artist="Xertica News"
+  variant="card"
+/>
+```
+
+### Global Bar (Bar)
+
+Ideal for continuous playback across the entire application.
+
+```tsx
+<AudioPlayer
+  src="url/to/audio.mp3"
+  title="Weekly Podcast"
+  variant="bar"
+  colorVariant="primary"
+  isOpen={true}
+  onClose={() => setOpen(false)}
+/>
+```
+
+---
+
+## Props
+
+| Prop              | Type                     | Default     | Description                                                   |
+| ----------------- | ------------------------ | ----------- | ------------------------------------------------------------- |
+| `variant`         | `'card' \| 'bar'`        | `'card'`    | Determines if the player is an embedded card or a fixed bar.  |
+| `colorVariant`    | `'default' \| 'primary'` | `'default'` | Visual style (`primary` is ideal for brand-focused podcasts). |
+| `isOpen`          | `boolean`                | `true`      | (Bar only) Whether the player bar is open or closed.          |
+| `enableAutoFloat` | `boolean`                | `true`      | (Card only) Whether to float when scrolling out of viewport.  |
+| `title`           | `string`                 | —           | Track title.                                                  |
+| `artist`          | `string`                 | —           | Author or subtitle.                                           |
+| `src`             | `string`                 | —           | Audio file URL.                                               |
+| `duration`        | `number`                 | —           | Total duration in seconds.                                    |
+
+---
+
+## Features and Behaviors
+
+### Dynamic Responsiveness
+
+The `AudioPlayer` doesn't just hide elements—it **reallocates** them. Depending on available screen space:
+
+- **Large Screens (Desktop)**: All controls (volume, speed, download) are visible on the bar.
+- **Medium/Small Screens**: Controls like volume and speed automatically move to the secondary options menu (`...`) to prevent visual clutter.
+
+### Playback Speed
+
+Supports speed adjustments: `0.5x`, `1x`, `1.5x`, and `2x`. The control adapts dynamically to the screen width.
+
+### Layout Integration
+
+The `bar` variant automatically detects the state of the **Sidebar** and **AI Assistant** via `LayoutContext`, adjusting its margins to ensure it never covers vital system elements.
+
+---
+
+## Headless Hook: `useAudioPlayer`
+
+For advanced use cases where you need a fully custom player UI, use the `useAudioPlayer` headless hook directly:
+
+```tsx
+import { useAudioPlayer } from 'xertica-ui/hooks';
+
+function MyCustomPlayer({ src }: { src: string }) {
+  const {
+    audioRef,
+    containerRef,
+    isPlaying,
+    togglePlay,
+    currentTime,
+    duration,
+    formatTime,
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onLoadedMetadata,
+  } = useAudioPlayer({ src, variant: 'card' });
+
+  return (
+    <div ref={containerRef}>
+      <audio
+        ref={audioRef}
+        src={src}
+        onPlay={onPlay}
+        onPause={onPause}
+        onEnded={onEnded}
+        onTimeUpdate={onTimeUpdate}
+        onLoadedMetadata={onLoadedMetadata}
+      />
+      <button onClick={togglePlay}>{isPlaying ? 'Pause' : 'Play'}</button>
+      <span>
+        {formatTime(currentTime)} / {formatTime(duration)}
+      </span>
+    </div>
+  );
+}
+```
+
+See [`hooks.md`](./hooks.md#useaudioplayer) for the complete `useAudioPlayer` API reference.
+
+---
+
+## Implementation Notes (v2.1.9+)
+
+### Latest-Ref Pattern in mode-switch effect
+
+The hook uses the **latest-ref pattern** to avoid stale closure problems when switching between floating and embedded modes:
+
+```ts
+const currentTimeRef = useRef(currentTime);
+const isPlayingRef = useRef(isPlaying);
+
+useEffect(() => {
+  currentTimeRef.current = currentTime;
+}, [currentTime]);
+useEffect(() => {
+  isPlayingRef.current = isPlaying;
+}, [isPlaying]);
+
+// mode-switch effect — reads from refs, not from state closure
+useEffect(() => {
+  const audio = audioRef.current;
+  if (audio) {
+    if (Math.abs(audio.currentTime - currentTimeRef.current) > 0.5)
+      audio.currentTime = currentTimeRef.current;
+    if (isPlayingRef.current) audio.play().catch(err => console.log('Playback interrupted:', err));
+  }
+}, [isFloating, variant]);
+```
+
+This eliminates the need for the `eslint-disable-next-line react-hooks/exhaustive-deps` comment that previously suppressed the stale-closure warning. When building a custom player with `useAudioPlayer`, you do not need to replicate this pattern — it is handled internally.
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+>
+> - **Branding Variants**: Use `colorVariant="primary"` for high-relevance or branded content (like Podcasts). Use the default style for utility audios.
+> - **Manual Floating**: In Card mode, users can click the "Maximize" icon to manually force floating mode.
+> - **Accessibility**: All buttons have appropriate ARIA labels. Always provide a descriptive `title` for each audio track.
+> - **Custom UI**: Use `useAudioPlayer` from `xertica-ui/hooks` only when you need a fully custom player interface. For standard playback, always use `<AudioPlayer>` directly.

package/docs/components/avatar.md

@@ -1,101 +1,101 @@
-# Avatar
-
-## Overview
-
-Displays a user's identity visually — either as a profile photo or as an initials-based fallback. Used in headers, sidebars, comment threads, and table rows to represent people.
-
----
-
-## When to Use
-
-- User profile representation in headers and sidebars
-- Author attribution in activity feeds and comment lists
-- List items that represent people or organizations
-
----
-
-## Anatomy
-
-```
-<Avatar>
-  <AvatarImage />    ← Actual photo
-  <AvatarFallback /> ← Shown when image fails or hasn't loaded
-</Avatar>
-```
-
----
-
-## Props
-
-### Avatar
-
-| Prop        | Type     | Default | Required | Description                                                  |
-| ----------- | -------- | ------- | -------- | ------------------------------------------------------------ |
-| `className` | `string` | —       | No       | Size and shape overrides (default: `h-10 w-10 rounded-full`) |
-
-### AvatarImage
-
-| Prop  | Type     | Required | Description                 |
-| ----- | -------- | -------- | --------------------------- |
-| `src` | `string` | No       | Image URL                   |
-| `alt` | `string` | No       | Accessible alternative text |
-
-### AvatarFallback
-
-| Prop        | Type        | Description                            |
-| ----------- | ----------- | -------------------------------------- |
-| `className` | `string`    | Style the fallback background and text |
-| `children`  | `ReactNode` | Initials string or fallback icon       |
-| `delayMs`   | `number`    | Delay before fallback appears (ms)     |
-
----
-
-## Examples
-
-### With Image + Fallback Initials
-
-```tsx
-import { Avatar, AvatarImage, AvatarFallback } from 'xertica-ui/ui';
-
-<Avatar>
-  <AvatarImage src="https://github.com/johndoe.png" alt="John Doe" />
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>;
-```
-
-### Small (in table rows)
-
-```tsx
-<Avatar className="h-8 w-8">
-  <AvatarImage src={user.avatar} alt={user.name} />
-  <AvatarFallback className="text-xs">{user.name.charAt(0).toUpperCase()}</AvatarFallback>
-</Avatar>
-```
-
-### With Icon Fallback
-
-```tsx
-import { User } from 'lucide-react';
-
-<Avatar>
-  <AvatarImage src={user.avatar} />
-  <AvatarFallback className="bg-primary/10 text-primary">
-    <User className="w-4 h-4" />
-  </AvatarFallback>
-</Avatar>;
-```
-
----
-
-## AI Rules
-
-- Always include `<AvatarFallback>` — never render `<AvatarImage>` alone. If the image fails to load, the component will be blank without a fallback.
-- The fallback should be initials (`user.name.charAt(0)`) or a `lucide-react` user icon — never an external image.
-- Size the Avatar using `className="h-8 w-8"` (small) or `className="h-10 w-10"` (default). Do not use Tailwind `w-` and `h-` classes that don't correspond to standard rem multiples.
-
----
-
-## Related Components
-
-- [`Header`](./header.md) — Avatar is used in the user profile dropdown
-- [`Sidebar`](./sidebar.md) — Avatar in the sidebar footer
+# Avatar
+
+## Overview
+
+Displays a user's identity visually — either as a profile photo or as an initials-based fallback. Used in headers, sidebars, comment threads, and table rows to represent people.
+
+---
+
+## When to Use
+
+- User profile representation in headers and sidebars
+- Author attribution in activity feeds and comment lists
+- List items that represent people or organizations
+
+---
+
+## Anatomy
+
+```
+<Avatar>
+  <AvatarImage />    ← Actual photo
+  <AvatarFallback /> ← Shown when image fails or hasn't loaded
+</Avatar>
+```
+
+---
+
+## Props
+
+### Avatar
+
+| Prop        | Type     | Default | Required | Description                                                  |
+| ----------- | -------- | ------- | -------- | ------------------------------------------------------------ |
+| `className` | `string` | —       | No       | Size and shape overrides (default: `h-10 w-10 rounded-full`) |
+
+### AvatarImage
+
+| Prop  | Type     | Required | Description                 |
+| ----- | -------- | -------- | --------------------------- |
+| `src` | `string` | No       | Image URL                   |
+| `alt` | `string` | No       | Accessible alternative text |
+
+### AvatarFallback
+
+| Prop        | Type        | Description                            |
+| ----------- | ----------- | -------------------------------------- |
+| `className` | `string`    | Style the fallback background and text |
+| `children`  | `ReactNode` | Initials string or fallback icon       |
+| `delayMs`   | `number`    | Delay before fallback appears (ms)     |
+
+---
+
+## Examples
+
+### With Image + Fallback Initials
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from 'xertica-ui/ui';
+
+<Avatar>
+  <AvatarImage src="https://github.com/johndoe.png" alt="John Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>;
+```
+
+### Small (in table rows)
+
+```tsx
+<Avatar className="h-8 w-8">
+  <AvatarImage src={user.avatar} alt={user.name} />
+  <AvatarFallback className="text-xs">{user.name.charAt(0).toUpperCase()}</AvatarFallback>
+</Avatar>
+```
+
+### With Icon Fallback
+
+```tsx
+import { User } from 'lucide-react';
+
+<Avatar>
+  <AvatarImage src={user.avatar} />
+  <AvatarFallback className="bg-primary/10 text-primary">
+    <User className="w-4 h-4" />
+  </AvatarFallback>
+</Avatar>;
+```
+
+---
+
+## AI Rules
+
+- Always include `<AvatarFallback>` — never render `<AvatarImage>` alone. If the image fails to load, the component will be blank without a fallback.
+- The fallback should be initials (`user.name.charAt(0)`) or a `lucide-react` user icon — never an external image.
+- Size the Avatar using `className="h-8 w-8"` (small) or `className="h-10 w-10"` (default). Do not use Tailwind `w-` and `h-` classes that don't correspond to standard rem multiples.
+
+---
+
+## Related Components
+
+- [`Header`](./header.md) — Avatar is used in the user profile dropdown
+- [`Sidebar`](./sidebar.md) — Avatar in the sidebar footer