@omnitron-dev/prism 0.2.0 → 0.3.1

package/dist/core/provider-stack.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Provider Stack Utilities
+ *
+ * Composable provider pattern for building flexible provider hierarchies.
+ *
+ * @module core/provider-stack
+ */
+import type { ReactNode, ComponentType, FC } from 'react';
+/**
+ * A provider component with its props.
+ */
+export type ProviderEntry<P = Record<string, unknown>> = [ComponentType<P & {
+    children: ReactNode;
+}>, P];
+/**
+ * A provider that takes only children.
+ */
+export type SimpleProvider = ComponentType<{
+    children: ReactNode;
+}>;
+/**
+ * Provider entry that can be a simple component or a tuple with props.
+ */
+export type ProviderConfig = SimpleProvider | ProviderEntry;
+/**
+ * Options for createProviderStack.
+ */
+export interface ProviderStackOptions {
+    /** Display name for debugging */
+    displayName?: string;
+}
+/**
+ * Compose multiple providers into a single component.
+ * Providers are applied from left to right (first provider wraps outermost).
+ *
+ * @param providers - Array of providers to compose
+ * @returns A single component that renders all providers
+ *
+ * @example
+ * ```tsx
+ * const AppProviders = composeProviders([
+ *   ThemeProvider,
+ *   [AuthProvider, { client: authClient }],
+ *   [QueryProvider, { client: queryClient }],
+ *   ToastProvider,
+ * ]);
+ *
+ * function App() {
+ *   return (
+ *     <AppProviders>
+ *       <YourApp />
+ *     </AppProviders>
+ *   );
+ * }
+ * ```
+ */
+export declare function composeProviders(providers: ProviderConfig[]): FC<{
+    children: ReactNode;
+}>;
+/**
+ * Create a provider stack factory for building customizable provider hierarchies.
+ *
+ * @param baseProviders - Base providers that are always included
+ * @param options - Configuration options
+ * @returns A factory function for creating provider components
+ *
+ * @example
+ * ```tsx
+ * // Define base stack
+ * const createAppProviders = createProviderStack([
+ *   ThemeProvider,
+ *   [I18nProvider, { locale: 'en' }],
+ * ]);
+ *
+ * // Create with additional providers
+ * const AppProviders = createAppProviders({
+ *   prepend: [ErrorBoundaryProvider],
+ *   append: [ToastProvider, NotificationProvider],
+ * });
+ *
+ * // Or use without modifications
+ * const SimpleProviders = createAppProviders();
+ * ```
+ */
+export declare function createProviderStack(baseProviders: ProviderConfig[], options?: ProviderStackOptions): (config?: {
+    prepend?: ProviderConfig[];
+    append?: ProviderConfig[];
+    replace?: ProviderConfig[];
+}) => FC<{
+    children: ReactNode;
+}>;
+/**
+ * Props for ProviderStack component.
+ */
+export interface ProviderStackProps {
+    /** Provider configurations */
+    providers: ProviderConfig[];
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * ProviderStack - Declarative provider composition component.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const providers = useMemo(() => [
+ *     ThemeProvider,
+ *     [AuthProvider, { client }],
+ *     ToastProvider,
+ *   ], [client]);
+ *
+ *   return (
+ *     <ProviderStack providers={providers}>
+ *       <YourApp />
+ *     </ProviderStack>
+ *   );
+ * }
+ * ```
+ */
+export declare function ProviderStack({ providers, children }: ProviderStackProps): ReactNode;
+/**
+ * Create a provider component with bound props.
+ * Useful for creating reusable provider configurations.
+ *
+ * @param Provider - The provider component
+ * @param props - Props to bind to the provider
+ * @returns A new component with bound props
+ *
+ * @example
+ * ```tsx
+ * const BoundQueryProvider = withProviderProps(QueryClientProvider, {
+ *   client: queryClient,
+ * });
+ *
+ * // Use like a simple provider
+ * <BoundQueryProvider>
+ *   <App />
+ * </BoundQueryProvider>
+ * ```
+ */
+export declare function withProviderProps<P extends object>(Provider: ComponentType<P & {
+    children: ReactNode;
+}>, props: P): SimpleProvider;
+/**
+ * Create a conditional provider that only renders when condition is true.
+ *
+ * @param Provider - The provider component
+ * @param condition - Whether to render the provider
+ * @returns A provider that renders conditionally
+ *
+ * @example
+ * ```tsx
+ * const providers = [
+ *   ThemeProvider,
+ *   conditionalProvider(DevToolsProvider, process.env.NODE_ENV === 'development'),
+ *   AuthProvider,
+ * ];
+ * ```
+ */
+export declare function conditionalProvider<P extends {
+    children: ReactNode;
+}>(Provider: ComponentType<P>, condition: boolean, props?: Omit<P, 'children'>): ProviderConfig | null;
+/**
+ * Filter out null/undefined providers from a provider array.
+ *
+ * @param providers - Array of providers that may contain nulls
+ * @returns Filtered array of valid providers
+ *
+ * @example
+ * ```tsx
+ * const providers = filterProviders([
+ *   ThemeProvider,
+ *   conditionalProvider(DevToolsProvider, isDev),
+ *   conditionalProvider(MockProvider, isMocking),
+ *   AuthProvider,
+ * ]);
+ * ```
+ */
+export declare function filterProviders(providers: (ProviderConfig | null | undefined)[]): ProviderConfig[];
+//# sourceMappingURL=provider-stack.d.ts.map

package/dist/core/provider-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-stack.d.ts","sourceRoot":"","sources":["../../src/core/provider-stack.tsx"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAG1D;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEzG;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,aAAa,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAYzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,cAAc,EAAE,EAC/B,OAAO,GAAE,oBAAyB,GACjC,CAAC,MAAM,CAAC,EAAE;IACX,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B,KAAK,EAAE,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAYhC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,uBAAuB;IACvB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAGpF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,QAAQ,EAAE,aAAa,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,EACpD,KAAK,EAAE,CAAC,GACP,cAAc,CAKhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACnE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,SAAS,EAAE,OAAO,EAClB,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,GAC1B,cAAc,GAAG,IAAI,CAMvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,cAAc,EAAE,CAElG"}

package/dist/core/provider.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Prism Provider
+ *
+ * Root provider for the Prism design system.
+ * Uses useSettingsStore (Zustand) as the single source of truth for settings.
+ *
+ * @module core/provider
+ */
+import type { ReactNode } from 'react';
+import type { PartialPrismConfig } from '../types/config.js';
+import type { PrismSettingsState } from './context.js';
+export interface PrismThemeOverrideContext {
+    /** Actual palette mode after resolving the operating-system preference. */
+    mode: 'light' | 'dark';
+}
+export type PrismThemeOverrides = Record<string, unknown> | ((context: PrismThemeOverrideContext) => Record<string, unknown>);
+/**
+ * Props for PrismProvider.
+ */
+export interface PrismProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** Configuration overrides */
+    config?: PartialPrismConfig;
+    /** Default settings (overrides defaults but not persisted values) */
+    defaultSettings?: Partial<PrismSettingsState>;
+    /** Disable CSS baseline */
+    disableCssBaseline?: boolean;
+    /** Static overrides or an application palette derived from the resolved native mode. */
+    themeOverrides?: PrismThemeOverrides;
+    /**
+     * Locale code passed to MUI's `LocalizationProvider` as
+     * `adapterLocale` — e.g. `'ru'`, `'en'`. Must be a locale already
+     * registered with dayjs (e.g. `import 'dayjs/locale/ru'`).
+     * Switches calendar month/weekday labels and date masks.
+     * If omitted, MUI falls back to dayjs's global locale (English).
+     */
+    dateAdapterLocale?: string;
+    /**
+     * Override for MUI x-date-pickers' built-in strings
+     * (e.g. ARIA labels, toolbar text). Passed straight through to
+     * `LocalizationProvider.localeText`. Typically pulled from
+     * `@mui/x-date-pickers/locales` (e.g. `ruRU.components.MuiLocalizationProvider.defaultProps.localeText`).
+     */
+    dateLocaleText?: Record<string, unknown>;
+}
+/**
+ * PrismProvider - Root provider for Prism design system.
+ *
+ * Provides theme, settings, and configuration to all child components.
+ * Uses Zustand's useSettingsStore as the single source of truth for settings.
+ *
+ * @example
+ * ```tsx
+ * import { PrismProvider } from '@omnitron-dev/prism';
+ *
+ * function App() {
+ *   return (
+ *     <PrismProvider
+ *       config={{
+ *         theme: { preset: 'luxury', mode: 'dark' },
+ *         features: { darkMode: true, rtl: true },
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </PrismProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function PrismProvider({ children, config: configOverrides, defaultSettings, disableCssBaseline, themeOverrides, dateAdapterLocale, dateLocaleText, }: PrismProviderProps): ReactNode;
+//# sourceMappingURL=provider.d.ts.map

package/dist/core/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/core/provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAI1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAKvD,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,CAAC,CAAC,OAAO,EAAE,yBAAyB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uBAAuB;IACvB,QAAQ,EAAE,SAAS,CAAC;IACpB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9C,2BAA2B;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wFAAwF;IACxF,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AA6BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,MAAM,EAAE,eAAe,EACvB,eAAe,EACf,kBAA0B,EAC1B,cAAc,EACd,iBAAiB,EACjB,cAAc,GACf,EAAE,kBAAkB,GAAG,SAAS,CAwLhC"}