@bamboocss/vite 1.13.0

package/dist/index.d.cts

@@ -0,0 +1,154 @@
+import { Context } from "@bamboocss/core";
+import { Dict, ParserResultInterface } from "@bamboocss/types";
+import MagicString from "magic-string";
+import { Plugin } from "vite";
+
+//#region src/runtime-css.d.ts
+/**
+ * The generated runtime's `css`, rebuilt in-process from a resolved context.
+ *
+ * A fold replaces a call with the string the runtime would have returned, so it has
+ * to compute that string the same way the runtime does — not the way the stylesheet
+ * does. The two differ in one respect that matters here: `StyleDecoder` escapes class
+ * names for use in a CSS selector (`.c_red\.300`), while the runtime emits the raw
+ * value that belongs in a `class` attribute (`c_red.300`). Folding the decoder's form
+ * would put a stray backslash in the DOM.
+ *
+ * Matching the runtime this way makes the substitution behaviour-preserving by
+ * construction. What still needs asserting — and is asserted in `__tests__` — is that
+ * these class names correspond to rules the build actually emits.
+ *
+ * Mirrors `generateCssFn` in `@bamboocss/generator`: `css = (...styles) =>
+ * cssFn(mergeCss(...styles))`.
+ */
+interface RuntimeCss {
+  (...styles: Dict[]): string;
+}
+declare const createRuntimeCss: (ctx: Context) => RuntimeCss;
+//#endregion
+//#region src/fold.d.ts
+/**
+ * Why a call site was left alone. Surfaced through `panda`-style diagnostics so a
+ * user can tell the difference between "this folded" and "this silently didn't".
+ */
+type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty';
+interface FoldedCall {
+  name: string;
+  /** The class string resolved outright, empty when the whole call lowered to ternaries. */
+  className: string;
+  /**
+   * Every class literal the replacement emits, including both arms of each ternary — so a
+   * consumer checking that folded classes have CSS behind them sees the branches too,
+   * which `className` alone does not carry.
+   */
+  classNames: string[];
+  start: number;
+  end: number;
+}
+interface SkippedCall {
+  name: string;
+  reason: SkipReason;
+  start: number;
+  end: number;
+}
+interface FoldResult {
+  code: string;
+  /** Null when nothing was folded, so callers can return the original module untouched. */
+  map: ReturnType<MagicString['generateMap']> | null;
+  folded: FoldedCall[];
+  skipped: SkippedCall[];
+  /**
+   * Other modules a folded value came from.
+   *
+   * The extractor resolves values across files, so `css(importedStyles, { … })` folds
+   * to a string that depends on a file this module only imports. Without registering
+   * that edge, editing the imported module leaves a stale literal behind in every
+   * consumer. Bundlers need these as watch files.
+   */
+  dependencies: string[];
+}
+interface FoldOptions {
+  ctx: Context;
+  code: string;
+  parserResult: ParserResultInterface;
+  filePath: string;
+  /** Reuse one runtime `css` across files in a build. */
+  runtimeCss?: RuntimeCss;
+  /**
+   * Also collapse `styled.*` and pattern elements to the tag they render. On by default,
+   * since the JSX factory is where most style resolution happens at runtime.
+   */
+  jsx?: boolean;
+  /**
+   * Split a `css()` call or a `styled.*` element that is only partly static, keeping the
+   * dynamic half at runtime. On by default.
+   */
+  partial?: boolean;
+}
+declare const foldSource: (options: FoldOptions) => FoldResult;
+//#endregion
+//#region src/plugin.d.ts
+interface BambooVitePluginOptions {
+  /**
+   * Rewrite statically-resolvable `css()` and pattern calls into literal class
+   * strings, so they cost nothing at runtime.
+   *
+   * Off by default, and build-only — see the "Source transformation" guide for why.
+   *
+   * @default false
+   */
+  transform?: boolean;
+  /**
+   * Also collapse `styled.*` and pattern elements to the tag they render, rather than
+   * folding call sites alone.
+   *
+   * On by default, and the larger of the two wins: the factory runs `splitProps`,
+   * `css()` and `cx` for every element on every render, inside a `forwardRef` component.
+   *
+   * @default true
+   */
+  jsx?: boolean;
+  /**
+   * Split a call or element that is only partly static, so the resolvable half becomes a
+   * literal and only the rest keeps its runtime call. On by default.
+   *
+   * Without it a single dynamic value declines the whole site.
+   *
+   * @default true
+   */
+  partial?: boolean;
+  /** Path to `bamboo.config.ts`. Resolved the same way the CLI resolves it. */
+  configPath?: string;
+  cwd?: string;
+  /**
+   * Report every call site that did *not* fold, and why, per file. Useful when a call
+   * you expected to collapse still shows up in the bundle.
+   *
+   * @default false
+   */
+  reportSkipped?: boolean;
+  /**
+   * Print a coverage summary when the build finishes: how much folded, and what the
+   * remainder was declined for.
+   *
+   * On by default. Without it there is no signal that the transform did anything, and
+   * no way to tell a project where everything folds from one where nothing does.
+   *
+   * @default true
+   */
+  reportSummary?: boolean;
+}
+/**
+ * Vite integration for Bamboo CSS.
+ *
+ * This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
+ * job is the optional build-time fold.
+ *
+ * It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+ * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
+ * sees them would otherwise make the two disagree, and a folded class could end up
+ * with no matching rule.
+ */
+declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin;
+//#endregion
+export { type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, bamboocss, bamboocss as default, createRuntimeCss, foldSource };

package/dist/index.d.mts

@@ -0,0 +1,154 @@
+import MagicString from "magic-string";
+import { Context } from "@bamboocss/core";
+import { Dict, ParserResultInterface } from "@bamboocss/types";
+import { Plugin } from "vite";
+
+//#region src/runtime-css.d.ts
+/**
+ * The generated runtime's `css`, rebuilt in-process from a resolved context.
+ *
+ * A fold replaces a call with the string the runtime would have returned, so it has
+ * to compute that string the same way the runtime does — not the way the stylesheet
+ * does. The two differ in one respect that matters here: `StyleDecoder` escapes class
+ * names for use in a CSS selector (`.c_red\.300`), while the runtime emits the raw
+ * value that belongs in a `class` attribute (`c_red.300`). Folding the decoder's form
+ * would put a stray backslash in the DOM.
+ *
+ * Matching the runtime this way makes the substitution behaviour-preserving by
+ * construction. What still needs asserting — and is asserted in `__tests__` — is that
+ * these class names correspond to rules the build actually emits.
+ *
+ * Mirrors `generateCssFn` in `@bamboocss/generator`: `css = (...styles) =>
+ * cssFn(mergeCss(...styles))`.
+ */
+interface RuntimeCss {
+  (...styles: Dict[]): string;
+}
+declare const createRuntimeCss: (ctx: Context) => RuntimeCss;
+//#endregion
+//#region src/fold.d.ts
+/**
+ * Why a call site was left alone. Surfaced through `panda`-style diagnostics so a
+ * user can tell the difference between "this folded" and "this silently didn't".
+ */
+type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty';
+interface FoldedCall {
+  name: string;
+  /** The class string resolved outright, empty when the whole call lowered to ternaries. */
+  className: string;
+  /**
+   * Every class literal the replacement emits, including both arms of each ternary — so a
+   * consumer checking that folded classes have CSS behind them sees the branches too,
+   * which `className` alone does not carry.
+   */
+  classNames: string[];
+  start: number;
+  end: number;
+}
+interface SkippedCall {
+  name: string;
+  reason: SkipReason;
+  start: number;
+  end: number;
+}
+interface FoldResult {
+  code: string;
+  /** Null when nothing was folded, so callers can return the original module untouched. */
+  map: ReturnType<MagicString['generateMap']> | null;
+  folded: FoldedCall[];
+  skipped: SkippedCall[];
+  /**
+   * Other modules a folded value came from.
+   *
+   * The extractor resolves values across files, so `css(importedStyles, { … })` folds
+   * to a string that depends on a file this module only imports. Without registering
+   * that edge, editing the imported module leaves a stale literal behind in every
+   * consumer. Bundlers need these as watch files.
+   */
+  dependencies: string[];
+}
+interface FoldOptions {
+  ctx: Context;
+  code: string;
+  parserResult: ParserResultInterface;
+  filePath: string;
+  /** Reuse one runtime `css` across files in a build. */
+  runtimeCss?: RuntimeCss;
+  /**
+   * Also collapse `styled.*` and pattern elements to the tag they render. On by default,
+   * since the JSX factory is where most style resolution happens at runtime.
+   */
+  jsx?: boolean;
+  /**
+   * Split a `css()` call or a `styled.*` element that is only partly static, keeping the
+   * dynamic half at runtime. On by default.
+   */
+  partial?: boolean;
+}
+declare const foldSource: (options: FoldOptions) => FoldResult;
+//#endregion
+//#region src/plugin.d.ts
+interface BambooVitePluginOptions {
+  /**
+   * Rewrite statically-resolvable `css()` and pattern calls into literal class
+   * strings, so they cost nothing at runtime.
+   *
+   * Off by default, and build-only — see the "Source transformation" guide for why.
+   *
+   * @default false
+   */
+  transform?: boolean;
+  /**
+   * Also collapse `styled.*` and pattern elements to the tag they render, rather than
+   * folding call sites alone.
+   *
+   * On by default, and the larger of the two wins: the factory runs `splitProps`,
+   * `css()` and `cx` for every element on every render, inside a `forwardRef` component.
+   *
+   * @default true
+   */
+  jsx?: boolean;
+  /**
+   * Split a call or element that is only partly static, so the resolvable half becomes a
+   * literal and only the rest keeps its runtime call. On by default.
+   *
+   * Without it a single dynamic value declines the whole site.
+   *
+   * @default true
+   */
+  partial?: boolean;
+  /** Path to `bamboo.config.ts`. Resolved the same way the CLI resolves it. */
+  configPath?: string;
+  cwd?: string;
+  /**
+   * Report every call site that did *not* fold, and why, per file. Useful when a call
+   * you expected to collapse still shows up in the bundle.
+   *
+   * @default false
+   */
+  reportSkipped?: boolean;
+  /**
+   * Print a coverage summary when the build finishes: how much folded, and what the
+   * remainder was declined for.
+   *
+   * On by default. Without it there is no signal that the transform did anything, and
+   * no way to tell a project where everything folds from one where nothing does.
+   *
+   * @default true
+   */
+  reportSummary?: boolean;
+}
+/**
+ * Vite integration for Bamboo CSS.
+ *
+ * This plugin does not emit CSS — keep your existing PostCSS setup for that. Its only
+ * job is the optional build-time fold.
+ *
+ * It runs with `enforce: 'pre'` so it sees module source as close as possible to what
+ * the CSS extractor reads off disk. A plugin that rewrites style calls before bamboo
+ * sees them would otherwise make the two disagree, and a folded class could end up
+ * with no matching rule.
+ */
+declare const bamboocss: (options?: BambooVitePluginOptions) => Plugin;
+//#endregion
+export { type BambooVitePluginOptions, type FoldOptions, type FoldResult, type FoldedCall, type RuntimeCss, type SkipReason, type SkippedCall, bamboocss, bamboocss as default, createRuntimeCss, foldSource };