uifolio 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barronakn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,305 @@
-# Temporary Holding Version
+# UIfolio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/uifolio.svg)](https://www.npmjs.com/package/uifolio)
+[![license](https://img.shields.io/npm/l/uifolio.svg)](https://www.npmjs.com/package/uifolio)
+[![node](https://img.shields.io/node/v/uifolio.svg)](https://www.npmjs.com/package/uifolio)
+
+Ma librairie de composants et animations : le code vit dans le projet, se copie et se modifie.
+
+Le paquet npm `uifolio` contient la CLI, les 14 composants et leurs 9 helpers — rien d'autre.
+Le site de démonstration (Vite, animations, playgrounds) vit dans le dépôt du projet et ne
+fait pas partie du paquet.
+
+## Démarrage
+
+```bash
+npm install
+npm run dev      # serveur de démo (http://localhost:5173)
+npm run build    # typecheck + build de production
+npm run preview  # sert le build
+npm run lint     # oxlint
+npm test         # tests du CLI (copie, couleur, manifeste npm)
+```
+
+Routes (hash) :
+
+- `#/` — page d'accueil (identité UIFolio)
+- `#/docs` — introduction, installation, thème
+- `#/components` — catalogue documenté
+- `#/components/video` — playground VideoPlayer
+- `#/components/calendar`, `/time`, `/audio`, `/stories`, `/editor`, `/upload`,
+  `/shortcuts`, `/panels`, `/choice`, `/color-picker`, `/icon-picker`
+- `#/animations/otp` — démo OTP animée
+- `#/animations/accordeon-horizontal`, `/storytelling`, `/empilement`,
+  `/texte-progressif`, `/images-fondues` — animations au scroll et fondus d’images
+
+Thème **clair/sombre** : bouton dans le header, choix persisté dans
+`localStorage (uifolio-theme)`, initialisation avant le premier rendu (aucun flash),
+défaut = préférence système.
+
+**Personnalisation globale** : le panneau de droite (ou l'accordéon sur mobile)
+règle la couleur `--primary` et l'arrondi `--radius` pour tous les composants.
+Le sélecteur avancé propose saturation/luminosité, teinte, alpha, pipette, canaux
+RGB, presets et formats HEX/RGB/HSL/RGBA. Le choix est persisté dans
+`localStorage (uifolio:design)` et repris dans les commandes CLI copiées
+(`--color`, `--radius`).
+
+## Utiliser les composants dans un autre projet (CLI)
+
+Comme shadcn : tu installes les fichiers dans **ton** projet, avec leurs helpers,
+et l'alias est réécrit automatiquement.
+
+```bash
+# depuis n'importe quel projet, via le paquet npm
+npx uifolio@latest add calendar --color "#10B981" --radius 6
+pnpm dlx uifolio@latest add video-player otp
+
+# depuis la racine du projet qui contient UIfolio
+npm run uifolio -- list
+npm run uifolio -- init --cwd ../mon-projet
+npm run uifolio -- add video-player calendar otp --cwd ../mon-projet
+
+# ou directement, exécutable via « bin »
+node cli/uifolio.mjs add otp --cwd ../mon-projet
+node cli/uifolio.mjs add file-upload --alias "#lib" --dry-run   # simulate
+```
+
+| Commande | Rôle |
+| --- | --- |
+| `uifolio list` | les composants disponibles |
+| `uifolio init` | écrit `uifolio.json` (dir, lib, alias) dans le projet cible |
+| `uifolio add <noms...>` | copie composant **+ dépendances transitives** (helpers `@/lib/*`) |
+
+Options : `--cwd <dir>`, `--dir <chemin>` (défaut `src/components/ui`),
+`--lib <chemin>` (défaut `src/lib`), `--alias <alias>` (défaut `@`),
+`--force` (écraser), `--dry-run` (simuler), `--color <hex>` et `--radius <px>`.
+
+`--color` écrit la couleur **directement dans les fichiers copiés** : les classes
+Tailwind (`bg-primary`, `border-primary/50`, `ring-primary/40`…) et les `var(--primary)`
+deviennent la valeur hex (`bg-[#10b981]`, `border-[#10b981]/50`…). Le composant garde donc
+la couleur choisie même si le projet cible ne définit pas `--primary`. `--radius` (seul)
+écrit `uifolio-theme.css` avec l'arrondi (et les tokens de couleur par défaut).
+
+À la fin, la CLI affiche les dépendances npm détectées, par ex. :
+
+```bash
+npm install clsx tailwind-merge lucide-react hls.js
+```
+
+Le projet cible doit fournir les tokens du thème (`bg-background`, `border`, `text-muted-foreground`…) :
+copie les variables CSS de `src/index.css` (`:root`, `.dark`, `@theme`) si ton projet ne les a pas.
+
+## Thèmes clair/sombre
+
+- Tokens CSS : `:root` (clair) et `.dark` (sombre) dans `src/index.css`,
+  branchés à Tailwind via `@theme inline` + `@custom-variant dark`.
+- `useTheme()` (`src/lib/use-theme.ts`) : `{ theme, setTheme, toggle }`,
+  persistance `localStorage('uifolio-theme')`.
+- `<ThemeToggle />` (`src/components/theme-toggle.tsx`) : bouton Sun/Moon.
+- Jamais de couleur figée dans les composants : tout passe par
+  `background`, `foreground`, `card`, `muted`, `border`, `primary`, `accent`, `ring`.
+
+## Upload réel
+
+Le `FileUpload` ne connaît pas ton backend : il appelle
+`uploader(file, onProgress) => Promise<url>` et affiche progression, succès et lien
+vers l'URL publique renvoyée.
+
+La démo utilise `createUploader()` (`src/lib/uploader.ts`) :
+
+1. `POST /api/upload/sign` → `{ key, uploadUrl, publicUrl }` (URL signée) ;
+2. `PUT` du fichier en **XHR avec progression** ;
+3. **reprise automatique** (2 retries, backoff) en réutilisant la même URL signée ;
+   un 4xx ne réessaie pas (refus définitif).
+
+Côté serveur, le plugin `upload-plugin.ts` (branché dans `vite.config.ts`) :
+
+- **Mode local (défaut, zéro config)** : écrit dans `public/uploads/` et sert
+  `/uploads/<key>` ;
+- **Mode S3 compatible** (AWS S3, Cloudflare R2, MinIO) : si `S3_ENDPOINT`,
+  `S3_BUCKET`, `S3_ACCESS_KEY_ID` et `S3_SECRET_ACCESS_KEY` sont définis, le serveur
+  renvoie une URL PUT signée **SigV4** (implémentée avec `node:crypto`, aucun SDK)
+  et le navigateur envoie directement au bucket.
+
+Configuration dans `.env` — voir `.env.example`.
+
+Brancher son propre uploader :
+
+```tsx
+const upload = createUploader({ signEndpoint: '/api/upload/sign' })
+
+// ou ton propre backend :
+const upload = async (file: File, onProgress: (v: number) => void) => {
+  const form = new FormData()
+  form.append('file', file)
+  const res = await fetch('/api/ton-endpoint', { method: 'POST', body: form })
+  const { url } = await res.json()
+  return url
+}
+
+<FileUpload accept="image/*" uploader={upload} onChange={setFiles} />
+```
+
+## Stack
+
+- Vite 8 · React 19 · TypeScript
+- Tailwind CSS 4 (tokens CSS, aucune config JS)
+- `lucide-react` pour les icônes, `clsx` + `tailwind-merge` pour `cn()`
+- `hls.js` importé **dynamiquement**, uniquement quand un flux `.m3u8` est lu
+- Aucune autre dépendance : éditeur, calendrier, time picker, panneaux, palette,
+  OTP et signature SigV4 sont maison
+
+## Composants
+
+| Composant | Fichier | Ce qu'il gère |
+| --- | --- | --- |
+| VideoPlayer | `src/components/ui/video-player.tsx` | URL, File/Blob, qualités, HLS, YouTube/Vimeo, sous-titres VTT, contrôles et lecture |
+| Calendar | `src/components/ui/calendar.tsx` | date simple, plage start–end, saisie manuelle, min/max, jours désactivés |
+| TimePicker | `src/components/ui/time-picker.tsx` | 12/24 h, secondes, pas, saisie et flèches |
+| AudioPlayer | `src/components/ui/audio-player.tsx` | variantes carte/compact, seek, volume, vitesse, égaliseur |
+| Stories | `src/components/ui/stories.tsx` | viewer Instagram : images, vidéos, slides texte, pause, progression |
+| RichTextEditor | `src/components/ui/rich-text-editor.tsx` | WYSIWYG `contentEditable`, toolbar, HTML en sortie |
+| FileUpload | `src/components/ui/file-upload.tsx` | drag & drop, validation, aperçus, progression, URL publique, retrait |
+| CommandMenu | `src/components/ui/command-menu.tsx` | palette Ctrl/⌘ + K, recherche, clavier |
+| ResizablePanels | `src/components/ui/resizable.tsx` | groupes horizontal/vertical, poignées, min-size, clavier |
+| OtpInput | `src/components/ui/otp-input.tsx` | 4 champs, collage, rotate + coche de succès |
+| ColorPicker | `src/components/ui/color-picker.tsx` | panneau avancé, saturation/luminosité, teinte, alpha, pipette, canaux RGB, presets, HEX/RGB/HSL/RGBA |
+
+Helpers copiables (la CLI les suit automatiquement) : `src/lib/utils.ts`,
+`src/lib/video.ts`, `src/lib/vtt.ts`, `src/lib/date.ts`, `src/lib/uploader.ts`, `src/lib/color.ts`,
+`src/lib/use-theme.ts`, `src/lib/use-hotkeys.ts`, `src/lib/use-reduced-motion.ts`.
+
+## VideoPlayer
+
+```tsx
+<VideoPlayer
+  sources={file ?? '/video.mp4'}
+  aspectRatio="16/9"
+  fit="cover"
+  controls="full"          // full | minimal | none
+  accent="#facc15"
+  autoPlay
+  muted
+  loop
+  lazy
+  subtitles={[
+    { src: '/fr.vtt', label: 'Français', lang: 'fr', default: true },
+    { src: '/en.vtt', label: 'English', lang: 'en' },
+  ]}
+  subtitleClassName="bottom-20"
+  overlay={(state) => <MonBadge playing={state.playing} />}
+/>
+```
+
+- Sources : URL directe, `File`/`Blob`, tableau de qualités (`{ src, quality }`), `.m3u8`,
+  YouTube et Vimeo.
+- Pour les embeds, l'iframe n'est injectée qu'au clic (façade + miniature) et les contrôles
+  natifs sont masqués : la barre du composant pilote le lecteur de la plateforme
+  (progression, temps, volume, vitesse, lecture/pause) via `postMessage`.
+- `ref` expose `play`, `pause`, `seek`, `mute`, `setVolume`, `setPlaybackRate`,
+  `requestFullscreen`, `getVideo`.
+- La barre de progression et le volume suivent l'arrondi global `--radius` (poignées
+  comprises), comme le reste du catalogue.
+- Optimisations : chargement lazy, pause hors écran, `preload` maîtrisé, `hls.js` en chunk séparé,
+  object URLs révoquées, changement de qualité sans perdre la position.
+- Sous-titres : parsing VTT tolérant, pistes fichier ou URL, style libre via
+  `subtitleClassName`, menu CC.
+
+## Calendar / TimePicker
+
+```tsx
+const [date, setDate] = useState<CalendarValue>(null)
+<Calendar mode="single" value={date} onChange={setDate} min={min} max={max} />
+<Calendar mode="range" value={range} onChange={setRange} />
+<Calendar disabled={(day) => day.getDay() === 0} />
+
+<TimePicker value={time} onChange={setTime} withSeconds step={15} hour12 />
+```
+
+La saisie manuelle accepte `jj/mm/aaaa`, `jj-mm-aaaa` et `aaaa-mm-jj`.
+
+## Audio / Stories
+
+```tsx
+<AudioPlayer src="/audio.wav" title="Titre" cover="/cover.svg" accent="#facc15" />
+<AudioPlayer variant="compact" src="/audio.wav" title="Titre" />
+
+<Stories items={stories} open={open} onOpenChange={setOpen} duration={5000} />
+```
+
+Une story peut être une image, une vidéo ou un slide texte avec son propre fond et sa durée.
+
+## Éditeur / Upload / Raccourcis / Panneaux / OTP
+
+```tsx
+<RichTextEditor value={html} onChange={setHtml} toolbar />
+
+<FileUpload accept="image/*,video/*" maxFiles={3} uploader={upload} onChange={setFiles} />
+
+<CommandMenu items={items} open={open} onOpenChange={setOpen} />
+useHotkeys({ 'mod+k': () => setOpen(true) })
+
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={34} minSize={20}>…</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={66} minSize={25}>…</ResizablePanel>
+</ResizablePanelGroup>
+
+<OtpInput length={4} value={code} onChange={setCode} onComplete={valider} />
+```
+
+L'OTP aligne de 4 à 8 champs, forme un cercle à la validation puis affiche une coche.
+L'animation respecte `prefers-reduced-motion`.
+
+## Animations
+
+Chaque animation a sa propre page documentée : `#/animations/otp` pour l'OTP, puis
+`#/animations/accordeon-horizontal` et `#/animations/storytelling` pour les cartes
+horizontales, et `#/animations/empilement` pour les cartes qui s'empilent au scroll avec
+une couleur de texte pilotée par la progression. Les couleurs suivent `--primary`. Le
+nombre de cartes se règle de 4 à 8 directement dans chaque aperçu. Ces démos autonomes ne
+sont pas installables via la CLI.
+
+## Publier le paquet
+
+Le paquet publié ne contient que la CLI, les composants et les helpers (`files`) : aucune
+dépendance d'exécution, React et Tailwind restent en `devDependencies` pour ne pas les
+installer chez ceux qui lancent `npx uifolio`.
+
+```bash
+npm login                          # une fois par machine
+npm profile enable-2fa auth-and-writes   # npm refuse de publier sans 2FA
+npm publish --otp 123456           # prepublishOnly vérifie cli/uifolio.mjs
+```
+
+Un jeton *granular* avec « Bypass 2FA » fonctionne aussi, mais npm restreint
+progressivement ces jetons pour la publication : la 2FA + `--otp` est la voie sûre.
+
+Ensuite `npx uifolio@latest add <composant>` et `pnpm dlx uifolio@latest add <composant>`
+fonctionnent.
+
+### Publication automatique (GitHub Actions)
+
+`.github/workflows/publish.yml` publie sur npm à chaque tag `v*` : il vérifie que le tag
+correspond à la version de `package.json`, installe avec `npm ci`, lance `oxlint`,
+`npm pack --dry-run` et `npm test`, puis publie via **trusted publishing** (OIDC, aucun
+token stocké). Un second job crée ensuite la **GitHub Release** du tag avec les notes
+générées à partir des commits.
+
+```bash
+npm version patch        # 0.3.0 → 0.3.1, commit + tag v0.3.1
+git push --follow-tags   # déclenche le workflow
+```
+
+Prérequis, une seule fois :
+
+1. première publication manuelle (ci-dessus) — le paquet doit exister sur npm ;
+2. npmjs.com → `uifolio` → Settings → **Trusted publishing** → GitHub Actions :
+   organisation `Barronakn`, dépôt `UIfolio`, workflow `publish.yml`,
+   action « npm publish » autorisée ;
+3. une configuration neuve doit réussir sa première publication **sous 2 jours**,
+   sinon elle expire et il faut la recréer.
+
+Le workflow doit être présent sur le commit taggé. Après activation, tu peux durcir le
+paquet avec Settings → Publishing access → « Require two-factor authentication and
+disallow tokens ».