@webstudio-is/css-data 0.90.0 → 0.266.0

package/lib/types/css-tree.d.ts

@@ -0,0 +1,772 @@
+// Minimal-yet-safe TypeScript typings for css-tree v3.x
+// Covers: AST node types, parse/generate, walk/find, List, lexer API,
+// value definition syntax helpers, and common utils used in this project.
+
+declare module "css-tree" {
+  // -------------------------------------------------
+  // Common
+  // -------------------------------------------------
+  export interface SourceLocation {
+    source: string;
+    start: { offset: number; line: number; column: number };
+    end: { offset: number; line: number; column: number };
+  }
+
+  export interface BaseNode {
+    type: string;
+    loc: SourceLocation | null;
+  }
+
+  // Doubly-linked list used by csstree
+  export interface ListItem<T> {
+    prev: ListItem<T> | null;
+    next: ListItem<T> | null;
+    data: T;
+  }
+
+  export class List<T> implements Iterable<T> {
+    static createItem<T>(data: T): ListItem<T>;
+
+    constructor();
+    // iteration
+    [Symbol.iterator](): IterableIterator<T>;
+    // props
+    readonly size: number;
+    readonly isEmpty: boolean;
+    readonly first: T | null;
+    readonly last: T | null;
+    // traversal helpers
+    forEach(
+      fn: (data: T, item: ListItem<T>, list: List<T>) => void,
+      thisArg?: any
+    ): void;
+    forEachRight(
+      fn: (data: T, item: ListItem<T>, list: List<T>) => void,
+      thisArg?: any
+    ): void;
+    // conversion
+    fromArray(items: T[]): this;
+    toArray(): T[];
+    toJSON(): T[];
+    // mutation (minimal surface used by walkers)
+    clear(): void;
+    remove(item: ListItem<T>): ListItem<T>;
+    insert(item: ListItem<T>, before?: ListItem<T> | null): void;
+    insertData(data: T, before?: ListItem<T> | null): void;
+    append(item: ListItem<T>): void;
+    appendData(data: T): void;
+    prepend(item: ListItem<T>): void;
+    prependData(data: T): void;
+    replace(oldItem: ListItem<T>, newItemOrList: ListItem<T> | List<T>): void;
+  }
+
+  // -------------------------------------------------
+  // AST Nodes (as per docs/ast.md)
+  // -------------------------------------------------
+  export interface AnPlusB extends BaseNode {
+    type: "AnPlusB";
+    a: string | null;
+    b: string | null;
+  }
+  export interface Atrule extends BaseNode {
+    type: "Atrule";
+    name: string;
+    prelude: AtrulePrelude | Raw | null;
+    block: Block | null;
+  }
+  export interface AtrulePrelude extends BaseNode {
+    type: "AtrulePrelude";
+    children: List<CssNode>;
+  }
+  export interface AttributeSelector extends BaseNode {
+    type: "AttributeSelector";
+    name: Identifier;
+    matcher: string | null;
+    value: StringNode | Identifier | null;
+    flags: string | null;
+  }
+  export interface Block extends BaseNode {
+    type: "Block";
+    children: List<Atrule | Rule | Declaration>;
+  }
+  export interface Brackets extends BaseNode {
+    type: "Brackets";
+    children: List<CssNode>;
+  }
+  export interface CDC extends BaseNode {
+    type: "CDC";
+  }
+  export interface CDO extends BaseNode {
+    type: "CDO";
+  }
+  export interface ClassSelector extends BaseNode {
+    type: "ClassSelector";
+    name: string;
+  }
+  export interface Combinator extends BaseNode {
+    type: "Combinator";
+    name: string;
+  }
+  export interface Comment extends BaseNode {
+    type: "Comment";
+    value: string;
+  }
+  export interface Condition extends BaseNode {
+    type: "Condition";
+    kind: string;
+    children: List<
+      | Identifier
+      | Feature
+      | FeatureFunction
+      | FeatureRange
+      | SupportsDeclaration
+    >;
+  }
+  export interface Declaration extends BaseNode {
+    type: "Declaration";
+    important: boolean | string;
+    property: string;
+    value: Value | Raw;
+  }
+  export interface DeclarationList extends BaseNode {
+    type: "DeclarationList";
+    children: List<Declaration | Atrule | Rule>;
+  }
+  export interface Dimension extends BaseNode {
+    type: "Dimension";
+    value: string;
+    unit: string;
+  }
+  export interface Feature extends BaseNode {
+    type: "Feature";
+    kind: string;
+    name: string;
+    value: Identifier | NumberNode | Dimension | Ratio | FunctionNode | null;
+  }
+  export interface FeatureFunction extends BaseNode {
+    type: "FeatureFunction";
+    kind: string;
+    feature: string;
+    value: Declaration | Selector;
+  }
+  export interface FeatureRange extends BaseNode {
+    type: "FeatureRange";
+    kind: string;
+    left: Identifier | NumberNode | Dimension | Ratio | FunctionNode;
+    leftComparison: string;
+    middle: Identifier | NumberNode | Dimension | Ratio | FunctionNode;
+    rightComparison: string | null;
+    right: Identifier | NumberNode | Dimension | Ratio | FunctionNode | null;
+  }
+  export interface FunctionNode extends BaseNode {
+    type: "Function";
+    name: string;
+    children: List<CssNode>;
+  }
+  export interface GeneralEnclosed extends BaseNode {
+    type: "GeneralEnclosed";
+    kind: string;
+    function: string | null;
+    children: List<CssNode>;
+  }
+  export interface Hash extends BaseNode {
+    type: "Hash";
+    value: string;
+  }
+  export interface IdSelector extends BaseNode {
+    type: "IdSelector";
+    name: string;
+  }
+  export interface Identifier extends BaseNode {
+    type: "Identifier";
+    name: string;
+  }
+  export interface Layer extends BaseNode {
+    type: "Layer";
+    name: string;
+  }
+  export interface LayerList extends BaseNode {
+    type: "LayerList";
+    children: List<Layer>;
+  }
+  export interface MediaQuery extends BaseNode {
+    type: "MediaQuery";
+    modifier: string | null;
+    mediaType: string | null;
+    condition: Condition | null;
+  }
+  export interface MediaQueryList extends BaseNode {
+    type: "MediaQueryList";
+    children: List<MediaQuery>;
+  }
+  export interface NestingSelector extends BaseNode {
+    type: "NestingSelector";
+  }
+  export interface Nth extends BaseNode {
+    type: "Nth";
+    nth: AnPlusB | Identifier;
+    selector: SelectorList | null;
+  }
+  export interface NumberNode extends BaseNode {
+    type: "Number";
+    value: string;
+  }
+  export interface Operator extends BaseNode {
+    type: "Operator";
+    value: string;
+  }
+  export interface Parentheses extends BaseNode {
+    type: "Parentheses";
+    children: List<CssNode>;
+  }
+  export interface Percentage extends BaseNode {
+    type: "Percentage";
+    value: string;
+  }
+  export interface PseudoClassSelector extends BaseNode {
+    type: "PseudoClassSelector";
+    name: string;
+    children: List<Raw> | null;
+  }
+  export interface PseudoElementSelector extends BaseNode {
+    type: "PseudoElementSelector";
+    name: string;
+    children: List<Raw> | null;
+  }
+  export interface Ratio extends BaseNode {
+    type: "Ratio";
+    left: NumberNode | FunctionNode;
+    right: NumberNode | FunctionNode | null;
+  }
+  export interface Raw extends BaseNode {
+    type: "Raw";
+    value: string;
+  }
+  export interface Rule extends BaseNode {
+    type: "Rule";
+    prelude: SelectorList | Raw;
+    block: Block;
+  }
+  export interface Scope extends BaseNode {
+    type: "Scope";
+    root: SelectorList | Raw | null;
+    limit: SelectorList | Raw | null;
+  }
+  export interface Selector extends BaseNode {
+    type: "Selector";
+    children: List<
+      | TypeSelector
+      | IdSelector
+      | ClassSelector
+      | AttributeSelector
+      | PseudoClassSelector
+      | PseudoElementSelector
+      | Combinator
+      | NestingSelector
+    >;
+  }
+  export interface SelectorList extends BaseNode {
+    type: "SelectorList";
+    children: List<Selector | Raw>;
+  }
+  export interface StringNode extends BaseNode {
+    type: "String";
+    value: string;
+  }
+  export interface StyleSheet extends BaseNode {
+    type: "StyleSheet";
+    children: List<Comment | CDO | CDC | Atrule | Rule | Raw>;
+  }
+  export interface SupportsDeclaration extends BaseNode {
+    type: "SupportsDeclaration";
+    declaration: Declaration;
+  }
+  export interface TypeSelector extends BaseNode {
+    type: "TypeSelector";
+    name: string;
+  }
+  export interface UnicodeRange extends BaseNode {
+    type: "UnicodeRange";
+    value: string;
+  }
+  export interface Url extends BaseNode {
+    type: "Url";
+    value: string;
+  }
+  export interface Value extends BaseNode {
+    type: "Value";
+    children: List<CssNode>;
+  }
+  export interface WhiteSpace extends BaseNode {
+    type: "WhiteSpace";
+    value: string;
+  }
+
+  export type CssNode =
+    | AnPlusB
+    | Atrule
+    | AtrulePrelude
+    | AttributeSelector
+    | Block
+    | Brackets
+    | CDC
+    | CDO
+    | ClassSelector
+    | Combinator
+    | Comment
+    | Condition
+    | Declaration
+    | DeclarationList
+    | Dimension
+    | Feature
+    | FeatureFunction
+    | FeatureRange
+    | FunctionNode
+    | GeneralEnclosed
+    | Hash
+    | IdSelector
+    | Identifier
+    | Layer
+    | LayerList
+    | MediaQuery
+    | MediaQueryList
+    | NestingSelector
+    | Nth
+    | NumberNode
+    | Operator
+    | Parentheses
+    | Percentage
+    | PseudoClassSelector
+    | PseudoElementSelector
+    | Ratio
+    | Raw
+    | Rule
+    | Scope
+    | Selector
+    | SelectorList
+    | StringNode
+    | StyleSheet
+    | SupportsDeclaration
+    | TypeSelector
+    | UnicodeRange
+    | Url
+    | Value
+    | WhiteSpace;
+
+  // A plain-object form where children are arrays (for JSON, etc.)
+  export type CssNodePlain = Omit<CssNode, "children" | "loc"> & {
+    children?: CssNodePlain[] | null;
+    loc?: SourceLocation | null;
+  };
+
+  // -------------------------------------------------
+  // Parsing / Generation
+  // -------------------------------------------------
+  export type ParseContext =
+    | "stylesheet"
+    | "atrule"
+    | "atrulePrelude"
+    | "mediaQueryList"
+    | "mediaQuery"
+    | "rule"
+    | "selectorList"
+    | "selector"
+    | "block"
+    | "declarationList"
+    | "declaration"
+    | "value";
+
+  export interface ParseOptions {
+    context?: ParseContext;
+    atrule?: string | null;
+    positions?: boolean;
+    onParseError?: (error: any, fallbackNode?: Raw) => void;
+    onComment?: (value: string, loc: SourceLocation | null) => void;
+    onToken?:
+      | ((type: number, start: number, end: number, index: number) => void)
+      | Array<{ type: number; start: number; end: number }>
+      | null;
+    filename?: string;
+    offset?: number;
+    line?: number;
+    column?: number;
+    parseAtrulePrelude?: boolean;
+    parseRulePrelude?: boolean;
+    parseValue?: boolean;
+    parseCustomProperty?: boolean;
+  }
+
+  // Strict overloads by context
+  export function parse(source: string): StyleSheet;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context?: "stylesheet" }
+  ): StyleSheet;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "atrule" }
+  ): Atrule;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "atrulePrelude" }
+  ): AtrulePrelude;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "mediaQueryList" }
+  ): MediaQueryList;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "mediaQuery" }
+  ): MediaQuery;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "rule" }
+  ): Rule;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "selectorList" }
+  ): SelectorList;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "selector" }
+  ): Selector;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "block" }
+  ): Block;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "declarationList" }
+  ): DeclarationList;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "declaration" }
+  ): Declaration;
+  export function parse(
+    source: string,
+    options: ParseOptions & { context: "value" }
+  ): Value;
+  // Fallback
+  export function parse(source: string, options: ParseOptions): CssNode;
+
+  export function generate(
+    ast: CssNode,
+    options: {
+      sourceMap: true;
+      decorator?: (node: CssNode) => any;
+      mode?: "spec" | "safe";
+    }
+  ): { css: string; map: any };
+  export function generate(
+    ast: CssNode,
+    options?: {
+      sourceMap?: false;
+      decorator?: (node: CssNode) => any;
+      mode?: "spec" | "safe";
+    }
+  ): string;
+
+  // -------------------------------------------------
+  // Traversal helpers
+  // -------------------------------------------------
+  export type WalkHandler = (
+    node: CssNode,
+    item?: ListItem<CssNode>,
+    list?: List<CssNode>
+  ) => any;
+  export interface WalkOptions {
+    enter?: WalkHandler;
+    leave?: WalkHandler;
+    visit?: CssNode["type"] | null;
+    reverse?: boolean;
+  }
+  export function walk(ast: CssNode, options: WalkOptions | WalkHandler): void;
+  export function find(ast: CssNode, fn: WalkHandler): CssNode | null;
+  export function findLast(ast: CssNode, fn: WalkHandler): CssNode | null;
+  export function findAll(ast: CssNode, fn: WalkHandler): CssNode[];
+
+  // -------------------------------------------------
+  // Utils
+  // -------------------------------------------------
+  export function clone<T extends CssNode>(ast: T): T;
+  export function fromPlainObject<T extends { children?: any }>(obj: T): T;
+  export function toPlainObject<T extends { children?: any }>(ast: T): T;
+
+  export interface PropertyInfo {
+    basename: string;
+    name: string;
+    hack: string;
+    vendor: string;
+    prefix: string;
+    custom: boolean;
+  }
+  export function property(name: string): PropertyInfo;
+
+  export interface KeywordInfo {
+    basename: string;
+    name: string;
+    vendor: string;
+    prefix: string;
+    custom: boolean;
+  }
+  export function keyword(name: string): KeywordInfo;
+
+  export namespace ident {
+    function decode(value: string): string;
+    function encode(value: string): string;
+  }
+  export namespace string {
+    function decode(value: string): string;
+    function encode(value: string, preferSingleQuotes?: boolean): string;
+  }
+  export namespace url {
+    function decode(value: string): string;
+    function encode(value: string): string;
+  }
+
+  // -------------------------------------------------
+  // Definition syntax (values) sub-API
+  // -------------------------------------------------
+  export namespace definitionSyntax {
+    // AST nodes for definition syntax are intentionally minimal here
+    interface Base {
+      type: string;
+    }
+    interface Group extends Base {
+      type: "Group";
+      terms: Base[];
+      combinator: " " | "|" | "||" | "&&";
+      disallowEmpty: boolean;
+      explicit: boolean;
+    }
+    interface Keyword extends Base {
+      type: "Keyword";
+      name: string;
+    }
+    interface Function extends Base {
+      type: "Function";
+      name: string;
+    }
+    interface String extends Base {
+      type: "String";
+      value: string;
+    }
+    interface Property extends Base {
+      type: "Property";
+      name: string;
+    }
+    interface Type extends Base {
+      type: "Type";
+      name: string;
+      opts: Range | null;
+    }
+    interface Range extends Base {
+      type: "Range";
+      min: number | null;
+      max: number | null;
+    }
+    interface Multiplier extends Base {
+      type: "Multiplier";
+      comma: boolean;
+      min: number;
+      max: number;
+      term: Base;
+    }
+
+    type Node =
+      | Group
+      | Keyword
+      | Function
+      | String
+      | Property
+      | Type
+      | Range
+      | Multiplier
+      | Base;
+
+    function parse(source: string): Node;
+    function walk(
+      node: Node,
+      options:
+        | { enter?: (n: Node) => void; leave?: (n: Node) => void }
+        | ((n: Node) => void),
+      context?: any
+    ): void;
+    function generate(
+      node: Node,
+      options?: {
+        forceBraces?: boolean;
+        compact?: boolean;
+        decorate?: (content: string, node: Node) => string;
+      }
+    ): string;
+  }
+
+  // -------------------------------------------------
+  // Lexer
+  // -------------------------------------------------
+  export interface AtruleSyntaxConfig {
+    prelude?: string | definitionSyntax.Node | ((ref?: any) => any) | null;
+    descriptors?: Record<
+      string,
+      string | definitionSyntax.Node | ((ref?: any) => any)
+    > | null;
+  }
+
+  export interface LexerConfig {
+    generic?: boolean;
+    cssWideKeywords?: string[];
+    units?: Record<string, string[]>;
+    types?: Record<
+      string,
+      string | definitionSyntax.Node | ((ref?: any) => any)
+    >;
+    atrules?: Record<string, AtruleSyntaxConfig>;
+    properties?: Record<
+      string,
+      string | definitionSyntax.Node | ((ref?: any) => any)
+    >;
+  }
+
+  export interface MatchResult {
+    matched: any;
+    error: Error | null;
+    iterations: number;
+    isType(node: CssNode | null | undefined, name: string): boolean;
+    getTrace(
+      node: CssNode | null | undefined
+    ): Array<{ type: string; name: string }>;
+  }
+
+  export interface FragmentResult {
+    parent: List<CssNode>;
+    nodes: List<CssNode>;
+  }
+
+  export class Lexer {
+    constructor(config?: LexerConfig, syntax?: any, structure?: any);
+
+    cssWideKeywords: string[];
+    units: Record<string, string[]>;
+
+    checkStructure(
+      ast: CssNode
+    ): false | Array<{ node: CssNode; message: string }>;
+
+    checkAtruleName(atruleName: string): Error | void;
+    checkAtrulePrelude(
+      atruleName: string,
+      prelude?: string | CssNode | null
+    ): Error | void;
+    checkAtruleDescriptorName(
+      atruleName: string,
+      descriptorName: string
+    ): Error | void;
+    checkPropertyName(propertyName: string): Error | void;
+
+    matchAtrulePrelude(
+      atruleName: string,
+      prelude?: string | CssNode | null
+    ): MatchResult;
+    matchAtruleDescriptor(
+      atruleName: string,
+      descriptorName: string,
+      value: string | CssNode
+    ): MatchResult;
+    matchDeclaration(node: CssNode): MatchResult;
+    matchProperty(propertyName: string, value: string | CssNode): MatchResult;
+    matchType(typeName: string, value: string | CssNode): MatchResult;
+    match(
+      syntax: string | definitionSyntax.Node,
+      value: string | CssNode
+    ): MatchResult;
+
+    findValueFragments(
+      propertyName: string,
+      value: Value,
+      type: string,
+      name: string
+    ): FragmentResult[];
+    findDeclarationValueFragments(
+      declaration: Declaration,
+      type: string,
+      name: string
+    ): FragmentResult[];
+    findAllFragments(
+      ast: CssNode,
+      type: string,
+      name: string
+    ): FragmentResult[];
+
+    // descriptor getters
+    getAtrule(atruleName: string, fallbackBasename?: boolean): any | null;
+    getAtrulePrelude(
+      atruleName: string,
+      fallbackBasename?: boolean
+    ): any | null;
+    getAtruleDescriptor(atruleName: string, name: string): any | null;
+    getProperty(propertyName: string, fallbackBasename?: boolean): any | null;
+    getType(name: string): any | null;
+
+    validate(): null | {
+      errors: string[];
+      types: string[];
+      properties: string[];
+    };
+    dump(syntaxAsAst?: boolean, pretty?: boolean): any;
+    toString(): string;
+  }
+
+  export const lexer: Lexer;
+  export function createLexer(config?: LexerConfig): Lexer;
+
+  // -------------------------------------------------
+  // Tokenizer / misc exports (lightly typed)
+  // -------------------------------------------------
+  export const tokenTypes: Record<string, number>;
+  export const tokenNames: string[];
+  export function tokenize(input: string): IterableIterator<any>;
+
+  // Syntax factory and forking
+  export function createSyntax(config: any): any;
+  export function fork(ext?: any): any;
+}
+
+// Optional subpath module shims to enable tree-shake-style imports
+declare module "css-tree/lexer" {
+  export * from "css-tree";
+}
+declare module "css-tree/parser" {
+  export type { ParseOptions, CssNode } from "css-tree";
+  export { parse as default } from "css-tree";
+}
+declare module "css-tree/generator" {
+  export { generate as default } from "css-tree";
+}
+declare module "css-tree/walker" {
+  export {
+    walk,
+    find,
+    findAll,
+    findLast,
+    WalkOptions,
+    WalkHandler,
+  } from "css-tree";
+}
+declare module "css-tree/definition-syntax" {
+  export { definitionSyntax } from "css-tree";
+}
+declare module "css-tree/utils" {
+  export {
+    List,
+    ListItem,
+    clone,
+    fromPlainObject,
+    toPlainObject,
+    property,
+    keyword,
+    ident,
+    string,
+    url,
+  } from "css-tree";
+}