@xemahq/ui-kernel 0.11.1 → 0.11.2

package/src/lib/biome-host/use-mutation-with-error-toast.ts

@@ -1,90 +0,0 @@
-/**
- * Unified mutation hook with automatic success/error toast notifications.
- *
- * Rebuilt on the {@link HostBridge}: toasts route through `bridge.toast` and
- * error copy is decoded by the bridge's error decoder (falling back to the
- * kernel {@link getUserFacingErrorMessage}). Biome code stays decoupled from
- * any particular toast library or error-envelope shape.
- *
- * Requires `@tanstack/react-query` (an optional peer of the kernel) and a
- * `QueryClientProvider` mounted above.
- *
- * Usage:
- *   const mutation = useMutationWithErrorToast(
- *     { mutationFn: (vars) => apiFn(vars), onSuccess: () => invalidate() },
- *     { successTitle: 'Saved', errorTitle: 'Save failed' },
- *   );
- */
-import { useMutation, type UseMutationOptions } from '@tanstack/react-query';
-
-import { getUserFacingErrorMessage } from './errors';
-import { useHostBridge } from './host-bridge';
-
-export type MutationCoreOptions<
-  TData = unknown,
-  TError = Error,
-  TVariables = unknown,
-  TContext = unknown,
-> = Omit<UseMutationOptions<TData, TError, TVariables, TContext>, 'onError'>;
-
-export interface MutationToastOptions<TError = Error> {
-  /** Title for the success toast. Omit or pass null to suppress the success toast. */
-  successTitle?: string | null;
-  /** Optional description for the success toast. */
-  successDescription?: string;
-  /** Title for the error toast. Omit to suppress the error toast. */
-  errorTitle?: string;
-  /**
-   * Custom error side-effect. Called before the auto-error-toast.
-   * Return `true` to suppress the automatic toast.
-   */
-  onError?: (error: TError) => boolean | void;
-}
-
-export function useMutationWithErrorToast<
-  TData = unknown,
-  TError extends Error = Error,
-  TVariables = unknown,
-  TContext = unknown,
->(
-  mutationOptions: MutationCoreOptions<TData, TError, TVariables, TContext>,
-  toastOptions?: MutationToastOptions<TError>,
-) {
-  const bridge = useHostBridge();
-  const decodeError =
-    bridge.errors?.getUserFacingErrorMessage ?? getUserFacingErrorMessage;
-
-  const { onSuccess: userOnSuccess, ...coreMutationOptions } = mutationOptions;
-  const {
-    successTitle,
-    successDescription,
-    errorTitle,
-    onError: customOnError,
-  } = toastOptions ?? {};
-
-  return useMutation({
-    ...coreMutationOptions,
-    onSuccess: (data, variables, context, mutation) => {
-      if (successTitle !== null && successTitle !== undefined) {
-        bridge.toast.success(successTitle, successDescription);
-      }
-      if (userOnSuccess) {
-        userOnSuccess(data, variables, context, mutation);
-      }
-    },
-    onError: (error: TError) => {
-      if (errorTitle !== undefined) {
-        const shouldSuppressToast = customOnError?.(error) === true;
-        if (!shouldSuppressToast) {
-          const errorMessage = decodeError(
-            error,
-            'Unable to complete this action.',
-          );
-          bridge.toast.error(errorTitle, errorMessage);
-        }
-      } else {
-        customOnError?.(error);
-      }
-    },
-  });
-}

package/src/lib/biome-host/use-page-state.ts

@@ -1,248 +0,0 @@
-/**
- * usePageState — page-level UI state synced to the URL query string.
- *
- * State survives refresh, back/forward, and is shareable via URL. Rebuilt on
- * the {@link HostBridge} navigation port (`useSearchParams` to read,
- * `useLocation` for the current path, `push`/`replace` to write) so biome code
- * never imports a router primitive (`next/navigation`, `react-router-dom`)
- * directly — the host owns history semantics.
- *
- * Usage:
- *   const [activeTab, setActiveTab] = usePageState<string>('tab', 'runs');
- *   const [selectedId, setSelectedId] = usePageState<string | null>('run', null);
- */
-
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-import { useHostBridge } from './host-bridge';
-
-/** Default debounce for the URL mirror of a free-text input, in ms. */
-const INPUT_URL_MIRROR_DEBOUNCE_MS = 300;
-
-function buildPath(pathname: string, params: URLSearchParams): string {
-  const queryString = params.toString();
-  return queryString ? `${pathname}?${queryString}` : pathname;
-}
-
-function serializeValue<T>(value: T): string {
-  if (typeof value === 'string') {
-    return value;
-  }
-  if (typeof value === 'number' || typeof value === 'boolean') {
-    return String(value);
-  }
-  return JSON.stringify(value);
-}
-
-function tryParseJson(rawValue: string): unknown {
-  try {
-    return JSON.parse(rawValue);
-  } catch {
-    return undefined;
-  }
-}
-
-function deserializePrimitive<T>(
-  rawValue: string,
-  defaultValue: T,
-): T | undefined {
-  if (typeof defaultValue === 'string') {
-    return rawValue as T;
-  }
-
-  if (typeof defaultValue === 'number') {
-    const numericValue = Number(rawValue);
-    return (Number.isNaN(numericValue) ? defaultValue : numericValue) as T;
-  }
-
-  if (typeof defaultValue === 'boolean') {
-    if (rawValue === 'true') {
-      return true as T;
-    }
-    if (rawValue === 'false') {
-      return false as T;
-    }
-    return defaultValue;
-  }
-
-  return undefined;
-}
-
-function deserializeValue<T>(rawValue: string | null, defaultValue: T): T {
-  if (rawValue === null) {
-    return defaultValue;
-  }
-
-  const primitive = deserializePrimitive(rawValue, defaultValue);
-  if (primitive !== undefined) {
-    return primitive;
-  }
-
-  // Default is null/undefined or a complex type (array/object). The value was
-  // written via JSON.stringify in serializeValue, so attempt to parse it back.
-  // If parsing yields a structured value (array/object/null), return it;
-  // otherwise fall back to the raw string (covers `T = string | null`).
-  const parsedValue = tryParseJson(rawValue);
-  if (parsedValue !== undefined && typeof parsedValue === 'object') {
-    return parsedValue as T;
-  }
-
-  if (defaultValue === null || defaultValue === undefined) {
-    return rawValue as T;
-  }
-
-  if (parsedValue !== undefined) {
-    return parsedValue as T;
-  }
-
-  if (Array.isArray(defaultValue)) {
-    return rawValue ? ([rawValue] as unknown as T) : defaultValue;
-  }
-
-  return defaultValue;
-}
-
-export function usePageState<T>(
-  stateKey: string,
-  defaultValue: T,
-): [T, (value: T) => void] {
-  const { navigation } = useHostBridge();
-  const searchParams = navigation.useSearchParams();
-  const { pathname } = navigation.useLocation();
-
-  const rawValue = searchParams.get(stateKey);
-  const value = deserializeValue(rawValue, defaultValue);
-
-  const setValue = useCallback(
-    (newValue: T) => {
-      const next = new URLSearchParams(searchParams);
-      if (
-        newValue === null ||
-        newValue === undefined ||
-        serializeValue(newValue) === serializeValue(defaultValue)
-      ) {
-        next.delete(stateKey);
-      } else {
-        next.set(stateKey, serializeValue(newValue));
-      }
-      navigation.push(buildPath(pathname, next));
-    },
-    [defaultValue, stateKey, searchParams, pathname, navigation],
-  );
-
-  return [value, setValue];
-}
-
-/**
- * usePageInputState — like {@link usePageState}, but tuned for FREE-TEXT
- * `<Input>` values that are mirrored to the URL on every keystroke.
- *
- * The returned value lives in LOCAL React state, so typing is instant. The URL
- * is mirrored — debounced — via the host's `replace` (an in-place history entry
- * update), so the value stays shareable / refresh-survivable WITHOUT pushing a
- * new history entry per keystroke.
- *
- * The local value re-syncs whenever the underlying search param changes from
- * the outside (a real navigation, a "Clear" button writing the param, or
- * back/forward), so external resets still flow through.
- *
- * Use this ONLY for free-text inputs. Tabs, selects, and row selection are real
- * navigations — keep them on {@link usePageState}.
- *
- * Usage:
- *   const [filter, setFilter] = usePageInputState('runFilter', '');
- *   <Input value={filter} onChange={(e) => setFilter(e.target.value)} />
- */
-export function usePageInputState(
-  stateKey: string,
-  defaultValue: string,
-  debounceMs: number = INPUT_URL_MIRROR_DEBOUNCE_MS,
-): [string, (value: string) => void] {
-  const { navigation } = useHostBridge();
-  const searchParams = navigation.useSearchParams();
-  const { pathname } = navigation.useLocation();
-
-  const urlValue = searchParams.get(stateKey) ?? defaultValue;
-
-  const [localValue, setLocalValue] = useState(urlValue);
-
-  // Resync local state when the URL param changes from the outside (real
-  // navigation, Clear button, back/forward). We compare against the value we
-  // last mirrored so our own debounced writes don't bounce back and clobber
-  // freshly-typed characters.
-  const lastMirroredRef = useRef(urlValue);
-  useEffect(() => {
-    if (urlValue !== lastMirroredRef.current) {
-      lastMirroredRef.current = urlValue;
-      setLocalValue(urlValue);
-    }
-  }, [urlValue]);
-
-  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  useEffect(
-    () => () => {
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-      }
-    },
-    [],
-  );
-
-  const setValue = useCallback(
-    (newValue: string) => {
-      // Instant: drive the input from local state synchronously.
-      setLocalValue(newValue);
-
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      debounceTimerRef.current = setTimeout(() => {
-        debounceTimerRef.current = null;
-        lastMirroredRef.current =
-          newValue === defaultValue ? defaultValue : newValue;
-        const next = new URLSearchParams(searchParams);
-        if (newValue === defaultValue || newValue.length === 0) {
-          next.delete(stateKey);
-        } else {
-          next.set(stateKey, newValue);
-        }
-        navigation.replace(buildPath(pathname, next));
-      }, debounceMs);
-    },
-    [debounceMs, defaultValue, stateKey, searchParams, pathname, navigation],
-  );
-
-  return [localValue, setValue];
-}
-
-/**
- * Batch-update multiple page-state keys in a single navigation.
- *
- * Pass `null` for a value to delete the key (reset to default).
- *
- * Usage:
- *   const batch = useBatchPageState();
- *   batch({ selectedId: 'abc', mainTab: null, contextTab: null });
- */
-export function useBatchPageState(): (
-  updates: Record<string, string | null>,
-) => void {
-  const { navigation } = useHostBridge();
-  const searchParams = navigation.useSearchParams();
-  const { pathname } = navigation.useLocation();
-
-  return useCallback(
-    (updates: Record<string, string | null>) => {
-      const next = new URLSearchParams(searchParams);
-      for (const [key, value] of Object.entries(updates)) {
-        if (value === null) {
-          next.delete(key);
-        } else {
-          next.set(key, value);
-        }
-      }
-      navigation.push(buildPath(pathname, next));
-    },
-    [searchParams, pathname, navigation],
-  );
-}

package/src/lib/capabilities/capability-context.ts

@@ -1,25 +0,0 @@
-import { createContext, useContext } from 'react';
-
-import type { MeCapabilitiesSnapshot } from './types';
-
-export interface CapabilityContextValue {
-  readonly snapshot: MeCapabilitiesSnapshot | undefined;
-  readonly isLoading: boolean;
-  readonly error: unknown;
-}
-
-export const CapabilityContext =
-  createContext<CapabilityContextValue | null>(null);
-CapabilityContext.displayName = 'CapabilityContext';
-
-export function useCapabilityContext(): CapabilityContextValue {
-  const ctx = useContext(CapabilityContext);
-  if (!ctx) {
-    throw new Error(
-      '[xema-ui-kernel] useCapability()/useCapabilities() called outside ' +
-        '<CapabilityProvider>. The host (or biome shell) must mount the ' +
-        'capability provider above any capability-gated subtree.',
-    );
-  }
-  return ctx;
-}

package/src/lib/capabilities/capability-provider.tsx

@@ -1,73 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-
-import {
-  CapabilityContext,
-  type CapabilityContextValue,
-} from './capability-context';
-import { useHostBridge } from '../biome-host/host-bridge';
-
-import type { CapabilityPort, MeCapabilitiesSnapshot } from './types';
-import type { ReactNode } from 'react';
-
-/**
- * Stable query-key root for the capability snapshot. Folded with the active
- * org so each org caches independently and a re-fetch fires when the org
- * changes — same tenant-isolation discipline as `useScopedQuery`.
- */
-const CAPABILITIES_QUERY_ROOT = ['xema', 'capabilities', 'me'] as const;
-
-export interface CapabilityProviderProps {
-  readonly children: ReactNode;
-  /**
-   * Override the host-provided port. Defaults to `bridge.capabilities`. Exists
-   * for tests and for hosts that compose the provider outside a bridge subtree;
-   * production wiring reads it OFF the bridge so biomes need no extra prop.
-   */
-  readonly port?: CapabilityPort;
-  /**
-   * Override the active org. Defaults to `null` (the host's
-   * currently-selected org). When provided, the port is asked for that org and
-   * the cache key includes it.
-   */
-  readonly orgId?: string | null;
-}
-
-/**
- * Fetches the caller's server-authoritative capability set once per active org
- * and exposes it (plus loading/error) to descendants via React context.
- *
- * Wiring: the {@link CapabilityPort} is read OFF `HostBridge.capabilities`
- * (not prop-drilled) — the same decoupling the rest of the kernel uses to
- * reach the host. The active org is read from the bridge's auth source. The
- * bridge's `QueryClient` (TanStack Query) owns caching/refetch; the kernel
- * rolls no bespoke state. The query re-runs when the org changes because the
- * org is part of the query key.
- *
- * Rendering is fail-soft (callers can show a loading state), but failures are
- * SURFACED via `error` rather than masquerading as an empty capability set.
- */
-export function CapabilityProvider(
-  props: CapabilityProviderProps,
-): JSX.Element {
-  const bridge = useHostBridge();
-  const port = props.port ?? bridge.capabilities;
-  const orgId =
-    props.orgId !== undefined ? props.orgId : bridge.auth.getOrgId();
-
-  const query = useQuery<MeCapabilitiesSnapshot>({
-    queryKey: [...CAPABILITIES_QUERY_ROOT, orgId],
-    queryFn: () => port.list(orgId ? { orgId } : undefined),
-  });
-
-  const value: CapabilityContextValue = {
-    snapshot: query.data,
-    isLoading: query.isLoading,
-    error: query.error,
-  };
-
-  return (
-    <CapabilityContext.Provider value={value}>
-      {props.children}
-    </CapabilityContext.Provider>
-  );
-}

package/src/lib/capabilities/index.ts

@@ -1,17 +0,0 @@
-/**
- * Host-agnostic capabilities SDK for `@xemahq/ui-kernel`.
- *
- * Lets a biome UI gate on SERVER-AUTHORITATIVE capabilities (the caller's
- * effective set from `GET /bff/me/capabilities`) instead of cosmetic role
- * booleans. The kernel defines the contract and the React surface; it never
- * fetches — the HOST implements {@link CapabilityPort} (hung off
- * `HostBridge.capabilities`) and maps its Orval client response onto the
- * local {@link MeCapabilitiesSnapshot} shape.
- *
- * Biome usage:
- *   import { CapabilityProvider, useCapability } from '@xemahq/ui-kernel';
- */
-export * from './types';
-export * from './capability-context';
-export * from './capability-provider';
-export * from './use-capability';

package/src/lib/capabilities/types.ts

@@ -1,69 +0,0 @@
-import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
-
-/**
- * One server-authoritative capability the caller holds, mirroring the
- * FROZEN `GET /bff/me/capabilities` wire entry.
- *
- * These types are defined LOCALLY in the kernel — deliberately NOT imported
- * from a backend DTO or an Orval client — so `@xemahq/ui-kernel` stays
- * host-agnostic (no fetch lib, no generated client). The concrete host
- * (`submodules/xema-host-web`) maps its client response onto this shape when
- * it implements {@link CapabilityPort}.
- */
-export interface CapabilityEntry {
-  /**
-   * The capability reference (e.g. `capability:session.launch`). Matched
-   * verbatim by {@link useCapability}; the kernel does not parse it.
-   */
-  readonly ref: string;
-  /**
-   * The execution environments in which the caller holds this capability.
-   * A gate that names an `environment` is allowed only if it appears here.
-   */
-  readonly environments: ExecutionEnvironmentKind[];
-  /**
-   * When `true`, holding the capability still requires a human approval step
-   * before the side-effect runs — so a UI affordance should route through the
-   * approval flow rather than acting directly.
-   */
-  readonly approvalRequired: boolean;
-}
-
-/**
- * The caller's effective capability set for one active org, mirroring the
- * FROZEN `MeCapabilitiesResponse` wire shape.
- */
-export interface MeCapabilitiesSnapshot {
-  /** The subject (user) the snapshot was resolved for. */
-  readonly subjectId: string;
-  /** The org the snapshot is scoped to. */
-  readonly orgId: string;
-  /** Every capability the subject effectively holds in this org. */
-  readonly capabilities: CapabilityEntry[];
-}
-
-/**
- * Host-implemented port that fetches the caller's effective capability set.
- *
- * The kernel never calls an API directly — the HOST implements this against
- * its Orval client (`GET /bff/me/capabilities`) and maps the response onto
- * {@link MeCapabilitiesSnapshot}. The implementation is hung off
- * {@link HostBridge.capabilities}; {@link CapabilityProvider} reads it from
- * the bridge and uses the bridge's `QueryClient` for caching/refetch.
- */
-export interface CapabilityPort {
-  /**
-   * Return the caller's effective capability set for the active org.
-   *
-   * @param options.orgId The org to resolve for. When omitted the host
-   *   resolves against its currently-selected org.
-   * @param options.environment Optional environment hint the host MAY pass to
-   *   the backend to narrow the set. Callers gate by environment client-side
-   *   via {@link useCapability}, so a host MAY ignore this and return the full
-   *   set; it exists so a host can request a pre-filtered snapshot.
-   */
-  list(options?: {
-    orgId?: string;
-    environment?: ExecutionEnvironmentKind;
-  }): Promise<MeCapabilitiesSnapshot>;
-}

package/src/lib/capabilities/use-capability.ts

@@ -1,79 +0,0 @@
-import {
-  useCapabilityContext,
-  type CapabilityContextValue,
-} from './capability-context';
-
-import type { MeCapabilitiesSnapshot } from './types';
-import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
-
-export interface UseCapabilityOptions {
-  /**
-   * Gate against a specific execution environment. When set, the capability
-   * counts only if the snapshot lists it for this environment.
-   */
-  readonly environment?: ExecutionEnvironmentKind;
-}
-
-export interface CapabilityDecision {
-  /**
-   * `true` only when the caller holds the capability, holds it in the named
-   * environment (if one was given), AND it does NOT require approval. A gate
-   * that should let the user act directly checks this.
-   */
-  readonly allowed: boolean;
-  /**
-   * `true` when the caller holds the capability (in the named environment, if
-   * given) but it requires a human approval step first — render the
-   * approval-routed affordance instead of acting directly.
-   */
-  readonly approvalRequired: boolean;
-  /** The snapshot is still being fetched; treat as "unknown", not "denied". */
-  readonly isLoading: boolean;
-  /** The fetch failed; surfaced so callers never conflate failure with denial. */
-  readonly error: unknown;
-}
-
-/**
- * Server-authoritative capability gate.
- *
- * Resolves `ref` against the cached {@link CapabilityProvider} snapshot:
- * - `allowed`  = entry exists AND (no environment asked OR listed for it) AND NOT approvalRequired.
- * - `approvalRequired` = entry exists AND (no environment asked OR listed for it) AND approvalRequired.
- *
- * While the snapshot is loading, `allowed` is `false` and `isLoading` is
- * `true` — callers gate on `isLoading` to distinguish "unknown" from "denied".
- * On error, `allowed` is `false` and `error` is set; the hook never silently
- * degrades a failed fetch into a confident denial.
- */
-export function useCapability(
-  ref: string,
-  opts?: UseCapabilityOptions,
-): CapabilityDecision {
-  const { snapshot, isLoading, error } = useCapabilityContext();
-
-  const entry = snapshot?.capabilities.find((c) => c.ref === ref);
-  const inEnvironment =
-    !!entry &&
-    (!opts?.environment || entry.environments.includes(opts.environment));
-
-  return {
-    allowed: inEnvironment && !entry.approvalRequired,
-    approvalRequired: inEnvironment && entry.approvalRequired,
-    isLoading,
-    error,
-  };
-}
-
-/**
- * Accessor for the raw capability snapshot plus its loading/error state.
- * Use when a component needs to enumerate capabilities rather than gate on a
- * single `ref`.
- */
-export function useCapabilities(): {
-  snapshot: MeCapabilitiesSnapshot | undefined;
-  isLoading: boolean;
-  error: unknown;
-} {
-  const ctx: CapabilityContextValue = useCapabilityContext();
-  return { snapshot: ctx.snapshot, isLoading: ctx.isLoading, error: ctx.error };
-}