@algenium/blocks 1.12.0 → 1.14.0

package/README.md

@@ -20,6 +20,13 @@ This package requires the following peer dependencies:
 pnpm add react react-dom next-themes lucide-react motion
 ```
 
+`hls.js` (`>=1.5`) is an **optional** peer dependency required only by
+`VideoPlayer`; install it in apps that use the player:
+
+```bash
+pnpm add hls.js
+```
+
 ## Configuration
 
 ### Tailwind CSS
@@ -415,6 +422,159 @@ interface Notification {
 
 ---
 
+### EmojiPicker
+
+A zero-dependency emoji picker with bilingual (English + Spanish) search,
+category navigation, a persisted "frequently used" section, a global skin-tone
+preference, and desktop-first keyboard navigation. The emoji dataset (~1,900
+emoji, Unicode ≤ 15.1) is generated at build time from Unicode CLDR annotations
+and committed to the repo, so consuming apps ship **no** extra runtime
+dependencies. Because the package is `sideEffects: false` and tree-shaken, apps
+that never import `EmojiPicker` don't bundle the data at all.
+
+**Features:**
+
+- Bilingual search: "corazón", "corazon" and "heart" all match ❤️
+- 9 categories with an icon tab bar and scroll-to-section
+- "Frequently used" recents, persisted in `localStorage`
+- Global skin-tone selector (applied to capable emoji), persisted
+- Keyboard navigation: arrows move, Enter/Space selects
+- `labels` + `locale` props for i18n; search is always bilingual
+
+**Usage:**
+
+```tsx
+import { useRef, useState } from "react";
+import { EmojiPickerPopover } from "@algenium/blocks";
+
+function Composer() {
+	const ref = useRef<HTMLTextAreaElement>(null);
+	const [value, setValue] = useState("");
+
+	function insert(emoji: string) {
+		const el = ref.current;
+		if (!el) return setValue((v) => v + emoji);
+		const start = el.selectionStart ?? value.length;
+		const end = el.selectionEnd ?? value.length;
+		setValue(value.slice(0, start) + emoji + value.slice(end));
+	}
+
+	return (
+		<div className="flex items-end gap-2">
+			<textarea
+				ref={ref}
+				value={value}
+				onChange={(e) => setValue(e.target.value)}
+			/>
+			<EmojiPickerPopover locale="es" onSelect={insert} />
+		</div>
+	);
+}
+```
+
+Use the standalone panel when you want to place it inside your own anchor:
+
+```tsx
+import { EmojiPicker } from "@algenium/blocks";
+
+<EmojiPicker locale="es" onSelect={(emoji) => insert(emoji)} />;
+```
+
+**Props (`EmojiPicker`):**
+
+```typescript
+interface EmojiPickerProps {
+	onSelect: (emoji: string) => void;
+	locale?: "en" | "es"; // Section titles + skin-tone names. Default "en"
+	labels?: EmojiPickerLabels; // Overrides individual strings / category titles
+	className?: string;
+	recentLimit?: number; // Default 24
+	storageKey?: string | null; // localStorage namespace; null disables persistence
+}
+```
+
+`EmojiPickerPopover` accepts every `EmojiPicker` prop plus `triggerLabel`,
+`triggerClassName`, `side`, `align`, `open`/`onOpenChange` (controlled), and
+`keepOpenOnSelect`.
+
+---
+
+### VideoPlayer
+
+A standardized HLS video player with a fully custom control bar (no native
+`controls`), for both live streams and on-demand recordings. `hls.js` is an
+**optional peer dependency** loaded on demand via dynamic import — apps that
+already depend on it (`app`, `admin`, `media`) bundle nothing new, and Safari
+falls back to native HLS.
+
+**Features:**
+
+- Click-to-play poster (attaches HLS only after the user gesture)
+- Play/pause, mute + hover volume slider, keyboard shortcuts
+- Resolution picker (Auto + hls.js levels), playback speed (VOD)
+- Picture-in-Picture and fullscreen (menus stay usable in fullscreen)
+- VOD: seekbar with buffered ranges + current/total time
+- Live: red pulsing badge, **no seekbar**, and a "go live" affordance when the
+  playhead drifts behind the edge
+- `stats` prop renders live viewer / VOD reproduction counts
+- Loading / waiting / error states with retry; errors surfaced via `onError`
+  (no bundled reporting) and localized via `labels`
+
+**Usage:**
+
+```tsx
+import { VideoPlayer, usePlaybackStats } from "@algenium/blocks";
+
+function Recording({ mediaId, src, poster }: Props) {
+	const stats = usePlaybackStats(
+		`https://media.example.com/playback/${mediaId}/stats`,
+	);
+
+	return (
+		<VideoPlayer
+			src={src}
+			mode="vod"
+			poster={poster}
+			stats={stats}
+			labels={{ live: "EN VIVO", formatViews: (n) => `${n} reproducciones` }}
+			onFirstPlay={() => {
+				void fetch(`https://media.example.com/playback/${mediaId}/view`, {
+					method: "POST",
+				});
+			}}
+			onError={(e) => reportToSentry(e)}
+		/>
+	);
+}
+```
+
+For live playback pass `mode="live"` and, typically, `autoPlay muted`.
+
+**Props:**
+
+```typescript
+interface VideoPlayerProps {
+	src: string;
+	mode: "live" | "vod";
+	poster?: string;
+	autoPlay?: boolean;
+	muted?: boolean;
+	stats?: { viewers?: number; views?: number };
+	labels?: VideoPlayerLabels;
+	showQualitySelector?: boolean; // Default true
+	onPlayingChange?: (playing: boolean) => void;
+	onFirstPlay?: () => void; // Fires once — wire your view beacon here
+	onError?: (error: DescribedPlaybackError) => void;
+	className?: string;
+}
+```
+
+Also exported: `useHlsPlayback` (the attach/detach hook), `usePlaybackStats`
+(polls a stats endpoint), `createLiveHlsConfig` / `createVodHlsConfig`, and
+`describePlaybackError`.
+
+---
+
 ## UI Primitives
 
 The package also exports underlying UI primitives that can be used independently: