@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/core/hooks/useVireoFullscreen/useVireoFullscreen.js

@@ -0,0 +1,63 @@
+import React from "react";
+const EMPTY_SUBSCRIBE = () => () => undefined;
+const GET_EMPTY_SNAPSHOT = () => null;
+function resolveSupportedTarget(target) {
+    if (target === null) {
+        throw new Error("useVireoFullscreen requires a target element.");
+    }
+    const ownerDocument = target.ownerDocument;
+    if (ownerDocument.fullscreenEnabled !== true ||
+        typeof target.requestFullscreen !== "function" ||
+        typeof ownerDocument.exitFullscreen !== "function") {
+        throw new Error("The Fullscreen API is not supported for the useVireoFullscreen target.");
+    }
+    return { target, ownerDocument };
+}
+/**
+ * Observes and controls the standard Fullscreen API for one target element.
+ */
+export function useVireoFullscreen(target) {
+    const targetRef = React.useRef(target);
+    targetRef.current = target;
+    const ownerDocument = target?.ownerDocument ?? null;
+    const subscribe = React.useCallback((listener) => {
+        if (ownerDocument === null)
+            return EMPTY_SUBSCRIBE();
+        ownerDocument.addEventListener("fullscreenchange", listener);
+        return () => ownerDocument.removeEventListener("fullscreenchange", listener);
+    }, [ownerDocument]);
+    const getSnapshot = React.useCallback(() => ownerDocument?.fullscreenElement ?? null, [ownerDocument]);
+    const fullscreenElement = React.useSyncExternalStore(subscribe, getSnapshot, GET_EMPTY_SNAPSHOT);
+    const isSupported = target !== null &&
+        ownerDocument?.fullscreenEnabled === true &&
+        typeof target.requestFullscreen === "function" &&
+        typeof ownerDocument.exitFullscreen === "function";
+    const enterFullscreen = React.useCallback(async (options) => {
+        const { target: currentTarget, ownerDocument: currentDocument } = resolveSupportedTarget(targetRef.current);
+        if (currentDocument.fullscreenElement === currentTarget)
+            return;
+        await currentTarget.requestFullscreen(options);
+    }, []);
+    const exitFullscreen = React.useCallback(async () => {
+        const { target: currentTarget, ownerDocument: currentDocument } = resolveSupportedTarget(targetRef.current);
+        if (currentDocument.fullscreenElement !== currentTarget)
+            return;
+        await currentDocument.exitFullscreen();
+    }, []);
+    const toggleFullscreen = React.useCallback(async (options) => {
+        const { target: currentTarget, ownerDocument: currentDocument } = resolveSupportedTarget(targetRef.current);
+        if (currentDocument.fullscreenElement === currentTarget) {
+            await currentDocument.exitFullscreen();
+            return;
+        }
+        await currentTarget.requestFullscreen(options);
+    }, []);
+    return {
+        isSupported,
+        isFullscreen: fullscreenElement === target && target !== null,
+        fullscreenElement,
+        enterFullscreen,
+        exitFullscreen,
+        toggleFullscreen,
+    };
+}

package/dist/core/hooks/useVireoFullscreen/useVireoFullscreen.types.d.ts

@@ -0,0 +1,14 @@
+export type VireoFullscreen = {
+    /** Whether the target's owner document exposes the standard Fullscreen API. */
+    isSupported: boolean;
+    /** Whether the target itself is the current fullscreen element. */
+    isFullscreen: boolean;
+    /** The target owner document's current fullscreen element, including external owners. */
+    fullscreenElement: Element | null;
+    /** Requests fullscreen for the target. */
+    enterFullscreen: (options?: FullscreenOptions) => Promise<void>;
+    /** Exits fullscreen only when the target owns it. */
+    exitFullscreen: () => Promise<void>;
+    /** Enters or exits fullscreen according to whether the target owns it. */
+    toggleFullscreen: (options?: FullscreenOptions) => Promise<void>;
+};

package/dist/core/hooks/useVireoFullscreen/useVireoFullscreen.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/hooks/useVireoIcons/useVireoIcons.d.ts

@@ -0,0 +1,2 @@
+/** Returns the icon components registered by VireoIconRegistryProvider. */
+export declare function useVireoIcons(): import("../../../core/providers/VireoIconRegistryProvider/VireoIconRegistryProvider.js").VireoIconRegistryContextValue;

package/dist/core/hooks/useVireoIcons/useVireoIcons.js

@@ -0,0 +1,9 @@
+import { VireoIconRegistryContext } from "../../../core/providers/VireoIconRegistryProvider/VireoIconRegistryProvider.js";
+import React from "react";
+/** Returns the icon components registered by VireoIconRegistryProvider. */
+export function useVireoIcons() {
+    const context = React.useContext(VireoIconRegistryContext);
+    if (!context)
+        throw new Error("useVireoIcons must be used within VireoIconRegistryProvider");
+    return context;
+}

package/dist/core/hooks/useVireoOnlineStatus/useVireoOnlineStatus.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Subscribes a React owner to the browser's online/offline status.
+ *
+ * The browser signal is a connectivity hint, not proof that an application
+ * endpoint is reachable. Use Infrastructure's connectivity state when a
+ * heartbeat-backed health decision is required.
+ */
+export declare function useVireoOnlineStatus(): boolean;

package/dist/core/hooks/useVireoOnlineStatus/useVireoOnlineStatus.js

@@ -0,0 +1,12 @@
+import { getAppOnlineStatus, subscribeToAppNetworkStatus } from "@vireocodedev/infrastructure/network-status";
+import React from "react";
+/**
+ * Subscribes a React owner to the browser's online/offline status.
+ *
+ * The browser signal is a connectivity hint, not proof that an application
+ * endpoint is reachable. Use Infrastructure's connectivity state when a
+ * heartbeat-backed health decision is required.
+ */
+export function useVireoOnlineStatus() {
+    return React.useSyncExternalStore(subscribeToAppNetworkStatus, getAppOnlineStatus, () => true);
+}

package/dist/core/hooks/useVireoSearchParamState/useVireoSearchParamState.d.ts

@@ -0,0 +1,10 @@
+import type { VireoNullableSearchParamStateOptions, VireoSearchParamCodec, VireoSearchParamStateOptions, VireoSearchParamStateResult, VireoStringSearchParamStateOptions } from "./useVireoSearchParamState.types.js";
+export type { VireoNullableSearchParamStateOptions, VireoSearchParamCodec, VireoSearchParamHistory, VireoSearchParamStateOptions, VireoSearchParamStateResult, VireoSearchParamStateSetter, VireoStringSearchParamStateOptions, } from "./useVireoSearchParamState.types.js";
+export declare const vireoSearchParamCodecs: Readonly<{
+    string: VireoSearchParamCodec<string>;
+    number: VireoSearchParamCodec<number>;
+    boolean: VireoSearchParamCodec<boolean>;
+}>;
+export declare function useVireoSearchParamState(key: string, options: VireoStringSearchParamStateOptions): VireoSearchParamStateResult<string>;
+export declare function useVireoSearchParamState<T>(key: string, options: VireoNullableSearchParamStateOptions<T>): VireoSearchParamStateResult<T | null>;
+export declare function useVireoSearchParamState<T extends NonNullable<unknown>>(key: string, options: VireoSearchParamStateOptions<T>): VireoSearchParamStateResult<T>;

package/dist/core/hooks/useVireoSearchParamState/useVireoSearchParamState.js

@@ -0,0 +1,239 @@
+import React from "react";
+const DECIMAL_NUMBER_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const stringCodec = Object.freeze({
+    parse: (rawValue) => rawValue,
+    serialize: (value) => {
+        if (typeof value !== "string")
+            throw new TypeError("The Vireo string search-parameter codec requires a string.");
+        return value;
+    },
+});
+const numberCodec = Object.freeze({
+    parse: (rawValue) => {
+        if (!DECIMAL_NUMBER_PATTERN.test(rawValue))
+            throw new TypeError("Invalid decimal search-parameter value.");
+        const value = Number(rawValue);
+        if (!Number.isFinite(value))
+            throw new TypeError("Invalid finite search-parameter number.");
+        return value;
+    },
+    serialize: (value) => {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new TypeError("The Vireo number search-parameter codec requires a finite number.");
+        }
+        return Object.is(value, -0) ? "0" : String(value);
+    },
+});
+const booleanCodec = Object.freeze({
+    parse: (rawValue) => {
+        if (rawValue === "true")
+            return true;
+        if (rawValue === "false")
+            return false;
+        throw new TypeError("Invalid boolean search-parameter value.");
+    },
+    serialize: (value) => {
+        if (typeof value !== "boolean")
+            throw new TypeError("The Vireo boolean search-parameter codec requires a boolean.");
+        return value ? "true" : "false";
+    },
+});
+export const vireoSearchParamCodecs = Object.freeze({
+    string: stringCodec,
+    number: numberCodec,
+    boolean: booleanCodec,
+});
+class CodecContractError extends TypeError {
+}
+const listeners = new Set();
+let subscribedWindow = null;
+function emitStoreChange() {
+    for (const listener of [...listeners])
+        listener();
+}
+function handlePopState() {
+    emitStoreChange();
+}
+function subscribe(listener) {
+    if (typeof window === "undefined")
+        return () => undefined;
+    if (subscribedWindow !== window) {
+        subscribedWindow?.removeEventListener("popstate", handlePopState);
+        subscribedWindow = window;
+        subscribedWindow.addEventListener("popstate", handlePopState);
+    }
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0 && subscribedWindow !== null) {
+            subscribedWindow.removeEventListener("popstate", handlePopState);
+            subscribedWindow = null;
+        }
+    };
+}
+function getBrowserSnapshot() {
+    return window.location.search;
+}
+function getServerSnapshot() {
+    return "";
+}
+function validateKey(key) {
+    if (typeof key !== "string" || key.length === 0 || key.trim() !== key) {
+        throw new TypeError("useVireoSearchParamState key must be a non-empty string without surrounding whitespace.");
+    }
+}
+function serializeCodecValue(codec, value) {
+    const serialized = codec.serialize(value);
+    if (typeof serialized !== "string") {
+        throw new TypeError("useVireoSearchParamState codec.serialize must return a string.");
+    }
+    return serialized;
+}
+function resolveConfiguration(key, options) {
+    validateKey(key);
+    if (options.defaultValue === undefined) {
+        throw new TypeError("useVireoSearchParamState defaultValue must not be undefined.");
+    }
+    const nullable = options.defaultValue === null;
+    const codec = options.codec ?? (typeof options.defaultValue === "string" ? stringCodec : undefined);
+    if (codec === undefined) {
+        throw new TypeError("useVireoSearchParamState requires a codec for non-string and nullable state.");
+    }
+    if (typeof codec.parse !== "function" || typeof codec.serialize !== "function") {
+        throw new TypeError("useVireoSearchParamState codec must provide parse and serialize functions.");
+    }
+    const history = options.history ?? "replace";
+    if (history !== "replace" && history !== "push") {
+        throw new TypeError('useVireoSearchParamState history must be either "replace" or "push".');
+    }
+    const keepDefaultInUrl = options.keepDefaultInUrl ?? false;
+    if (typeof keepDefaultInUrl !== "boolean") {
+        throw new TypeError("useVireoSearchParamState keepDefaultInUrl must be a boolean.");
+    }
+    if (nullable && keepDefaultInUrl) {
+        throw new TypeError("useVireoSearchParamState cannot keep a null default value in the URL.");
+    }
+    return {
+        key,
+        defaultValue: options.defaultValue,
+        defaultSerialized: nullable ? null : serializeCodecValue(codec, options.defaultValue),
+        codec,
+        history,
+        keepDefaultInUrl,
+        nullable,
+    };
+}
+function fallbackReadResult(configuration, rawValues) {
+    const desiredUrlRaw = configuration.keepDefaultInUrl ? configuration.defaultSerialized : null;
+    return {
+        value: configuration.defaultValue,
+        canonicalValueRaw: configuration.defaultSerialized,
+        desiredUrlRaw,
+        urlIsCanonical: desiredUrlRaw === null ? rawValues.length === 0 : rawValues.length === 1 && rawValues[0] === desiredUrlRaw,
+    };
+}
+function readSearchParam(configuration, search) {
+    const rawValues = new URLSearchParams(search).getAll(configuration.key);
+    if (rawValues.length === 0)
+        return fallbackReadResult(configuration, rawValues);
+    let value;
+    try {
+        value = configuration.codec.parse(rawValues[0]);
+    }
+    catch (error) {
+        if (error instanceof CodecContractError)
+            throw error;
+        return fallbackReadResult(configuration, rawValues);
+    }
+    if (value === null || value === undefined) {
+        throw new CodecContractError("useVireoSearchParamState codec.parse must not return null or undefined.");
+    }
+    let canonicalValueRaw;
+    try {
+        canonicalValueRaw = serializeCodecValue(configuration.codec, value);
+    }
+    catch {
+        return fallbackReadResult(configuration, rawValues);
+    }
+    const isDefault = !configuration.nullable && canonicalValueRaw === configuration.defaultSerialized;
+    const desiredUrlRaw = isDefault && !configuration.keepDefaultInUrl ? null : canonicalValueRaw;
+    return {
+        value,
+        canonicalValueRaw,
+        desiredUrlRaw,
+        urlIsCanonical: desiredUrlRaw === null ? rawValues.length === 0 : rawValues.length === 1 && rawValues[0] === desiredUrlRaw,
+    };
+}
+function writeSearchParam(configuration, rawValue, history) {
+    const url = new URL(window.location.href);
+    if (rawValue === null)
+        url.searchParams.delete(configuration.key);
+    else
+        url.searchParams.set(configuration.key, rawValue);
+    const method = history === "push" ? "pushState" : "replaceState";
+    window.history[method](window.history.state, "", url);
+    emitStoreChange();
+}
+function serializeNextValue(configuration, value) {
+    if (value === undefined) {
+        throw new TypeError("useVireoSearchParamState state must not be undefined.");
+    }
+    if (value === null) {
+        if (!configuration.nullable) {
+            throw new TypeError("useVireoSearchParamState non-null state must not be null.");
+        }
+        return { canonicalValueRaw: null, desiredUrlRaw: null };
+    }
+    const canonicalValueRaw = serializeCodecValue(configuration.codec, value);
+    const isDefault = !configuration.nullable && canonicalValueRaw === configuration.defaultSerialized;
+    return {
+        canonicalValueRaw,
+        desiredUrlRaw: isDefault && !configuration.keepDefaultInUrl ? null : canonicalValueRaw,
+    };
+}
+/**
+ * Synchronizes one scalar React state value with one URL search parameter.
+ *
+ * Hook instances sharing a key must use compatible codecs, defaults, and default-retention policy.
+ */
+export function useVireoSearchParamState(key, options) {
+    const configuration = resolveConfiguration(key, options);
+    const configurationRef = React.useRef(configuration);
+    configurationRef.current = configuration;
+    const search = React.useSyncExternalStore(subscribe, getBrowserSnapshot, getServerSnapshot);
+    const readResult = readSearchParam(configuration, search);
+    React.useEffect(() => {
+        if (typeof window === "undefined" || window.location.search !== search || readResult.urlIsCanonical)
+            return;
+        try {
+            writeSearchParam(configurationRef.current, readResult.desiredUrlRaw, "replace");
+        }
+        catch {
+            // URL cleanup is best-effort: state still safely falls back to the configured default.
+        }
+    }, [
+        configuration.codec,
+        configuration.defaultSerialized,
+        configuration.keepDefaultInUrl,
+        configuration.key,
+        readResult.desiredUrlRaw,
+        readResult.urlIsCanonical,
+        search,
+    ]);
+    const setValue = React.useCallback(valueOrUpdater => {
+        if (typeof window === "undefined") {
+            throw new Error("useVireoSearchParamState cannot update search parameters outside a browser environment.");
+        }
+        const currentConfiguration = configurationRef.current;
+        const current = readSearchParam(currentConfiguration, window.location.search);
+        const nextValue = typeof valueOrUpdater === "function"
+            ? valueOrUpdater(current.value)
+            : valueOrUpdater;
+        const next = serializeNextValue(currentConfiguration, nextValue);
+        if (current.urlIsCanonical && current.desiredUrlRaw === next.desiredUrlRaw)
+            return;
+        const history = current.canonicalValueRaw === next.canonicalValueRaw ? "replace" : currentConfiguration.history;
+        writeSearchParam(currentConfiguration, next.desiredUrlRaw, history);
+    }, []);
+    return [readResult.value, setValue];
+}

package/dist/core/hooks/useVireoSearchParamState/useVireoSearchParamState.types.d.ts

@@ -0,0 +1,29 @@
+export interface VireoSearchParamCodec<T> {
+    /** Parses one decoded URLSearchParams value. Throw when the external value is invalid. */
+    parse(rawValue: string): T;
+    /** Serializes one value without applying URL percent encoding. */
+    serialize(value: T): string;
+}
+export type VireoSearchParamHistory = "replace" | "push";
+type VireoSearchParamCommonOptions = {
+    /** @default 'replace' */
+    history?: VireoSearchParamHistory;
+    /** @default false */
+    keepDefaultInUrl?: boolean;
+};
+export interface VireoStringSearchParamStateOptions extends VireoSearchParamCommonOptions {
+    defaultValue: string;
+    codec?: VireoSearchParamCodec<string>;
+}
+export interface VireoSearchParamStateOptions<T extends NonNullable<unknown>> extends VireoSearchParamCommonOptions {
+    defaultValue: T;
+    codec: VireoSearchParamCodec<T>;
+}
+export interface VireoNullableSearchParamStateOptions<T> extends Omit<VireoSearchParamCommonOptions, "keepDefaultInUrl"> {
+    defaultValue: null;
+    codec: VireoSearchParamCodec<T>;
+    keepDefaultInUrl?: false;
+}
+export type VireoSearchParamStateSetter<T> = (value: T | ((currentValue: T) => T)) => void;
+export type VireoSearchParamStateResult<T> = readonly [value: T, setValue: VireoSearchParamStateSetter<T>];
+export {};

package/dist/core/hooks/useVireoSearchParamState/useVireoSearchParamState.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/hooks/useVireoTransitionPresence/useVireoTransitionPresence.d.ts

@@ -0,0 +1,6 @@
+import type { UseVireoTransitionPresenceOptions, VireoTransitionPresence } from "./useVireoTransitionPresence.types.js";
+export type { UseVireoTransitionPresenceOptions, VireoTransitionPresence } from "./useVireoTransitionPresence.types.js";
+/**
+ * Retains a non-null value while an external transition finishes its exit.
+ */
+export declare function useVireoTransitionPresence<TValue>(value: TValue | null, { onExited }?: UseVireoTransitionPresenceOptions): VireoTransitionPresence<TValue>;

package/dist/core/hooks/useVireoTransitionPresence/useVireoTransitionPresence.js

@@ -0,0 +1,58 @@
+import React from "react";
+const useBrowserLayoutEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
+/**
+ * Retains a non-null value while an external transition finishes its exit.
+ */
+export function useVireoTransitionPresence(value, { onExited } = {}) {
+    const initialState = React.useRef({
+        visible: value !== null,
+        renderedValue: value,
+        exitPending: false,
+    });
+    const [state, setState] = React.useState(initialState.current);
+    const stateRef = React.useRef(state);
+    const latestNonNullValueRef = React.useRef(value);
+    const onExitedRef = React.useRef(onExited);
+    onExitedRef.current = onExited;
+    if (value !== null)
+        latestNonNullValueRef.current = value;
+    const commitState = React.useCallback((nextState) => {
+        stateRef.current = nextState;
+        setState(nextState);
+    }, []);
+    useBrowserLayoutEffect(() => {
+        const currentState = stateRef.current;
+        if (value !== null) {
+            if (!currentState.visible || currentState.exitPending) {
+                commitState({ visible: true, renderedValue: value, exitPending: false });
+            }
+            return;
+        }
+        if (currentState.visible && currentState.renderedValue !== null) {
+            commitState({
+                visible: false,
+                renderedValue: latestNonNullValueRef.current,
+                exitPending: true,
+            });
+        }
+    }, [commitState, value]);
+    const dismiss = React.useCallback(() => {
+        const currentState = stateRef.current;
+        if (!currentState.visible || currentState.renderedValue === null)
+            return;
+        commitState({
+            visible: false,
+            renderedValue: latestNonNullValueRef.current,
+            exitPending: true,
+        });
+    }, [commitState]);
+    const completeExit = React.useCallback(() => {
+        const currentState = stateRef.current;
+        if (!currentState.exitPending || currentState.visible)
+            return;
+        commitState({ visible: false, renderedValue: null, exitPending: false });
+        onExitedRef.current?.();
+    }, [commitState]);
+    const renderedValue = state.visible && value !== null ? value : state.renderedValue;
+    return React.useMemo(() => ({ visible: state.visible, renderedValue, dismiss, completeExit }), [completeExit, dismiss, renderedValue, state.visible]);
+}

package/dist/core/hooks/useVireoTransitionPresence/useVireoTransitionPresence.types.d.ts

@@ -0,0 +1,14 @@
+export type UseVireoTransitionPresenceOptions = {
+    /** Runs after an exit cycle completes and the retained value has been cleared. */
+    onExited?: () => void;
+};
+export type VireoTransitionPresence<TValue> = {
+    /** Whether the transition should currently render its entered state. */
+    visible: boolean;
+    /** The latest non-null value retained until an active exit completes. */
+    renderedValue: TValue | null;
+    /** Starts an exit while preserving the rendered value. */
+    dismiss: () => void;
+    /** Completes the active exit and clears the rendered value. */
+    completeExit: () => void;
+};

package/dist/core/hooks/useVireoTransitionPresence/useVireoTransitionPresence.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/providers/VireoIconRegistryProvider/VireoIconRegistryProvider.d.ts

@@ -0,0 +1,27 @@
+import { type SvgIcon } from "@mui/material";
+import React from "react";
+declare const BUILT_IN_ICON_REGISTRY: {
+    readonly "check-circle": () => React.JSX.Element;
+    readonly "x-circle": () => React.JSX.Element;
+};
+export type VireoBuiltInIconName = keyof typeof BUILT_IN_ICON_REGISTRY;
+/** Augment this interface to register application-owned icons by name. */
+export interface VireoIconRegistry extends Record<VireoBuiltInIconName, React.ComponentType> {
+}
+export type VireoIconName = keyof VireoIconRegistry;
+type IconsFromRegistry = {
+    [TIconName in VireoIconName]: React.ComponentType;
+};
+export type VireoIconRegistryContextValue = {
+    muiIconsMap: {
+        [TIconName in VireoIconName]: typeof SvgIcon;
+    };
+};
+export declare const VireoIconRegistryContext: React.Context<VireoIconRegistryContextValue | undefined>;
+export type VireoIconRegistryProviderProps = React.PropsWithChildren<{
+    /** Application icon geometry keyed by the augmented registry names. Built-in icons may be overridden. */
+    icons?: Partial<IconsFromRegistry> & Record<string, React.ComponentType>;
+}>;
+/** Provides the typed icon registry consumed by VireoIcon. */
+export declare function VireoIconRegistryProvider({ children, icons }: VireoIconRegistryProviderProps): React.JSX.Element;
+export {};

package/dist/core/providers/VireoIconRegistryProvider/VireoIconRegistryProvider.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createSvgIcon } from "@mui/material";
+import React from "react";
+const BUILT_IN_ICON_REGISTRY = {
+    "check-circle": () => (_jsx("path", { d: "M7.5 12L10.5 15L16.5 9M22 12C22 17.5228 17.5228 22 12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12Z", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" })),
+    "x-circle": () => (_jsx("path", { d: "M15 9L9 15M9 9L15 15M22 12C22 17.5228 17.5228 22 12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12Z", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" })),
+};
+export const VireoIconRegistryContext = React.createContext(undefined);
+/** Provides the typed icon registry consumed by VireoIcon. */
+export function VireoIconRegistryProvider({ children, icons = {} }) {
+    const muiIconsMap = React.useMemo(() => {
+        const mergedIcons = { ...BUILT_IN_ICON_REGISTRY, ...icons };
+        return Object.fromEntries(Object.entries(mergedIcons).map(([iconName, IconComponent]) => [
+            iconName,
+            createSvgIcon(_jsx(IconComponent, {}), String(iconName)),
+        ]));
+    }, [icons]);
+    return _jsx(VireoIconRegistryContext.Provider, { value: { muiIconsMap }, children: children });
+}

package/dist/core/providers/VireoProviderComposer/VireoProviderComposer.d.ts

@@ -0,0 +1,4 @@
+import type { VireoProviderComposerProps } from "./VireoProviderComposer.types.js";
+/** Composes configured provider wrappers from outermost to innermost without obscuring their props. */
+export declare function VireoProviderComposer({ children, providers }: VireoProviderComposerProps): import("react").JSX.Element;
+export type { VireoProviderComposerProps, VireoProviderWrapper } from "./VireoProviderComposer.types.js";

package/dist/core/providers/VireoProviderComposer/VireoProviderComposer.js

@@ -0,0 +1,5 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/** Composes configured provider wrappers from outermost to innermost without obscuring their props. */
+export function VireoProviderComposer({ children, providers }) {
+    return _jsx(_Fragment, { children: providers.reduceRight((nestedChildren, wrap) => wrap(nestedChildren), children) });
+}

package/dist/core/providers/VireoProviderComposer/VireoProviderComposer.types.d.ts

@@ -0,0 +1,8 @@
+import type React from "react";
+/** Wraps already-composed children with one configured provider. */
+export type VireoProviderWrapper = (children: React.ReactNode) => React.ReactElement;
+export type VireoProviderComposerProps = {
+    children: React.ReactNode;
+    /** Provider wrappers ordered from outermost to innermost. */
+    providers: readonly VireoProviderWrapper[];
+};

package/dist/core/providers/VireoProviderComposer/VireoProviderComposer.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/providers/VireoThemeColorMeta/VireoThemeColorMeta.d.ts

@@ -0,0 +1,4 @@
+import type { VireoThemeColorMetaProps } from "./VireoThemeColorMeta.types.js";
+/** Owns one browser theme-color meta tag without disturbing other media-specific variants. */
+export declare function VireoThemeColorMeta({ color, media: mediaProp }: VireoThemeColorMetaProps): null;
+export type { VireoThemeColorMetaProps } from "./VireoThemeColorMeta.types.js";

package/dist/core/providers/VireoThemeColorMeta/VireoThemeColorMeta.js

@@ -0,0 +1,36 @@
+import { useTheme } from "@mui/material/styles";
+import React from "react";
+function findThemeColorMeta(media) {
+    return Array.from(document.head.querySelectorAll('meta[name="theme-color"]')).find(meta => media === undefined ? !meta.hasAttribute("media") : meta.getAttribute("media") === media);
+}
+/** Owns one browser theme-color meta tag without disturbing other media-specific variants. */
+export function VireoThemeColorMeta({ color, media: mediaProp }) {
+    const theme = useTheme();
+    const resolvedColor = color ?? theme.palette.background.paper;
+    const media = mediaProp?.trim() || undefined;
+    React.useEffect(() => {
+        const existing = findThemeColorMeta(media);
+        const meta = existing ?? document.createElement("meta");
+        const hadContent = meta.hasAttribute("content");
+        const previousContent = meta.getAttribute("content");
+        if (!existing) {
+            meta.setAttribute("name", "theme-color");
+            if (media)
+                meta.setAttribute("media", media);
+            document.head.append(meta);
+        }
+        meta.setAttribute("content", resolvedColor);
+        return () => {
+            if (!existing) {
+                meta.remove();
+            }
+            else if (hadContent) {
+                meta.setAttribute("content", previousContent ?? "");
+            }
+            else {
+                meta.removeAttribute("content");
+            }
+        };
+    }, [media, resolvedColor]);
+    return null;
+}

package/dist/core/providers/VireoThemeColorMeta/VireoThemeColorMeta.types.d.ts

@@ -0,0 +1,6 @@
+export type VireoThemeColorMetaProps = {
+    /** Explicit browser theme color. Defaults to `theme.palette.background.paper`. */
+    color?: string;
+    /** Optional media query identifying a dedicated theme-color tag. */
+    media?: string;
+};

package/dist/core/providers/VireoThemeColorMeta/VireoThemeColorMeta.types.js

@@ -0,0 +1 @@
+export {};