@cincoai/vox-react

React UI library for the VOX organizational voice campaign system.

Guide d'intégration complet : voir Exemple.md pour le pas-à-pas d'intégration dans un nouveau projet hôte Next.js + NestJS.

Personnalisation couleurs & textes : voir CUSTOMIZATION.md.
Adapters (required / optional) : voir ADAPTERS.md.
Vite / Webpack / CSS : voir BUNDLERS.md.

Installation

npm install @cincoai/vox-react @cincoai/vox-api

Peer dependencies: React 18+, @apollo/client, graphql, lucide-react, zustand, @dnd-kit/*, CodeMirror packages.

Quick start (Next.js)

/* app/globals.css — once, at app entry (not the VOX layout) */
@layer vox, theme, base, components, utilities;
@import '@cincoai/vox-react/styles.css' layer(vox);

// app/vox/layout.tsx
'use client';
import { VoxProvider } from '@cincoai/vox-react';
import { createPortailVoxAdapters } from '@/lib/vox/portailVoxConfig';

export default function Layout({ children }) {
  return (
    <VoxProvider
      graphqlUrl={process.env.NEXT_PUBLIC_GRAPHQL_API_URL!}
      getAccessToken={() => localStorage.getItem('access_token')}
      adapters={createPortailVoxAdapters(apolloClient)}
      apolloClient={apolloClient}
    >
      {children}
    </VoxProvider>
  );
}

// app/vox/page.tsx
import { VoxHub } from '@cincoai/vox-react';
export default function Page() {
  return <VoxHub />;
}

Exported screens

| Component | Description | |-----------|-------------| | VoxHub | Role-based navigation hub | | VoxAdminPacks / VoxAdminPolicies / VoxAdminCampaigns | Admin Studio. VoxAdminCampaigns hides Lancer l’orchestrateur by default; pass showRunOrchestratorButton to show it. Demo checkbox is enabled only when every selected org unit is virtual; create + isDemo auto-runs the orchestrator. | | VoxAdminVirtualOrgs | Generate a virtual subsidiary via the generate agent job (names + personas, no roleCode). Hub card is simulationOnly (voxSimulationEnabled). | | VoxContribution | Contributor campaign list | | VoxContributionCampaign | Campaign item table | | VoxContributionItemCoach | AI conversational coach | | VoxManager | Manager dashboard | | VoxManagerItemDetail | Item synthesis detail | | VoxManagerDepartmentDetail | Org-unit diagnostic | | VoxSharedManager | Read-only shared syntheses |

Adapters

| Adapter | Purpose | |---------|---------| | router | Link, useRouter, useParams (framework-agnostic) | | hostQueries | Organizations, user search (host GraphQL) | | hostComponents | OrganizationsTreePicker, StateBadge | | toast | Snackbar notifications | | exportPdf | PDF download callbacks | | coach | Optional AI coach session actions | | simulationAgents | Optional generate job (brief or structured fields) + run-demo-campaign (Next /api/agents proxy) | | labels | Partial UI label overrides (see CUSTOMIZATION.md) |

Personnalisation

Couleurs : le thème hôte (--color-*) est la source de vérité. styles.css n’alias que les tokens VOX-only. Textes via adapters.labels :

<VoxProvider
  adapters={{
    router: hostRouter,
    labels: {
      'hub.title': 'Quality Voice',
      'signal.0': 'Critical',
    },
  }}
  // …
/>

/* Host theme wins — do not rely on the package to set --color-primary */
html:root {
  --color-primary: #2563eb;
}

Détails : CUSTOMIZATION.md.

Styling (Tailwind)

The published styles.css only ships VOX-only aliases (--color-surface-2, --color-tooltip-bg, …) derived from the host palette. It does not set shared tokens such as --color-primary. Import it once at the app entry (prefer a CSS layer below the host theme), not inside the VOX route layout. The components themselves rely on Tailwind utility classes, so the host app must run Tailwind and include this package in its content scan:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@cincoai/vox-react/dist/**/*.{js,cjs}',
  ],
};

Map semantic Tailwind colors to the same --color-* variables (see CUSTOMIZATION.md for the full token list).

PDF export (server)

For Next.js API routes:

import {
  buildExportPayload,
  generateExportPdf,
} from '@cincoai/vox-react/export-server';

Note: buildExportPayload resolves the exporting user through a built-in stub (getUserForToken) that returns a placeholder identity. The host app is responsible for resolving the real user (e.g. from its own token/session) before relying on the "Généré par" field in the generated PDF.

Development

npm install
npm run migrate:from-portail  # sync from portail-owliance
npm run codegen
npm run build
npm test
npm run check:parity

Backend

Requires @cincoai/vox-api NestJS module on the GraphQL API. See graphql/README.md.

Host integration example (portal-kit): see portal-kit/docs/VOX_INTEGRATION.md.

Limitations & host adaptation

Must provide

| Item | Detail | |------|--------| | adapters.router | Framework router (Link, useRouter, useParams) — required | | Routes under /apps/vox/* (default) | Override with VoxProvider basePath + host mount; navigation via exported voxRoutes | | getAccessToken | Bearer for GraphQL (Keycloak / host session) | | Host GraphQL shape | getOrganizations, authenticated user with voxRole / roleCode / userOrganizations as expected by embedded ops | | Tailwind content scan | Include node_modules/@cincoai/vox-react/dist/** |

Optional adapters

hostQueries, hostComponents (OrganizationsTreePicker, StateBadge), toast, exportPdf, coach, labels.

Hard limitations (today)

• PDF “Généré par” needs a real user from the host (built-in stub is a placeholder).
• Coach typically needs a host proxy (e.g. Next /api/agents → coach-bridge); not fully self-contained.
• Tailwind-centric styling — Vite/Webpack hosts must configure content scan themselves.

Suggested package improvements (roadmap)

Goals: less host glue, multi-portal reuse. Advantages if delivered:

| Benefit | Effect | |---------|--------| | Time-to-integrate ↓ | Wire adapters without copying portal-kit | | Less host debt | Fewer custom PDF/coach Next routes | | Multi-client / multi-path | Same UI under /vox, /apps/feedback, etc. | | Bundle / perf | Ship only the screens a role needs | | DX | Integrate without reading a full host repo |

| Priority | Suggestion | Status / advantage | |----------|------------|-------------------| | P0 | Configurable basePath + voxRoutes | Done — VoxProvider({ basePath }), setVoxBasePath / voxRoutes.* | | P0 | Full VoxAdapters docs + minimal example | Done — ADAPTERS.md | | P1 | First-class coach adapter (createHttpCoachAdapter) | Done | | P1 | exportPdf + HTTP fallback (createHttpExportPdfAdapter) | Done | | P1 | Hook useVoxAccess() | Done | | P1 | Bundler-agnostic CSS + Vite/Webpack guide | Done — BUNDLERS.md | | P2 | Split entrypoints admin / contribution / manager | Done — @cincoai/vox-react/{admin,contribution,manager} | | P2 | Exported i18n keys + locale helper | Done — VOX_LABEL_KEYS / createLocaleLabels | | P2 | Storybook / mock GraphQL playground | Partial — PLAYGROUND.md → exemples/vox-demo |

Full context (host + API): portal-kit/docs/VOX_INTEGRATION.md.