rnwind 0.0.1 → 0.0.2

package/lib/esm/core/parser/tw-parser.d.ts

@@ -0,0 +1,194 @@
+import { type SourceEntry } from '@tailwindcss/oxide';
+import { type GradientAtomInfo } from './gradient';
+import { type HapticRequest } from './haptics';
+import type { RNStyle } from './types';
+/** Parser configuration — one instance per Metro session, theme CSS fixed. */
+export interface TailwindParserConfig {
+    /**
+     * Theme CSS passed to `@tailwindcss/node`'s compiler. Typically the
+     * user's `global.css`. We append `theme(inline)` to the tailwindcss
+     * import so Tailwind resolves every `var(--theme-token)` at compile
+     * time — that gives lightningcss fully-typed values (integers / rems /
+     * colors) instead of unresolved `var()` references.
+     */
+    themeCss: string;
+    /**
+     * Glob sources the oxide Scanner walks at project-scan time
+     * (`parseProject()`). Typically
+     * `[{ base: projectRoot, pattern: '**\/*.{ts,tsx,js,jsx}', negated: false }]`
+     * plus negated globs for `node_modules` and the rnwind cache dir.
+     *
+     * When omitted, the scanner has no sources and `parseProject()`
+     * returns an empty result — `parseAtoms()` (per-file, content-driven)
+     * still works without sources.
+     */
+    sources?: readonly SourceEntry[];
+}
+/** Per-call inputs — Metro hands us file content + filename; we derive the extension. */
+export interface ParseOptions {
+    content: string;
+    extension: string;
+}
+/** One parsed keyframe step — offset plus the RN style at that offset. */
+export interface KeyframeStep {
+    offset: string;
+    style: RNStyle;
+}
+/** One parsed `@keyframes` animation block. */
+export interface KeyframeBlock {
+    name: string;
+    steps: KeyframeStep[];
+}
+/** Interactive variant ('active' / 'focus') an `active:`/`focus:` atom carries. */
+export type InteractiveStateTag = 'active' | 'focus';
+/**
+ * Per-scheme resolved style for a single utility class. Keys are scheme
+ * names declared via `@variant <name>` in the theme CSS (or the synthetic
+ * `'base'` scheme for themes without variants). Values are the RN style
+ * object under that scheme.
+ *
+ * The reserved `__state` key is set on `active:` / `focus:` atoms so
+ * the build-side style-builder can tag the atom for `precomputeHoist`
+ * — which routes interactive atoms into the stated-hoist's 4-state
+ * precompute. Standard atoms have no `__state`.
+ */
+export type SchemedStyle = Readonly<Record<string, RNStyle>> & {
+    /** Interactive-state gate set by `active:` / `focus:` variants. */
+    readonly __state?: InteractiveStateTag;
+};
+/** Full result of one `parseAtoms` call. */
+export interface ParsedOutput {
+    /** Resolved RN style per utility class, per declared scheme. */
+    atoms: Map<string, SchemedStyle>;
+    /** `@keyframes <name> { ... }` blocks the candidates pulled in. */
+    keyframes: Map<string, KeyframeBlock>;
+    /** `@property --x { initial-value: y }` declared custom-property defaults. */
+    propertyDefaults: Map<string, string>;
+    /**
+     * Gradient metadata per atom, for atoms that play a role in a
+     * Tailwind v4 gradient (`from-*`, `via-*`, `to-*`, `bg-gradient-to-*`,
+     * `bg-linear-to-*`). The transformer reads this map to extract
+     * `colors / start / end` props at JSX-rewrite time. Regular non-
+     * gradient atoms don't appear here.
+     */
+    gradientAtoms: Map<string, GradientAtomInfo>;
+    /**
+     * Haptic metadata per atom for classes that emit a
+     * `--rnwind-haptic` marker. The transformer reads this map to
+     * strip the atom from the className and wire a mount-time or
+     * press-time call into the `onHaptics` callback registered on
+     * `<SchemeProvider>`.
+     */
+    hapticAtoms: Map<string, HapticRequest>;
+    /** Candidates oxide surfaced, in document order. */
+    candidates: readonly string[];
+    /** Every scheme the theme declares (or `['base']` when there are no `@variant` blocks). */
+    schemes: readonly string[];
+    /**
+     * Responsive breakpoint name → minimum-width threshold (px). Pulled from
+     * `--breakpoint-*` tokens in the compiled `:root` block, so both
+     * Tailwind defaults (`sm`, `md`, `lg`, `xl`, `2xl`) and any user
+     * override (e.g. `--breakpoint-3xl: 120rem`) land here. Used by the
+     * style-builder to emit `registerBreakpoints({...})` in the manifest
+     * so the runtime can filter `md:*` / `lg:*` atoms based on the
+     * provider's `windowWidth`.
+     */
+    breakpoints: ReadonlyMap<string, number>;
+}
+/**
+ * Parses one source file's Tailwind usage into RN-ready style objects.
+ *
+ * Pipeline:
+ *  1. `@tailwindcss/oxide` Scanner finds every Tailwind candidate.
+ *  2. `@tailwindcss/node` compiler emits CSS for those candidates with
+ *     theme tokens inlined.
+ *  3. lightningcss `transform` + typed visitor walks the emitted CSS:
+ *     - `style` rules → per-class RN-style object.
+ *     - `@keyframes` rules → per-name step map (Reanimated-ready).
+ *     - `@property` rules → custom-property initial values.
+ *
+ * One instance holds one Scanner + one lazily-built compiler so repeated
+ * calls share upstream state. Theme CSS is fixed at construction — theme
+ * edits require a new parser.
+ */
+export declare class TailwindParser {
+    private readonly config;
+    private readonly scanner;
+    private compiler;
+    private readonly themeSchemes;
+    private readonly schemeAliases;
+    /**
+     * Memoise `resolveCandidates` results by candidate-list fingerprint.
+     * Fast Refresh hits this on every save: oxide's scan is cheap, but
+     * the LightningCSS visitor walk over the compiled CSS is ~2ms per
+     * file. A file whose `className` literals didn't change returns the
+     * SAME candidate set, so the second `parseAtoms` call returns the
+     * cached `ParsedOutput` — zero compile, zero visitor walk.
+     *
+     * Theme CSS changes build a new `TailwindParser` (from
+     * `getRnwindState` detecting the hash shift), so this cache is
+     * naturally invalidated — no stale-theme values leak through.
+     */
+    private readonly parseCache;
+    /**
+     * Build a parser bound to a theme CSS source. `@theme` and
+     * `@variant` blocks are extracted eagerly into a scheme table the
+     * visitor consults when resolving `var(--x)` references.
+     * @param config Parser configuration.
+     */
+    constructor(config: TailwindParserConfig);
+    /**
+     * Schemes declared by the user — either every `@variant <name>` block
+     * found (in declaration order) or just `['base']` for themes without
+     * any variants. Used to decide how many per-scheme buckets the
+     * per-atom resolver fills. Exposed publicly so Metro integration can
+     * hand the names to the `.d.ts` generator without a full parse.
+     * @returns Scheme names.
+     */
+    get declaredSchemes(): readonly string[];
+    /**
+     * Build an effective var table for one scheme — base vars overridden by
+     * variant vars. When the scheme IS `'base'` (no variants declared), the
+     * base table is returned unchanged.
+     * @param scheme Scheme name.
+     * @returns Effective var name → value lookup for the scheme.
+     */
+    private effectiveVars;
+    /**
+     * Build the Tailwind compiler on first use and cache it. The theme CSS
+     * gets a `theme(inline)` modifier on its `@import 'tailwindcss'` so
+     * lightningcss sees resolved colors/lengths instead of `var()` refs.
+     * @returns Cached compiler instance.
+     */
+    private ensureCompiler;
+    /**
+     * Parse one file's Tailwind usage into the full typed result.
+     * @param options Source content + extension.
+     * @param options.content Raw source text to scan for Tailwind candidates.
+     * @param options.extension File extension (`tsx`, `ts`, `jsx`, `js`) — feeds oxide's tokenizer.
+     * @returns RN atoms, keyframes, property defaults, candidates list.
+     */
+    parseAtoms({ content, extension }: ParseOptions): Promise<ParsedOutput>;
+    /**
+     * Scan every source file the Scanner was configured to watch via
+     * `sources` and resolve the union of candidates in one pass. Used by
+     * `UnionBuilder` at Metro startup (and on first worker access) to
+     * populate the complete atom registry before ANY per-file transform
+     * has run — so scheme files never ship a partial view of the theme.
+     *
+     * Hot-reload path uses `parseAtoms` for the per-file delta; this one
+     * only runs once per parser instance (and whenever the parser is
+     * rebuilt due to a theme CSS change).
+     * @returns Full RN atoms, keyframes, property defaults for every
+     *   candidate discovered across the configured sources.
+     */
+    parseProject(): Promise<ParsedOutput>;
+    /**
+     * Compile + typed-visit the given candidate class names. Shared
+     * implementation for both `parseAtoms` (single file) and
+     * `parseProject` (whole project).
+     * @param candidates Class-name candidates the oxide Scanner produced.
+     * @returns Fully-typed parser result.
+     */
+    private resolveCandidates;
+}