@asteby/metacore-runtime-react 23.9.2 → 23.10.0

package/src/license/license-gate.tsx

@@ -0,0 +1,277 @@
+/**
+ * <LicenseGate> — el primitivo del blindaje. Un host lo monta en UNA línea
+ * envolviendo su app autenticada:
+ *
+ *   <LicenseGate state={state} onActivate={activate}>
+ *     <AppShell />
+ *   </LicenseGate>
+ *
+ * Comportamiento según el estado (resuelto por el backend del host):
+ *   - Sin enforcement, o estado operable (valid/stale/grace) → renderiza children.
+ *     stale/grace además montan el <LicenseExpiryBanner> degradado por encima.
+ *   - enforcement && missing/invalid/expired → modal BLOQUEANTE full-screen,
+ *     no descartable, con el formulario de activación. Al activar con éxito el
+ *     host refresca el estado y el gate se abre sin recargar.
+ *
+ * Es branding-aware si el host pasa `branding` (logo/nombre desde el
+ * PlatformConfig del SDK); si no, cae a un encabezado neutro.
+ *
+ * INDEPENDIENTE del kernel: no importa su cliente ni fija su versión. Solo
+ * consume `LicenseState` y una promesa `onActivate`.
+ */
+import { useState, type ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { ShieldAlert, Clock, Loader2 } from 'lucide-react'
+import { Button, Input } from '@asteby/metacore-ui'
+import {
+    isLicenseBlocking,
+    isTrialExpired,
+    type LicenseState,
+    type LicenseBranding,
+} from './types'
+import { LicenseStatusBadge } from './license-status-badge'
+import { LicenseExpiryBanner } from './license-expiry-banner'
+
+function cx(...parts: Array<string | false | undefined>): string {
+    return parts.filter(Boolean).join(' ')
+}
+
+export interface LicenseGateProps {
+    /** Estado actual, resuelto por el backend del host. `undefined` mientras
+     * carga → fail-open (renderiza children, nunca destella el candado). */
+    state: LicenseState | undefined
+    /** Activa una licencia con el código/token pegado. Resuelve → el host
+     * refresca `state` y el gate se abre. Rechaza con un Error cuyo `message`
+     * se muestra al usuario. */
+    onActivate: (code: string) => Promise<void>
+    children: ReactNode
+    /** Branding opcional (logo/nombre) para el encabezado del modal. */
+    branding?: LicenseBranding
+    /** Acción "Gestionar licencia" del banner degradado (opcional). */
+    onManage?: () => void
+    className?: string
+}
+
+export function LicenseGate({
+    state,
+    onActivate,
+    children,
+    branding,
+    onManage,
+    className,
+}: LicenseGateProps) {
+    const blocking = isLicenseBlocking(state)
+
+    return (
+        <>
+            {/* stale/grace/upcoming degradan con banner; el propio banner
+                decide si mostrarse. Bloqueado → no hace falta, el modal manda. */}
+            {!blocking && (
+                <LicenseExpiryBanner state={state} onManage={onManage} />
+            )}
+            {children}
+            {blocking && state && (
+                <LicenseGateModal
+                    state={state}
+                    onActivate={onActivate}
+                    branding={branding}
+                    className={className}
+                />
+            )}
+        </>
+    )
+}
+
+interface LicenseGateModalProps {
+    state: LicenseState
+    onActivate: (code: string) => Promise<void>
+    branding?: LicenseBranding
+    className?: string
+}
+
+function LicenseGateModal({
+    state,
+    onActivate,
+    branding,
+    className,
+}: LicenseGateModalProps) {
+    const { t } = useTranslation()
+    const [code, setCode] = useState('')
+    const [submitting, setSubmitting] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    const trialExpired = isTrialExpired(state)
+
+    const title = trialExpired
+        ? t('license.gate.trial_title', {
+              defaultValue: 'Tu prueba gratuita terminó',
+          })
+        : t('license.gate.title', { defaultValue: 'Activa tu licencia' })
+
+    const description = trialExpired
+        ? t('license.gate.trial_description', {
+              defaultValue:
+                  'Tu prueba gratuita terminó. Activa una licencia para continuar. Pega tu clave (lic_…) o el token firmado que te entregaron.',
+          })
+        : state.status === 'expired'
+          ? t('license.gate.expired_description', {
+                defaultValue:
+                    'Tu licencia venció y el periodo de gracia terminó. Activa una licencia vigente para seguir operando. Pega tu clave (lic_…) o el token firmado.',
+            })
+          : state.status === 'invalid'
+            ? t('license.gate.invalid_description', {
+                  defaultValue:
+                      'La licencia de esta instancia no es válida. Pega una clave (lic_…) o el token firmado que te entregó tu proveedor para reactivarla.',
+              })
+            : t('license.gate.missing_description', {
+                  defaultValue:
+                      'Esta instancia necesita una licencia activa para operar. Pega tu clave (lic_…) o el token firmado para activarla.',
+              })
+
+    const canSubmit = code.trim().length > 0 && !submitting
+
+    const submit = async () => {
+        if (!canSubmit) return
+        setSubmitting(true)
+        setError(null)
+        try {
+            await onActivate(code.trim())
+            // Éxito → el host refresca `state`; el gate se re-renderiza y este
+            // modal se desmonta solo. No recargamos.
+        } catch (e) {
+            const message =
+                e instanceof Error && e.message
+                    ? e.message
+                    : t('license.gate.activate_error', {
+                          defaultValue: 'No se pudo activar la licencia.',
+                      })
+            setError(message)
+            setSubmitting(false)
+        }
+    }
+
+    return (
+        <div
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="license-gate-title"
+            data-license-status={state.status}
+            className={cx(
+                'fixed inset-0 z-[100] flex items-center justify-center bg-background/90 p-4 backdrop-blur-sm',
+                className,
+            )}
+        >
+            <div className="w-full max-w-lg overflow-hidden rounded-2xl border bg-card text-card-foreground shadow-2xl">
+                <div className="flex flex-col gap-4 p-6">
+                    <div className="flex items-start gap-3">
+                        {branding?.logo ? (
+                            <img
+                                src={branding.logo}
+                                alt={branding.name ?? ''}
+                                className="h-10 w-10 shrink-0 rounded-xl object-contain"
+                            />
+                        ) : (
+                            <div
+                                className={cx(
+                                    'flex h-10 w-10 shrink-0 items-center justify-center rounded-xl',
+                                    trialExpired
+                                        ? 'bg-primary/10 text-primary'
+                                        : 'bg-destructive/10 text-destructive',
+                                )}
+                            >
+                                {trialExpired ? (
+                                    <Clock className="h-5 w-5" aria-hidden />
+                                ) : (
+                                    <ShieldAlert className="h-5 w-5" aria-hidden />
+                                )}
+                            </div>
+                        )}
+                        <div className="flex min-w-0 flex-col gap-1">
+                            <h2
+                                id="license-gate-title"
+                                className="text-lg leading-tight font-semibold"
+                            >
+                                {title}
+                            </h2>
+                            <div className="flex flex-wrap items-center gap-2">
+                                <LicenseStatusBadge status={state.status} />
+                                <span className="text-muted-foreground text-xs">
+                                    {branding?.name
+                                        ? branding.name
+                                        : t('license.gate.instance', {
+                                              defaultValue: 'Esta instancia',
+                                          })}
+                                </span>
+                            </div>
+                        </div>
+                    </div>
+
+                    <p className="text-muted-foreground text-sm">{description}</p>
+
+                    {state.reason && (
+                        <p className="bg-muted/50 text-muted-foreground rounded-md px-3 py-2 text-xs">
+                            {state.reason}
+                        </p>
+                    )}
+
+                    <form
+                        className="flex flex-col gap-2"
+                        onSubmit={(e) => {
+                            e.preventDefault()
+                            void submit()
+                        }}
+                    >
+                        <label
+                            htmlFor="license-gate-code"
+                            className="text-sm font-medium"
+                        >
+                            {t('license.gate.code_label', {
+                                defaultValue: 'Clave o token de licencia',
+                            })}
+                        </label>
+                        <Input
+                            id="license-gate-code"
+                            autoFocus
+                            autoComplete="off"
+                            spellCheck={false}
+                            placeholder={t('license.gate.code_placeholder', {
+                                defaultValue: 'lic_… o pega el token firmado',
+                            })}
+                            value={code}
+                            disabled={submitting}
+                            aria-invalid={error ? true : undefined}
+                            onChange={(e) => {
+                                setCode(e.target.value)
+                                if (error) setError(null)
+                            }}
+                        />
+                        {error && (
+                            <p role="alert" className="text-destructive text-sm">
+                                {error}
+                            </p>
+                        )}
+                        <Button
+                            type="submit"
+                            className="mt-1 w-full"
+                            disabled={!canSubmit}
+                        >
+                            {submitting && (
+                                <Loader2
+                                    className="h-4 w-4 animate-spin"
+                                    aria-hidden
+                                />
+                            )}
+                            {submitting
+                                ? t('license.gate.activating', {
+                                      defaultValue: 'Activando…',
+                                  })
+                                : t('license.gate.activate', {
+                                      defaultValue: 'Activar licencia',
+                                  })}
+                        </Button>
+                    </form>
+                </div>
+            </div>
+        </div>
+    )
+}

package/src/license/license-status-badge.tsx

@@ -0,0 +1,93 @@
+/**
+ * Insignia de estado de licencia — un chip que traduce el `LicenseStatus` a
+ * color + etiqueta legible. Reutilizable suelto (p. ej. en Ajustes de licencia)
+ * o embebido en el encabezado del <LicenseGate>.
+ */
+import { useTranslation } from 'react-i18next'
+import {
+    ShieldCheck,
+    ShieldAlert,
+    ShieldQuestion,
+    Clock,
+    CloudOff,
+} from 'lucide-react'
+import { Badge } from '@asteby/metacore-ui'
+import type { LicenseStatus } from './types'
+
+type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline'
+
+interface StatusMeta {
+    variant: BadgeVariant
+    Icon: typeof ShieldCheck
+    key: string
+    defaultValue: string
+    /** Tinte amarillo para posturas degradadas (grace/stale) que `variant` no
+     * cubre — el sistema de badges no tiene "warning". */
+    warn?: boolean
+}
+
+const STATUS_META: Record<LicenseStatus, StatusMeta> = {
+    valid: {
+        variant: 'default',
+        Icon: ShieldCheck,
+        key: 'license.status.valid',
+        defaultValue: 'Activa',
+    },
+    stale: {
+        variant: 'outline',
+        Icon: CloudOff,
+        key: 'license.status.stale',
+        defaultValue: 'Sin verificar',
+        warn: true,
+    },
+    grace: {
+        variant: 'outline',
+        Icon: Clock,
+        key: 'license.status.grace',
+        defaultValue: 'En gracia',
+        warn: true,
+    },
+    expired: {
+        variant: 'destructive',
+        Icon: ShieldAlert,
+        key: 'license.status.expired',
+        defaultValue: 'Vencida',
+    },
+    missing: {
+        variant: 'secondary',
+        Icon: ShieldQuestion,
+        key: 'license.status.missing',
+        defaultValue: 'Sin licencia',
+    },
+    invalid: {
+        variant: 'destructive',
+        Icon: ShieldAlert,
+        key: 'license.status.invalid',
+        defaultValue: 'Inválida',
+    },
+}
+
+export interface LicenseStatusBadgeProps {
+    status: LicenseStatus
+    className?: string
+}
+
+export function LicenseStatusBadge({ status, className }: LicenseStatusBadgeProps) {
+    const { t } = useTranslation()
+    const meta = STATUS_META[status] ?? STATUS_META.missing
+    const { Icon } = meta
+
+    return (
+        <Badge
+            variant={meta.variant}
+            className={
+                (meta.warn
+                    ? 'border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-400 '
+                    : '') + (className ?? '')
+            }
+        >
+            <Icon aria-hidden />
+            {t(meta.key, { defaultValue: meta.defaultValue })}
+        </Badge>
+    )
+}

package/src/license/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Licencia de instancia — el contrato de estado que el backend del host (ops
+ * vía kernel `LicenseService`) expone y que este módulo pinta. El SDK NO habla
+ * con el kernel ni impone su versión: el host resuelve el `LicenseState` con su
+ * propio transporte y se lo pasa a <LicenseGate>. Así el gate es un primitivo
+ * reutilizable e INDEPENDIENTE del release del kernel.
+ *
+ * División de responsabilidades del blindaje:
+ *   - kernel  → enforcement (qué está permitido; firma/verifica el estado).
+ *   - SDK     → UX (este módulo: gate, banner, badge).
+ *   - hub     → emisión (mintea el token Ed25519).
+ *   - hosts   → wiring (resuelven el estado y montan <LicenseGate> en 1 línea).
+ */
+
+/** El estado operativo de la licencia, tal como lo deriva el backend. */
+export type LicenseStatus =
+    | 'valid'
+    | 'stale'
+    | 'grace'
+    | 'expired'
+    | 'missing'
+    | 'invalid'
+
+export interface LicenseState {
+    /** Licensing activo en esta instancia (LICENSING_ENFORCE). Si es false el
+     * gate es transparente: nunca bloquea ni degrada. */
+    enforced: boolean
+    configured: boolean
+    valid: boolean
+    status: LicenseStatus
+    reason?: string
+    org_id?: string
+    plan?: string
+    preset?: string
+    entitlements: string[]
+    wildcard: boolean
+    /** Lease: la instancia falló su check-in obligatorio con el hub. */
+    stale: boolean
+    max_offline_hours?: number
+    issued_at?: string
+    expires_at?: string
+    in_grace: boolean
+    grace_until?: string
+    days_remaining: number
+    last_checked_at?: string
+}
+
+/** La licencia es OPERABLE cuando permite operar (aunque sea degradada):
+ * valid, la postura `stale` del lease, o dentro de la ventana de gracia.
+ * missing/invalid/expired no son operables. Sin enforcement → siempre operable.
+ * Espeja `State.Operable()` del backend. */
+export function isLicenseOperable(state: LicenseState | undefined): boolean {
+    if (!state || !state.enforced) return true
+    return state.valid || state.in_grace
+}
+
+/** La instancia debe BLOQUEARSE tras el modal de activación cuando hay
+ * enforcement y la licencia es missing/invalid/expired (pasada la gracia).
+ * grace/stale degradan con banner en vez de bloquear. Espeja `State.Blocking()`.
+ * Mientras el estado aún carga (undefined) NO bloquea: fail-open en la UI para
+ * que un check lento/fallido nunca destelle un candado sobre la app. */
+export function isLicenseBlocking(state: LicenseState | undefined): boolean {
+    if (!state || !state.enforced) return false
+    return !isLicenseOperable(state)
+}
+
+/** Un preset/vertical está habilitado si la licencia otorga wildcard o lo lista
+ * explícitamente. Sin enforcement → todo habilitado. */
+export function isPresetEntitled(
+    state: LicenseState | undefined,
+    presetKey: string,
+): boolean {
+    if (!state || !state.enforced) return true
+    if (state.wildcard) return true
+    return state.entitlements?.includes(presetKey) ?? false
+}
+
+/** Marca trial vencido: el copy del gate cambia a "tu prueba terminó". */
+export function isTrialExpired(state: LicenseState | undefined): boolean {
+    return !!state && state.plan === 'trial' && state.status === 'expired'
+}
+
+/** Branding opcional para teñir el gate/banner. El host lo pasa desde su
+ * PlatformConfig del SDK (o cualquier fuente); sin él, fallback neutro. */
+export interface LicenseBranding {
+    /** Nombre de la plataforma/tenant, para el encabezado del gate. */
+    name?: string
+    /** URL del logo (se embebe como <img>). */
+    logo?: string
+}

package/src/types.ts

@@ -554,6 +554,13 @@ export interface PaginationMeta {
 // ActionMetadata re-exported from the sdk's action-registry. We mirror the
 // subset needed for the dispatcher so consumers of runtime-react don't have to
 // import the sdk directly for prop typings.
+/** One page of a multi-step (wizard) action. Mirrors the sdk's ActionStep. */
+export interface ActionStep {
+    title: string
+    description?: string
+    fields: ActionFieldDef[]
+}
+
 export interface ActionMetadata {
     key: string
     label: string
@@ -562,6 +569,8 @@ export interface ActionMetadata {
     confirm?: boolean
     confirmMessage?: string
     fields?: ActionFieldDef[]
+    /** Multi-step wizard form; when present the dispatcher renders a wizard. */
+    steps?: ActionStep[]
     requiresState?: string[]
     executable?: boolean
     placement?: 'row' | 'table' | 'create'

package/src/use-i18n-resource-version.ts

@@ -0,0 +1,42 @@
+// A tiny hook that returns a version counter which bumps every time i18next's
+// resource store changes (a bundle is `added`, a language `loaded`, or a key
+// `removed`).
+//
+// Why this exists: addon i18n bundles are fetched and merged asynchronously
+// (addResourceBundle) AFTER the board first paints. react-i18next only
+// re-renders a `useTranslation()` consumer on a store mutation when the host
+// configured `bindI18nStore` to include those events — a host-level setting the
+// SDK cannot assume. Without it a lane whose label is a manifest i18n key
+// (e.g. "integration_github.stage.in_progress") renders the RAW key until an
+// unrelated re-render happens to re-run `t()`.
+//
+// Depending on this version inside a memo/render makes the component re-resolve
+// its labels the moment the bundle lands, regardless of the host's
+// react-i18next binding config. Self-contained and cheap: one listener per
+// mounting component, torn down on unmount.
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+
+export function useI18nResourceVersion(): number {
+  const { i18n } = useTranslation()
+  const [version, setVersion] = useState(0)
+  useEffect(() => {
+    if (!i18n) return
+    const bump = () => setVersion((v) => v + 1)
+    // `added`/`removed` fire on the resource STORE (addResourceBundle);
+    // `loaded` fires when a backend finishes a language; `languageChanged`
+    // covers a runtime locale flip. Listening to all keeps a label correct
+    // through every path a translation can arrive.
+    i18n.store?.on?.('added', bump)
+    i18n.store?.on?.('removed', bump)
+    i18n.on?.('loaded', bump)
+    i18n.on?.('languageChanged', bump)
+    return () => {
+      i18n.store?.off?.('added', bump)
+      i18n.store?.off?.('removed', bump)
+      i18n.off?.('loaded', bump)
+      i18n.off?.('languageChanged', bump)
+    }
+  }, [i18n])
+  return version
+}