@mhmo91/schmancy 0.4.72 → 0.4.74

package/types/src/area/route.test.d.ts

@@ -0,0 +1,20 @@
+import './area.component';
+import './area-route.component';
+declare const TestHome_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+declare class TestHome extends TestHome_base {
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare const TestAbout_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+declare class TestAbout extends TestAbout_base {
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare const TestUser_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+declare class TestUser extends TestUser_base {
+    userId?: string;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare const TestApp_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+declare class TestApp extends TestApp_base {
+    render(): import("lit-html").TemplateResult<1>;
+}
+export { TestApp, TestHome, TestAbout, TestUser };

package/types/src/steps/schmancy-steps-container.d.ts

@@ -1,4 +1,10 @@
 import { StepsController } from './steps.context';
+/**
+ * Custom event emitted when the current step changes
+ */
+export type SchmancyStepsChangeEvent = CustomEvent<{
+    value: number;
+}>;
 declare const SchmancyStepsContainer_base: CustomElementConstructor & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 export declare class SchmancyStepsContainer extends SchmancyStepsContainer_base {
     private controller;
@@ -19,5 +25,8 @@ declare global {
     interface HTMLElementTagNameMap {
         'schmancy-steps-container': SchmancyStepsContainer;
     }
+    interface HTMLElementEventMap {
+        'schmancy-steps:change': SchmancyStepsChangeEvent;
+    }
 }
 export {};

package/types/src/store/context-collection.d.ts

@@ -13,9 +13,33 @@ export default class SchmancyCollectionStore<V = any> extends BaseStore<Map<stri
      */
     static getInstance<V = any>(storage: StorageType, key: string, defaultValue: Map<string, V>): SchmancyCollectionStore<V>;
     /**
-     * Set a value in the collection with proper typing and immutability
+     * Set values in the collection with proper typing and immutability.
+     * Supports multiple input types to prevent common developer mistakes.
+     *
+     * @example
+     * // Single key-value pair
+     * store.set('key1', value1)
+     *
+     * @example
+     * // Merge from a Map
+     * const dataMap = new Map([['key1', value1], ['key2', value2]])
+     * store.set(dataMap)
+     *
+     * @example
+     * // Merge from an object
+     * store.set({ key1: value1, key2: value2 })
      */
-    set<T = V>(key: string, value: T): void;
+    set<T = V>(keyOrData: string | Map<string, T> | Record<string, T>, value?: T): void;
+    /**
+     * Merge a Map into the collection. This is a helper method that provides
+     * explicit semantics for merging operations.
+     *
+     * @param map The Map to merge into the collection
+     * @example
+     * const dataMap = new Map([['key1', value1], ['key2', value2]])
+     * store.merge(dataMap)
+     */
+    merge<T = V>(map: Map<string, T>): void;
     /**
      * Delete a value from the collection immutably
      */

package/types/src/theme/context.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Lit Context for sharing theme configuration across components.\n *
+ * This context is provided by SchmancyThemeComponent and can be consumed
+ * by any child component to access the current theme configuration.
+ *
+ * @type {Context<Partial<TSchmancyTheme>>}
+ *
+ * @example
+ * ```typescript
+ * import { consume } from '@lit/context'
+ * import { themeContext } from '@schmancy/theme'
+ *
+ * class MyComponent extends LitElement {
+ *   @consume({ context: themeContext })
+ *   theme?: Partial<TSchmancyTheme>
+ *
+ *   render() {
+ *     // Access theme variables
+ *     const primaryColor = this.theme?.sys?.color?.primary?.default
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
 export declare const themeContext: {
     __context__: Partial<{
         sys: {

package/types/src/theme/index.d.ts

@@ -1,3 +1,5 @@
 export * from './theme.component';
+export * from './theme.events';
 export * from './theme.format';
 export * from './theme.interface';
+export * from './theme.service';

package/types/src/theme/theme.component.d.ts

@@ -1,18 +1,61 @@
 import { TSchmancyTheme } from './theme.interface';
-export type ThemeWhereAreYouEvent = CustomEvent<void>;
-export declare const ThemeWhereAreYou = "theme-where-are-you";
-export type ThemeHereIAmEvent = CustomEvent<{
-    theme: HTMLElement;
-}>;
-export declare const ThemeHereIAm = "theme-here-i-am";
 export declare const tailwindStyles: import("lit").CSSResult;
 declare const SchmancyThemeComponent_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<import("lit").LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
+/**
+ * SchmancyThemeComponent - Provides theming capabilities for Schmancy components.
+ *
+ * This component manages color schemes, primary colors, and theme distribution
+ * throughout the component tree. It can be used at the root level or nested
+ * to provide different themes to different parts of the application.
+ *
+ * @element schmancy-theme
+ *
+ * @example
+ * ```html
+ * <!-- Root theme provider -->
+ * <schmancy-theme color="#6200ee" scheme="auto" root>
+ *   <your-app></your-app>
+ * </schmancy-theme>
+ *
+ * <!-- Nested theme for specific section -->
+ * <schmancy-theme color="#2196f3" scheme="dark">
+ *   <div class="dark-section">
+ *     <!-- Components here will use blue dark theme -->
+ *   </div>
+ * </schmancy-theme>
+ * ```
+ */
 export declare class SchmancyThemeComponent extends SchmancyThemeComponent_base {
+    /**
+     * Primary color for the theme in hex format.
+     * @attr color
+     * @type {string}
+     * @default Random generated color
+     * @example "#6200ee"
+     */
     color: string;
+    /**
+     * Color scheme for the theme.
+     * @attr scheme
+     * @type {'dark' | 'light' | 'auto'}
+     * @default 'auto'
+     */
     scheme: 'dark' | 'light' | 'auto';
+    /**
+     * Whether this theme should be applied at the root level (document.body).
+     * @attr root
+     * @type {boolean}
+     * @default false
+     */
     root: boolean;
+    /**
+     * Theme configuration object containing all theme variables.
+     * @property {Partial<TSchmancyTheme>} theme
+     * @internal
+     */
     theme: Partial<TSchmancyTheme>;
     connectedCallback(): void;
+    updated(changedProperties: Map<string | number | symbol, unknown>): void;
     registerTheme(): void;
     registerThemeValues(prefix: string, path: string, value: Partial<TSchmancyTheme>): string | undefined;
     generateRandomColor(): string;

package/types/src/theme/theme.events.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Theme discovery event system.
+ *
+ * These events facilitate communication between theme components and consumers,
+ * allowing components to discover the nearest theme provider in the DOM hierarchy.
+ */
+/**
+ * Event dispatched by components to discover the nearest theme provider.
+ * Theme components listen for this event and respond with ThemeHereIAmEvent.
+ *
+ * @event ThemeWhereAreYouEvent
+ * @type {CustomEvent<void>}
+ *
+ * @example
+ * ```typescript
+ * // Dispatch discovery request
+ * window.dispatchEvent(
+ *   new CustomEvent('theme-where-are-you', {
+ *     bubbles: true,
+ *     composed: true
+ *   })
+ * )
+ * ```
+ */
+export type ThemeWhereAreYouEvent = CustomEvent<void>;
+/**
+ * Event name constant for theme discovery request.
+ * @const {string}
+ */
+export declare const ThemeWhereAreYou = "theme-where-are-you";
+/**
+ * Event dispatched by theme components in response to discovery requests.
+ * Contains reference to the theme component element.
+ *
+ * @event ThemeHereIAmEvent
+ * @type {CustomEvent<{theme: HTMLElement}>}
+ * @property {HTMLElement} detail.theme - The theme component element
+ *
+ * @example
+ * ```typescript
+ * // Listen for theme response
+ * window.addEventListener('theme-here-i-am', (event: ThemeHereIAmEvent) => {
+ *   const themeComponent = event.detail.theme
+ *   console.log('Found theme component:', themeComponent)
+ * })
+ * ```
+ */
+export type ThemeHereIAmEvent = CustomEvent<{
+    theme: HTMLElement;
+}>;
+/**
+ * Event name constant for theme discovery response.
+ * @const {string}
+ */
+export declare const ThemeHereIAm = "theme-here-i-am";

package/types/src/theme/theme.interface.d.ts

@@ -62,6 +62,42 @@ declare const theme: {
         };
     };
 };
+/**
+ * Type definition for the Schmancy theme configuration.
+ * Contains all available theme variables including colors, elevations, and outlines.
+ *
+ * @typedef {Object} TSchmancyTheme
+ *
+ * @example
+ * ```typescript
+ * import type { TSchmancyTheme } from '@schmancy/theme'
+ *
+ * const myTheme: Partial<TSchmancyTheme> = {
+ *   sys: {
+ *     color: {
+ *       primary: {
+ *         default: '#6200ee'
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export type TSchmancyTheme = (typeof theme)[keyof typeof theme];
+/**
+ * Default Schmancy theme configuration object.
+ * Provides access to all theme CSS variables through JavaScript.
+ *
+ * @constant {TSchmancyTheme}
+ *
+ * @example
+ * ```typescript
+ * import { SchmancyTheme } from '@schmancy/theme'
+ *
+ * // Access primary color variable
+ * const primaryColor = SchmancyTheme.sys.color.primary.default
+ * // Returns: 'var(--schmancy-sys-color-primary-default)'
+ * ```
+ */
 declare const SchmancyTheme: TSchmancyTheme;
 export { SchmancyTheme };

package/types/src/theme/theme.service.d.ts

@@ -0,0 +1,261 @@
+import { Observable } from 'rxjs';
+import type { SchmancyThemeComponent } from './theme.component';
+import type { TSchmancyTheme } from './theme.interface';
+/**
+ * Theme Service - Provides centralized theme management for Schmancy components.
+ *
+ * This service acts as a singleton interface to interact with the theme system,
+ * providing reactive observables for theme state and methods to control theming.
+ *
+ * @example
+ * ```typescript
+ * import { theme } from '@schmancy/theme'
+ *
+ * // Subscribe to theme changes
+ * theme.scheme$.subscribe(scheme => {
+ *   console.log('Current scheme:', scheme) // 'light' | 'dark' | 'auto'
+ * })
+ *
+ * // Get current values synchronously
+ * const currentScheme = theme.scheme
+ * const currentColor = theme.color
+ *
+ * // Toggle between light and dark mode
+ * theme.toggleScheme()
+ *
+ * // Set specific scheme
+ * theme.setScheme('dark')
+ *
+ * // Check if dark mode is active
+ * theme.isDarkMode().subscribe(isDark => {
+ *   console.log('Is dark mode:', isDark)
+ * })
+ * ```
+ */
+declare class ThemeService {
+    private static instance;
+    private _scheme$;
+    private _color$;
+    private _theme$;
+    private _themeComponent$;
+    readonly scheme$: Observable<"auto" | "dark" | "light">;
+    readonly color$: Observable<string>;
+    readonly theme$: Observable<Partial<{
+        sys: {
+            color: {
+                scrim: string;
+                outline: string;
+                outlineVariant: string;
+                surface: {
+                    default: string;
+                    dim: string;
+                    bright: string;
+                    container: string;
+                    low: string;
+                    high: string;
+                    highest: string;
+                    lowest: string;
+                    on: string;
+                    onVariant: string;
+                };
+                primary: {
+                    default: string;
+                    on: string;
+                    container: string;
+                    onContainer: string;
+                };
+                secondary: {
+                    default: string;
+                    on: string;
+                    container: string;
+                    onContainer: string;
+                };
+                tertiary: {
+                    default: string;
+                    on: string;
+                    container: string;
+                    onContainer: string;
+                };
+                error: {
+                    default: string;
+                    on: string;
+                    container: string;
+                    onContainer: string;
+                };
+                success: {
+                    default: string;
+                    on: string;
+                    container: string;
+                    onContainer: string;
+                };
+            };
+            elevation: {
+                0: string;
+                1: string;
+                2: string;
+                3: string;
+                4: string;
+                5: string;
+            };
+            outline: {
+                1: string;
+            };
+        };
+    }>>;
+    readonly themeComponent$: Observable<SchmancyThemeComponent>;
+    get scheme(): 'dark' | 'light' | 'auto';
+    get color(): string;
+    get theme(): Partial<TSchmancyTheme>;
+    get themeComponent(): SchmancyThemeComponent | null;
+    readonly resolvedScheme$: Observable<"dark" | "light">;
+    constructor();
+    /**
+     * Discover the nearest theme component in the DOM.
+     * This method can be called to refresh the theme discovery process.
+     *
+     * @returns {Observable<SchmancyThemeComponent | null>} Observable that emits the discovered theme component or null
+     *
+     * @example
+     * ```typescript
+     * theme.discoverTheme().subscribe(component => {
+     *   if (component) {
+     *     console.log('Theme component found:', component)
+     *   } else {
+     *     console.log('No theme component found')
+     *   }
+     * })
+     * ```
+     */
+    discoverTheme(): Observable<SchmancyThemeComponent | null>;
+    /**
+     * Register a theme component and subscribe to its changes.
+     * This is typically called internally by theme components when they mount or update.
+     *
+     * @param {SchmancyThemeComponent} component - The theme component to register
+     *
+     * @internal
+     */
+    registerThemeComponent(component: SchmancyThemeComponent): void;
+    /**
+     * Update theme values. Usually called internally by theme components.
+     *
+     * @param {Object} values - Theme values to update
+     * @param {'dark' | 'light' | 'auto'} [values.scheme] - Color scheme to set
+     * @param {string} [values.color] - Primary color in hex format
+     * @param {Partial<TSchmancyTheme>} [values.theme] - Theme configuration object
+     *
+     * @internal
+     */
+    updateTheme(values: {
+        scheme?: 'dark' | 'light' | 'auto';
+        color?: string;
+        theme?: Partial<TSchmancyTheme>;
+    }): void;
+    /**
+     * Set the color scheme for the application.
+     *
+     * @param {'dark' | 'light' | 'auto'} scheme - The color scheme to set
+     *
+     * @example
+     * ```typescript
+     * // Set to dark mode
+     * theme.setScheme('dark')
+     *
+     * // Set to auto (follows system preference)
+     * theme.setScheme('auto')
+     * ```
+     */
+    setScheme(scheme: 'dark' | 'light' | 'auto'): void;
+    /**
+     * Set the primary color for the theme.
+     *
+     * @param {string} color - Primary color in hex format (e.g., '#6200ee')
+     *
+     * @example
+     * ```typescript
+     * // Set primary color to purple
+     * theme.setColor('#6200ee')
+     *
+     * // Set primary color to blue
+     * theme.setColor('#2196f3')
+     * ```
+     */
+    setColor(color: string): void;
+    /**
+     * Check if dark mode is currently active.
+     * This resolves 'auto' scheme to the actual value based on system preference.
+     *
+     * @returns {Observable<boolean>} Observable that emits true if dark mode is active, false otherwise
+     *
+     * @example
+     * ```typescript
+     * theme.isDarkMode().subscribe(isDark => {
+     *   if (isDark) {
+     *     console.log('Dark mode is active')
+     *   } else {
+     *     console.log('Light mode is active')
+     *   }
+     * })
+     * ```
+     */
+    isDarkMode(): Observable<boolean>;
+    /**
+     * Toggle between light and dark mode.
+     * If currently in 'auto' mode, defaults to 'light'.
+     *
+     * @example
+     * ```typescript
+     * // Toggle theme on button click
+     * button.addEventListener('click', () => {
+     *   theme.toggleScheme()
+     * })
+     * ```
+     */
+    toggleScheme(): void;
+    /**
+     * Get the current value of a CSS variable from the theme.
+     *
+     * @param {string} variableName - Name of the CSS variable (without '--schmancy-' prefix)
+     * @returns {string} The CSS variable value or empty string if not found
+     *
+     * @example
+     * ```typescript
+     * // Get primary color variable
+     * const primaryColor = theme.getCSSVariable('color-primary')
+     *
+     * // Get surface color
+     * const surfaceColor = theme.getCSSVariable('color-surface')
+     * ```
+     */
+    getCSSVariable(variableName: string): string;
+    /**
+     * Subscribe to changes of a specific CSS variable.
+     *
+     * @param {string} variableName - Name of the CSS variable to watch (without '--schmancy-' prefix)
+     * @returns {Observable<string>} Observable that emits the CSS variable value when it changes
+     *
+     * @example
+     * ```typescript
+     * // Watch for primary color changes
+     * theme.watchCSSVariable('color-primary').subscribe(color => {
+     *   console.log('Primary color changed to:', color)
+     * })
+     *
+     * // Watch for surface color changes
+     * theme.watchCSSVariable('color-surface').subscribe(color => {
+     *   console.log('Surface color changed to:', color)
+     * })
+     * ```
+     */
+    watchCSSVariable(variableName: string): Observable<string>;
+    /**
+     * Get the singleton instance of ThemeService.
+     *
+     * @returns {ThemeService} The singleton ThemeService instance
+     *
+     * @internal
+     */
+    static getInstance(): ThemeService;
+}
+export declare const theme: ThemeService;
+export default theme;