uifolio 0.5.1 → 0.5.4

package/README.md

@@ -2,311 +2,112 @@
 
 [![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.
+A small, theme-friendly UI registry (components live in the target project, copied and edited) with a shadcn-like CLI (`uifolio add`).
 
-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.
+## Using the components in another project (CLI)
 
-## Démarrage
+Like shadcn: you install the files into **your** project, with their helpers,
+and the alias is rewritten automatically.
 
 ```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
+# from any project, through the npm package
 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
+# from the root of the project that contains UIfolio
 npm run uifolio -- list
-npm run uifolio -- init --cwd ../mon-projet
-npm run uifolio -- add video-player calendar otp --cwd ../mon-projet
+npm run uifolio -- init --cwd ../my-project
+npm run uifolio -- add video-player calendar otp --cwd ../my-project
 
-# ou directement, exécutable via « bin »
-node cli/uifolio.mjs add otp --cwd ../mon-projet
+# or directly, through the « bin »
+node cli/uifolio.mjs add otp --cwd ../my-project
 node cli/uifolio.mjs add file-upload --alias "#lib" --dry-run   # simulate
 ```
 
-| Commande | Rôle |
+| Command | Purpose |
 | --- | --- |
-| `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 `@`),
-`--page <chemin>` (créé s'il n'existe pas), `--interactive` (forcer les questions),
-`--force` (écraser), `--dry-run` (simuler), `--color <hex>` et `--radius <px>`.
-
-`add` ne s'arrête pas à la copie : sans `--dir` ni `--page`, la CLI demande
-**dans quel dossier** copier les composants, puis **dans quel fichier** les
-utiliser. La page est créée si elle manque ; si elle existe, l'import et le
-`<Composant />` sont ajoutés dans son JSX (sans doublon). Réponds `-` à la
-seconde question pour installer sans toucher à une page.
-
-Les couleurs passent par des **tokens Tailwind CSS 4** : la CLI écrit
-`uifolio-theme.css` (`:root`, `.dark`, puis `@theme inline` qui expose
-`--color-primary`, `--color-muted-foreground`, …) et l'importe automatiquement
-dans le CSS global du projet (celui qui fait `@import 'tailwindcss'`). Les
-composants gardent donc `bg-primary`, `border-primary/50`, `ring-primary/40` :
-aucune couleur en dur, `--color` change `--primary` dans le thème et `--radius`
-y ajoute `--radius`. Sans CSS global Tailwind détecté, le fichier est écrit à la
-racine et l'import à ajouter est affiché.
-
-À la fin, la CLI affiche les dépendances npm détectées, par ex. :
-
-```bash
-npm install clsx tailwind-merge lucide-react hls.js
-```
-
-## 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.
+| `uifolio list` | the available components |
+| `uifolio init` | writes `uifolio.json` (dir, lib, alias) in the target project |
+| `uifolio add <names...>` | copies the component **+ transitive dependencies** (helpers `@/lib/*`) |
 
-La démo utilise `createUploader()` (`src/lib/uploader.ts`) :
+Options: `--cwd <dir>`, `--dir <path>` (default `src/components/ui`), `--lib <path>` (default `src/lib`), `--alias <alias>` (default `@`), `--page <path>` (created if missing), `--interactive` (force the questions), `--force` (overwrite), `--dry-run` (simulate), `--color <hex>` and `--radius <px>`.
 
-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).
+`add` does not stop at the copy. The components always land in
+`src/components/ui` (override with `--dir`) and the page imports them through
+the `@/` alias. Without `--page`, the CLI asks where to use them:
 
-Côté serveur, le plugin `upload-plugin.ts` (branché dans `vite.config.ts`) :
+1. *Do you already have a file ready to receive the component (…component…) (y/N) ?* `yes` → *In which file should the component (…component…) be copied (e.g. src/pages/calendar.tsx) ?*: the import and a ready-to-render example are added without duplication, and the file is created when missing;
+2. `no` → *Would you like to create a new folder and an import file (Y/n) ?* `yes` → *Please specify the new path (e.g. src/pages/calendar.tsx) ?*: the folder and the file are created; `no` → install only, no file is touched.
 
-- **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.
+The example is a small component (`<CalendarExample />` plus its definition)
+that carries the data and props each component needs (items for `Stories` and
+`CommandMenu`, a source for the players, children for the resizable panels…),
+so the component is visible immediately instead of an empty `<Component />`.
 
-Configuration dans `.env` — voir `.env.example`.
+Answering `-` to a path question installs the component without creating or
+modifying any page.
 
-Brancher son propre uploader :
+Colors go through **Tailwind CSS 4 tokens**: the CLI writes
+`uifolio-theme.css` (`:root`, `.dark`, then `@theme inline`, which exposes
+`--color-primary`, `--color-muted-foreground`, …) and imports it automatically
+into the project's global CSS (the one with `@import 'tailwindcss'`). The
+components therefore keep `bg-primary`, `border-primary/50`, `ring-primary/40`:
+no hard-coded colors. `--color` changes `--primary` in the theme and `--radius`
+adds `--radius` to it. When no global Tailwind CSS is found, the file is written
+at the root and the import to add is printed.
 
-```tsx
-const upload = createUploader({ signEndpoint: '/api/upload/sign' })
+At the end, the CLI prints the detected npm dependencies, for example:
 
-// 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} />
+```bash
+npm install clsx tailwind-merge lucide-react hls.js
 ```
 
-## Stack
+### Preview parity
 
-- 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
+The docs preview and the installed component render identically because the page
+written by the CLI ships a demo of the same shape as the docs. If a component
+needs data to show anything (for example Stories, CommandMenu, FileUpload,
+AudioPlayer, VideoPlayer or the resizable panels), the page is created with that
+data, not an empty instance.
 
-## Composants
+If the docs entry for a component is missing, the detail page does not show a blank
+placeholder. It falls back to the preview as-is (or a minimal coherent state) and
+only marks the installation as complete when that is relevant.
 
-| 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 |
+## Components
 
-Helpers copiables (la CLI les suit automatiquement) : `src/lib/utils.ts`,
+| Component | File | What it handles |
+| --- | --- | --- |
+| VideoPlayer | `src/components/ui/video-player.tsx` | URL, File/Blob, qualities, HLS, YouTube/Vimeo, VTT subtitles, controls and playback |
+| Calendar | `src/components/ui/calendar.tsx` | single date, start–end range, manual input, min/max, disabled days |
+| TimePicker | `src/components/ui/time-picker.tsx` | 12/24 h, seconds, step, typing and arrow keys |
+| AudioPlayer | `src/components/ui/audio-player.tsx` | card/compact variants, seek, volume, speed, equalizer |
+| Stories | `src/components/ui/stories.tsx` | Instagram viewer: images, videos, text slides, pause, progress |
+| RichTextEditor | `src/components/ui/rich-text-editor.tsx` | `contentEditable` WYSIWYG, toolbar, HTML output |
+| FileUpload | `src/components/ui/file-upload.tsx` | drag & drop, validation, previews, progress, public URL, removal |
+| CommandMenu | `src/components/ui/command-menu.tsx` | Ctrl/⌘ + K palette, search, keyboard |
+| ResizablePanels | `src/components/ui/resizable.tsx` | horizontal/vertical groups, handles, min-size, keyboard |
+| OtpInput | `src/components/ui/otp-input.tsx` | 4 fields, paste, rotate + success check |
+| ColorPicker | `src/components/ui/color-picker.tsx` | advanced panel, saturation/lightness, hue, alpha, eyedropper, RGB channels, presets, HEX/RGB/HSL/RGBA |
+| Table | `src/components/ui/table.tsx` | typed data table, uniform `px-4` cells and a wider gap before Actions, selection and row actions |
+
+Copyable helpers (the CLI follows them automatically): `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`.
+## Publishing the package
 
 ```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
+npm publish
 ```
 
-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)
+Automatic publishing is wired in `.github/workflows/publish.yml` and runs on tag push.
 
-`.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
-```
+### Automatic publishing (GitHub Actions)
 
-Prérequis, une seule fois :
+The workflow publishes on tag `v*`. Run `git tag vX.Y.Z && git push --tags` to publish.
 
-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.
+More info: [README on GitHub](https://github.com/Barronakn/UIfolio#readme).
 
-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 ».
+License: [MIT](https://opensource.org/license/mit).