@xemahq/ui-kernel 0.1.6 → 0.1.8

package/src/session-kit/approvals/ScopedBody.tsx

@@ -0,0 +1,392 @@
+/**
+ * Scoped approval bodies (HANDOFF §6) — the biome-supplied typed detail
+ * that renders UNDER the generic frame.
+ *
+ * `ScopedBody` is an EXHAUSTIVE switch over `ApprovalScopeKind`. A scope
+ * whose `kind` is outside the closed set fails SAFE to a visible
+ * "unknown scope" placeholder (it surfaces the raw kind) rather than
+ * silently dropping the body — the same fail-fast-but-visible contract as
+ * the unknown-obligation and unknown-chat-widget paths.
+ *
+ * Icon-agnostic: bodies that need a glyph take a `renderIcon` mapping a
+ * stable `ScopeIcon` key to a host icon node.
+ */
+import {
+  ApprovalScopeKind,
+  type ApprovalScope,
+  type DeployScope,
+  type FilesScope,
+  type PaymentScope,
+  type SlackScope,
+  type SqlScope,
+} from './approval-model';
+import { ScopeIcon, type ScopeIconRenderer } from './scope-icons';
+
+import type { ReactElement, ReactNode } from 'react';
+
+export interface ScopedBodyProps {
+  readonly scope: ApprovalScope;
+  readonly renderIcon: ScopeIconRenderer;
+}
+
+export function ScopedBody({
+  scope,
+  renderIcon,
+}: ScopedBodyProps): ReactElement {
+  switch (scope.kind) {
+    case ApprovalScopeKind.Payment:
+      return <PaymentBody s={scope} />;
+    case ApprovalScopeKind.Sql:
+      return <SqlBody s={scope} renderIcon={renderIcon} />;
+    case ApprovalScopeKind.Slack:
+      return <SlackBody s={scope} renderIcon={renderIcon} />;
+    case ApprovalScopeKind.Deploy:
+      return <DeployBody s={scope} renderIcon={renderIcon} />;
+    case ApprovalScopeKind.Files:
+      return <FilesBody s={scope} renderIcon={renderIcon} />;
+    default:
+      return <UnknownScopeBody scope={scope} />;
+  }
+}
+
+/** Visible fallback for a scope kind the host does not (yet) understand. */
+function UnknownScopeBody({
+  scope,
+}: Readonly<{ scope: { readonly kind: string } }>): ReactElement {
+  return (
+    <div
+      style={{
+        padding: '8px 11px',
+        borderRadius: 7,
+        border: '1px dashed hsl(var(--rule-2))',
+        background: 'hsl(var(--muted))',
+        fontSize: 12,
+        color: 'hsl(var(--ink-3))',
+      }}
+    >
+      Unknown approval detail{' '}
+      <span className="mono" style={{ color: 'hsl(var(--ink-2))' }}>
+        {scope.kind}
+      </span>{' '}
+      — this biome ships a scope kind this host build cannot render. Review
+      the request before deciding.
+    </div>
+  );
+}
+
+function KV({
+  k,
+  v,
+  mono,
+  strong,
+}: Readonly<{
+  k: string;
+  v: ReactNode;
+  mono?: boolean;
+  strong?: boolean;
+}>): ReactElement {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        justifyContent: 'space-between',
+        gap: 12,
+        padding: '3px 0',
+      }}
+    >
+      <span
+        style={{ fontSize: 12, color: 'hsl(var(--ink-3))', whiteSpace: 'nowrap' }}
+      >
+        {k}
+      </span>
+      <span
+        className={mono ? 'mono' : undefined}
+        style={{
+          fontSize: mono ? 12 : 12.5,
+          color: 'hsl(var(--ink))',
+          fontWeight: strong ? 600 : 450,
+          textAlign: 'right',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        {v}
+      </span>
+    </div>
+  );
+}
+
+function PaymentBody({ s }: Readonly<{ s: PaymentScope }>): ReactElement {
+  return (
+    <div>
+      <div style={{ marginBottom: 9 }}>
+        <div
+          className="serif"
+          style={{
+            fontSize: 27,
+            fontWeight: 600,
+            color: 'hsl(var(--ink))',
+            lineHeight: 1.05,
+          }}
+        >
+          {s.amount}
+        </div>
+        <div
+          style={{ fontSize: 12.5, color: 'hsl(var(--ink-3))', marginTop: 2 }}
+        >
+          to {s.payee}
+        </div>
+      </div>
+      <div style={{ borderTop: '1px solid hsl(var(--rule))', paddingTop: 4 }}>
+        <KV k="Method" v={s.method} />
+        <KV k="Account" v={s.account} mono />
+        {s.memo && <KV k="Memo" v={s.memo} />}
+      </div>
+    </div>
+  );
+}
+
+function SqlBody({
+  s,
+  renderIcon,
+}: Readonly<{ s: SqlScope; renderIcon: ScopeIconRenderer }>): ReactElement {
+  return (
+    <div>
+      <div
+        style={{ display: 'flex', gap: 8, marginBottom: 7, flexWrap: 'wrap' }}
+      >
+        <Tag icon={renderIcon(ScopeIcon.Database, 12)} t={s.dialect} />
+        <Tag icon={renderIcon(ScopeIcon.Layers, 12)} t={s.table} />
+        <Tag
+          icon={renderIcon(ScopeIcon.Alert, 12)}
+          t={`${s.rowsAffected} rows`}
+          warn
+        />
+      </div>
+      <pre
+        className="mono"
+        style={{
+          margin: 0,
+          padding: '10px 12px',
+          background: 'hsl(var(--ink) / 0.04)',
+          border: '1px solid hsl(var(--rule))',
+          borderRadius: 8,
+          fontSize: 12,
+          lineHeight: 1.6,
+          color: 'hsl(var(--ink))',
+          overflowX: 'auto',
+          whiteSpace: 'pre',
+        }}
+      >
+        {s.query}
+      </pre>
+    </div>
+  );
+}
+
+function SlackBody({
+  s,
+  renderIcon,
+}: Readonly<{ s: SlackScope; renderIcon: ScopeIconRenderer }>): ReactElement {
+  return (
+    <div>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          marginBottom: 7,
+          fontSize: 12.5,
+        }}
+      >
+        <span style={{ color: 'hsl(var(--ink-3))', display: 'inline-flex' }}>
+          {renderIcon(ScopeIcon.Send, 13)}
+        </span>
+        <span
+          className="mono"
+          style={{ color: 'hsl(var(--ink))', fontWeight: 600 }}
+        >
+          {s.channel}
+        </span>
+        <span style={{ color: 'hsl(var(--ink-4))' }}>
+          · {s.workspace} · as {s.as}
+        </span>
+      </div>
+      <div
+        style={{
+          padding: '10px 12px',
+          background: 'hsl(var(--paper-elev))',
+          border: '1px solid hsl(var(--rule))',
+          borderRadius: 8,
+          fontSize: 13,
+          lineHeight: 1.55,
+          color: 'hsl(var(--ink-2))',
+          whiteSpace: 'pre-wrap',
+        }}
+      >
+        {s.message}
+      </div>
+    </div>
+  );
+}
+
+function DeployBody({
+  s,
+  renderIcon,
+}: Readonly<{ s: DeployScope; renderIcon: ScopeIconRenderer }>): ReactElement {
+  return (
+    <div>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          marginBottom: 8,
+        }}
+      >
+        <span
+          className="mono serif"
+          style={{ fontSize: 18, fontWeight: 600, color: 'hsl(var(--ink))' }}
+        >
+          {s.version}
+        </span>
+        <span style={{ color: 'hsl(var(--ink-4))', display: 'inline-flex' }}>
+          {renderIcon(ScopeIcon.ArrowRight, 14)}
+        </span>
+        <Tag icon={renderIcon(ScopeIcon.Globe, 12)} t={s.cluster} warn />
+      </div>
+      <div style={{ display: 'flex', gap: 14, marginBottom: 8 }}>
+        <Stat2 n={s.services} l="services" />
+        <Stat2 n={s.migrations} l="migrations" warn />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+        {s.changelog.map((c) => (
+          <div
+            key={c}
+            style={{
+              display: 'flex',
+              gap: 8,
+              fontSize: 12,
+              color: 'hsl(var(--ink-2))',
+            }}
+          >
+            <span
+              style={{
+                marginTop: 7,
+                width: 3,
+                height: 3,
+                borderRadius: '50%',
+                background: 'hsl(var(--ink-4))',
+                flexShrink: 0,
+              }}
+            />
+            <span className="mono" style={{ fontSize: 11.5 }}>
+              {c}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function FilesBody({
+  s,
+  renderIcon,
+}: Readonly<{ s: FilesScope; renderIcon: ScopeIconRenderer }>): ReactElement {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 5 }}>
+      {s.files.map((f) => (
+        <div
+          key={f.path}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 9,
+            padding: '5px 9px',
+            background: 'hsl(var(--paper-elev))',
+            border: '1px solid hsl(var(--rule))',
+            borderRadius: 7,
+          }}
+        >
+          <span style={{ color: 'hsl(var(--warning))', display: 'inline-flex' }}>
+            {renderIcon(ScopeIcon.FileEdit, 13)}
+          </span>
+          <span
+            className="mono"
+            style={{
+              fontSize: 12,
+              color: 'hsl(var(--ink))',
+              flex: 1,
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {f.path}
+          </span>
+          <span
+            className="mono"
+            style={{ fontSize: 11, color: 'hsl(var(--success))' }}
+          >
+            +{f.add}
+          </span>
+          <span
+            className="mono"
+            style={{ fontSize: 11, color: 'hsl(var(--danger))' }}
+          >
+            −{f.del}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function Tag({
+  icon,
+  t,
+  warn,
+}: Readonly<{ icon: ReactNode; t: string; warn?: boolean }>): ReactElement {
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 5,
+        padding: '2px 8px',
+        borderRadius: 6,
+        fontSize: 11.5,
+        background: warn ? 'hsl(var(--warning) / 0.1)' : 'hsl(var(--muted))',
+        border: `1px solid ${
+          warn ? 'hsl(var(--warning) / 0.3)' : 'hsl(var(--rule))'
+        }`,
+        color: warn ? 'hsl(var(--warning))' : 'hsl(var(--ink-2))',
+      }}
+    >
+      {icon}
+      {t}
+    </span>
+  );
+}
+
+function Stat2({
+  n,
+  l,
+  warn,
+}: Readonly<{ n: number; l: string; warn?: boolean }>): ReactElement {
+  return (
+    <span style={{ display: 'inline-flex', alignItems: 'baseline', gap: 5 }}>
+      <span
+        className="serif"
+        style={{
+          fontSize: 18,
+          fontWeight: 600,
+          color: warn ? 'hsl(var(--warning))' : 'hsl(var(--ink))',
+        }}
+      >
+        {n}
+      </span>
+      <span style={{ fontSize: 11.5, color: 'hsl(var(--ink-3))' }}>{l}</span>
+    </span>
+  );
+}

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

@@ -0,0 +1,31 @@
+/**
+ * The icon contract for the approval surfaces. The kit is icon-agnostic
+ * (it never imports an icon set), so the host supplies one bundle that
+ * resolves every glyph the approval frame, scoped bodies, obligation
+ * chips and Center need. Keeping it as a single typed bundle means a
+ * consumer wires icons ONCE and passes it to every approval surface.
+ */
+import type { ObligationIcon } from './obligation-display';
+import type { ScopeIcon } from './scope-icons';
+import type { ReactNode } from 'react';
+
+export interface ApprovalIcons {
+  /** Map a stable obligation-chip glyph key → host icon node. */
+  readonly obligation: (key: ObligationIcon, size: number) => ReactNode;
+  /** Map a stable scoped-body glyph key → host icon node. */
+  readonly scope: (key: ScopeIcon, size: number) => ReactNode;
+  /** Frame: the "approval required" / approve shield. */
+  readonly shield: (size: number) => ReactNode;
+  /** Frame: capability-ref leading bolt. */
+  readonly capability: (size: number) => ReactNode;
+  /** Frame: approver-role person glyph. */
+  readonly user: (size: number) => ReactNode;
+  /** Quorum: multi-approver glyph. */
+  readonly users: (size: number) => ReactNode;
+  /** Resolved state: approved tick. */
+  readonly approved: (size: number) => ReactNode;
+  /** Resolved state: denied cross. */
+  readonly denied: (size: number) => ReactNode;
+  /** Generic small check (action buttons / Center). */
+  readonly check: (size: number) => ReactNode;
+}

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';