effcss 1.3.5 → 2.0.0

package/dist/types/src/types.d.ts

@@ -1,31 +1,86 @@
 /**
- * Style config
+ * Stylesheet config
  * @description
- * Config which is used as initial settings for the {@link IStyleProvider | style provider}.
+ * Contains descriptions of rules, variables, keyframes, and interpolation dictionaries used within the stylesheet.
  */
-export interface IStyleConfig {
+export type TStyleSheetConfig = {
     /**
-     * Global params
+     * CSS variables
+     * @see {@link TVariable}
      */
-    params?: TDisplayModeValues;
+    _?: Record<string, TVariable>;
+    /**
+     * Keyframes
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes}
+     */
+    kf?: Record<string, Record<string, Record<string, string>>>;
+    /**
+     * Keys interpolation dictionary
+     * @description
+     * Dictionary with primitive type values.
+     * In interpolation expressions, these values will have an advantage over the global ones.
+     */
+    k?: Record<string, string>;
+    /**
+     * Values interpolation dictionary
+     * @description
+     * Dictionary with object type values. Each object is a mini dictionary of grouped variant values.
+     * In interpolation expressions, these values will have an advantage over the global ones.
+     */
+    v?: Record<string, Record<string, string | number>>;
+    /**
+     * Stylesheet content
+     * @description
+     * This object will be compiled to CSSStylesheet string content.
+     * The conversion rules are defined by the {@link IStyleProcessor | style processor}.
+     */
+    c: object;
+};
+/**
+ * Style target
+ */
+export type TStyleTarget = string | TStyleSheetConfig;
+/**
+ * Provider settings
+ */
+export type TProviderSettings = {
+    /**
+     * Style themes
+     */
+    themes?: TThemes;
+    /**
+     * Root styles
+     */
+    rootStyle?: object;
     /**
      * Global params units
      */
     units?: Record<string, string>;
     /**
-     * Stylesheets` configs
+     * Global keys
      */
-    styles?: Record<string, TStyleSheetConfig>;
+    keys?: Record<string, string>;
     /**
-     * Stylesheets` extra rules
+     * Global sets of keys
      */
-    ext?: Record<string, string[]>;
-}
+    sets?: Record<string, Record<string, string | number>>;
+    /**
+     * Media queries breakpoints
+     */
+    mediaBP?: Record<string, string>;
+    /**
+     * Container queries breakpoints
+     */
+    containerBP?: Record<string, string>;
+};
+/**
+ * Provider initial content
+ */
+export type TProviderInitContent = Record<string, TStyleSheetConfig>;
 /**
  * Style manager
  * @description
- * Class that manages CSS stylesheets.
- * You usually don't need to use it directly, as it is contained in the {@link IStyleProvider.manager | style provider}.
+ * Manages CSS stylesheets.
  */
 export interface IStyleManager {
     /**
@@ -33,7 +88,7 @@ export interface IStyleManager {
      * @param key - stylesheet key
      * @returns CSS stylesheet if found with this key, otherwise `undefined`
      */
-    get(key: string): CSSStyleSheet | undefined;
+    get(key?: string): CSSStyleSheet | undefined;
     /**
      * Get all stylesheets
      * @returns CSS stylesheet dicitonary
@@ -68,25 +123,21 @@ export interface IStyleManager {
      */
     pack(key: string, styles: string): boolean | void;
     /**
-     * Caches CSS rules in the special dictionary so that they can be expanded.
+     * Check if stylesheet exist
      * @param key - stylesheet key
-     * @param styleSheet - {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet | CSSStylesheet} instance
+     * @returns boolean flag
      */
-    cacheRules: (key: string, stylesheet: CSSStyleSheet) => void;
+    has(key?: string): boolean;
     /**
-     * Get expanded selectors by stylesheet key
+     * Switch stylesheet on
      * @param key - stylesheet key
-     * @returns expanded selectors Set
      */
-    getExpandedSelectors: (key: string) => Set<string>;
+    on(key?: string): boolean | undefined;
     /**
-     * Expand existing CSS rule
+     * Switch stylesheet off
      * @param key - stylesheet key
-     * @param init - initial selector
-     * @param exp - expanded selector
-     * @returns `true` if rule is expanded, otherwise `undefined`
      */
-    expandRule: (key: string, init: string, exp: string) => true | void;
+    off(key?: string): boolean | undefined;
     /**
      * Apply stylesheets to style consumer
      * @param consumer - {@link TStyleConsumer | style consumer}
@@ -102,12 +153,6 @@ export interface IStyleManager {
      * @description
      * A registered consumer will automatically receive up-to-date styles when they are added, modified, or deleted.
      * If the style provider does not contain the `isolated` {@link IStyleProviderParams.isolated | attribute}, the current document will be automatically registered.
-     * @example
-     * ```ts
-     * // register web component shadow root as consumer
-     * const shadow = this.attachShadow({mode: 'open'});
-     * getProvider().manager.registerNode(shadow);
-     * ```
      */
     registerNode(consumer: TStyleConsumer): void;
     /**
@@ -131,7 +176,7 @@ export interface IStyleManager {
  * Creates a selector from the passed parts.
  * @returns BEM selector string
  */
-type TGetBEMSelector = (params: {
+export type TResolveSelector = (params: {
     /**
      * {@link https://en.bem.info/methodology/key-concepts/#block | Block}
      */
@@ -162,11 +207,11 @@ type TGetBEMSelector = (params: {
  * The object content depends on the value of the style provider's `mode` {@link IStyleProviderParams.mode | attribute}.
  * @returns object containing target attribute with its value.
  */
-type TGetBEMAttr = (
+export type TResolveAttr = (
 /**
  * {@link https://en.bem.info/methodology/key-concepts/#block | Block}
  */
-b: string) => (
+b?: string) => (
 /**
  * {@link https://en.bem.info/methodology/key-concepts/#element | Element}
  */
@@ -176,61 +221,72 @@ e?: string) => (
  */
 m?: string | object) => Record<string, string>;
 /**
- * {@link BEM | https://en.bem.info/methodology/} resolver
+ * Style resolver
  * @description
- * Resolver object allows to create selectors/attribute by passed parts.
+ * Resolves stylesheets' selectors/attributes/identifiers
  */
-export interface IBEMResolver {
+export interface IStyleResolver {
     /**
      * Selector resolver
      */
-    selector: TGetBEMSelector;
+    selector: TResolveSelector;
     /**
      * Attribute resolver
      */
-    attr: TGetBEMAttr;
+    attr: TResolveAttr;
+    /**
+     * Var name resolver
+     */
+    varName: (...parts: (string | number)[]) => string;
+    /**
+     * Keyframes name resolver
+     */
+    kfName: (...parts: (string | number)[]) => string;
 }
+/**
+ * Stylesheet resolver getter
+ */
+export type TCreateResolver = (params?: {
+    mode?: TStyleMode | null;
+}) => IStyleResolver;
 /**
  * Style processor
  * @description
- * Class that converts style object to CSSStylesheet string content
- * You usually don't need to use it directly, as it is contained in the {@link IStyleProvider.processor | style provider}.
+ * Converts stylesheet config to CSSStylesheet string content.
  */
 export interface IStyleProcessor {
     /**
-     * Base styles
-     * @description
-     * Contains base styles created in the constructor that define global variables and display modes.
+     * Compile style config to CSS stylesheet text content
+     * @param b - block key
+     * @param config - stylesheet config
      */
-    baseStyles: string;
+    compile(b: string, config: TStyleSheetConfig): string;
+}
+/**
+ * Style collector
+ * @description
+ * Collects stylesheet configs and maps them with keys
+ */
+export interface IStyleCollector {
     /**
-     * BEM resolver
-     * @description
-     * Allows to get BEM selectors/attributes by passed parts
+     * Collect config
+     * @param config - stylesheet config
+     * @param key - stylesheet key
      */
-    bem: IBEMResolver;
+    use(config: TStyleSheetConfig, key?: string): string;
     /**
-     * Create expanded selector with state
-     * @param b
-     * @param selector
+     * Get key of collected config
+     * @param config - stylesheet config
      */
-    expandSelector(b: string, selector: string): [string, string];
+    getKey(config: TStyleSheetConfig): string | undefined;
     /**
-     * Parse BEM selector
-     * @param selector
+     * Get all collected keys
      */
-    parseSelector(selector: string): {
-        e?: string;
-        m?: string;
-        mv?: string;
-        s?: string;
-    };
+    getKeys(): string[];
     /**
-     * Compile style config to CSS stylesheet text content
-     * @param b - block key
-     * @param config - stylesheet config
+     * Get all collected configs
      */
-    compile(b: string, config: TStyleSheetConfig): string;
+    getConfigs(): Record<string, TStyleSheetConfig>;
 }
 /**
  * Style provider
@@ -239,75 +295,91 @@ export interface IStyleProcessor {
  */
 export interface IStyleProvider {
     /**
-     * {@link IStyleManager | Style manager}
+     * Provider initial content
      */
-    manager: IStyleManager;
+    initContent: TProviderInitContent;
     /**
-     * {@link IStyleProcessor | Style processor}
+     * Provider settings
      */
-    processor: IStyleProcessor;
+    settingsContent: TProviderSettings;
     /**
      * Use stylesheet
      * @param config - stylesheet config
-     * @returns {@link IBEMResolver.attr | attribute resolver}
+     * @returns {@link IStyleResolver.attr | attribute resolver}
      * @description
      * The method allows to use stylesheet without having its key.
-     * It returns {@link IBEMResolver.attr | attribute resolver}, that can create BEM selectors for config passed.
+     * It returns {@link IStyleResolver.attr | attribute resolver}, that can create BEM selectors for config passed.
      */
-    useStyleSheet(config: TStyleSheetConfig): ReturnType<IBEMResolver['attr']>;
+    use(config: TStyleSheetConfig, key?: string): ReturnType<TResolveAttr>;
     /**
-     * Compile stylesheet
-     * @key - stylesheet key
-     * @config - stylesheet config
-     * @returns `true` if stylesheet compiled, otherwise `undefined`
+     * Use public stylesheet configs
+     * @param configs - stylesheet configs
      */
-    compileStyleSheet(key: string, config: TStyleSheetConfig): boolean | undefined;
+    usePublic(configs: Record<string, TStyleSheetConfig>): Record<string, ReturnType<TResolveAttr>>;
     /**
-     * Expand stylesheet
-     * @param key - stylesheet key
-     * @param selectors - stylesheet extra selectors
-     * @returns processed rules count if stylesheet expanded, otherwise `undefined`
+     * Use private stylesheet configs
+     * @param configs - stylesheet configs
      */
-    expandStyleSheet(key: string, selectors: string[]): number | undefined;
+    usePrivate(configs: TStyleSheetConfig[]): ReturnType<TResolveAttr>[];
     /**
      * Resolve stylesheet
      * @param key - stylesheet key
      * @returns BEM attribute resolver for stylesheet
      */
-    resolveStyleSheet(key: string): ReturnType<IStyleProcessor['bem']['attr']>;
+    resolve(key?: string): ReturnType<TResolveAttr>;
+    /**
+     * Prepare CSS from config
+     * @param config - stylesheet config
+     * @param key - stylesheet key
+     */
+    css(config: TStyleSheetConfig, key: string): string;
     /**
-     * Process configs
-     * @param styles - stylesheet dictionary
-     * @param ext - extra rules dictionary
+     * Get CSS stylesheet
+     * @param target - target stylesheet config or key
      */
-    processStyles(styles?: Record<string, TStyleSheetConfig>, ext?: Record<string, string[]>): void;
+    get(target?: TStyleTarget): CSSStyleSheet | undefined;
+    /**
+     * Switch stylesheet on
+     * @param target - target stylesheet config or key
+     */
+    on(target?: TStyleTarget): boolean | undefined;
+    /**
+     * Switch stylesheet off
+     * @param target - target stylesheet config or key
+     */
+    off(target?: TStyleTarget): boolean | undefined;
+    /**
+     * Get many CSS stylesheets
+     * @param target - target stylesheet configs and/or keys
+     */
+    getMany(targets?: TStyleTarget[]): (CSSStyleSheet | undefined)[];
 }
 /**
  * Style dispatcher
  * @description
- * Class that allows to directly call the style provider's methods
+ * Dispatches style operations to provider
  */
 export interface IStyleDispatcher {
     /**
      * Use stylesheet
-     * @see {@link IStyleProvider.useStyleSheet}
+     * @see {@link IStyleProvider.use}
      */
-    use: IStyleProvider['useStyleSheet'];
+    use: IStyleProvider['use'];
     /**
-     * Compile stylesheet
-     * @see {@link IStyleProvider.compileStyleSheet}
+     * Use public stylesheet configs
+     * @see {@link IStyleProvider.usePublic}
      */
-    compile: IStyleProvider['compileStyleSheet'];
+    usePublic: IStyleProvider['usePublic'];
     /**
-     * Expand stylesheet
-     * @see {@link IStyleProvider.expandStyleSheet}
+     * Use private stylesheet configs
+     * @see {@link IStyleProvider.usePrivate}
      */
-    expand: IStyleProvider['expandStyleSheet'];
+    usePrivate: IStyleProvider['usePrivate'];
     /**
-     * Process configs
-     * @see {@link IStyleProvider.processStyles}
+     * Resolve stylesheet
+     * @see {@link IStyleProvider.resolve}
      */
-    process: IStyleProvider['processStyles'];
+    resolve: IStyleProvider['resolve'];
 }
 /**
  * Variable type
@@ -348,53 +420,11 @@ export type TVariable = {
     all?: boolean;
 };
 /**
- * Stylesheet config
- * @description
- * Contains descriptions of rules, variables, keyframes, and interpolation dictionaries used within the stylesheet.
+ * Style themes
  */
-export type TStyleSheetConfig = {
-    /**
-     * CSS variables
-     * @see {@link TVariable}
-     */
-    _?: Record<string, TVariable>;
-    /**
-     * Keyframes
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes}
-     */
-    kf?: Record<string, Record<string, Record<string, string>>>;
-    /**
-     * Keys interpolation dictionary
-     * @description
-     * Dictionary with primitive type values.
-     * In interpolation expressions, these values will have an advantage over the global ones.
-     */
-    k?: Record<string, string>;
-    /**
-     * Values interpolation dictionary
-     * @description
-     * Dictionary with object type values. Each object is a mini dictionary of grouped variant values.
-     * In interpolation expressions, these values will have an advantage over the global ones.
-     */
-    v?: Record<string, Record<string, string | number>>;
-    /**
-     * Stylesheet content
-     * @description
-     * This object will be compiled to CSSStylesheet string content.
-     * The conversion rules are defined by the {@link IStyleProcessor | style processor}.
-     */
-    c: object;
-};
-/**
- * Display mode values
- * @description
- * The display mode allows you to override global values.
- * The required mode is root.
- * Other display modes can only override values from `root`, but not set their own.
- */
-export type TDisplayModeValues = Record<string, Record<string, Record<string, string | number>>>;
+export type TThemes = Record<string, Record<string, Record<string, string | number>>>;
 /**
- * Style generation mode for {@link IBEMResolver | BEM selectors}
+ * Style generation mode for {@link IStyleResolver | BEM selectors}
  * @description
  * `a` - attributes
  * `c` - classes
@@ -403,16 +433,20 @@ export type TStyleMode = 'a' | 'c';
 /**
  * Style provider attributes
  * @description
- * Attributes that can be set on a component.
+ * Attributes that can be set on a provider component.
  */
 export interface IStyleProviderParams {
     /**
-     * Settings script element id
+     * Settings script selector
      * @description
      * Allows to read the initial settings from a separate element script.
      * If not specified, `effcss` is used.
      */
     settingsid?: string;
+    /**
+     * Initial content script selector
+     */
+    initcls?: string;
     /**
      * Prefix
      * @description
@@ -432,16 +466,11 @@ export interface IStyleProviderParams {
      * @description
      * If specified, provider won`t register document as dependent node
      */
-    isolated?: string | null;
+    isolated?: '' | null;
     /**
-     * Initializer stylesheet key
-     * @description
-     * It value controls initializer stylesheet:
-     * - if it is equals '', the stylesheet will be omitted;
-     * - if it is not specified, the stylesheet will be generated with default `initkey`;
-     * - if it is specified as no-empty string, the stylesheet will be generated with specified key.
+     * Hydrate initial stylesheets
      */
-    initkey?: string | null;
+    hydrate?: '' | null;
 }
 /**
  * Style consumer node
@@ -451,4 +480,3 @@ export interface IStyleProviderParams {
 export type TStyleConsumer = {
     adoptedStyleSheets: CSSStyleSheet[];
 };
-export {};

package/dist/types/src/utils/browser.d.ts

@@ -0,0 +1,123 @@
+import { IStyleDispatcher, IStyleProvider, TStyleSheetConfig, TStyleTarget } from '../types';
+/**
+ * Get style provider component
+ * @param root - style provider scope
+ * @description
+ * Use this function to get the first provider element found in the document
+ * @see {@link IStyleProvider}
+ */
+export declare const getProvider: (root?: Document, tag?: string) => IStyleProvider;
+/**
+ * Use stylesheet
+ * @param config - stylesheet config
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const useStyleSheet: (config: TStyleSheetConfig, key?: string, provider?: IStyleProvider) => (e?: string) => (m?: string | object) => Record<string, string>;
+/**
+ * Use public stylehseet configs
+ * @param styles - stylesheet configs
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const usePublicStyleSheets: (styles: Parameters<IStyleProvider["usePublic"]>[0], provider?: IStyleProvider) => Record<string, (e?: string) => (m?: string | object) => Record<string, string>>;
+/**
+ * Use private stylehseet configs
+ * @param styles - stylesheet configs
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const usePrivateStyleSheets: (styles: Parameters<IStyleProvider["usePrivate"]>[0], provider?: IStyleProvider) => ((e?: string) => (m?: string | object) => Record<string, string>)[];
+/**
+ * Resolve stylesheet
+ * @param key stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const resolveStyleSheet: (key?: string, provider?: IStyleProvider) => (e?: string) => (m?: string | object) => Record<string, string>;
+/**
+ * Get stylesheet from provider
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const getStyleSheet: (key?: TStyleTarget, provider?: IStyleProvider) => CSSStyleSheet | undefined;
+/**
+ * Get stylesheet from provider
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const getManyStyleSheets: (key?: TStyleTarget[], provider?: IStyleProvider) => (CSSStyleSheet | undefined)[];
+/**
+ * Stringify stylesheet
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const stringifyOne: (key?: TStyleTarget, provider?: IStyleProvider) => string;
+/**
+ * Stringify stylesheet
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const stringifyMany: (key?: TStyleTarget[], provider?: IStyleProvider) => string;
+/**
+ * Get rules count for stylesheet
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const measureOne: (key: string, provider?: IStyleProvider) => number;
+/**
+ * Get rules count for stylesheet
+ * @param key - stylesheet key
+ * @param provider - style provider
+ * @see {@link IStyleProvider}
+ */
+export declare const measureMany: (keys: string[], provider?: IStyleProvider) => number;
+interface IStyleDispatcherParams {
+    root?: Document;
+    tag?: string;
+}
+/**
+ * Basic class for manipulating stylesheets
+ */
+declare class StyleDispatcher implements IStyleDispatcher {
+    /**
+     * Style provider
+     */
+    protected _provider: IStyleProvider;
+    constructor(params?: IStyleDispatcherParams);
+    /**
+     * Use stylesheet
+     * @param config - stylesheet config
+     * @see {@link IStyleProvider}
+     */
+    use: IStyleProvider['use'];
+    /**
+     * Use public stylesheet configs
+     * @param styles - stylesheet configs
+     * @see {@link IStyleProvider}
+     */
+    usePublic: IStyleProvider['usePublic'];
+    /**
+     * Use private stylesheet configs
+     * @param styles - stylesheet configs
+     * @see {@link IStyleProvider}
+     */
+    usePrivate: IStyleProvider['usePrivate'];
+    /**
+     * Resolve stylesheet
+     * @param key - stylesheet key
+     * @see {@link IStyleProvider}
+     */
+    resolve: IStyleProvider['resolve'];
+}
+/**
+ * Create style dispatcher
+ * @param params - dispatcher params
+ */
+export declare function createDispatcher(params?: IStyleDispatcherParams): StyleDispatcher;
+export {};