@xemahq/ui-kernel 0.9.0 → 0.9.2

package/src/registry/index.ts

@@ -4,5 +4,6 @@ export * from './lib/biome-slot';
 export * from './lib/biomes-enabled-context';
 export * from './lib/session-selectors';
 export * from './lib/session-context-builder';
+export * from './lib/session-context';
 export * from './lib/session-context-provider';
 export * from './lib/primitives';

package/src/registry/lib/primitives/SessionEventCard.tsx

@@ -125,13 +125,15 @@ export function SessionEventCard({
           <span style={{ color: 'hsl(var(--ink, 228 14% 11%))', wordBreak: 'break-word' }}>
             {title}
           </span>
-          {detail != null && (
+          {detail !== null && detail !== undefined && (
             <span style={{ color: 'hsl(var(--ink-3, 228 6% 40%))', wordBreak: 'break-word' }}>
               {detail}
             </span>
           )}
         </div>
-        {children != null && <div style={{ marginTop: 4 }}>{children}</div>}
+        {children !== null && children !== undefined && (
+          <div style={{ marginTop: 4 }}>{children}</div>
+        )}
       </div>
     </div>
   );

package/src/registry/lib/session-context-provider.tsx

@@ -10,12 +10,11 @@
  * stable, importable hook — `import { useCurrentSessionContext } from
  * '@xemahq/ui-kernel/registry'`.
  */
-import { type ReactNode, type ReactElement, createContext, useContext } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 
-import type { SessionContext } from '../../index';
+import { SessionContextValue } from './session-context';
 
-const Ctx = createContext<SessionContext | null>(null);
-Ctx.displayName = 'SessionContext';
+import type { SessionContext } from '../../index';
 
 export interface SessionContextProviderProps {
   readonly value: SessionContext;
@@ -26,25 +25,9 @@ export function SessionContextProvider({
   value,
   children,
 }: SessionContextProviderProps): ReactElement {
-  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
-}
-
-export function useCurrentSessionContext(): SessionContext {
-  const ctx = useContext(Ctx);
-  if (!ctx) {
-    throw new Error(
-      '[biome-registry-web] useCurrentSessionContext() called outside <SessionContextProvider>. ' +
-        'The host shell must wrap session UI with the provider before any biome reads it.',
-    );
-  }
-  return ctx;
-}
-
-/**
- * Non-throwing variant for components that may render outside a session
- * context (e.g. shared primitives reused on the design-system-builder page).
- * Returns `null` instead of throwing.
- */
-export function useOptionalSessionContext(): SessionContext | null {
-  return useContext(Ctx);
+  return (
+    <SessionContextValue.Provider value={value}>
+      {children}
+    </SessionContextValue.Provider>
+  );
 }

package/src/registry/lib/session-context.ts

@@ -0,0 +1,21 @@
+import { createContext, useContext } from 'react';
+
+import type { SessionContext } from '../../index';
+
+export const SessionContextValue = createContext<SessionContext | null>(null);
+SessionContextValue.displayName = 'SessionContext';
+
+export function useCurrentSessionContext(): SessionContext {
+  const ctx = useContext(SessionContextValue);
+  if (!ctx) {
+    throw new Error(
+      '[biome-registry-web] useCurrentSessionContext() called outside <SessionContextProvider>. ' +
+        'The host shell must wrap session UI with the provider before any biome reads it.',
+    );
+  }
+  return ctx;
+}
+
+export function useOptionalSessionContext(): SessionContext | null {
+  return useContext(SessionContextValue);
+}

package/src/registry/lib/session-selectors.ts

@@ -52,7 +52,9 @@ function applies<T extends { readonly appliesTo?: (...args: never[]) => boolean
   args: Parameters<PredicateOf<T>>,
 ): boolean {
   const predicate = item.appliesTo as PredicateOf<T> | undefined;
-  return predicate == null ? true : predicate(...args);
+  return predicate === null || predicate === undefined
+    ? true
+    : predicate(...args);
 }
 
 // ── Slash commands ────────────────────────────────────────────────────

package/src/ui/branding/app-branding-context.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+export interface AppBrandingContextValue {
+  readonly displayName: string;
+  readonly logoUrl?: string;
+  readonly primaryColor?: string;
+}
+
+export const AppBrandingContext =
+  React.createContext<AppBrandingContextValue | null>(null);
+
+export function useAppBranding(): AppBrandingContextValue {
+  const ctx = React.useContext(AppBrandingContext);
+  if (ctx === null) {
+    throw new Error(
+      'useAppBranding must be used within an <AppBrandingProvider>.',
+    );
+  }
+  return ctx;
+}

package/src/ui/branding/app-branding-provider.tsx

@@ -23,6 +23,10 @@ import * as React from 'react';
 import type { BrandingConfig } from '@xemahq/kernel-contracts/app-platform';
 
 import { cn } from '../cn';
+import {
+  AppBrandingContext,
+  type AppBrandingContextValue,
+} from './app-branding-context';
 
 import {
   sanitizeCssCustomPropertyName,
@@ -33,32 +37,6 @@ import {
 /** CSS custom property carrying the app's resolved primary brand color. */
 export const APP_PRIMARY_COLOR_VAR = '--app-primary-color';
 
-/** Values a branded header needs — sanitized, safe to render. */
-export interface AppBrandingContextValue {
-  readonly displayName: string;
-  readonly logoUrl?: string;
-  readonly primaryColor?: string;
-}
-
-const AppBrandingContext = React.createContext<AppBrandingContextValue | null>(
-  null,
-);
-
-/**
- * Resolved branding for the nearest enclosing {@link AppBrandingProvider}.
- * Throws when used outside one — a header that assumes branding must not
- * silently render an unbranded surface.
- */
-export function useAppBranding(): AppBrandingContextValue {
-  const ctx = React.useContext(AppBrandingContext);
-  if (ctx === null) {
-    throw new Error(
-      'useAppBranding must be used within an <AppBrandingProvider>.',
-    );
-  }
-  return ctx;
-}
-
 export interface AppBrandingProviderProps {
   /** The app's base branding (from the App definition / release). */
   readonly branding: BrandingConfig;
@@ -137,7 +115,7 @@ export function AppBrandingProvider({
         className={cn(className)}
         // Custom properties are not part of `React.CSSProperties`; the cast is
         // the standard way to set `--*` vars inline.
-        style={cssVars as React.CSSProperties}
+        style={cssVars}
       >
         {children}
       </div>

package/src/ui/capture/field-spec-to-zod.ts

@@ -43,10 +43,30 @@ function scalarSchema(field: CaptureFieldSpec): z.ZodTypeAny {
   }
 }
 
+/** True when `value` parses as JSON. Total — never throws. */
+export function isParsableJson(value: string): boolean {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
   let base: z.ZodTypeAny;
   if (field.type === CaptureFieldType.Object) {
     base = objectSchema(field.fields ?? []);
+  } else if (field.type === CaptureFieldType.Json) {
+    // A JSON blob is carried as TEXT and validated as parseable. `''` passes
+    // the shape check so an optional blank field stays valid; requiredness is
+    // enforced by the `.min(1)` below, not by the parse rule.
+    const text = field.required
+      ? z.string().min(1, { message: `${field.label} is required` })
+      : z.string();
+    base = text.refine((v) => v === '' || isParsableJson(v), {
+      message: `${field.label} must be valid JSON`,
+    });
   } else if (field.type === CaptureFieldType.List) {
     let arr = z.array(objectSchema(field.fields ?? []));
     if (typeof field.min === 'number') arr = arr.min(field.min, { message: `${field.label} needs at least ${field.min} item(s)` });
@@ -58,6 +78,8 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
       field.required &&
       (field.type === CaptureFieldType.String ||
         field.type === CaptureFieldType.Text ||
+        field.type === CaptureFieldType.Email ||
+        field.type === CaptureFieldType.Url ||
         field.type === CaptureFieldType.User ||
         field.type === CaptureFieldType.Reference ||
         field.type === CaptureFieldType.Datetime ||

package/src/ui/capture/field-spec-validate.ts

@@ -0,0 +1,147 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Total runtime validator for a `CaptureFieldSpec[]` arriving from the wire
+//
+// `fieldSpecToZod` validates the VALUES a form produces. This validates the
+// SCHEMA itself, for the case where the field list is not authored in TypeScript
+// but carried in an envelope (a Vista `form` surface payload, a biome
+// contribution, an agent-authored capture step).
+//
+// Contract: TOTAL and NEVER throws — it returns the narrowed specs or `null`,
+// exactly like the Vista payload validators, so a malformed schema degrades to
+// a visible typed fallback instead of a half-rendered form.
+// ═══════════════════════════════════════════════════════════════════════════
+import { CaptureFieldTransform, CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+
+const FIELD_TYPES: ReadonlySet<string> = new Set(Object.values(CaptureFieldType));
+const TRANSFORMS: ReadonlySet<string> = new Set(Object.values(CaptureFieldTransform));
+
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+function asRecord(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+/** `undefined` passes through; a present non-string is a rejection (`null`). */
+function optionalString(value: unknown): string | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'string' ? value : null;
+}
+
+/** `undefined` passes through; a present non-boolean is a rejection (`null`). */
+function optionalBoolean(value: unknown): boolean | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'boolean' ? value : null;
+}
+
+/** `undefined` passes through; a present non-number is a rejection (`null`). */
+function optionalNumber(value: unknown): number | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Narrow ONE field spec. Returns `null` for anything malformed. */
+export function validateCaptureField(raw: unknown): CaptureFieldSpec | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.key !== 'string' || record.key.length === 0) return null;
+  if (typeof record.label !== 'string' || record.label.length === 0) return null;
+  if (typeof record.type !== 'string' || !FIELD_TYPES.has(record.type)) return null;
+
+  const required = optionalBoolean(record.required);
+  if (required === null) return null;
+  const isSecret = optionalBoolean(record.isSecret);
+  if (isSecret === null) return null;
+  const description = optionalString(record.description);
+  if (description === null) return null;
+  const placeholder = optionalString(record.placeholder);
+  if (placeholder === null) return null;
+  const section = optionalString(record.section);
+  if (section === null) return null;
+  const referenceEntity = optionalString(record.referenceEntity);
+  if (referenceEntity === null) return null;
+  const accept = optionalString(record.accept);
+  if (accept === null) return null;
+  const min = optionalNumber(record.min);
+  if (min === null) return null;
+  const max = optionalNumber(record.max);
+  if (max === null) return null;
+
+  let transform: CaptureFieldTransform | undefined;
+  if (record.transform !== undefined) {
+    if (typeof record.transform !== 'string' || !TRANSFORMS.has(record.transform)) return null;
+    transform = record.transform as CaptureFieldTransform;
+  }
+
+  let enumValues: readonly string[] | undefined;
+  if (record.enumValues !== undefined) {
+    if (!Array.isArray(record.enumValues)) return null;
+    if (!record.enumValues.every((v) => typeof v === 'string')) return null;
+    enumValues = record.enumValues;
+  }
+
+  let capture: 'user' | 'environment' | undefined;
+  if (record.capture !== undefined) {
+    if (record.capture !== 'user' && record.capture !== 'environment') return null;
+    capture = record.capture;
+  }
+
+  let fields: readonly CaptureFieldSpec[] | undefined;
+  if (record.fields !== undefined) {
+    const nested = validateCaptureFields(record.fields);
+    if (nested === null) return null;
+    fields = nested;
+  }
+
+  const spec: {
+    key: string;
+    label: string;
+    type: CaptureFieldType;
+    required?: boolean;
+    isSecret?: boolean;
+    transform?: CaptureFieldTransform;
+    description?: string;
+    placeholder?: string;
+    section?: string;
+    referenceEntity?: string;
+    accept?: string;
+    capture?: 'user' | 'environment';
+    enumValues?: readonly string[];
+    fields?: readonly CaptureFieldSpec[];
+    min?: number;
+    max?: number;
+  } = { key: record.key, label: record.label, type: record.type as CaptureFieldType };
+
+  if (required !== undefined) spec.required = required;
+  if (isSecret !== undefined) spec.isSecret = isSecret;
+  if (transform !== undefined) spec.transform = transform;
+  if (description !== undefined) spec.description = description;
+  if (placeholder !== undefined) spec.placeholder = placeholder;
+  if (section !== undefined) spec.section = section;
+  if (referenceEntity !== undefined) spec.referenceEntity = referenceEntity;
+  if (accept !== undefined) spec.accept = accept;
+  if (capture !== undefined) spec.capture = capture;
+  if (enumValues !== undefined) spec.enumValues = enumValues;
+  if (fields !== undefined) spec.fields = fields;
+  if (min !== undefined) spec.min = min;
+  if (max !== undefined) spec.max = max;
+
+  return spec;
+}
+
+/**
+ * Narrow a whole field list. An EMPTY array is valid and narrows to `[]` — an
+ * empty schema is a real, meaningful state (the server is the authority on
+ * whether a form with no fields may be submitted), not a validation failure.
+ */
+export function validateCaptureFields(raw: unknown): readonly CaptureFieldSpec[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: CaptureFieldSpec[] = [];
+  for (const entry of raw) {
+    const spec = validateCaptureField(entry);
+    if (spec === null) return null;
+    out.push(spec);
+  }
+  return out;
+}

package/src/ui/capture/field-spec.ts

@@ -50,6 +50,53 @@ export enum CaptureFieldType {
   Image = 'image',
   File = 'file',
   Audio = 'audio',
+  // ── Scalar text refinements (absorbed from the connector credential form) ──
+  // These change only the NATIVE INPUT TYPE (keyboard + browser affordances);
+  // the value is a plain string. `Json` additionally renders as a mono textarea
+  // and is validated as parseable JSON.
+  Email = 'email',
+  Url = 'url',
+  Json = 'json',
+}
+
+/**
+ * Normalization applied to a captured STRING value at the input boundary.
+ *
+ * Value-identical in meaning to the connector `CredentialFieldTransform`
+ * (`NONE`/`UPPERCASE`/`LOWERCASE`/`TRIM`) but named in this kit's lowercase
+ * vocabulary, because the capture kit is domain-agnostic and must not import a
+ * connector contract. The connector→capture adapter lives at the consuming
+ * seam, not here.
+ *
+ * This is the ONLY normalization the kit performs. There is deliberately no
+ * blanket trim on submit: an undeclared transform would silently override a
+ * field that declared {@link CaptureFieldTransform.None}.
+ */
+export enum CaptureFieldTransform {
+  None = 'none',
+  Uppercase = 'uppercase',
+  Lowercase = 'lowercase',
+  Trim = 'trim',
+}
+
+/** Apply a declared transform to a string value. Total; absent = unchanged. */
+export function applyCaptureTransform(
+  value: string,
+  transform: CaptureFieldTransform | `${CaptureFieldTransform}` | undefined,
+): string {
+  switch (transform) {
+    case CaptureFieldTransform.Uppercase:
+      return value.toUpperCase();
+    case CaptureFieldTransform.Lowercase:
+      return value.toLowerCase();
+    case CaptureFieldTransform.Trim:
+      return value.trim();
+    case CaptureFieldTransform.None:
+    case undefined:
+      return value;
+    default:
+      return value;
+  }
 }
 
 /**
@@ -96,6 +143,21 @@ export interface CaptureFieldSpec {
    * explicit). See {@link groupFieldsBySection}.
    */
   readonly section?: string;
+  /**
+   * DECLARED write-only secrecy. When true the input is masked, never
+   * pre-filled from a read, and never echoed back by any read path.
+   *
+   * Secrecy is DECLARED, never inferred from {@link type}: a plain-`string`
+   * field can be a secret and a `password`-shaped field can be public. The
+   * renderer reads this flag and nothing else — do not re-introduce a
+   * `type === password` inference.
+   */
+  readonly isSecret?: boolean;
+  /**
+   * Declared normalization applied to the string value at the input boundary.
+   * Absent = {@link CaptureFieldTransform.None}.
+   */
+  readonly transform?: CaptureFieldTransform | `${CaptureFieldTransform}`;
 }
 
 /** A titled group of fields — the explicit sectioned schema shape. */

package/src/ui/capture/index.ts

@@ -11,6 +11,8 @@
 // ── field-spec model (aligned superset of app-forge's AppFieldType) ──
 export {
   CaptureFieldType,
+  CaptureFieldTransform,
+  applyCaptureTransform,
   isSectioned,
   toFieldList,
   toSections,
@@ -21,8 +23,14 @@ export {
   type CaptureValues,
 } from './field-spec';
 
+// ── total runtime validator for a wire-carried schema ──
+export { validateCaptureField, validateCaptureFields } from './field-spec-validate';
+
 // ── schema → zod adapter ──
-export { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+export { fieldSpecToZod, isEmptyValue, isParsableJson } from './field-spec-to-zod';
+
+// ── values → wire payload ──
+export { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
 
 // ── validation + "missing info" ──
 export { useSchemaValidation, type SchemaValidationResult } from './use-schema-validation';