@presage-kit/react

Bindings de React para Presage. Proporciona un proveedor de contexto, componentes declarativos y hooks.

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

<AdaptiveProvider>

Proporciona el AdaptiveClient a los componentes descendientes mediante el contexto de React.

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

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

Props:

Prop	Tipo	Requerido	Descripcion
client	AdaptiveClient	Si	Cliente creado con createAdaptiveClient()
children	ReactNode	Si	Arbol de componentes

<Adaptive>

Declara un adaptation point. Evalua las reglas y renderiza el hijo <Variant> correspondiente.

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	Tipo	Requerido	Descripcion
id	string	Si	Identificador del adaptation point
defaultVariant	string	Si	ID de variante de respaldo
children	ReactNode	Si	Debe contener elementos <Variant>

Comportamiento:

• Extrae los hijos <Variant> y sus IDs
• Llama internamente a useAdaptive() con la lista de variantes extraida
• Renderiza el contenido del <Variant> correspondiente
• Devuelve null si ninguna variante coincide (no deberia ocurrir con defaultVariant)

<Variant>

Declara una variante dentro de un bloque <Adaptive>. No renderiza nada por si mismo; <Adaptive> controla cual variante es visible.

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

Props:

Prop	Tipo	Requerido	Descripcion
id	string	Si	Identificador de la variante (referenciado en las acciones de reglas)
children	ReactNode	Si	Contenido a renderizar cuando es seleccionada

<AdaptiveNav>

Renderiza elementos de navegacion con reordenamiento adaptativo.

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	Tipo	Requerido	Descripcion
id	string	Si	Identificador del adaptation point
items	T[]	Si	Array de elementos que extienden NavItem
renderItem	(item: T, index: number) => ReactNode	Si	Funcion de renderizado por elemento

Interfaz NavItem:

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

Manejo de acciones:

• { type: 'reorder', order: [...] } — Reordena los elementos para coincidir con el array de orden. Los elementos que no estan en el array se agregan al final.
• { type: 'hide' } — Devuelve null (oculta toda la navegacion).
• Otras acciones o sin coincidencia — Renderiza los elementos en su orden original.

Genericos: AdaptiveNav es generico sobre el tipo de elemento:

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)

Resuelve un adaptation point y rastrea impresiones.

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

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

Parametros:

Parametro	Tipo	Descripcion
adaptationId	string	ID unico del adaptation point
config.variants	readonly V[]	Array de IDs de variantes
config.defaultVariant	NoInfer<V>	Variante por defecto (debe estar en variants)
config.strategy	Strategy	Opcional. Por defecto { type: 'rules' }

Tipo de retorno: UseAdaptiveResult<V>

Campo	Tipo	Descripcion
selectedVariant	V	Variante seleccionada actualmente
resolution	ResolvedAdaptation	Metadatos completos de resolucion
context	UserContext	Contexto actual del usuario
track	(event: string, props?: Record<string, unknown>) => void	Funcion de rastreo que adjunta automaticamente _adaptationId

Impresiones: Rastrea automaticamente presage:impression cuando selectedVariant cambia, con las propiedades:

{
  adaptationId: string
  variant: string
  strategy: string
}

TypeScript: Usa NoInfer<V> para evitar que defaultVariant amplie el tipo. Use as const en el array de variantes para una mejor inferencia de tipos:

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

useVariant(adaptationId, config)

Hook ligero que devuelve unicamente la cadena de la variante seleccionada.

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

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

Parametros: Los mismos que useAdaptive().

Tipo de retorno: V — La cadena de la variante seleccionada.

Internamente delega a useAdaptive() y desestructura selectedVariant.

useAdaptiveClient()

Devuelve el AdaptiveClient desde el contexto.

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()

Tipo de retorno: AdaptiveClient

Lanza: Error si se llama fuera de <AdaptiveProvider>.