import { MultiMap, ObjectDictionary } from "@opticss/util"; import { ParsedSelector, postcss, postcssSelectorParser as selectorParser } from "opticss"; import { Root as BlockAST } from "../BlockParser/ast"; import { BlockPath } from "../BlockSyntax"; import { ResolvedConfiguration } from "../configuration"; import { CssBlockError } from "../errors"; import { FileIdentifier } from "../importing"; import { SourceFile, SourceRange } from "../SourceLocation"; import { BlockClass } from "./BlockClass"; import { Inheritable } from "./Inheritable"; import { Styles } from "./Styles"; /** * In-memory representation of a Block. If you're thinking of CSS Blocks * in relation to the BEM architecture for CSS, this is the... well... "Block". * Well, with a slight caveat.... * * The Block is always the root node of a BlockTree. The Block may be the * parent to any number of BlockClass nodes. Notably, the Block class only * stores meta information about the block. Any CSS properties assigned to the * `:scope` selector are stored on a special BlockClass node that is a child of * the Block. You can access this node directly through the * `rootClass` property. * * Block nodes store all data related to any `@block` imports, the * `block-name`, implemented Blocks, the inherited Block, and any other * metadata stored in the Block file. */ export declare class Block extends Inheritable { blockAST?: BlockAST; private _blockReferences; private _blockReferencesReverseLookup; private _blockExports; private _blockExportReverseLookup; private _identifier; private _implements; private _blockErrors; private hasHadNameReset; /** * A unique identifier for this Block. Generally created from a hash * of the FileIdentifier and other process information. * * For caching to work properly, this GUID must be unique to the block and * shouldn't change between recompiles. You shouldn't use file contents to * create this hash. */ readonly guid: string; /** * array of paths that this block depends on and, if changed, would * invalidate the compiled css of this block. This is usually only useful in * pre-processed blocks. */ private _dependencies; /** * A direct reference to the BlockClass that holds style information for the * `:scope` selector of this Block. The rootClass is also available through * other traversal methods, as you would access any other BlockClass that * belongs to this Block. */ readonly rootClass: BlockClass; /** * The PostCSS AST of the stylesheet this Block was built from. Used * primarily for error reporting, if present. */ stylesheet: postcss.Root | undefined; /** * The PostCSS AST of the compiled CSS this block was built from. * If this is set, the stylesheet property is only the definition file contents. */ precompiledStylesheet: postcss.Root | undefined; /** * The full contents of the compiled CSS this block was built from, if available. * This content is copied verbatim from the file system and has not been transformed * or processed by PostCSS in any way. */ precompiledStylesheetUnedited: string | undefined; blockReferencePaths: Map; private _resolveImplementedBlocksResult; /** * Creates a new Block. * * @param name - The default name for this block. This can be reset once (and only once) * using the `setName()` method. * @param identifier - An unique ID referencing the file/blob this Block is created from. * @param guid - The GUID for this block. This GUID should be unique. (BlockFactory is * responsible for enforcing uniqueness.) * @param stylesheet - The PostCSS AST of the stylesheet this block is built from. */ constructor(name: string, identifier: FileIdentifier, guid: string, stylesheet?: postcss.Root, precompiledStylesheet?: postcss.Root); protected get ChildConstructor(): typeof BlockClass; /** @returns This Block's self-proclaimed name. */ get name(): string; /** * Sets `name` value of this `Block`. Block names may change depending on the * value passed to its `block-name` property in `:scope`. * @prop name string The new uid for this `Block`. */ setName(name: string): void; /** * Sets the base Block that this Block inherits from. * @prop base Block The new base Block. */ setBase(base: Block): void; /** * Lookup a sub-block either locally, or on a referenced foreign block. * @param reference * A reference to a block object adhering to the following grammar: * reference -> '.' // reference through sub-block * | // reference to sub-block * | '.' // reference to class in this block * | // reference to attribute in this block * | '.' // reference to this block * sub-reference -> '.' // reference through sub-sub-block * | // reference to object in sub-block * object-selector -> // reference to this sub-block * | // reference to class in sub-block * | // reference to attribute in this sub-block * block-selector -> 'root' * class-selector -> * attribute-selector -> '[' ']' * ident -> regex:[a-zA-Z_-][a-zA-Z0-9]* * A single dot by itself returns the current block. * @returns The Style referenced at the supplied path. */ lookup(path: string | BlockPath, errLoc?: SourceRange | SourceFile): Styles | undefined; /** * Lookup a sub-block either locally, or on a exported foreign block. * @param reference * A reference to a block object adhering to the following grammar: * reference -> '.' // reference through sub-block * | // reference to sub-block * | '.' // reference to class in this block * | // reference to attribute in this block * | '.' // reference to this block * sub-reference -> '.' // reference through sub-sub-block * | // reference to object in sub-block * object-selector -> // reference to this sub-block * | // reference to class in sub-block * | // reference to attribute in this sub-block * block-selector -> 'root' * class-selector -> * attribute-selector -> '[' ']' * ident -> regex:[a-zA-Z_-][a-zA-Z0-9]* * A single dot by itself returns the current block. * @returns The Style referenced at the supplied path. */ externalLookup(path: string | BlockPath, errLoc?: SourceRange | SourceFile): Styles | undefined; /** * Stores a block error along with the block * @param error CssBlockError that is added to the block */ addError(error: CssBlockError): void; isValid(): boolean; /** * Checks for errors on the block * @returns true if the block is valid else throws the errors on the block */ assertValid(): Block; /** * Add an absolute, normalized path as a compilation dependency. This is used * to invalidate caches and trigger watchers when those files change. * * It is not necessary or helpful to add css-block files. */ addDependency(filepath: string): void; get dependencies(): string[]; get identifier(): FileIdentifier; getClass(name: string): BlockClass | null; resolveClass(name: string): BlockClass | null; get classes(): BlockClass[]; addClass(blockClass: BlockClass): void; ensureClass(name: string): BlockClass; getImplementedBlocks(): Block[]; addImplementation(b: Block): number; /** * Validate that this block implements all foreign selectors from blocks it implements. * @param b The block to check implementation against. * @returns The Styles from b that are missing in the block. */ checkImplementation(b: Block): Styles[]; /** * Validate that all foreign blocks this block implements are fully...implemented. */ checkImplementations(): void; find(sourceName: string): Styles | undefined; eachBlockReference(callback: (name: string, block: Block) => unknown): void; /** * Add a Block reference accessible internally to the block as `localName`. * @param localName The name to expose this block internally as. * @param block The block to expose internally. */ addBlockReference(localName: string, block: Block): void; /** * Get an imported Block at name `localName`. * @param localName The local name name of the requested imported block. * @returns Block | null. */ getReferencedBlock(localName: string): Block | null; /** * Reverse imported Block lookup. Given a Block, return its private local alias. * @param block The requested Block to lookup. * @returns string | null. */ getReferencedBlockLocalName(block: Block | undefined): string | null; /** * Add a Block export to be exposed to importers at name `remoteName`. * @param remoteName The name to expose this block publicly as. * @param block The block to expose publicly. */ addBlockExport(remoteName: string, block: Block): void; /** * Iterates over each exported block, applying the callback to it * @param callback the function to iterate over each exported block */ eachBlockExport(callback: (name: string, block: Block) => unknown): void; /** * Get an exported Block at name `remoteName`. * @param remoteName The public name of the requested exported block. * @returns Block | null. */ getExportedBlock(remoteName: string): Block | null; /** * Reverse exported Block lookup. Given a Block, return its publicly exported name. * @param block The requested Block to lookup. * @returns string | null. */ getExportedBlockRemoteName(block: Block | undefined): string | null; transitiveBlockDependencies(): Set; /** * Returns a new array of ancestors in order of inheritance * with the first one being the immediate super block. * * If this block doesn't inherit, the array is empty. **/ getAncestors(): Array; /** * Return array self and all children. * @param shallow Pass true to not include inherited objects. * @returns Array of Styles. */ all(shallow?: boolean): Styles[]; /** * Outputs a dictionary of style source string to most specific style in the * inheritance hierarchy. */ resolvedStyleInterface(): ObjectDictionary; /** * Fetch a dictionary of styles associated with this block, using any preset * selector as the key. If a given style doesn't have a preset selector, it * will be excluded from this dictionary. * * @param shallow - Pass true to exclude inherited objects. * @returns Collection of Styles objects, organized by preset selector value. */ presetClassesMap(shallow?: boolean): ObjectDictionary; merged(): MultiMap; /** * Return all the style aliases defined on the block. * @returns Array of style aliases. */ getAllStyleAliases(): Set; nodeAsStyle(node: selectorParser.Node): [Styles, number] | null; rewriteSelectorNodes(nodes: selectorParser.Node[], config: ResolvedConfiguration, reservedClassNames: Set): selectorParser.Node[]; rewriteSelectorToString(selector: ParsedSelector, config: ResolvedConfiguration, reservedClassNames: Set): string; rewriteSelector(selector: ParsedSelector, config: ResolvedConfiguration, reservedClassNames: Set): ParsedSelector; debug(config: ResolvedConfiguration): string[]; /** * Test if the supplied block is the same block object. * @param other The other Block to test against. * @return True or False if self and `other` are equal. */ equal(other: Block | undefined | null): boolean | null | undefined; isAncestorOf(other: Block | undefined | null): boolean; /** * Gets all the blocks that are implemented by this block or by any ancestor. * This includes: * - This block. * - The blocks this block inherits from. * - The blocks the above blocks explicitly declare that they implement. * - The blocks all the above blocks implement transitively. * Such that `blockA.resolveImplementedBlocks().has(blockB)` is true iff * `blockA` implements the interface of `blockB`. */ resolveImplementedBlocks(): Set; isImplementationOf(other: Block): boolean; /** * Objects that contain Blocks are often passed into assorted libraries' options * hashes. Some libraries like to `JSON.stringify()` their options to create * unique identifiers for re-run caching. (ex: Webpack, awesome-typescript-loader) * Blocks contain circular dependencies, so we need to override their `toJSON` * method so these libraries don't implode. * @return The name of the block. */ toJSON(): string; } export declare function isBlock(o?: object): o is Block; //# sourceMappingURL=Block.d.ts.map