@presage-kit/react

Bindings React pour Presage. Fournit un provider de contexte, des composants déclaratifs et des hooks.

pnpm add @presage-kit/core @presage-kit/react

<AdaptiveProvider>

Fournit le AdaptiveClient aux composants descendants via le contexte React.

import { AdaptiveProvider } from '@presage-kit/react'

<AdaptiveProvider client={client}>
  <App />
</AdaptiveProvider>

Props :

Prop	Type	Requis	Description
client	AdaptiveClient	Oui	Client issu de createAdaptiveClient()
children	ReactNode	Oui	Arbre de composants

<Adaptive>

Déclare un point d’adaptation. Evalue les règles et rend l’enfant <Variant> correspondant.

import { Adaptive, Variant } from '@presage-kit/react'

<Adaptive id="onboarding" defaultVariant="standard">
  <Variant id="guided-tour"><GuidedTour /></Variant>
  <Variant id="standard"><StandardView /></Variant>
</Adaptive>

Props :

Prop	Type	Requis	Description
id	string	Oui	Identifiant du point d’adaptation
defaultVariant	string	Oui	ID de la variante de repli
children	ReactNode	Oui	Doit contenir des éléments <Variant>

Comportement :

• Extrait les enfants <Variant> et leurs IDs
• Appelle useAdaptive() en interne avec la liste de variantes extraite
• Rend le contenu du <Variant> correspondant
• Retourne null si aucune variante ne correspond (ne devrait pas arriver avec defaultVariant)

<Variant>

Déclare une variante au sein d’un bloc <Adaptive>. Ne rend rien par lui-même — <Adaptive> contrôle quelle variante est visible.

<Variant id="guided-tour">
  <GuidedTour />
</Variant>

Props :

Prop	Type	Requis	Description
id	string	Oui	Identifiant de la variante (référencé dans les actions de règles)
children	ReactNode	Oui	Contenu à rendre quand sélectionné

<AdaptiveNav>

Rend les éléments de navigation avec un réordonnancement adaptatif.

import { AdaptiveNav, type NavItem } from '@presage-kit/react'

<AdaptiveNav<MenuItem>
  id="sidebar"
  items={menuItems}
  renderItem={(item, index) => <NavLink key={item.id} item={item} />}
/>

Props :

Prop	Type	Requis	Description
id	string	Oui	Identifiant du point d’adaptation
items	T[]	Oui	Tableau d’éléments étendant NavItem
renderItem	(item: T, index: number) => ReactNode	Oui	Fonction de rendu par élément

Interface NavItem :

interface NavItem {
  id: string
  [key: string]: unknown
}

Gestion des actions :

• { type: 'reorder', order: [...] } — Réordonne les éléments selon le tableau d’ordre. Les éléments absents du tableau sont ajoutés à la fin.
• { type: 'hide' } — Retourne null (masque la navigation entière).
• Autres actions ou aucune correspondance — Rend les éléments dans leur ordre d’origine.

Génériques : AdaptiveNav est générique sur le type d’élément :

interface MenuItem extends NavItem {
  label: string
  href: string
  icon: React.ReactNode
}

<AdaptiveNav<MenuItem>
  id="sidebar"
  items={menuItems}
  renderItem={(item) => (
    <a href={item.href}>{item.icon} {item.label}</a>
  )}
/>

useAdaptive(adaptationId, config)

Résout un point d’adaptation et suit les impressions.

import { useAdaptive } from '@presage-kit/react'

const { selectedVariant, resolution, context, track } = useAdaptive('feature-panel', {
  variants: ['compact', 'expanded', 'hidden'] as const,
  defaultVariant: 'compact',
})

Paramètres :

Param	Type	Description
adaptationId	string	ID unique du point d’adaptation
config.variants	readonly V[]	Tableau d’IDs de variantes
config.defaultVariant	NoInfer<V>	Variante par défaut (doit figurer dans variants)
config.strategy	Strategy	Optionnel. Par défaut { type: 'rules' }

Type de retour : UseAdaptiveResult<V>

Champ	Type	Description
selectedVariant	V	Variante actuellement sélectionnée
resolution	ResolvedAdaptation	Métadonnées complètes de résolution
context	UserContext	Contexte utilisateur courant
track	(event: string, props?: Record<string, unknown>) => void	Fonction de suivi qui attache automatiquement _adaptationId

Impressions : Suit automatiquement presage:impression quand selectedVariant change, avec les propriétés :

{
  adaptationId: string
  variant: string
  strategy: string
}

TypeScript : Utilise NoInfer<V> pour empêcher defaultVariant d’élargir le type. Utilisez as const sur le tableau de variantes pour une meilleure inférence de type :

const { selectedVariant } = useAdaptive('x', {
  variants: ['a', 'b', 'c'] as const,
  defaultVariant: 'a',
})
// selectedVariant: 'a' | 'b' | 'c'

useVariant(adaptationId, config)

Hook léger retournant uniquement la chaîne de la variante sélectionnée.

import { useVariant } from '@presage-kit/react'

const variant = useVariant('layout', {
  variants: ['sidebar', 'topnav'] as const,
  defaultVariant: 'sidebar',
})
// variant: 'sidebar' | 'topnav'

Paramètres : Identiques à useAdaptive().

Type de retour : V — La chaîne de la variante sélectionnée.

Délègue en interne à useAdaptive() et déstructure selectedVariant.

useAdaptiveClient()

Retourne le AdaptiveClient depuis le contexte.

import { useAdaptiveClient } from '@presage-kit/react'

const client = useAdaptiveClient()

client.track('button_clicked', { buttonId: 'cta' })
client.identify('user-456', { role: 'editor' })
const ctx = client.getContext()

Type de retour : AdaptiveClient

Lance une erreur : Error si appelé en dehors de <AdaptiveProvider>.