@c15t/react 3.0.0-alpha.0 → 3.0.0-alpha.10

package/dist-types/components/shared/ui/button/index.d.ts

@@ -1,2 +1,2 @@
-export * from './button';
-export * from './button.types';
+export * from './button.js';
+export * from './button.types.js';

package/dist-types/components/shared/ui/collapsible/index.d.ts

@@ -1 +1 @@
-export * from './collapsible';
+export * from './collapsible.js';

package/dist-types/components/shared/ui/dialog/index.d.ts

@@ -1 +1 @@
-export * from './dialog';
+export * from './dialog.js';

package/dist-types/components/shared/ui/icon.d.ts

@@ -1,6 +1,7 @@
 import type { ElementType, JSX, SVGProps } from 'react';
 type LucideIconProps = SVGProps<SVGSVGElement> & {
-    title: string;
+    /** Omit for a decorative icon that must add nothing to an accessible name. */
+    title?: string;
     iconPath: JSX.Element;
 };
 export declare const LucideIcon: ({ title, iconPath }: LucideIconProps) => ElementType;

package/dist-types/components/shared/ui/logo.d.ts

@@ -16,14 +16,4 @@ export declare const InthLogo: (props: SVGProps<SVGSVGElement> & IconProps) => i
  * INTH icon-only mark for compact placements like floating triggers.
  */
 export declare const InthIconOnly: (props: SVGProps<SVGSVGElement> & IconProps) => import("react").JSX.Element;
-/**
- * Fingerprint icon for privacy/consent contexts.
- * A generic icon representing user identity and privacy.
- */
-export declare const FingerprintIcon: ({ title, titleId, ...props }: SVGProps<SVGSVGElement> & IconProps) => import("react").JSX.Element;
-/**
- * Settings/gear icon for preference contexts.
- * A generic icon representing configuration and settings.
- */
-export declare const SettingsIcon: ({ title, titleId, ...props }: SVGProps<SVGSVGElement> & IconProps) => import("react").JSX.Element;
 export {};

package/dist-types/components/shared/ui/preference-item/index.d.ts

@@ -1 +1 @@
-export * from './preference-item';
+export * from './preference-item.js';

package/dist-types/components/shared/ui/preference-item/preference-item.d.ts

@@ -66,6 +66,19 @@ export interface PreferenceItemTitleProps extends HTMLAttributes<HTMLHeadingElem
 }
 declare const PreferenceItemTitle: import("react").ForwardRefExoticComponent<PreferenceItemTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
 export interface PreferenceItemContentProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Render the children while the item has never been opened.
+     *
+     * By default the content element is always rendered, so the trigger's
+     * `aria-controls` target exists, but its children mount the first time
+     * the item opens and then stay mounted, so the close transition and any
+     * state inside them survive. Collapsed content is `inert` and
+     * `aria-hidden` either way. Set this when collapsed children must be in
+     * the DOM, for example when custom CSS shows them.
+     *
+     * @defaultValue false
+     */
+    forceMount?: boolean;
     innerClassName?: string;
     innerSlotKey?: ConsentComponentSlotKey;
     noStyle?: boolean;

package/dist-types/components/shared/ui/switch/index.d.ts

@@ -1,2 +1,2 @@
-export * from './switch';
-export type { SwitchCSSVariables, SwitchRootCSSVariables, SwitchThumbCSSVariables, SwitchTrackCSSVariables, } from './switch.types';
+export * from './switch.js';
+export type { SwitchCSSVariables, SwitchRootCSSVariables, SwitchThumbCSSVariables, SwitchTrackCSSVariables, } from './switch.types.js';

package/dist-types/components/shared/ui/switch/switch.d.ts

@@ -1,5 +1,5 @@
 import type { ButtonHTMLAttributes } from 'react';
-import type { ThemeValue } from '../../../../types/theme';
+import type { ThemeValue } from '../../../../types/theme/index.js';
 export type SwitchSize = 'medium' | 'small';
 export interface SwitchVariantsProps {
     size?: SwitchSize;

package/dist-types/components/shared/ui/tabs/index.d.ts

@@ -1 +1 @@
-export * from './tabs';
+export * from './tabs.js';

package/dist-types/consent-gate.d.ts

@@ -0,0 +1 @@
+export { ConsentGate, ConsentGateButton, type ConsentGateCompoundComponent, type ConsentGateProps, ConsentGateRoot, ConsentGateTitle, Frame, FrameButton, type FrameCompoundComponent, type FrameProps, FrameRoot, FrameTitle, } from './components/consent-gate/index.js';

package/dist-types/consent-theme.d.ts

@@ -0,0 +1,38 @@
+import type { Theme } from './types/theme/index.js';
+/** Props for {@link ConsentTheme}. */
+export interface ConsentThemeProps {
+    /**
+     * Theme tokens: colors, dark colors, typography, spacing, radius,
+     * shadows and motion. Defaults to the built-in theme, which the package
+     * stylesheet already contains, so omit it only to pick a `colorScheme`
+     * before hydration.
+     */
+    theme?: Theme;
+    /**
+     * Color scheme to apply before hydration. `'dark'` makes the dark
+     * tokens the default, and `'system'` follows `prefers-color-scheme`.
+     * Omit it to follow the `dark` / `c15t-dark` class on `<html>`. Pass the
+     * same value as the provider's `colorScheme` option.
+     */
+    colorScheme?: 'light' | 'dark' | 'system' | null;
+    /** Content Security Policy nonce for the `<style>` element. */
+    nonce?: string;
+}
+/**
+ * Renders the `--c15t-*` CSS variables for a theme as a `<style>` element.
+ *
+ * Render it once, next to the consent provider, where your framework renders
+ * on the server. The provider does not generate theme CSS itself.
+ *
+ * @param props - The theme, color scheme and CSP nonce.
+ * @returns A `<style id="c15t-theme">` element.
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Server Component)
+ * import { ConsentTheme } from '@c15t/nextjs';
+ * import { theme } from './consent-theme';
+ *
+ * <ConsentTheme theme={theme} colorScheme="system" />
+ * ```
+ */
+export declare const ConsentTheme: ({ theme, colorScheme, nonce, }: ConsentThemeProps) => import("react").JSX.Element;

package/dist-types/context/consent-tracking-context.d.ts

@@ -1,3 +1,4 @@
+import type { SaveUISource } from '@c15t/core';
 /**
  * Value provided by the ConsentTrackingContext.
  *
@@ -30,3 +31,12 @@ export declare const ConsentTrackingContext: import("react").Context<ConsentTrac
  * @public
  */
 export declare const useConsentTracking: () => ConsentTrackingValue;
+/**
+ * Narrow a tracking `uiSource` to a value the kernel records. Custom labels
+ * fall back to the kernel's `activeUI` attribution.
+ *
+ * @param value - The `uiSource` from props or context.
+ * @returns A kernel save source, or `undefined` to keep the default.
+ * @public
+ */
+export declare const toSaveUISource: (value: string | undefined) => SaveUISource | undefined;

package/dist-types/context/index.d.ts

@@ -1,3 +1,3 @@
-export * from '../context';
-export * from './consent-tracking-context';
-export * from './theme-context';
+export { HydrationSnapshotContext, KernelContext, type ProviderServices, ProviderServicesContext, StreamedPrefetchContext, } from '../context.js';
+export { ConsentTrackingContext, type ConsentTrackingValue, toSaveUISource, useConsentTracking, } from './consent-tracking-context.js';
+export { GlobalThemeContext, LocalThemeContext, type ThemeContextValue, } from './theme-context.js';

package/dist-types/context/theme-context.d.ts

@@ -1,4 +1,4 @@
-import type { Theme } from '../types/theme';
+import type { Theme } from '../types/theme/index.js';
 /**
  * Configuration value type for the ThemeContext.
  *
@@ -41,10 +41,10 @@ export interface ThemeContextValue {
      */
     trapFocus?: boolean;
     /**
-     * Color scheme preference.
+     * Color scheme preference. `null` when the provider leaves the class alone.
      * @default 'system'
      */
-    colorScheme?: 'light' | 'dark' | 'system';
+    colorScheme?: 'light' | 'dark' | 'system' | null;
 }
 /**
  * Context for providing theme values to components.

package/dist-types/context.d.ts

@@ -1,4 +1,5 @@
-import type { AllConsentNames, ConsentKernel, ConsentPresentation } from '@c15t/core';
+import type { AllConsentNames, ConsentKernel, ConsentPresentation, ConsentSnapshot } from '@c15t/core';
+import type { StreamedPrefetch } from '@c15t/core/runtime';
 /**
  * React context carrying the kernel instance.
  *
@@ -13,5 +14,28 @@ export interface ProviderServices {
     clearRecords: () => void;
     getPresentation: () => ConsentPresentation | undefined;
     getConsentCategories: () => readonly AllConsentNames[];
+    /** Whether the runtime has started: records hydrated, prefetch adopted. */
+    isStarted: () => boolean;
+    /**
+     * Store a language override and load its copy: init runs again on the
+     * provider's own kernel while it is enabled, and a borrowed runtime
+     * reinitializes itself.
+     */
+    setLanguage: (code: string) => void;
 }
 export declare const ProviderServicesContext: import("react").Context<ProviderServices | null>;
+/**
+ * The provider runtime's streamed `prefetch`, while `prefetch` is a promise.
+ * Consent surfaces render inside a boundary that waits for it.
+ *
+ * @internal
+ */
+export declare const StreamedPrefetchContext: import("react").Context<StreamedPrefetch | undefined>;
+/**
+ * The snapshot a streamed consent surface was server-rendered from, which
+ * its hydration must read in place of the kernel's own server snapshot.
+ * `null` everywhere else.
+ *
+ * @internal
+ */
+export declare const HydrationSnapshotContext: import("react").Context<ConsentSnapshot | null>;

package/dist-types/devtools-launcher.d.ts

@@ -0,0 +1,29 @@
+import type { DevToolsDock } from '@c15t/ui/utils/devtools-launcher';
+export { publishDevToolsLauncher } from '@c15t/ui/utils/devtools-launcher';
+export type { DevToolsDock } from '@c15t/ui/utils/devtools-launcher';
+/** Controls for the DevTools button a consent trigger renders. */
+export interface DevToolsLauncherControls {
+    /** Whether the DevTools panel is open. */
+    isOpen: boolean;
+    /** Open or close the panel. */
+    toggle: () => void;
+    /** Anchor the panel to the trigger, or release it with `null`. */
+    dock: (dock: DevToolsDock | null) => void;
+}
+/**
+ * Whether a `<ConsentDevTools>` is mounted for the nearest provider.
+ * @returns `true` while DevTools can hand its launcher to a trigger.
+ * @internal
+ */
+export declare const useDevToolsLauncherAvailable: () => boolean;
+/**
+ * Claim the DevTools launcher for this trigger.
+ *
+ * Only one trigger renders the launcher at a time; others get `null` until
+ * the owner unmounts. Releasing the claim, or DevTools unmounting, brings
+ * the floating launcher back.
+ *
+ * @returns Launcher controls while this trigger owns the launcher.
+ * @internal
+ */
+export declare const useDevToolsLauncher: () => DevToolsLauncherControls | null;

package/dist-types/devtools.d.ts

@@ -15,7 +15,7 @@ export type DevToolsProps = ConsentDevToolsProps;
  * @param props - Presentation options passed to the DevTools engine.
  * @returns `null`; the engine mounts its interface into `document.body`.
  */
-export declare const ConsentDevTools: ({ disabled, clearRecords, getPresentation, defaultOpen, defaultTab, getConsentCategories, maxEvents, position, }: ConsentDevToolsProps) => null;
+export declare const ConsentDevTools: ({ disabled, clearRecords, getPresentation, defaultOpen, defaultTab, getConsentCategories, maxEvents, position, shadow, }: ConsentDevToolsProps) => null;
 /** Compatible short name for {@link ConsentDevTools}. */
 export declare const DevTools: typeof ConsentDevTools;
 /** Backward-compatible name for {@link ConsentDevTools}. */
@@ -24,13 +24,24 @@ export declare const C15TDevTools: typeof ConsentDevTools;
 export interface C15tTanStackDevtoolsPanelProps extends HTMLAttributes<HTMLDivElement>, Pick<DevToolsOptions, 'defaultTab' | 'maxEvents' | 'getConsentCategories' | 'getPresentation' | 'clearRecords'> {
     /** Prevents the embedded DevTools engine from mounting. @default false */
     disabled?: boolean;
+    /**
+     * Color scheme of the surrounding devtools shell. Omit to follow the
+     * operating system. {@link c15tDevtools} passes TanStack's theme.
+     */
+    theme?: TanStackDevtoolsTheme;
+}
+/** Color scheme TanStack Devtools passes to plugin panels. */
+export type TanStackDevtoolsTheme = 'light' | 'dark';
+/** Props React TanStack Devtools passes to a plugin's render function. */
+export interface TanStackDevtoolsPluginProps {
+    theme?: TanStackDevtoolsTheme;
 }
 /** Plugin configuration accepted by React TanStack Devtools. */
 export interface TanStackDevtoolsPlugin {
     id?: string;
     name: string;
     defaultOpen?: boolean;
-    render: ReactElement;
+    render: (element: HTMLElement, props?: TanStackDevtoolsPluginProps | TanStackDevtoolsTheme) => ReactElement;
 }
 /** Options for {@link c15tDevtools}. */
 export interface C15tDevtoolsPluginOptions extends C15tTanStackDevtoolsPanelProps {

package/dist-types/draft-context.d.ts

@@ -0,0 +1,31 @@
+import type { ConsentKernel, SaveInput, SaveResult, SaveUISource } from '@c15t/core';
+import type { PreferenceDraft } from '@c15t/core/preference-draft';
+/**
+ * The draft a `ConsentDraftProvider` shares. Here, apart from the draft
+ * module, so the banner's buttons can read it without loading the draft:
+ * the draft only runs once a preference surface renders.
+ */
+export declare const DraftContext: import("react").Context<PreferenceDraft | null>;
+export declare const REFUSED: SaveResult;
+/** The kernel in context; throws outside a provider. */
+export declare const useDraftKernel: () => ConsentKernel;
+/**
+ * Whether `owner` is still the kernel this component last committed.
+ *
+ * A handle or save action kept across a runtime switch, by an async submit
+ * or a descendant's layout effect in the switch commit, calls through this,
+ * so it records nothing into the previous runtime. The committed kernel is
+ * read at call time (see `useCommittedRef`). A component that only unmounts
+ * keeps its last kernel, so a submit that outlives its dialog still saves.
+ */
+export declare const useKernelGuard: (owner: ConsentKernel) => () => boolean;
+/**
+ * Internal UI save path shared by stock controls and headless actions.
+ *
+ * Inside a `ConsentDraftProvider` an omitted input saves the shared draft.
+ * Bulk and explicit inputs go straight to the kernel; a bulk one also
+ * discards the draft's staged edits.
+ *
+ * @internal
+ */
+export declare const useConsentSaveAction: () => (input?: SaveInput, uiSource?: SaveUISource) => Promise<SaveResult>;

package/dist-types/draft.d.ts

@@ -1,31 +1,103 @@
-import type { AllConsentNames, ConsentState, SaveResult, SaveInput } from '@c15t/core';
+import type { AllConsentNames, ConsentState, SaveResult } from '@c15t/core';
+import type { PreferenceDraft, PreferenceDraftState } from '@c15t/core/preference-draft';
 import type { ReactNode } from 'react';
 /** A local, unmasked selection, committed only by an explicit save. */
 export interface ConsentDraftHandle {
     values: Readonly<ConsentState>;
     displayedCategories: readonly AllConsentNames[];
+    /**
+     * Granted flag per declared vendor. Seeded from the denials the gate
+     * honors, so a vendor declared `disabled` reads `true` whatever an older
+     * record says; every vendor not denied is `true`. Empty under an `iab`
+     * policy.
+     */
+    vendors: Readonly<Record<string, boolean>>;
     isDirty: boolean;
-    /** A material policy change requires reset and review before saving. */
+    /** A policy or displayed-category change requires reset and review before saving. */
     isStale: boolean;
     set: (category: AllConsentNames, value: boolean) => void;
     update: (patch: Partial<ConsentState>) => void;
+    /**
+     * Stage one vendor's grant. Recorded by the next save. Ignored for a
+     * vendor that is not declared or is declared `disabled`, since the kernel
+     * would drop the grant on save.
+     */
+    setVendor: (vendorId: string, granted: boolean) => void;
     acceptAll: () => void;
     rejectAll: () => void;
     save: () => Promise<SaveResult>;
     reset: () => void;
 }
+type DraftStore = PreferenceDraft;
 export interface ConsentDraftProviderProps {
     children: ReactNode;
     /** Defaults apply only to categories without an explicit receipt. */
     initial?: Partial<ConsentState>;
 }
+/**
+ * Share one draft with every draft hook and stock control below it. The
+ * preference dialog renders one, so its switches, vendor rows and save
+ * button stage into and confirm the same draft.
+ */
 export declare const ConsentDraftProvider: ({ children, initial, }: ConsentDraftProviderProps) => import("react").JSX.Element;
-/** Internal UI save path shared by stock controls and headless actions. */
-export declare const useConsentSaveAction: () => (input?: SaveInput) => Promise<SaveResult>;
-/** Keep the compatibility manager selection and its save on the same draft. */
-export declare const useConsentManagerDraft: () => {
-    draft: ConsentDraftHandle;
-    save: (input?: SaveInput) => Promise<SaveResult>;
-};
+/**
+ * The nearest consent draft, for the stock preference rows. Pair with
+ * {@link useConsentDraftSlice} so a row re-renders only when its own slice
+ * changes, not on every staged edit elsewhere in the draft.
+ *
+ * @returns The shared draft, or a local one outside a provider.
+ * @internal
+ */
+export declare const useConsentDraftStore: () => DraftStore;
+/**
+ * Subscribes to one slice of a consent draft.
+ *
+ * @param draft - Draft from {@link useConsentDraftStore}.
+ * @param selector - Picks the slice. Return a primitive or a reference the
+ * draft already holds.
+ * @returns The selected slice.
+ * @internal
+ */
+export declare const useConsentDraftSlice: <SliceType>(draft: DraftStore, selector: (state: PreferenceDraftState) => SliceType) => SliceType;
 /** Read and edit displayed choices without replacing masked effective permissions. */
 export declare const useConsentDraft: () => ConsentDraftHandle;
+/** The vendor slice of the consent draft, for a custom vendor control. */
+export interface VendorDraftHandle {
+    /** Granted flag per declared vendor. See {@link ConsentDraftHandle.vendors}. */
+    vendors: Readonly<Record<string, boolean>>;
+    /** Stage one vendor's grant for the next save. See {@link ConsentDraftHandle.setVendor}. */
+    setVendor: (vendorId: string, granted: boolean) => void;
+    /** Whether any draft value, category or vendor, differs from the record. */
+    isDirty: boolean;
+    /**
+     * Whether the policy or the vendor surface changed under an unsaved edit.
+     * `save` refuses a stale draft. See {@link ConsentDraftHandle.isStale}.
+     */
+    isStale: boolean;
+    /** Confirm the draft, categories and vendors together. */
+    save: () => Promise<SaveResult>;
+    /** Discard staged edits and reseed from the record. See {@link ConsentDraftHandle.reset}. */
+    reset: () => void;
+}
+/**
+ * Read and stage vendor grants on the same draft the category switches use.
+ * A custom vendor toggle needs only this; the categories stay where the
+ * stock widget or `useConsentDraft()` left them, and one save confirms both.
+ * When the policy or the vendor list changes under a staged edit the draft
+ * turns stale and `save` refuses it; `reset` reseeds it from the record.
+ *
+ * @returns The draft's vendor map, the setter, the dirty and stale flags,
+ * the save and the reset.
+ * @example
+ * ```tsx
+ * const { vendors, setVendor, isStale, reset, save } = useVendorDraft();
+ * <Switch
+ *   checked={vendors['meta-pixel'] ?? true}
+ *   onCheckedChange={(on) => setVendor('meta-pixel', on)}
+ * />;
+ * {isStale && <button onClick={reset}>Review again</button>}
+ * ```
+ * @public
+ */
+export declare const useVendorDraft: () => VendorDraftHandle;
+export {};

package/dist-types/gpp.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeGPPOptions } from '@c15t/core/runtime';
+/** Props for {@link ConsentGPP}: the GPP options, all optional. */
+export type ConsentGPPProps = RuntimeGPPOptions;
+/**
+ * Installs `window.__gpp`, the IAB GPP CMP API, on the surrounding
+ * provider's kernel and keeps its GPP string in step with the visitor's
+ * choices. Renders nothing. Unmounting removes `__gpp`.
+ *
+ * Render it inside `ConsentProvider` (or `ConsentRoot` in Next.js and
+ * TanStack Start). Every prop is plain data, so a Server Component can
+ * render it.
+ *
+ * @param props - GPP options. See `RuntimeGPPOptions`.
+ * @returns `null`.
+ * @throws {Error} When rendered outside a consent provider.
+ *
+ * @example
+ * ```tsx
+ * import { ConsentGPP } from '@c15t/react/gpp';
+ *
+ * <ConsentProvider options={{ mode: hosted({ backendURL }) }}>
+ *   <ConsentGPP usFallback="none" />
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ */
+export declare const ConsentGPP: ({ cmpId, mspaMode, optOutCategories, tcf, usApproach, usFallback, }: ConsentGPPProps) => null;

package/dist-types/headless.d.ts

@@ -5,10 +5,9 @@
  * Pair with `ConsentProvider` from `@c15t/react` (or `@c15t/react/provider`).
  */
 export { defaultTranslationConfig, detectBrowserLanguage, mergeTranslationConfigs, prepareTranslationConfig, } from '@c15t/core';
-export { type ConsentDialogTriggerVisibility, type UseConsentDialogTriggerOptions, type UseConsentDialogTriggerResult, useConsentDialogTrigger, } from './component-hooks/use-panel-trigger';
-export { useConsentManager } from './component-hooks/use-manager';
-export { type HeadlessConsentBannerAction, type HeadlessConsentBannerState, type HeadlessConsentDialogAction, type HeadlessConsentDialogState, type HeadlessConsentSurface, type HeadlessConsentSurfaceAction, type HeadlessConsentSurfaceState, type HeadlessConsentWriteAction, useHeadlessConsentUI, } from './component-hooks/use-headless-consent-ui';
-export { useTranslations } from './component-hooks/use-translations';
-export { useColorScheme } from './hooks/use-color-scheme';
-export { useFocusTrap } from './hooks/use-focus-trap';
-export type { ReactUIOptions } from './types/manager';
+export { type ConsentDialogTriggerVisibility, type UseConsentDialogTriggerOptions, type UseConsentDialogTriggerResult, useConsentDialogTrigger, } from './component-hooks/use-panel-trigger.js';
+export { type HeadlessConsentBannerAction, type HeadlessConsentBannerState, type HeadlessConsentDialogAction, type HeadlessConsentDialogState, type HeadlessConsentSurface, type HeadlessConsentSurfaceAction, type HeadlessConsentSurfaceState, type HeadlessConsentWriteAction, useHeadlessConsentUI, } from './component-hooks/use-headless-consent-ui.js';
+export { useTranslations } from './component-hooks/use-translations.js';
+export { useColorScheme } from './hooks/use-color-scheme.js';
+export { useFocusTrap } from './hooks/use-focus-trap.js';
+export type { ReactUIOptions } from './types/manager.js';

package/dist-types/hooks/use-committed-ref.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A ref that holds `value` from the render React most recently committed.
+ *
+ * Consent guards use it to answer "is this still the kernel, draft or IAB
+ * selection this component renders?" when a kept callback runs, including
+ * from a descendant's layout effect in the very commit that switched
+ * runtimes.
+ *
+ * Why an insertion effect: React runs insertion effects while it applies a
+ * commit, before any layout effect of that commit, and never for a render it
+ * discards. Assigning the ref during render would publish values from
+ * renders React throws away (an interrupted concurrent render, StrictMode's
+ * second render). A layout effect is too late, because descendants' layout
+ * effects run before their ancestors'. A passive effect is later still.
+ * Assigning the committed value is idempotent, so StrictMode's replayed
+ * effects cannot leave a stale value behind.
+ *
+ * @param value - The value this render uses.
+ * @returns A ref whose `current` is the last committed `value`.
+ * @internal
+ */
+export declare const useCommittedRef: <Value>(value: Value) => {
+    readonly current: Value;
+};

package/dist-types/hooks/use-focus-trap.d.ts

@@ -1,3 +1,4 @@
+import type { FocusTrapOptions } from '@c15t/ui/utils/dom';
 import type { RefObject } from 'react';
 /**
  * Hook that manages focus trapping within a container.
@@ -8,7 +9,8 @@ import type { RefObject } from 'react';
  *
  * @param shouldTrap - Boolean indicating whether focus should be trapped
  * @param containerRef - Reference to the container element
+ * @param options - Where the trap puts focus when it starts
  *
  * @public
  */
-export declare const useFocusTrap: (shouldTrap: boolean, containerRef: RefObject<HTMLElement | null> | null) => void;
+export declare const useFocusTrap: (shouldTrap: boolean, containerRef: RefObject<HTMLElement | null> | null, options?: FocusTrapOptions) => void;

package/dist-types/hooks/use-headless-iab-consent-ui.d.ts

@@ -1,5 +1,5 @@
 import type { HeadlessIABBannerAction, HeadlessIABDialogAction, HeadlessIABPreferenceTab } from '@c15t/iab/headless';
-import { useIABConsentManager } from './use-iab-manager';
+import { useIABConsentManager } from './use-iab-manager.js';
 export type { HeadlessIABBannerAction, HeadlessIABDialogAction, HeadlessIABPreferenceTab, };
 export interface HeadlessIABBannerState {
     isVisible: boolean;

package/dist-types/hooks/use-iab-manager.d.ts

@@ -1,7 +1,7 @@
 import type { ActiveUI, ConsentPresentation, TranslationConfig } from '@c15t/core';
 export declare const useIABConsentManager: (overrides?: ConsentPresentation) => {
     activeUI: ActiveUI;
-    iab: import("../iab-context").ReactIABState | null;
+    iab: import("../iab-context.js").ReactIABState | null;
     model: import("@c15t/core").KernelModel | null;
     policyBanner: {
         allowedActions: import("@c15t/core").PresentationAction[];
@@ -11,8 +11,8 @@ export declare const useIABConsentManager: (overrides?: ConsentPresentation) =>
         actionGroups: import("@c15t/core").PresentationAction[][];
         primaryActions: import("@c15t/core").PresentationAction[];
         diagnostics: import("@c15t/core").PresentationDiagnostic[];
-        rights: readonly import("@c15t/schema/types").PolicyRight[];
-        preferenceControls: Exclude<import("@c15t/schema/types").PolicyRight, 'disclosure'>[];
+        rights: readonly import("@c15t/schema").PolicyRight[];
+        preferenceControls: Exclude<import("@c15t/schema").PolicyRight, 'disclosure'>[];
         direction: 'row' | 'column';
         uiProfile: 'balanced' | 'compact' | 'strict';
         scrollLock: boolean;
@@ -32,8 +32,8 @@ export declare const useIABConsentManager: (overrides?: ConsentPresentation) =>
         actionGroups: import("@c15t/core").PresentationAction[][];
         primaryActions: import("@c15t/core").PresentationAction[];
         diagnostics: import("@c15t/core").PresentationDiagnostic[];
-        rights: readonly import("@c15t/schema/types").PolicyRight[];
-        preferenceControls: Exclude<import("@c15t/schema/types").PolicyRight, 'disclosure'>[];
+        rights: readonly import("@c15t/schema").PolicyRight[];
+        preferenceControls: Exclude<import("@c15t/schema").PolicyRight, 'disclosure'>[];
         direction: 'row' | 'column';
         uiProfile: 'balanced' | 'compact' | 'strict';
         scrollLock: boolean;

package/dist-types/hooks/use-iab-policy-guard.d.ts

@@ -0,0 +1,35 @@
+import { IABUnavailableError } from '@c15t/core';
+/**
+ * Record that `IABProvider` is part of the app. `@c15t/react/iab` calls
+ * this when it loads.
+ *
+ * @internal
+ */
+export declare const markIABProviderLoaded: () => void;
+/**
+ * The error the standard surfaces throw for an `iab` policy without
+ * `<IABProvider>`.
+ *
+ * @returns A fresh {@link IABUnavailableError}.
+ * @internal
+ */
+export declare const missingIABProviderError: () => IABUnavailableError;
+/**
+ * Throw while rendering when the visitor's policy needs a CMP and the app
+ * has none.
+ *
+ * The standard banner and dialog do not answer for the IAB model, so
+ * without `<IABProvider>` a visitor under an `iab` policy would see no
+ * consent UI at all. Throwing during render reaches error boundaries and
+ * framework error overlays, on the server render and in the browser alike,
+ * since both read the same snapshot.
+ *
+ * `<IABProvider>` usually sits beside the standard surfaces rather than
+ * around them, so a missing IAB context alone does not prove the app has
+ * none. The check also passes once `@c15t/react/iab` has loaded.
+ *
+ * @throws {IABUnavailableError} When the policy needs IAB and neither an
+ * IAB context nor `@c15t/react/iab` is present.
+ * @internal
+ */
+export declare const useIABPolicyGuard: () => void;

package/dist-types/hooks/use-late-entry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a banner that shows now arrives after the page has painted.
+ *
+ * Decided once each time `shown` turns on, and held while it stays on, so a
+ * re-render never restarts the entry. A banner hydrated from server HTML is
+ * part of the first paint: the hook answers `false` while hydrating, which
+ * also keeps the markup matching the server's.
+ *
+ * @param shown - Whether the banner is rendered.
+ * @returns Whether to mark the mount `data-entry="late"`.
+ *
+ * @internal
+ */
+export declare const useLateEntry: (shown: boolean) => boolean;

package/dist-types/hooks/use-theme.d.ts

@@ -1,2 +1,2 @@
-import type { ThemeContextValue } from '../context/theme-context';
+import type { ThemeContextValue } from '../context/theme-context.js';
 export declare const useTheme: () => ThemeContextValue;