tailwind-styled-v4 5.0.11 → 5.0.13

package/dist/index-DJv28Uzq.d.mts

@@ -0,0 +1,464 @@
+import { e as AnalyzerSemanticReport, d as AnalyzerReport, h as analyzeWorkspace$1 } from './analyzeWorkspace-DpVPccjz.mjs';
+import { b as ScanWorkspaceResult, a as ScanWorkspaceOptions } from './schemas-DR-SLxZZ.mjs';
+
+declare class RuleId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class SelectorId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class VariantChainId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class PropertyId {
+    readonly value: number;
+    readonly name?: string | undefined;
+    constructor(value: number, name?: string | undefined);
+    toString(): string;
+}
+declare class ValueId {
+    readonly value: number;
+    readonly name?: string | undefined;
+    constructor(value: number, name?: string | undefined);
+    toString(): string;
+}
+declare class LayerId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class ConditionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class CascadeResolutionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare enum Origin {
+    UserAgent = 0,
+    UserNormal = 1,
+    AuthorNormal = 2,
+    AuthorImportant = 3,
+    UserImportant = 4
+}
+declare enum Importance {
+    Normal = 0,
+    Important = 1
+}
+declare enum ConditionResult {
+    Active = 0,
+    Inactive = 1,
+    Unknown = 2
+}
+declare enum CascadeStage {
+    Origin = 0,
+    Layer = 1,
+    Importance = 2,
+    Specificity = 3,
+    Order = 4
+}
+type ResolutionCause = {
+    type: "LowerOrigin";
+    winnerOrigin: Origin;
+    loserOrigin: Origin;
+} | {
+    type: "LowerLayer";
+    winnerLayer: string;
+    loserLayer: string;
+} | {
+    type: "LowerImportance";
+} | {
+    type: "LowerSpecificity";
+    delta: number;
+} | {
+    type: "EarlierOrder";
+    delta: number;
+} | {
+    type: "InactiveCondition";
+    condition: string;
+};
+interface ResolutionReason {
+    causes: readonly ResolutionCause[];
+    finalDecision: string;
+}
+interface SelectorIR {
+    id: SelectorId;
+    normalized: string;
+    specificity: number;
+    parts: readonly string[];
+}
+interface VariantChainIR {
+    id: VariantChainId;
+    chain: readonly VariantChainId[];
+    conditionGraphId: number | null;
+}
+interface ConditionIR {
+    id: ConditionId;
+    conditionType: string;
+    expression: string;
+}
+interface RuleIR {
+    id: RuleId;
+    selector: SelectorId;
+    variantChain: VariantChainId;
+    property: PropertyId;
+    value: ValueId;
+    origin: Origin;
+    importance: Importance;
+    layer: LayerId | null;
+    layerOrder: number;
+    specificity: number;
+    condition: ConditionId | null;
+    conditionResult: ConditionResult;
+    insertionOrder: number;
+    fingerprint: string;
+    source: SourceLocation;
+}
+interface PropertyBucketIR {
+    property: PropertyId;
+    rules: readonly RuleId[];
+}
+interface CascadeResolutionIR {
+    id: CascadeResolutionId;
+    property: PropertyId;
+    winner: RuleId;
+    losers: readonly RuleId[];
+    reason: ResolutionReason;
+    stage: CascadeStage;
+}
+interface StyleGraphIR {
+    ruleConflicts: Map<RuleId, readonly RuleId[]>;
+}
+interface FinalComputedStyleIR {
+    className: string;
+    resolvedProperties: Map<PropertyId, CascadeResolutionId>;
+}
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Generate a short fingerprint string from a list of ordered parts.
+ * Native-only: delegates to Rust `create_fingerprint()` (FNV-1a, base-36 output).
+ */
+declare function createFingerprint(parts: string[]): string;
+declare function createResolutionReason(causes: ResolutionCause[], finalDecision: string): ResolutionReason;
+
+/**
+ * tailwind-styled-v4 — Cascade Resolver
+ *
+ * JS layer: state management (rule collection, class registration).
+ * Rust layer: cascade algorithm (sort, compare, resolve winner/loser).
+ *
+ * Moved to native: compareCascade, resolveProperty, buildResolutionReason,
+ * determineCascadeStage — all pure computation, zero browser API.
+ *
+ * Rust #[napi] fn: resolve_cascade(rules_json: String) -> String
+ */
+
+declare class CascadeResolver {
+    private readonly rules;
+    private readonly classRules;
+    private readonly styleGraph;
+    addRule(rule: RuleIR): void;
+    addRules(rules: RuleIR[]): void;
+    registerClass(className: string, ruleIds: RuleId[]): void;
+    getRule(ruleId: RuleId): RuleIR | undefined;
+    getClassRules(className: string): RuleId[] | undefined;
+    getStyleGraph(): StyleGraphIR;
+    /**
+     * Resolve cascade for a specific class.
+     * Delegates sort + winner selection to Rust.
+     */
+    resolveByClassName(className: string): {
+        resolvedProperties: Map<PropertyId, CascadeResolutionIR>;
+    } | null;
+    /**
+     * Resolve cascade for all rules.
+     * Delegates sort + winner selection to Rust.
+     */
+    resolveAllProperties(): Map<PropertyId, CascadeResolutionIR>;
+    /**
+     * Resolve cascade for a specific set of rule IDs.
+     */
+    resolveForClass(classRuleIds: RuleId[]): Map<PropertyId, CascadeResolutionIR>;
+    /**
+     * Resolve cascade for a single property bucket.
+     */
+    resolveProperty(property: PropertyId): CascadeResolutionIR | null;
+    getResolution(_id: CascadeResolutionId): CascadeResolutionIR | undefined;
+}
+
+/**
+ * tailwind-styled-v4 — Cascade Tracer
+ *
+ * Delegates cascade resolution to CascadeResolver (Rust-backed).
+ * JS layer: format trace output only.
+ *
+ * Removed from JS: resolvePropertyTraced, compareCascadeTraced,
+ * buildResolutionReasonTraced, determineCascadeStageTraced.
+ */
+
+interface VariantTrace {
+    name: string;
+    value: string;
+    source: SourceLocation;
+}
+interface RuleTrace {
+    property: string;
+    value: string;
+    applied: boolean;
+    reason: string | null;
+    source: SourceLocation;
+    specificity: number;
+}
+interface ConflictTrace {
+    property: string;
+    winner: string;
+    loser: string;
+    stage: string;
+    causes: string[];
+}
+interface FinalStyleProperty {
+    property: string;
+    value: string;
+}
+interface TraceResult {
+    class: string;
+    definedAt: SourceLocation;
+    variants: VariantTrace[];
+    rules: RuleTrace[];
+    conflicts: ConflictTrace[];
+    finalStyle: FinalStyleProperty[];
+}
+interface ProvenanceData {
+    className: string;
+    source: SourceLocation;
+    variants: Map<string, VariantTrace>;
+    rules: Map<string, RuleIR[]>;
+}
+declare function buildProvenanceChain(className: string): ProvenanceData;
+declare function trace(className: string, resolver: CascadeResolver): TraceResult;
+
+interface EngineMetricsSnapshot {
+    eventsReceived: number;
+    eventsProcessed: number;
+    batchesProcessed: number;
+    incrementalUpdates: number;
+    fullRescans: number;
+    skippedLargeFiles: number;
+    queueMaxSize: number;
+    lastBuildMs: number;
+    avgBuildMs: number;
+}
+declare class EngineMetricsCollector {
+    private eventsReceived;
+    private eventsProcessed;
+    private batchesProcessed;
+    private incrementalUpdates;
+    private fullRescans;
+    private skippedLargeFiles;
+    private queueMaxSize;
+    private lastBuildMs;
+    private totalBuildMs;
+    markEventReceived(queueSize: number): void;
+    markBatchProcessed(batchSize: number): void;
+    markIncremental(): void;
+    markFullRescan(): void;
+    markSkippedLargeFile(): void;
+    markBuildDuration(ms: number): void;
+    snapshot(): EngineMetricsSnapshot;
+}
+
+interface EnginePluginContext {
+    root: string;
+    timestamp: number;
+}
+interface EngineWatchContext {
+    root: string;
+    timestamp: number;
+}
+interface EnginePlugin {
+    name: string;
+    beforeScan?(context: EnginePluginContext): void | Promise<void>;
+    afterScan?(scan: ScanWorkspaceResult, context: EnginePluginContext): ScanWorkspaceResult | undefined | Promise<ScanWorkspaceResult | undefined>;
+    transformClasses?(classes: string[], context: EnginePluginContext): string[] | undefined | Promise<string[] | undefined>;
+    beforeBuild?(scan: ScanWorkspaceResult, context: EnginePluginContext): void | Promise<void>;
+    afterBuild?(result: BuildResult, context: EnginePluginContext): BuildResult | undefined | Promise<BuildResult | undefined>;
+    onError?(error: Error, context: EnginePluginContext): void | Promise<void>;
+    beforeWatch?(context: EngineWatchContext): void | Promise<void>;
+    afterWatch?(context: EngineWatchContext): void | Promise<void>;
+}
+declare function runBeforeScan(plugins: EnginePlugin[], context: EnginePluginContext): Promise<void>;
+declare function runAfterScan(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<ScanWorkspaceResult>;
+declare function runTransformClasses(plugins: EnginePlugin[], classes: string[], context: EnginePluginContext): Promise<string[]>;
+declare function runBeforeBuild(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<void>;
+declare function runAfterBuild(plugins: EnginePlugin[], result: BuildResult, context: EnginePluginContext): Promise<BuildResult>;
+declare function runOnError(plugins: EnginePlugin[], error: Error, context: EnginePluginContext): Promise<void>;
+declare function runBeforeWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
+declare function runAfterWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
+
+interface EngineOptions {
+    root?: string;
+    scanner?: ScanWorkspaceOptions;
+    compileCss?: boolean;
+    tailwindConfigPath?: string;
+    plugins?: EnginePlugin[];
+    /** Enable analyzer integration - provides semantic report (unused classes, conflicts). Default: false */
+    analyze?: boolean;
+}
+interface EngineWatchOptions {
+    debounceMs?: number;
+    maxEventsPerFlush?: number;
+    largeFileThreshold?: number;
+}
+interface BuildResult {
+    scan: ScanWorkspaceResult;
+    mergedClassList: string;
+    css: string;
+    /** Analyzer semantic report - present when analyze: true in options */
+    analysis?: {
+        unusedClasses: string[];
+        classConflicts: Array<{
+            className: string;
+            files: string[];
+            classes?: string[];
+            message?: string;
+        }>;
+        classUsage: Record<string, number>;
+        semantic?: AnalyzerSemanticReport;
+        report: AnalyzerReport;
+    };
+}
+type EngineBuildWatchEventType = "initial" | "change" | "unlink" | "full-rescan";
+type EngineWatchEvent = {
+    type: EngineBuildWatchEventType;
+    filePath?: string;
+    result: BuildResult;
+    metrics?: EngineMetricsSnapshot;
+} | {
+    type: "error";
+    filePath?: string;
+    error: string;
+    metrics?: EngineMetricsSnapshot;
+};
+interface TailwindStyledEngine {
+    scan(): Promise<ScanWorkspaceResult>;
+    scanWorkspace(): Promise<ScanWorkspaceResult>;
+    analyzeWorkspace(): Promise<Awaited<ReturnType<typeof analyzeWorkspace$1>>>;
+    generateSafelist(): Promise<string[]>;
+    build(): Promise<BuildResult>;
+    watch(onEvent: (event: EngineWatchEvent) => void, options?: EngineWatchOptions): Promise<{
+        close(): void;
+    }>;
+}
+declare function createEngine(rawOptions?: EngineOptions): Promise<TailwindStyledEngine>;
+
+/**
+ * Scan workspace dan return hasil scan.
+ * Facade tipis di atas scanWorkspaceAsync dari @tailwind-styled/scanner.
+ *
+ * @example
+ * const result = await scanWorkspace({ root: "./src" })
+ * console.log(result.uniqueClasses)
+ */
+declare function scanWorkspace(opts?: {
+    root?: string;
+    extensions?: string[];
+    ignoreDirectories?: string[];
+}): Promise<ScanWorkspaceResult>;
+/**
+ * Analyze workspace — scan + analyze classes.
+ * Facade di atas runWorkspaceAnalysis.
+ *
+ * @example
+ * const report = await analyzeWorkspace({ root: "./src" })
+ * console.log(report.topClasses)
+ */
+declare function analyzeWorkspace(opts?: {
+    root?: string;
+    top?: number;
+}): Promise<Awaited<ReturnType<typeof analyzeWorkspace$1>>>;
+/**
+ * Generate safelist dari scan result.
+ * Berguna untuk Tailwind config safelist generation.
+ *
+ * @example
+ * const safelist = await generateSafelist({ root: "./src" })
+ * // Pakai di tailwind.config.ts: { safelist }
+ */
+declare function generateSafelist(opts?: {
+    root?: string;
+}): Promise<string[]>;
+/**
+ * Build CSS dari scan result.
+ * One-shot build tanpa watch mode.
+ *
+ * @example
+ * const result = await build({ root: "./src" })
+ * fs.writeFileSync("dist/tailwind.css", result.css)
+ */
+declare function build(opts?: EngineOptions): Promise<{
+    css: string;
+    classes: string[];
+    totalFiles: number;
+}>;
+
+/**
+ * High-level trace API — satu entry point untuk semua tooling.
+ *
+ * Dipakai oleh:
+ * - CLI: `tw trace <class>`
+ * - DevTools: TracePanel fetch
+ * - Dashboard: trace endpoint
+ *
+ * @example
+ * const result = await traceClass("flex", scanResult, cssString)
+ * console.log(result.finalStyle)  // [{ property: "display", value: "flex" }]
+ */
+declare function traceClass(className: string, scanResult: ScanWorkspaceResult, css: string): Promise<TraceResult | null>;
+/**
+ * Trace multiple classes at once — for batch inspection.
+ */
+declare function traceClasses(classNames: string[], scanResult: ScanWorkspaceResult, css: string): Promise<Map<string, TraceResult>>;
+interface InspectionReport {
+    className: string;
+    /** CSS rules yang dihasilkan */
+    css: string;
+    /** Properties yang di-set */
+    properties: Array<{
+        property: string;
+        value: string;
+    }>;
+    /** Classes yang berkonflik dengan ini */
+    conflicts: string[];
+    /** Files yang menggunakan class ini */
+    usedIn: string[];
+    /** Risk level untuk removal */
+    risk: "low" | "medium" | "high";
+    /** Estimated bundle contribution */
+    bundleBytes: number;
+}
+/**
+ * Inspect a single class — gabungan trace + impact + usage.
+ * Reusable surface untuk CLI (`tw why`), DevTools panel, dashboard endpoint.
+ *
+ * @example
+ * const report = await inspectClass("flex", scanResult, cssString)
+ * console.log(report.properties)  // [{ property: "display", value: "flex" }]
+ * console.log(report.usedIn)      // ["src/Button.tsx", "src/Card.tsx"]
+ * console.log(report.risk)        // "low"
+ */
+declare function inspectClass(className: string, scanResult: ScanWorkspaceResult, css?: string): Promise<InspectionReport>;
+
+export { runBeforeWatch as $, VariantChainId as A, type BuildResult as B, type CascadeResolutionIR as C, type VariantTrace as D, type EnginePlugin as E, type FinalComputedStyleIR as F, analyzeWorkspace as G, build as H, Importance as I, buildProvenanceChain as J, createEngine as K, LayerId as L, createFingerprint as M, createResolutionReason as N, Origin as O, type PropertyBucketIR as P, generateSafelist as Q, type RuleIR as R, type SourceLocation as S, type TailwindStyledEngine as T, inspectClass as U, ValueId as V, runAfterBuild as W, runAfterScan as X, runAfterWatch as Y, runBeforeBuild as Z, runBeforeScan as _, RuleId as a, runOnError as a0, runTransformClasses as a1, scanWorkspace as a2, trace as a3, traceClass as a4, traceClasses as a5, CascadeResolutionId as b, CascadeResolver as c, CascadeStage as d, type ConditionIR as e, ConditionId as f, ConditionResult as g, type ConflictTrace as h, EngineMetricsCollector as i, type EngineMetricsSnapshot as j, type EngineOptions as k, type EnginePluginContext as l, type EngineWatchContext as m, type EngineWatchEvent as n, type EngineWatchOptions as o, type FinalStyleProperty as p, type InspectionReport as q, PropertyId as r, type ResolutionCause as s, type ResolutionReason as t, type RuleTrace as u, type SelectorIR as v, SelectorId as w, type StyleGraphIR as x, type TraceResult as y, type VariantChainIR as z };