@liorian/sdk 0.28.0-alpha.56010ca

package/README.md

@@ -0,0 +1,483 @@
+# `@liorian/sdk`
+
+Design system, shell applicatif et socle partagé du monorepo **Liorian**.
+
+Le package concentre l'ensemble des briques réutilisables utilisées par les hôtes frontend du
+monorepo (`frontend/liorian-socle`, `frontend/liorian-auth`, `frontend/liorian-connect`,
+`frontend/liorian-console`, `frontend/liorian-store`) ainsi que par les modules externes
+déclarés par les applications : primitives UI (style shadcn), thème **Katon**, composants
+composés (`DataGrid`, modales, sheets, lecteur multimédia…), providers, hooks, stores zustand,
+routines, services API, domaines, enums et utilitaires.
+
+| | |
+|---|---|
+| Nom du package | `@liorian/sdk` |
+| Chemin | `packages/sdk/` |
+| Type | ESM (`type: module`), TypeScript natif |
+| Point d'entrée | `src/index.tsx` (+ exports par sous-chemin `@liorian/sdk/<chemin>` ) |
+| License | MIT |
+| Peer deps | `react >= 19`, `react-dom >= 19`, `next >= 16` (optionnel) |
+
+---
+
+## Sommaire
+
+- [Pourquoi ce package ?](#pourquoi-ce-package-)
+- [Installation](#installation)
+- [Conventions d'import](#conventions-dimport)
+- [Structure du package](#structure-du-package)
+- [UI primitives (`presentation/ui`)](#ui-primitives--presentationui-)
+- [Composants composés (`presentation/components`)](#composants-composés--presentationcomponents-)
+- [DataGrid](#datagrid)
+- [Modales & sheets](#modales--sheets)
+- [Lecteur multimédia](#lecteur-multimédia)
+- [Thème Katon](#thème-katon)
+- [Design tokens & motion](#design-tokens--motion)
+- [Providers, hooks & stores](#providers-hooks--stores)
+- [Routines](#routines)
+- [Services API & utilitaires](#services-api--utilitaires)
+- [Domaine & types partagés](#domaine--types-partagés)
+- [Styles globaux](#styles-globaux)
+- [Développement](#développement)
+- [Publication npm](#publication-npm)
+- [Changelog](#changelog)
+- [License](#license)
+
+---
+
+## Pourquoi ce package ?
+
+Avant ce package, chaque hôte frontend dupliquait son design system, ses stores et ses services.
+`@liorian/sdk` centralise ces briques pour garantir :
+
+- **Cohérence visuelle** : une seule source de vérité pour les primitives UI, les tokens et le thème ;
+- **Réutilisabilité** : les modules métier (modules externes, apps) consomment le même socle sans
+  dépendre d'un hôte précis ;
+- **Maintenabilité** : un seul endroit pour corriger/étendre le design system, les stores et les
+  services partagés ;
+
+---
+
+## Installation
+
+### Dans le monorepo (bundler / Turbopack / Next.js)
+
+Le package est référencé via le protocole workspace de Bun :
+
+```jsonc
+// package.json d'un hôte frontend
+{
+  "dependencies": {
+    "@liorian/sdk": "workspace:*"
+  }
+}
+```
+
+Le TS `paths` résout les sous-chemins vers le source :
+
+```jsonc
+// tsconfig.json d'un hôte
+{
+  "compilerOptions": {
+    "paths": {
+      "@liorian/sdk": ["../../packages/sdk/src/index.ts"],
+      "@liorian/sdk/*": ["../../packages/sdk/src/*"]
+    }
+  }
+}
+```
+
+### Depuis npm (consommateur externe)
+
+```bash
+npm install @liorian/sdk
+# ou avec Bun
+bun add @liorian/sdk
+# ou avec Yarn pnpm...
+```
+
+Peer dependencies requises :
+
+| Peer | Contrainte |
+|---|---|
+| `react` | `>= 19` |
+| `react-dom` | `>= 19` |
+| `next` | `>= 16` *(optionnelle, utilisée pour les composants app-router)* |
+
+Le package est publié en TypeScript natif (source) ; votre builder doit supporter la
+transpilation TypeScript (Next.js/Turbopack, Vite, Bun…).
+
+---
+
+## Conventions d'import
+
+**Règle d'or : privilégier les imports par sous-chemin** `@liorian/sdk/<chemin>` plutôt que le
+barrel racine. Le barrel `@liorian/sdk` est réservé aux utilitaires transverses (`cn`,
+`CommonClassName`), au thème, aux données et aux tokens.
+
+```ts
+import {cn} from "@liorian/sdk";
+import {useIsMobile} from "@liorian/sdk/infrastructure/hooks/use-mobile";
+import {Button} from "@liorian/sdk/presentation/ui/button";
+import {DataGrid, DataGridColumnDef} from "@liorian/sdk/presentation/data-grid/data-grid";
+```
+
+Les sous-chemins correspondent à l'arborescence `src/` :
+
+```text
+@liorian/sdk/presentation/ui/button            → packages/sdk/src/presentation/ui/button
+@liorian/sdk/infrastructure/stores/module.store → packages/sdk/src/infrastructure/stores/module.store
+```
+
+---
+
+## Structure du package
+
+`@liorian/sdk` suit une organisation par couches, calquée sur l'architecture du monorepo :
+
+```text
+packages/sdk/src/
+├── index.ts                 # barrel (utilitaires, hooks, thème, SSO…)
+├── styles.css               # styles globaux du design system
+├── themes.css               # variables / feuilles du thème (claires & sombres)
+├── application/
+│   └── service/             # services appelants l'API (AuthApiService, Notifications…)
+├── domain/
+│   ├── config/              # AppConfig, AuthConfig, LogoConfig
+│   ├── entities/            # interfaces partagées (user, module, organization, notification…)
+│   ├── enums/               # enum modules, rôles, statuts…
+│   └── typing/              # types OAuth/MFA, réponses, caches…
+├── infrastructure/
+│   ├── capabilities/
+│   ├── common-classname.constant.ts
+│   ├── data/                # constantes (pays, genres…)
+│   ├── dataset/             # types DataSet (upload / métadonnées)
+│   ├── hooks/               # use-mobile, use-is-desktop, use-auth, use-notifications…
+│   ├── library/             # design tokens & utilitaires motion (GSAP)
+│   ├── providers/           # QueryProvider, AuthProvider, ModulesGuardProvider…
+│   ├── routines/            # classe Routine<T>, routine.hook, routine.tsx
+│   ├── stores/              # stores zustand (module, auth-user-connected, dataset, upload)
+│   └── utilities/           # api-service, socket-service, permission, format, ss o-auth…
+└── presentation/
+    ├── 8starlabs-ui/        # ligne graphique annexe (ui + hooks)
+    ├── charts/              # widgets graphiques (line, pie, area, radar, radial…)
+    ├── components/          # composants composés (data-table, waiting*, markdown-parser…)
+    ├── data-grid/           # DataGrid + moteur de recherche + état vide
+    ├── form-screen.tsx      # écran de formulaire (auth, onboarding)
+    ├── icons/               # wrappers d'icônes (lucide, remix, custom)
+    ├── modals/              # ModalPortal & co (components, hooks, stores, types)
+    ├── reui/                # couche réutilisable annexe
+    ├── sheets/              # sheets (legacy + composants)
+    ├── system/
+    ├── theme/               # préférence de thème, switch color scheme
+    ├── themes/katon/        # layout Katon (View, Wrapper, Header, Main, Footer, dashboard)
+    └── ui/                  # UI primitives (style shadcn)
+        └── media-player/    # lecteur multimédia unifié
+```
+
+---
+
+## UI primitives (`presentation/ui`)
+
+Composants de base de style shadcn. **Ne pas recréer une primitive existante** : réutilisez et
+étendez via `className` + `cn`.
+
+- **Formulaire** : `button`, `button-group`, `input`, `input-group`, `input-otp`, `textarea`,
+  `label`, `select`, `checkbox`, `switch`, `toggle`, `toggle-group`, `field`, `slider`, `progress`,
+  `slide-to-confirm`, `legacy-*` (`legacy-input`, `legacy-select-input`, `legacy-text-area`,
+  `legacy-phone-input`, `legacy-country-input`, `legacy-gender-input`, `legacy-birth-date-input`).
+- **Feedback** : `alert`, `alert-dialog`, `badge`, `sonner` (toasts), `empty`, `skeleton`,
+  `kpi-card`.
+- **Surcouches** : `dialog`, `drawer`, `sheet`, `dropdown-menu`, `context-menu`, `popover`,
+  `hover-card`, `tooltip`.
+- **Navigation** : `tabs`, `accordion`, `accordion-multiselect`, `breadcrumb`, `pagination`,
+  `menubar`, `navigation-menu`, `sidebar`, `table`, `aspect-ratio`, `resizable`.
+- **Choix / sélection** : `calendar`, `combobox`, `command`, `carousel`, `color-swatch-selector`,
+  `granularity-selector`, `label-selector`, `list-items`, `item`.
+- **Média / contenu** : `avatar`, `attachment`, `bubble`, `message`, `marker`, `text-gradient`,
+  `direction`, `clickable`, `timeline-steps`.
+
+Exemple d'utilisation :
+
+```tsx
+import {Button} from "@liorian/sdk/presentation/ui/button";
+import {Card, CardContent, CardHeader, CardTitle} from "@liorian/sdk/presentation/ui/card";
+
+<Card>
+  <CardHeader><CardTitle>Organisation</CardTitle></CardHeader>
+  <CardContent>
+    <Button>Enregistrer</Button>
+  </CardContent>
+</Card>
+```
+
+---
+
+## Composants composés (`presentation/components`)
+
+Composants complexes construits sur les primitives :
+
+- `data-table` — table de données générique ;
+- `animated-content`, `waiting`, `waiting-activity`, `waiting-bar`, `waiting-section` — états de
+  chargement/transition ;
+- `markdown-parser`, `message-scroller` — rendu markdown et flux de messages ;
+- `notifications-popover`, `notification-item`, `notification-details.modal`,
+  `push-notifications.provider` — centre de notifications ;
+- `floating-upload`, `upload-progress-dialog` — upload flottant avec suivi de progression ;
+- `module-guard`, `modules-guard-forbidden`, `modules-first-access.guard`,
+  `module-first-access-config.view`, `module-first-access-pending.view` — garde d'accès aux modules ;
+- `dynamic-icon` — rendu d'icône résolu dynamiquement ;
+- `local-time` — date/heure localisée ;
+- `auth-lock-screen`, `auth-session.view`, `auth/*` — écrans du flux SSO ;
+- `activity-descriptor-parser` — parsing des descripteurs d'activité.
+
+---
+
+## DataGrid
+
+La `DataGrid` (`@liorian/sdk/presentation/data-grid/data-grid`) est le composant central des
+listes métier (pages modules du manager). Elle embarque colonnes typées, tri, pagination, sélection,
+bulk actions et un moteur de recherche (`data-grid-search-engine`), plus un état vide
+(`data-grid-empty`).
+
+```tsx
+import {DataGrid, DataGridColumnDef} from "@liorian/sdk/presentation/data-grid/data-grid";
+
+const columns: DataGridColumnDef<OrgRow>[] = [
+  {accessorKey: "name", header: "Nom"},
+  {accessorKey: "membersCount", header: "Membres"},
+];
+
+<DataGrid columns={columns} data={rows} searchPlaceholder="Rechercher une organisation…" />;
+```
+
+Voir le skill `liorian-socle` pour les conventions d'usage détaillées.
+
+---
+
+## Modales & sheets
+
+- **Modales** : `@liorian/sdk/presentation/modals/...` — `ModalPortal`, steppers
+  (`useModalStepper`) et stores associés (dossier `hooks/`, `stores/`, `types/`).
+- **Sheets** : `@liorian/sdk/presentation/sheets/...` — panneaux latéraux (`legacy-sheet`,
+  `legacy-sheet-header`) et composants modernes.
+
+---
+
+## Lecteur multimédia
+
+`MediaPlayer` (`@liorian/sdk/presentation/ui/media-player`) : lecteur audio/vidéo unifié avec
+3 apparences — `voice-note`, `audio`, `video` —, flux live **HLS** (hls.js chargé dynamiquement),
+clavier YouTube + ARIA complet. **Ne pas recréer** de lecteur `<audio>`/`<video>` natif ni de
+lib tierce : utiliser `MediaPlayer` ou ses briques (`useMediaPlayer`, `PlayerScrubber`,
+`usePlayer()`).
+
+---
+
+## Thème Katon
+
+Le thème courant vit dans `presentation/themes/katon/` et fournit les composants de structure :
+
+- `View`, `Wrapper`, `Main`, `Footer` — squelette de page ;
+- `Header` + variantes (`header-menubar`, `header-modules-available`, `header-modules-recents`,
+  `header-modules-store`, `header-organization-select`, `header-routines`, `header-options`,
+  `header-tasks-connected-user`) ;
+- `dashboard-layout` — layout de dashboard complet avec metrics, stats, tables et section grid ;
+- `edge-section`, `main-wrapper`, `module-item-link`.
+
+Le switch clair/sombre est géré par `presentation/theme/` : `useThemePreferColorSchemeStore`,
+`ThemePreferColorSchemeProvider`, `SwitchColorScheme`, `ThemeSwitcherButton`.
+
+```tsx
+import {ThemePreferColorSchemeProvider, ThemeSwitcherButton} from "@liorian/sdk";
+```
+
+---
+
+## Design tokens & motion
+
+`@liorian/sdk/infrastructure/library/design-system` et `motion-utils` exposent les tokens de
+design et les utilitaires d'animation (GSAP). Importables depuis le barrel racine :
+
+```ts
+import {cn} from "@liorian/sdk";
+import {motionVariants, transitionEasing} from "@liorian/sdk/infrastructure/library/motion-utils";
+```
+
+---
+
+## Providers, hooks & stores
+
+### Providers (`infrastructure/providers/`)
+
+| Provider | Rôle |
+|---|---|
+| `QueryProvider` | Provider react-query global |
+| `AuthProvider` / `AuthGuard` | Sessions SSO : vérification et rafraîchissement du token |
+| `ModulesGuardProvider` | Garde d'accès et cartographie des domaines par module |
+| `ModulesSwitcherProvider` | Changement de module courant |
+| `ModulesRoutinesProvider` | Routines exposées par les modules |
+| `module-usage.provider` | Suivi d'usage des modules |
+
+### Hooks (`infrastructure/hooks/`)
+
+`use-auth`, `use-notifications`, `use-mobile`, `use-is-desktop`, `use-is-tauri`,
+`use-activity-lock-draft`, `use-elastic-interaction`, `use-recent-colors`, `use-recent-modules`.
+
+### Stores zustand (`infrastructure/stores/`)
+
+`module.store` (modules & activations), `auth-user-connected.store` (utilisateur connecté),
+`dataset.store`, `upload.store`.
+
+---
+
+## Routines
+
+L'infrastructure `infrastructure/routines/` définit la classe `Routine<T>` et ses helpers React :
+
+- `routine.ts` — classe de base ;
+- `routine.hook.ts` — hook de consommation ;
+- `routine.tsx` — composant d'exécution.
+
+Les routines permettent d'exécuter des tâches déclaratives (actions de module) depuis le shell
+manager. Reprendre la même source de vérité côté SDK et côté manager.
+
+---
+
+## Services API & utilitaires
+
+### Services (`application/service/`)
+
+- `AuthApiService`, `AuthUserService` — auth, MFA/OTP/OAuth (consomme `@liorian/api-core`) ;
+- `ModuleStoreApiService`, `ModuleActivationApiService` — catalogue de modules & activations ;
+- `OrganizationsApiService` — organisations ;
+- `NotificationsApiService`, `NotificationsPushService`, `NotificationsSocketService` — notifications ;
+- `OtpApiService`, `StorageApiService`, `UserPreferencesApiService`.
+
+### Utilitaires (`infrastructure/utilities/`)
+
+- `api-service.ts` — client HTTP de base ;
+- `socket-service.ts` — client socket ;
+- `permission.util`, `format.util`, `strings.util`, `classname.util` (`cn`/`CommonClassName`) ;
+- `encryption.service`, `activity-tracker.service`, `activity-lock.service` (verrouillage d'écran),
+  `form-snapshot.service` (brouillons de formulaire au verrouillage) ;
+- `sso-auth.util`, `auth-logout.util`, `route-access` (accès par route), `media-label.service`,
+  `push-permission.util`, `tauri.util`, `modules.ts`.
+
+---
+
+## Domaine & types partagés
+
+- **Config** : `AppConfig` (multi-hôtes par service : `AUTH`, `CONNECT`, `CORE_API`, `MANAGER`…),
+  `AuthConfig`, `LogoConfig`.
+- **Enums** : `domains.enum` (`ModuleDomain`), `module.enum`, `module-category.enum`, `routine.enum`,
+  `user-profile.enum`, `user-status.enum`, `coloring.enum`.
+- **Entités** : `user`, `user-profile`, `organization`, `module` / `module-store` /
+  `module-activation`, `notification`, `activity`, `media`.
+- **Typings** : `auth-oauth.types` (OAuth/MFA), `auth-caches`, `session.interface`, `response`,
+  `devise`, `statisticals`, `user-media-upload`, `values`, `routine.types`.
+
+---
+
+## Styles globaux
+
+- `styles.css` — styles du design system (à importer une fois par hôte) ;
+- `themes.css` — variables du thème (mode clair/sombre).
+
+```ts
+import "@liorian/sdk/styles.css";
+```
+
+Le champ `sideEffects` du `package.json` garantit que les CSS ne sont jamais tree-shakées.
+
+---
+
+## Développement
+
+### Typecheck
+
+```bash
+bun run --cwd packages/sdk typecheck
+```
+
+### Version & changelog
+
+Chaque changement de code dans le package doit :
+
+1. Mettre à jour `CHANGELOG.md` (format : changelog conventionnel, sections `Added` / `Changed` /
+   `Fixed` / `Removed`) ;
+2. Bumper la version dans `packages/sdk/package.json` (SemVer, suivant les conventions
+   [`liorian-commit`](../../.agents/skills/liorian-commit/SKILL.md)) et synchroniser les autres
+   packages si nécessaire.
+
+### Conventions
+
+Voir les skills du workspace : `liorian-core` (design system) et `liorian-conventions`
+(commits, versioning, style TypeScript strict, messages en français).
+
+---
+
+## Publication npm
+
+La publication sur npmjs est automatisée par le workflow GitHub
+`.github/workflows/publish-sdk.yml` du monorepo.
+
+### Déclencheurs
+
+- **Push sur une branche gérée** touchant au moins un fichier de `packages/sdk/**` (une publication
+  n'est déclenchée que s'il y a eu des changements du package) ;
+- **Déclenchement manuel** (`workflow_dispatch`) sur une branche gérée.
+
+### Versioning par branche
+
+Le dist-tag npm et la version publiée dépendent de la branche d'origine :
+
+| Branche | Dist-tag npm | Version publiée |
+|---|---|---|
+| `main` | `latest` | version du `package.json` (ex. `0.20.0`) |
+| `alpha` | `alpha` | `<version>-alpha.<sha court>` (pré-release) |
+| `beta` | `beta` | `<version>-beta.<sha court>` (pré-release) |
+| `rc` | `rc` | `<version>-rc.<sha court>` (pré-release) |
+| `nightly` | `nightly` | `<version>-nightly.<sha court>` (build quotidien) |
+
+Toute autre branche n'est pas publiée. Les versions pré-release intègrent le SHA court du commit
+(`0.20.0-beta.1a2b3c4`), ce qui garantit l'unicité de chaque publication et l'absence de collision
+de version. Aucune pré-release n'écrase le dist-tag `latest`.
+
+Consommation selon le canal voulu :
+
+```bash
+npm install @liorian/sdk            # dernière release stable (latest)
+npm install @liorian/sdk@beta       # dernière pré-release beta
+npm install @liorian/sdk@nightly    # dernier build nightly
+```
+
+### Processus de publication
+
+```text
+push <branche gérée> packages/sdk/** (ou manuel)
+        │
+        ▼
+┌────────────────────────┐    ┌──────────────────────────────────────────────┐
+│ Job resolve            │ ──►│ Job publish (skip si version déjà publiée)    │
+│  branche → dist-tag    │    │  bun install → typecheck → npm publish --tag  │
+│  version pre-release   │    │  --provenance → dist-tag cible                │
+└────────────────────────┘    └──────────────────────────────────────────────┘
+```
+
+### Prérequis
+
+Configurer le secret `NPM_TOKEN` du dépôt GitHub (avec droits de publication sur l'organisation
+`@liorian`).
+
+---
+
+## Changelog
+
+Toutes les évolutions sont documentées dans [`CHANGELOG.md`](./CHANGELOG.md).
+
+---
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@liorian/sdk",
+  "version": "0.28.0-alpha.56010ca",
+  "description": "Core package for the Liorian (application shell, domain, infrastructure, UI design system).",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "src/index.tsx",
+  "module": "src/index.tsx",
+  "types": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx",
+    "./application": "./src/application/index.ts",
+    "./application/*": "./src/application/*",
+    "./domain": "./src/domain/index.ts",
+    "./domain/*": "./src/domain/*",
+    "./infrastructure": "./src/infrastructure/index.tsx",
+    "./infrastructure/*": "./src/infrastructure/*",
+    "./presentation": "./src/presentation/index.tsx",
+    "./presentation/*": "./src/presentation/*",
+    "./styles.css": "./src/styles.css",
+    "./themes.css": "./src/themes.css"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@gsap/react": "^2.1.2",
+    "@radix-ui/react-accordion": "^1.2.14",
+    "@radix-ui/react-checkbox": "^1.3.5",
+    "@radix-ui/react-radio-group": "^1.4.1",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@remixicon/react": "^4.9.0",
+    "@shadcn/react": "^0.2.0",
+    "@tabler/icons-react": "^3.44.0",
+    "@tanstack/react-query": "^5.101.2",
+    "@tanstack/react-table": "^8.21.3",
+    "@tauri-apps/plugin-notification": "^2.3.3",
+    "axios": "^1.18.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "gsap": "^3.15.0",
+    "hls.js": "^1.7.1",
+    "input-otp": "^1.4.2",
+    "lucide-react": "^1.21.0",
+    "radix-ui": "^1.6.0",
+    "react-day-picker": "^10.0.1",
+    "react-resizable-panels": "^4.12.1",
+    "recharts": "3.8.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "vaul": "^1.1.2",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.14"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5"
+  }
+}