@xemahq/ui-kernel 0.1.5 → 0.1.7

package/src/session-kit/approvals/approval-model.ts

@@ -0,0 +1,205 @@
+/**
+ * Approval primitive — generic frame model + scoped-body payloads
+ * (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ *
+ * The approval is the runtime face of a kernel policy decision: a
+ * capability call returns `allow | deny | needs_approval`
+ * (`PolicyDecisionKind`); on `needs_approval` the gateway suspends the
+ * call and renders a TYPED approval. The frame is identical platform-wide
+ * (risk pill + capability ref + obligations + quorum + actions); each
+ * biome supplies a typed `scope` body for rich detail — the same
+ * generic-frame + biome-body pattern as the in-chat widget registry
+ * (HANDOFF §3.2) and the preview-tab kinds (HANDOFF §5).
+ *
+ * This module REUSES the kernel contracts rather than redefining them:
+ *   • `CapabilityRiskTier` (low/medium/high/critical) — risk pill + accent
+ *   • `PolicyObligationKind` (the closed 9-kind taxonomy) — obligation chips
+ *   • `CapabilityRef` (`domain.biome/action@v` mono ref)
+ * It only ADDS the two things the kernel has no opinion on: the closed
+ * `ApprovalScopeKind` set + its discriminated scope-payload union (the
+ * biome-supplied detail), and the binary `ApprovalDecision` the surfaces
+ * emit. Both are presentation contracts, not policy contracts.
+ */
+import type { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
+import type { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
+
+/**
+ * Closed set of biome-supplied scoped-body kinds (HANDOFF §6). This is the
+ * approval analogue of `ChatWidgetKind` — a typed, versioned catalogue of
+ * rich bodies that render UNDER the generic frame. The renderer
+ * (`ScopedBody`) switches on `kind`; an unknown kind fails SAFE to a
+ * visible "unknown scope" rendering rather than a silent drop.
+ *
+ * First-party kinds ship here; a biome registers a custom kind the same
+ * way it registers a chat widget (backend-defined, versioned). Extend the
+ * enum + add a body component + a `union` member in lockstep — never match
+ * on a free-form string.
+ */
+export enum ApprovalScopeKind {
+  Payment = 'payment',
+  Sql = 'sql',
+  Slack = 'slack',
+  Deploy = 'deploy',
+  Files = 'files',
+}
+
+/** Disbursement / payment scope (finance biomes). */
+export interface PaymentScope {
+  readonly kind: ApprovalScopeKind.Payment;
+  /** Pre-formatted display amount (e.g. `$18,400.00`). */
+  readonly amount: string;
+  readonly payee: string;
+  /** Payment rail, e.g. `ACH wire`. */
+  readonly method: string;
+  /** Masked account, e.g. `•••• 7741`. */
+  readonly account: string;
+  readonly memo?: string;
+}
+
+/** Write-query scope (data-warehouse biomes). */
+export interface SqlScope {
+  readonly kind: ApprovalScopeKind.Sql;
+  readonly dialect: string;
+  readonly table: string;
+  /** Pre-formatted affected-row estimate (e.g. `≈ 1,240`). */
+  readonly rowsAffected: string;
+  readonly query: string;
+}
+
+/** Outbound message scope (chat / outreach biomes). */
+export interface SlackScope {
+  readonly kind: ApprovalScopeKind.Slack;
+  readonly channel: string;
+  readonly workspace: string;
+  /** The identity the message is posted as (e.g. `@sales-bot`). */
+  readonly as: string;
+  readonly message: string;
+}
+
+/** Production-deploy scope (release biomes). */
+export interface DeployScope {
+  readonly kind: ApprovalScopeKind.Deploy;
+  readonly version: string;
+  readonly cluster: string;
+  readonly services: number;
+  readonly migrations: number;
+  readonly changelog: readonly string[];
+}
+
+/** A single changed file with line deltas. */
+export interface ApprovalFileChange {
+  readonly path: string;
+  readonly add: number;
+  readonly del: number;
+}
+
+/** Working-tree write scope (software-dev biomes). */
+export interface FilesScope {
+  readonly kind: ApprovalScopeKind.Files;
+  readonly files: readonly ApprovalFileChange[];
+}
+
+/**
+ * Discriminated union of every first-party scope payload. The `kind`
+ * discriminant maps 1:1 onto `ApprovalScopeKind`; `ScopedBody` is an
+ * exhaustive switch over it with a safe fallback for unknown kinds (so a
+ * biome that ships a not-yet-known scope renders a visible placeholder
+ * instead of crashing or silently dropping the body).
+ */
+export type ApprovalScope =
+  | PaymentScope
+  | SqlScope
+  | SlackScope
+  | DeployScope
+  | FilesScope;
+
+/**
+ * A rendered obligation — the `PolicyObligationKind` discriminant plus a
+ * pre-formatted display value the producer derived from the typed kernel
+ * `PolicyObligation` payload (e.g. `max-cost-usd` → `$25,000`,
+ * `max-duration-seconds` → `30s`). The kit deliberately takes a formatted
+ * `value` string rather than the raw typed payload so the chip stays
+ * presentation-only; the host's `obligationDisplay` helper does the
+ * typed→display mapping from the wire `PolicyObligation`.
+ */
+export interface ApprovalObligation {
+  readonly kind: PolicyObligationKind;
+  /** Pre-formatted display value for the chip's trailing mono span. */
+  readonly value?: string;
+}
+
+/**
+ * The generic approval request — the envelope every surface (inline card,
+ * sticky bar, Center row) renders. Field names mirror the kernel/wire
+ * shape so the backend approval envelope (capability ref, riskTier,
+ * obligations[], requireRole, requireApproverCount, approvalsIn, scope)
+ * maps onto it 1:1.
+ */
+export interface ApprovalRequest {
+  /** Stable id of the suspended invocation awaiting approval. */
+  readonly id: string;
+  /** Capability ref (`domain.biome/action@v`) rendered mono in the frame. */
+  readonly capability: string;
+  /** Owning biome id + display name (the scoped body's provenance). */
+  readonly biomeId: string;
+  readonly biomeName: string;
+  /** Serif title + one-line summary (the generic frame's headline). */
+  readonly title: string;
+  readonly summary: string;
+  /** Kernel risk tier — drives the pill + accent + low/critical action set. */
+  readonly riskTier: CapabilityRiskTier;
+  /** Obligations rendered as chips (closed `PolicyObligationKind` taxonomy). */
+  readonly obligations?: readonly ApprovalObligation[];
+  /** Approver role required by the matched `ApprovalRule`, if any. */
+  readonly requireRole?: string;
+  /** Quorum size; `1` (or absent) = single-approver. */
+  readonly requireApproverCount?: number;
+  /** Approvals already collected toward the quorum. */
+  readonly approvalsIn?: number;
+  /** Biome-supplied typed scope body. */
+  readonly scope: ApprovalScope;
+}
+
+/**
+ * Binary surface decision. Closed set — never a free-form string. The
+ * "allow once" vs "approve & remember" distinction is a UI affordance on
+ * top of the same `Approved` decision (the remember flag is carried
+ * separately when the backend supports it); both resolve the suspended
+ * call. The denied/override-rationale path is DEFERRED (HANDOFF §6).
+ */
+export enum ApprovalDecision {
+  Approved = 'approved',
+  Denied = 'denied',
+}
+
+/**
+ * A pending approval as it appears in the cross-portal Approvals Center —
+ * the request plus the portal/session context it was raised in. The
+ * portal fields are first-class so Pillar 4 (Portals) can batch and group
+ * approvals across portals without reshaping this model.
+ */
+export interface ApprovalCenterItem {
+  /** Mirrors `request.id`; kept distinct so a Center may track its own row id. */
+  readonly id: string;
+  readonly request: ApprovalRequest;
+  /** Portal the approval was raised in (Pillar 4 cross-portal context). */
+  readonly portalId?: string;
+  readonly portalName?: string;
+  /** Portal accent token (`var(--p-*)`) for the row glyph; optional. */
+  readonly portalAccentVar?: `var(--${string})`;
+  /** Session the suspended capability belongs to ("Open session"). */
+  readonly sessionId?: string;
+  readonly sessionTitle?: string;
+}
+
+/** True when the tier always demands an explicit Approve (no allow-once). */
+export function isExplicitApprovalTier(tier: CapabilityRiskTier): boolean {
+  // `critical` and `high` are explicit-only (HANDOFF §6: critical always
+  // explicit; high uses the warning accent and skips allow-once-remember).
+  return tier === 'critical' || tier === 'high';
+}
+
+/** True when the request carries a multi-approver quorum. */
+export function isQuorum(req: ApprovalRequest): boolean {
+  return (req.requireApproverCount ?? 1) > 1;
+}

package/src/session-kit/approvals/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@xemahq/ui-kernel/session-kit` approvals — the generic approval
+ * primitive (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ *
+ * Generic frame + scoped bodies + sticky bar + Approvals Center. Models on
+ * the kernel contracts (`CapabilityRiskTier`, `PolicyObligationKind`) and
+ * adds only the presentation contracts the kernel has no opinion on
+ * (`ApprovalScopeKind` + scope union, `ApprovalDecision`). Every component
+ * is icon-agnostic and prop-driven — the host supplies the icon bundle and
+ * the data.
+ */
+export * from './approval-model';
+export * from './obligation-display';
+export * from './scope-icons';
+export * from './risk-accent';
+export * from './approval-icons';
+export * from './ApprovalButton';
+export * from './Obligation';
+export * from './ScopedBody';
+export * from './ApprovalCard';
+export * from './CapabilityApprovalStickyBar';
+export * from './ApprovalsCenter';

package/src/session-kit/approvals/obligation-display.ts

@@ -0,0 +1,100 @@
+/**
+ * Obligation → display metadata map (HANDOFF §6).
+ *
+ * Covers ALL NINE obligation kinds in the kernel closed taxonomy —
+ * `audit`, `redact-secrets`, `require-runner-kind`,
+ * `require-human-approval`, `max-duration-seconds`, `max-cost-usd`,
+ * `restrict-output-classification`, `data-residency`, `egress-allowlist`.
+ *
+ * The map is typed `Record<PolicyObligationKind, …>` so it is EXHAUSTIVE
+ * over the installed kernel enum: adding a new `PolicyObligationKind`
+ * member is a COMPILE ERROR here until it gets a label + icon key. The
+ * published `@xemahq/kernel-contracts` enum now ships all nine members
+ * (incl. `egress-allowlist`), so every kind is keyed directly by its enum
+ * value — no literal-wire fallback is needed.
+ *
+ * The kit is icon-agnostic: this module names a stable `iconKey`
+ * (`ObligationIcon`) and the host translates it into a concrete icon node
+ * via the `Obligation`/`renderIcon` prop. No icon dependency leaks into
+ * the kernel package.
+ */
+import { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
+
+/**
+ * Stable, icon-set-agnostic glyph keys for obligation chips. The host
+ * maps each onto a concrete icon (lucide, etc.); the kit never imports an
+ * icon set. Closed set — one key per obligation family.
+ */
+export enum ObligationIcon {
+  Dollar = 'dollar',
+  ShieldCheck = 'shield-check',
+  Scroll = 'scroll',
+  Eye = 'eye',
+  Clock = 'clock',
+  Layers = 'layers',
+  Globe = 'globe',
+  Lock = 'lock',
+  Network = 'network',
+}
+
+export interface ObligationDisplayMeta {
+  readonly iconKey: ObligationIcon;
+  readonly label: string;
+}
+
+/**
+ * Chip metadata for every member of the kernel `PolicyObligationKind`
+ * enum. Typed as `Record<PolicyObligationKind, …>` so adding a new kernel
+ * enum member is a COMPILE ERROR here until it gets a label + icon key —
+ * the exhaustiveness guarantee.
+ */
+const ENUM_OBLIGATION_DISPLAY: Record<
+  PolicyObligationKind,
+  ObligationDisplayMeta
+> = {
+  [PolicyObligationKind.MaxCostUsd]: {
+    iconKey: ObligationIcon.Dollar,
+    label: 'Spend cap',
+  },
+  [PolicyObligationKind.RequireHumanApproval]: {
+    iconKey: ObligationIcon.ShieldCheck,
+    label: 'Human approval',
+  },
+  [PolicyObligationKind.Audit]: {
+    iconKey: ObligationIcon.Scroll,
+    label: 'Audited',
+  },
+  [PolicyObligationKind.RestrictOutputClassification]: {
+    iconKey: ObligationIcon.Eye,
+    label: 'Output limited',
+  },
+  [PolicyObligationKind.MaxDurationSeconds]: {
+    iconKey: ObligationIcon.Clock,
+    label: 'Time cap',
+  },
+  [PolicyObligationKind.RequireRunnerKind]: {
+    iconKey: ObligationIcon.Layers,
+    label: 'Runner',
+  },
+  [PolicyObligationKind.DataResidency]: {
+    iconKey: ObligationIcon.Globe,
+    label: 'Residency',
+  },
+  [PolicyObligationKind.RedactSecrets]: {
+    iconKey: ObligationIcon.Lock,
+    label: 'Redacted',
+  },
+  [PolicyObligationKind.EgressAllowlist]: {
+    iconKey: ObligationIcon.Network,
+    label: 'Egress',
+  },
+};
+
+/**
+ * The authoritative obligation-kind → chip metadata map, keyed by the
+ * obligation wire-string. Exhaustive over the installed kernel enum via
+ * `ENUM_OBLIGATION_DISPLAY` (compile-checked).
+ */
+export const OBLIGATION_DISPLAY: Record<string, ObligationDisplayMeta> = {
+  ...ENUM_OBLIGATION_DISPLAY,
+};

package/src/session-kit/approvals/risk-accent.ts

@@ -0,0 +1,47 @@
+/**
+ * Risk-tier → colour expressions for the approval frame's accent rail and
+ * the sticky bar (HANDOFF §6). RiskPill owns the PILL styling; this map is
+ * the matching surface accent (foreground / soft background / border) the
+ * frame and bar paint with. Both read the SAME kernel `CapabilityRiskTier`
+ * enum so the pill and the rail can never disagree on a tier's colour.
+ *
+ *   low      → ink / muted   (quiet)
+ *   medium   → --info
+ *   high     → --warning
+ *   critical → --destructive / --danger
+ */
+import { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
+
+export interface RiskAccent {
+  /** Solid accent (rail, icon, critical button). */
+  readonly fg: string;
+  /** Soft tinted background (sticky bar surface). */
+  readonly bg: string;
+  /** Border (sticky bar, critical card outline). */
+  readonly bd: string;
+}
+
+const DANGER = 'var(--destructive, var(--danger))';
+
+export const RISK_ACCENT: Record<CapabilityRiskTier, RiskAccent> = {
+  [CapabilityRiskTier.Low]: {
+    fg: 'hsl(var(--ink-3))',
+    bg: 'hsl(var(--muted))',
+    bd: 'hsl(var(--rule))',
+  },
+  [CapabilityRiskTier.Medium]: {
+    fg: 'hsl(var(--info))',
+    bg: 'hsl(var(--info) / 0.07)',
+    bd: 'hsl(var(--info) / 0.28)',
+  },
+  [CapabilityRiskTier.High]: {
+    fg: 'hsl(var(--warning))',
+    bg: 'hsl(var(--warning) / 0.08)',
+    bd: 'hsl(var(--warning) / 0.3)',
+  },
+  [CapabilityRiskTier.Critical]: {
+    fg: `hsl(${DANGER})`,
+    bg: `hsl(${DANGER} / 0.07)`,
+    bd: `hsl(${DANGER} / 0.32)`,
+  },
+};

package/src/session-kit/approvals/scope-icons.ts

@@ -0,0 +1,19 @@
+/**
+ * Stable, icon-set-agnostic glyph keys used by the scoped approval bodies
+ * (`ScopedBody`). Kept in its own module (not alongside the body
+ * components) so the icon bundle and the bodies can both import it without
+ * a component file also exporting a non-component value.
+ */
+import type { ReactNode } from 'react';
+
+export enum ScopeIcon {
+  Database = 'database',
+  Layers = 'layers',
+  Alert = 'alert',
+  Send = 'send',
+  Globe = 'globe',
+  ArrowRight = 'arrow-right',
+  FileEdit = 'file-edit',
+}
+
+export type ScopeIconRenderer = (key: ScopeIcon, size: number) => ReactNode;