@susilkumar006/widgets-test 1.0.0

package/dist/types/events.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Events: how a component reports outcomes to the host.
+ *
+ * Every event is an envelope of `type`, `payload` and `meta`. Components declare
+ * their events as a map of event name → payload type; the typed `on…`
+ * handler props are derived from that map, so handler names and event types
+ * cannot drift apart.
+ */
+import type { CorrelationId, EntityId, FacePeError } from './common.js';
+/** Metadata stamped on every event. Never carries credentials. */
+export interface FacePeEventMeta {
+    /**
+     * Version of the envelope's shape (`type`, `payload`, `meta`). Changes only
+     * if that shape changes incompatibly, independently of `sdkVersion`.
+     */
+    readonly schemaVersion: 1;
+    /** Ties the event to the request and gateway log entries that caused it. */
+    readonly correlationId: CorrelationId;
+    /** When the event was emitted, as an ISO 8601 timestamp. */
+    readonly timestamp: string;
+    /** Version of the SDK that emitted the event. */
+    readonly sdkVersion: string;
+    /** Name of the emitting component, e.g. "FacePeForm". */
+    readonly source: string;
+    /** The entity the emitting component works on, when it was given an `entityId`. */
+    readonly entityId?: EntityId;
+}
+/**
+ * A request to navigate, raised by a component and carried out by the host's
+ * router (the SDK never changes the URL itself).
+ */
+export type FacePeNavigationRequest = {
+    /** Destination, as the host's routing understands it (a route name, path or deep link). */
+    readonly to: string;
+    /** Route parameters. @default none */
+    readonly params?: Readonly<Record<string, string>>;
+    /** Replace the current history entry instead of pushing one. @default false */
+    readonly replace?: boolean;
+};
+/**
+ * The envelope every FacePe event is delivered in.
+ *
+ * @typeParam TType - the event name, e.g. "submit".
+ * @typeParam TPayload - the event's data.
+ */
+export interface FacePeEvent<TType extends string = string, TPayload = unknown> {
+    readonly type: TType;
+    readonly payload: TPayload;
+    readonly meta: FacePeEventMeta;
+}
+/** Map of event name → payload type that a component emits. */
+export type FacePeEventMap = Readonly<Record<string, unknown>>;
+/**
+ * The standard events defined by the architecture, by category:
+ * - lifecycle: `ready`, `error`
+ * - intent: `select`, `submit`, `cancel`
+ * - navigation: `navigate`
+ *
+ * `error` and `navigate` have fixed payloads; the others are `unknown` here,
+ * and a component narrows the ones it emits by intersecting this map with its
+ * own, e.g. `FacePeStandardEvents & { submit: MyFormValues }`.
+ */
+export type FacePeStandardEvents = {
+    readonly ready: unknown;
+    readonly select: unknown;
+    readonly submit: unknown;
+    readonly cancel: unknown;
+    readonly navigate: FacePeNavigationRequest;
+    readonly error: FacePeError;
+};
+/** The name of a standard event. */
+export type FacePeEventType = keyof FacePeStandardEvents;
+/** A callback receiving one event envelope. */
+export type FacePeEventHandler<TEvent extends FacePeEvent> = (event: TEvent) => void;
+/**
+ * The optional `on…` handler props derived from an event map:
+ * `{ submit: X }` becomes `{ onSubmit?: (event: FacePeEvent<'submit', X>) => void }`.
+ */
+export type FacePeEventHandlers<TEvents extends FacePeEventMap = FacePeStandardEvents> = {
+    readonly [K in keyof TEvents & string as `on${Capitalize<K>}`]?: FacePeEventHandler<FacePeEvent<K, TEvents[K]>>;
+};
+/** Union of every event envelope a component with this event map can emit. */
+export type FacePeEventOf<TEvents extends FacePeEventMap = FacePeStandardEvents> = {
+    [K in keyof TEvents & string]: FacePeEvent<K, TEvents[K]>;
+}[keyof TEvents & string];

package/dist/types/form.d.cts

@@ -0,0 +1,83 @@
+/**
+ * Contracts of `<FacePeForm>`.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.cjs';
+import type { FacePeStandardEvents } from './events.cjs';
+import type { FacePeFallbackContext } from './placement.cjs';
+import type { AsyncResult } from './results.cjs';
+/** The values the form collects. Deliberately small until the backend contract exists. */
+export type FacePeFormValues = {
+    readonly name: string;
+    readonly email: string;
+    readonly notes: string;
+};
+/**
+ * Events `<FacePeForm>` emits: its payload for each standard event it uses.
+ * `ready` and `cancel` carry no data (`null`).
+ */
+export type FacePeFormEvents = {
+    readonly ready: null;
+    readonly submit: FacePeFormValues;
+    readonly cancel: null;
+    readonly error: FacePeStandardEvents['error'];
+};
+/**
+ * What the `actions` slot's render function receives: the form's own submit
+ * and cancel, so a host-rendered action bar behaves like the built-in one.
+ */
+export type FacePeFormActionsContext = {
+    /** Validates and submits (the same path as the built-in Submit button). */
+    readonly submit: () => void;
+    /** Emits `cancel` (the same as the built-in Cancel button). */
+    readonly cancel: () => void;
+    /** A submission is in progress. */
+    readonly submitting: boolean;
+    /** The form is in `view` mode. */
+    readonly readOnly: boolean;
+};
+/**
+ * Host-rendered regions of the form: `header` above the fields, `actions`
+ * replacing the built-in Cancel/Submit bar, `footer` below it, and `fallback`
+ * in place of the form if it fails to render. @default none
+ */
+export type FacePeFormSlots = {
+    readonly header: void;
+    readonly actions: FacePeFormActionsContext;
+    readonly footer: void;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Field layout: one field per row, or name and email side by side when the container is wide enough. */
+export type FacePeFormVariant = 'stacked' | 'inline';
+/**
+ * Work to run with validated values before `submit` is emitted, e.g. saving
+ * them. The form shows its submitting state until it resolves. It resolves to
+ * a `Result`; a rejection is treated as a failure too.
+ */
+export type FacePeFormSubmitAction = (values: FacePeFormValues) => AsyncResult<void>;
+/** Props of `<FacePeForm>`. Configuration props override the provider's for this form. */
+export type FacePeFormProps = FacePeComponentProps<FacePeFormEvents, FacePeFormSlots> & {
+    /**
+     * Values the form starts with, and returns to on `reset()`. Leave out to
+     * pass the entity by reference instead: with an `entityId` (an order id)
+     * the form loads that order's customer details through the gateway.
+     * @default loaded by `entityId`; all empty without one
+     */
+    readonly initialValues?: Partial<FacePeFormValues>;
+    /**
+     * @default with an `entityId` and no `initialValues`: the values are saved
+     *   to that order through the gateway before `submit` is emitted; otherwise
+     *   `submit` is emitted as soon as the values are valid
+     */
+    readonly submitAction?: FacePeFormSubmitAction;
+    /** Layout variant (customization rung L2). @default 'stacked' */
+    readonly variant?: FacePeFormVariant;
+};
+/** Imperative handle of `<FacePeForm>`, reached through a React `ref`. */
+export interface FacePeFormHandle {
+    /** Validates and shows any errors, without submitting. */
+    readonly validate: FacePeHandleMethod<[], FacePeFormValues>;
+    /** Restores `initialValues` (or the last loaded or saved values) and clears errors. */
+    readonly reset: FacePeHandleMethod;
+    /** Moves keyboard focus to the first field. */
+    readonly focus: FacePeHandleMethod;
+}

package/dist/types/form.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Contracts of `<FacePeForm>`.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.js';
+import type { FacePeStandardEvents } from './events.js';
+import type { FacePeFallbackContext } from './placement.js';
+import type { AsyncResult } from './results.js';
+/** The values the form collects. Deliberately small until the backend contract exists. */
+export type FacePeFormValues = {
+    readonly name: string;
+    readonly email: string;
+    readonly notes: string;
+};
+/**
+ * Events `<FacePeForm>` emits: its payload for each standard event it uses.
+ * `ready` and `cancel` carry no data (`null`).
+ */
+export type FacePeFormEvents = {
+    readonly ready: null;
+    readonly submit: FacePeFormValues;
+    readonly cancel: null;
+    readonly error: FacePeStandardEvents['error'];
+};
+/**
+ * What the `actions` slot's render function receives: the form's own submit
+ * and cancel, so a host-rendered action bar behaves like the built-in one.
+ */
+export type FacePeFormActionsContext = {
+    /** Validates and submits (the same path as the built-in Submit button). */
+    readonly submit: () => void;
+    /** Emits `cancel` (the same as the built-in Cancel button). */
+    readonly cancel: () => void;
+    /** A submission is in progress. */
+    readonly submitting: boolean;
+    /** The form is in `view` mode. */
+    readonly readOnly: boolean;
+};
+/**
+ * Host-rendered regions of the form: `header` above the fields, `actions`
+ * replacing the built-in Cancel/Submit bar, `footer` below it, and `fallback`
+ * in place of the form if it fails to render. @default none
+ */
+export type FacePeFormSlots = {
+    readonly header: void;
+    readonly actions: FacePeFormActionsContext;
+    readonly footer: void;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Field layout: one field per row, or name and email side by side when the container is wide enough. */
+export type FacePeFormVariant = 'stacked' | 'inline';
+/**
+ * Work to run with validated values before `submit` is emitted, e.g. saving
+ * them. The form shows its submitting state until it resolves. It resolves to
+ * a `Result`; a rejection is treated as a failure too.
+ */
+export type FacePeFormSubmitAction = (values: FacePeFormValues) => AsyncResult<void>;
+/** Props of `<FacePeForm>`. Configuration props override the provider's for this form. */
+export type FacePeFormProps = FacePeComponentProps<FacePeFormEvents, FacePeFormSlots> & {
+    /**
+     * Values the form starts with, and returns to on `reset()`. Leave out to
+     * pass the entity by reference instead: with an `entityId` (an order id)
+     * the form loads that order's customer details through the gateway.
+     * @default loaded by `entityId`; all empty without one
+     */
+    readonly initialValues?: Partial<FacePeFormValues>;
+    /**
+     * @default with an `entityId` and no `initialValues`: the values are saved
+     *   to that order through the gateway before `submit` is emitted; otherwise
+     *   `submit` is emitted as soon as the values are valid
+     */
+    readonly submitAction?: FacePeFormSubmitAction;
+    /** Layout variant (customization rung L2). @default 'stacked' */
+    readonly variant?: FacePeFormVariant;
+};
+/** Imperative handle of `<FacePeForm>`, reached through a React `ref`. */
+export interface FacePeFormHandle {
+    /** Validates and shows any errors, without submitting. */
+    readonly validate: FacePeHandleMethod<[], FacePeFormValues>;
+    /** Restores `initialValues` (or the last loaded or saved values) and clears errors. */
+    readonly reset: FacePeHandleMethod;
+    /** Moves keyboard focus to the first field. */
+    readonly focus: FacePeHandleMethod;
+}

package/dist/types/index.d.cts

@@ -0,0 +1,18 @@
+/**
+ * The public TypeScript contracts of @facepe/widgets.
+ *
+ * Only types listed here are public; src/index.ts re-exports this list.
+ */
+export type { CorrelationId, EntityId, FacePeDataObject, FacePeDensity, FacePeError, FacePeFeatureFlags, FacePeLocale, FacePeMode, JsonArray, JsonObject, JsonPrimitive, JsonValue, } from './common.cjs';
+export type { FacePeConfig } from './config.cjs';
+export type { FacePeEvent, FacePeEventHandler, FacePeEventHandlers, FacePeEventMap, FacePeEventMeta, FacePeEventOf, FacePeNavigationRequest, FacePeEventType, FacePeStandardEvents, } from './events.cjs';
+export type { AsyncResult, Failure, Result, Success } from './results.cjs';
+export type { FacePeAvatarControlsContext, FacePeAvatarEvents, FacePeAvatarHandle, FacePeAvatarInfo, FacePeAvatarProps, FacePeAvatarSession, FacePeAvatarSessionEnd, FacePeAvatarSlots, FacePeAvatarStatus, FacePeTranscriptLine, } from './avatar.cjs';
+export type { FacePeTelemetry, FacePeTelemetryAttributes, FacePeTelemetryEvent } from './telemetry.cjs';
+export type { FacePeContextValue, FacePeProviderProps } from './provider.cjs';
+export type { FacePeColorScheme, FacePeFallbackContext, FacePeOverlayProps, FacePeOverlayVariant, FacePePageProps, FacePeThemeTokens, } from './placement.cjs';
+export type { FacePeCustomerPayload, FacePeHttpMethod, FacePePickerOptionsPayload, FacePeTimelinePayload, FacePeProviderEvents, FacePeSessionExpiredPayload, FacePeTokenProvider, FacePeTokenRequest, } from './api.cjs';
+export type { FacePeFormActionsContext, FacePeFormEvents, FacePeFormHandle, FacePeFormProps, FacePeFormSlots, FacePeFormSubmitAction, FacePeFormValues, FacePeFormVariant, } from './form.cjs';
+export type { FacePePickerEvents, FacePePickerHandle, FacePePickerOption, FacePePickerOptionSlotContext, FacePePickerProps, FacePePickerSelection, FacePePickerSlots, FacePePickerVariant, } from './picker.cjs';
+export type { FacePeTimelineEvents, FacePeTimelineHandle, FacePeTimelineItem, FacePeTimelineItemSlotContext, FacePeTimelineItemStatus, FacePeTimelineMetadata, FacePeTimelineProps, FacePeTimelineSelection, FacePeTimelineSlots, } from './timeline.cjs';
+export type { FacePeComponentProps, FacePeEmphasis, FacePeHandle, FacePeHandleMethod, FacePeSlot, FacePeSlotMap, FacePeSize, FacePeSlots, } from './components.cjs';

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The public TypeScript contracts of @facepe/widgets.
+ *
+ * Only types listed here are public; src/index.ts re-exports this list.
+ */
+export type { CorrelationId, EntityId, FacePeDataObject, FacePeDensity, FacePeError, FacePeFeatureFlags, FacePeLocale, FacePeMode, JsonArray, JsonObject, JsonPrimitive, JsonValue, } from './common.js';
+export type { FacePeConfig } from './config.js';
+export type { FacePeEvent, FacePeEventHandler, FacePeEventHandlers, FacePeEventMap, FacePeEventMeta, FacePeEventOf, FacePeNavigationRequest, FacePeEventType, FacePeStandardEvents, } from './events.js';
+export type { AsyncResult, Failure, Result, Success } from './results.js';
+export type { FacePeAvatarControlsContext, FacePeAvatarEvents, FacePeAvatarHandle, FacePeAvatarInfo, FacePeAvatarProps, FacePeAvatarSession, FacePeAvatarSessionEnd, FacePeAvatarSlots, FacePeAvatarStatus, FacePeTranscriptLine, } from './avatar.js';
+export type { FacePeTelemetry, FacePeTelemetryAttributes, FacePeTelemetryEvent } from './telemetry.js';
+export type { FacePeContextValue, FacePeProviderProps } from './provider.js';
+export type { FacePeColorScheme, FacePeFallbackContext, FacePeOverlayProps, FacePeOverlayVariant, FacePePageProps, FacePeThemeTokens, } from './placement.js';
+export type { FacePeCustomerPayload, FacePeHttpMethod, FacePePickerOptionsPayload, FacePeTimelinePayload, FacePeProviderEvents, FacePeSessionExpiredPayload, FacePeTokenProvider, FacePeTokenRequest, } from './api.js';
+export type { FacePeFormActionsContext, FacePeFormEvents, FacePeFormHandle, FacePeFormProps, FacePeFormSlots, FacePeFormSubmitAction, FacePeFormValues, FacePeFormVariant, } from './form.js';
+export type { FacePePickerEvents, FacePePickerHandle, FacePePickerOption, FacePePickerOptionSlotContext, FacePePickerProps, FacePePickerSelection, FacePePickerSlots, FacePePickerVariant, } from './picker.js';
+export type { FacePeTimelineEvents, FacePeTimelineHandle, FacePeTimelineItem, FacePeTimelineItemSlotContext, FacePeTimelineItemStatus, FacePeTimelineMetadata, FacePeTimelineProps, FacePeTimelineSelection, FacePeTimelineSlots, } from './timeline.js';
+export type { FacePeComponentProps, FacePeEmphasis, FacePeHandle, FacePeHandleMethod, FacePeSlot, FacePeSlotMap, FacePeSize, FacePeSlots, } from './components.js';

package/dist/types/picker.d.cts

@@ -0,0 +1,82 @@
+/**
+ * Contracts of `<FacePePicker>`.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.cjs';
+import type { FacePeStandardEvents } from './events.cjs';
+import type { FacePeFallbackContext } from './placement.cjs';
+/** One choice in the picker. */
+export type FacePePickerOption = {
+    /** Unique within the picker; what `select` reports. */
+    readonly value: string;
+    /** Text shown to the user. */
+    readonly label: string;
+    /** Secondary text, shown when the `picker.descriptions` feature flag is on. */
+    readonly description?: string;
+    /** Shown but not selectable. @default false */
+    readonly disabled?: boolean;
+};
+/** Payload of the `select` event and of a successful `select()` call. */
+export type FacePePickerSelection = {
+    readonly value: string;
+    readonly label: string;
+    /** The value selected before this one, or `null` if there was none. */
+    readonly previousValue: string | null;
+};
+/** Events `<FacePePicker>` emits. `ready` carries no data (`null`). */
+export type FacePePickerEvents = {
+    readonly ready: null;
+    readonly select: FacePePickerSelection;
+    readonly error: FacePeStandardEvents['error'];
+};
+/** What the `option` row renderer receives for each option. */
+export type FacePePickerOptionSlotContext = {
+    readonly option: FacePePickerOption;
+    readonly selected: boolean;
+    readonly disabled: boolean;
+};
+/**
+ * Host-rendered regions: `header` above the options, `option` rendering each
+ * option's content (the radio and its selection behaviour stay), `emptyState`
+ * in place of an empty list, and `fallback` in place of the picker if it
+ * fails to render. @default none
+ */
+export type FacePePickerSlots = {
+    readonly header: void;
+    readonly option: FacePePickerOptionSlotContext;
+    readonly emptyState: void;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Option layout: one per row, or a grid filling the container's width. */
+export type FacePePickerVariant = 'list' | 'grid';
+/**
+ * Props of `<FacePePicker>`. Configuration props override the provider's;
+ * `featureFlags` are merged per flag, the picker's own winning.
+ *
+ * Feature flags read: `picker.descriptions` (show option descriptions).
+ */
+export type FacePePickerProps = FacePeComponentProps<FacePePickerEvents, FacePePickerSlots> & {
+    /** The group's accessible label, shown as its legend. @default 'Choose an option' */
+    readonly label?: string;
+    /**
+     * The choices. Leave out to pass the entity by reference instead: with an
+     * `entityId` (a location id) the picker fetches that location's menu
+     * categories through the gateway (architecture §7.5).
+     * @default fetched by `entityId`; none without one
+     */
+    readonly options?: readonly FacePePickerOption[];
+    /**
+     * Value selected once the options are known (on first render, or when
+     * fetched options arrive). Ignored, with an `error` event, if it names no
+     * option or a disabled one. @default none
+     */
+    readonly defaultValue?: string;
+    /** Layout variant (customization rung L2). @default 'list' */
+    readonly variant?: FacePePickerVariant;
+};
+/** Imperative handle of `<FacePePicker>`, reached through a React `ref`. */
+export interface FacePePickerHandle {
+    /** Moves keyboard focus into the picker. */
+    readonly focus: FacePeHandleMethod;
+    /** Returns to the initial selection (`defaultValue`, or none). Emits nothing. */
+    readonly reset: FacePeHandleMethod;
+}

package/dist/types/picker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Contracts of `<FacePePicker>`.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.js';
+import type { FacePeStandardEvents } from './events.js';
+import type { FacePeFallbackContext } from './placement.js';
+/** One choice in the picker. */
+export type FacePePickerOption = {
+    /** Unique within the picker; what `select` reports. */
+    readonly value: string;
+    /** Text shown to the user. */
+    readonly label: string;
+    /** Secondary text, shown when the `picker.descriptions` feature flag is on. */
+    readonly description?: string;
+    /** Shown but not selectable. @default false */
+    readonly disabled?: boolean;
+};
+/** Payload of the `select` event and of a successful `select()` call. */
+export type FacePePickerSelection = {
+    readonly value: string;
+    readonly label: string;
+    /** The value selected before this one, or `null` if there was none. */
+    readonly previousValue: string | null;
+};
+/** Events `<FacePePicker>` emits. `ready` carries no data (`null`). */
+export type FacePePickerEvents = {
+    readonly ready: null;
+    readonly select: FacePePickerSelection;
+    readonly error: FacePeStandardEvents['error'];
+};
+/** What the `option` row renderer receives for each option. */
+export type FacePePickerOptionSlotContext = {
+    readonly option: FacePePickerOption;
+    readonly selected: boolean;
+    readonly disabled: boolean;
+};
+/**
+ * Host-rendered regions: `header` above the options, `option` rendering each
+ * option's content (the radio and its selection behaviour stay), `emptyState`
+ * in place of an empty list, and `fallback` in place of the picker if it
+ * fails to render. @default none
+ */
+export type FacePePickerSlots = {
+    readonly header: void;
+    readonly option: FacePePickerOptionSlotContext;
+    readonly emptyState: void;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Option layout: one per row, or a grid filling the container's width. */
+export type FacePePickerVariant = 'list' | 'grid';
+/**
+ * Props of `<FacePePicker>`. Configuration props override the provider's;
+ * `featureFlags` are merged per flag, the picker's own winning.
+ *
+ * Feature flags read: `picker.descriptions` (show option descriptions).
+ */
+export type FacePePickerProps = FacePeComponentProps<FacePePickerEvents, FacePePickerSlots> & {
+    /** The group's accessible label, shown as its legend. @default 'Choose an option' */
+    readonly label?: string;
+    /**
+     * The choices. Leave out to pass the entity by reference instead: with an
+     * `entityId` (a location id) the picker fetches that location's menu
+     * categories through the gateway (architecture §7.5).
+     * @default fetched by `entityId`; none without one
+     */
+    readonly options?: readonly FacePePickerOption[];
+    /**
+     * Value selected once the options are known (on first render, or when
+     * fetched options arrive). Ignored, with an `error` event, if it names no
+     * option or a disabled one. @default none
+     */
+    readonly defaultValue?: string;
+    /** Layout variant (customization rung L2). @default 'list' */
+    readonly variant?: FacePePickerVariant;
+};
+/** Imperative handle of `<FacePePicker>`, reached through a React `ref`. */
+export interface FacePePickerHandle {
+    /** Moves keyboard focus into the picker. */
+    readonly focus: FacePeHandleMethod;
+    /** Returns to the initial selection (`defaultValue`, or none). Emits nothing. */
+    readonly reset: FacePeHandleMethod;
+}

package/dist/types/placement.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Contracts for how embedded experiences are placed and styled by the host:
+ * display modes, error fallback, and the design-token rung of the
+ * customization ladder.
+ */
+import type { ReactNode } from 'react';
+import type { FacePeError } from './common.cjs';
+/** What a component's `fallback` slot receives after the component failed to render. */
+export type FacePeFallbackContext = {
+    /** Typed and safe to show or log: no stack trace, no credentials. */
+    readonly error: FacePeError;
+};
+/**
+ * Design tokens (customization rung L1), supplied by the host through the
+ * provider. Each is applied as the matching documented CSS custom property.
+ * The package hard-codes no colours or fonts: a token left out inherits from
+ * the host page (text colour, font, size) or stays neutral (transparent
+ * surface, borders tinted from the text colour). Values are plain CSS strings.
+ */
+export type FacePeThemeTokens = {
+    /** `--fp-color-surface` (frame and field background) @default transparent: the host's background */
+    readonly colorSurface?: string;
+    /** `--fp-color-surface-muted` (read-only fields, hover) @default a light tint of the text colour */
+    readonly colorSurfaceMuted?: string;
+    /** `--fp-color-text` @default inherited from the host */
+    readonly colorText?: string;
+    /** `--fp-color-muted` (secondary text) @default the text colour, partly transparent */
+    readonly colorMuted?: string;
+    /** `--fp-color-border` @default the text colour, mostly transparent */
+    readonly colorBorder?: string;
+    /** `--fp-color-accent` (primary action, focus, selection, links) @default the text colour */
+    readonly colorAccent?: string;
+    /** `--fp-color-on-accent` (text on the accent, e.g. the primary button) @default inherited text colour */
+    readonly colorOnAccent?: string;
+    /** `--fp-color-danger` (errors, failed status) @default the text colour */
+    readonly colorDanger?: string;
+    /** `--fp-color-success` (completed status) @default the text colour */
+    readonly colorSuccess?: string;
+    /** `--fp-font-family` @default inherited from the host */
+    readonly fontFamily?: string;
+    /** `--fp-font-size` (base of the type scale) @default inherited from the host */
+    readonly fontSize?: string;
+    /** `--fp-spacing` (unit of the spacing rhythm; gaps and padding are multiples) @default '0.25rem' */
+    readonly spacing?: string;
+    /** `--fp-radius` (field and button corners; frames use 1.5×) @default '0.375rem' */
+    readonly radius?: string;
+    /** `--fp-shadow` (elevation of `emphasis="strong"`) @default a soft shadow tinted from the text colour */
+    readonly shadow?: string;
+};
+/** Light or dark token scheme, chosen by the host (architecture §7.1). */
+export type FacePeColorScheme = 'light' | 'dark';
+/** Props of `<FacePePage>`: a component shown as a full view filling its container. */
+export type FacePePageProps = {
+    readonly children?: ReactNode;
+};
+/** How `<FacePeOverlay>` presents: a centred modal or a side drawer. */
+export type FacePeOverlayVariant = 'modal' | 'drawer';
+/** Props of `<FacePeOverlay>`: a component shown over the page. */
+export type FacePeOverlayProps = {
+    /** Whether it is shown. The host owns this state. */
+    readonly open: boolean;
+    /** The dialog's accessible name. */
+    readonly label: string;
+    /** @default 'modal' */
+    readonly variant?: FacePeOverlayVariant;
+    /** Asked to close (Escape). The host decides by setting `open`. @default none */
+    readonly onClose?: () => void;
+    readonly children?: ReactNode;
+};

package/dist/types/placement.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Contracts for how embedded experiences are placed and styled by the host:
+ * display modes, error fallback, and the design-token rung of the
+ * customization ladder.
+ */
+import type { ReactNode } from 'react';
+import type { FacePeError } from './common.js';
+/** What a component's `fallback` slot receives after the component failed to render. */
+export type FacePeFallbackContext = {
+    /** Typed and safe to show or log: no stack trace, no credentials. */
+    readonly error: FacePeError;
+};
+/**
+ * Design tokens (customization rung L1), supplied by the host through the
+ * provider. Each is applied as the matching documented CSS custom property.
+ * The package hard-codes no colours or fonts: a token left out inherits from
+ * the host page (text colour, font, size) or stays neutral (transparent
+ * surface, borders tinted from the text colour). Values are plain CSS strings.
+ */
+export type FacePeThemeTokens = {
+    /** `--fp-color-surface` (frame and field background) @default transparent: the host's background */
+    readonly colorSurface?: string;
+    /** `--fp-color-surface-muted` (read-only fields, hover) @default a light tint of the text colour */
+    readonly colorSurfaceMuted?: string;
+    /** `--fp-color-text` @default inherited from the host */
+    readonly colorText?: string;
+    /** `--fp-color-muted` (secondary text) @default the text colour, partly transparent */
+    readonly colorMuted?: string;
+    /** `--fp-color-border` @default the text colour, mostly transparent */
+    readonly colorBorder?: string;
+    /** `--fp-color-accent` (primary action, focus, selection, links) @default the text colour */
+    readonly colorAccent?: string;
+    /** `--fp-color-on-accent` (text on the accent, e.g. the primary button) @default inherited text colour */
+    readonly colorOnAccent?: string;
+    /** `--fp-color-danger` (errors, failed status) @default the text colour */
+    readonly colorDanger?: string;
+    /** `--fp-color-success` (completed status) @default the text colour */
+    readonly colorSuccess?: string;
+    /** `--fp-font-family` @default inherited from the host */
+    readonly fontFamily?: string;
+    /** `--fp-font-size` (base of the type scale) @default inherited from the host */
+    readonly fontSize?: string;
+    /** `--fp-spacing` (unit of the spacing rhythm; gaps and padding are multiples) @default '0.25rem' */
+    readonly spacing?: string;
+    /** `--fp-radius` (field and button corners; frames use 1.5×) @default '0.375rem' */
+    readonly radius?: string;
+    /** `--fp-shadow` (elevation of `emphasis="strong"`) @default a soft shadow tinted from the text colour */
+    readonly shadow?: string;
+};
+/** Light or dark token scheme, chosen by the host (architecture §7.1). */
+export type FacePeColorScheme = 'light' | 'dark';
+/** Props of `<FacePePage>`: a component shown as a full view filling its container. */
+export type FacePePageProps = {
+    readonly children?: ReactNode;
+};
+/** How `<FacePeOverlay>` presents: a centred modal or a side drawer. */
+export type FacePeOverlayVariant = 'modal' | 'drawer';
+/** Props of `<FacePeOverlay>`: a component shown over the page. */
+export type FacePeOverlayProps = {
+    /** Whether it is shown. The host owns this state. */
+    readonly open: boolean;
+    /** The dialog's accessible name. */
+    readonly label: string;
+    /** @default 'modal' */
+    readonly variant?: FacePeOverlayVariant;
+    /** Asked to close (Escape). The host decides by setting `open`. @default none */
+    readonly onClose?: () => void;
+    readonly children?: ReactNode;
+};