@bamboocss/types 1.33.0 → 1.34.1

package/dist/config.d.ts

@@ -407,6 +407,34 @@ interface CodegenOptions {
    * @default 'true'
    */
   shorthands?: boolean
+  /**
+   * Whether a lowered style leaf falls back to `css()` for a value that is not a scalar.
+   *
+   * Only the build-time fold calls the helper this governs. `css({ color: tone })` lowers to
+   * `cssLeaf('c_', 'color', tone)`, which builds the class by concatenation — and hands the
+   * value to `css()` when it turns out to be a condition object or a responsive array, which
+   * no concatenation describes.
+   *
+   * That fallback is the single edge keeping the css engine in a bundle. It is reachable only
+   * for a value the fold could not see the shape of, and it costs the whole prize: on
+   * `sandbox/runtime-perf`, one dynamic leaf takes a module from **923 B to 7,542 B gzipped**,
+   * because the reference pulls in `createCss`, the merge, the utility and shorthand tables
+   * and the conditions. Turned off, the same module keeps 10 top-level bindings instead of 39.
+   *
+   * Turning it off asserts something about your source: **a style value that varies at runtime
+   * is a scalar** — a string, a number, a boolean, or nothing. Write conditions and responsive
+   * values as literals at the call site, where the fold reads them and resolves each branch,
+   * rather than assembling them into a variable. A value that breaks the assertion throws,
+   * naming the property, instead of silently producing a class with no rule behind it.
+   *
+   * Pairs with `failOnUnfolded` in `@bamboocss/vite`: with the fallback off a lowered leaf no
+   * longer keeps the engine, so that option stops reporting one as a survivor. Together they
+   * are what makes zero runtime reachable for an app that has any dynamic styling at all —
+   * before this, it required an app with none.
+   *
+   * @default true
+   */
+  leafFallback?: boolean
   /**
    * File extension for generated javascript files.
    * @default 'mjs'
@@ -615,11 +643,20 @@ export interface PruneOptions {
    * are dead weight in the stylesheet that blocks first paint. Only keyframes the theme
    * declares are ever removed — one emitted by `global.css` is left alone.
    *
-   * A name is kept when any declaration in the generated css names it, and when it
-   * appears anywhere under `include`, which covers an animation assembled at runtime or
-   * applied through an inline `style` rather than through bamboo. That textual fallback
-   * is deliberately over-inclusive: keeping an unused keyframe costs bytes, dropping a
-   * used one breaks the animation.
+   * A name is kept when any declaration in the generated css names it, when a token
+   * declaration that *survives* `tokens` names it, and when it appears anywhere under
+   * `include` — which covers an animation assembled at runtime or applied through an inline
+   * `style` rather than through bamboo. That textual fallback is deliberately
+   * over-inclusive: keeping an unused keyframe costs bytes, dropping a used one breaks the
+   * animation.
+   *
+   * The middle one is why this cannot be read off the stylesheet alone. `--animations-drawer:
+   * slide-in-right 400ms` reaches its keyframe only if something reaches the property, and a
+   * property can be reached from outside the css entirely — a `token()` call, a `keepTokens`
+   * pattern, a theme, a `globalCss` export. Those are exactly the tokens `tokens` keeps, so
+   * this defers to that pass rather than asking again: a keyframe is dropped only when the
+   * declarations naming it were dropped too. Under `tokens: 'off'` nothing is removable, so
+   * every keyframe a declaration names is kept.
    *
    * @default true
    */
@@ -650,6 +687,37 @@ export interface Config
    * @default 'warn'
    */
   validation?: 'off' | 'warn' | 'error'
+
+  /**
+   * What to do about a style value shaped like a token path that resolves to no token.
+   *
+   * - `off` says nothing.
+   * - `warn` logs each one as it is transformed.
+   * - `error` fails the build, listing every one it found.
+   *
+   * Every branch of the resolver ends in `|| value`, so an unknown path is emitted as
+   * written: `background: 'accent.default'` ships as `background: accent.default`. That
+   * parses, so nothing downstream objects and the stylesheet is valid — the browser drops the
+   * declaration at compute time and the style is simply absent. It surfaces as "this colour
+   * never applied", a long way from the typo that caused it, and a build carrying one warns
+   * identically on every run until somebody happens to read the log.
+   *
+   * `warn` is the default because the test is a *shape*: a dotted value against the set of
+   * values the property enumerates. That is right about a mistyped token and cannot be sure
+   * about a literal, so escalating it is a choice a project makes once it knows its own
+   * source is clean. `[accent.default]` marks a value as literal and is never reported.
+   *
+   * Not to be confused with {@link PruneOptions.unresolvedPath}, which is about a `token()`
+   * *call* whose path the prune scan cannot follow statically — a question about pruning
+   * coverage, asked of a token that usually exists. This one is about a token that does not.
+   *
+   * A binding that does not exist is not graded here and always throws: that is read off an
+   * entrypoint's own export list rather than inferred, so there is no setting under which it
+   * is what someone meant.
+   *
+   * @default 'warn'
+   */
+  unresolvedToken?: 'off' | 'warn' | 'error'
 }
 
 export interface Preset extends ExtendableOptions, PresetOptions {

package/dist/runtime.d.ts

@@ -19,6 +19,8 @@ export interface WatchOptions extends InputOptions {
 interface FileSystem {
   readDirSync(dir: string): string[]
   existsSync(fileLike: string): boolean
+  /** False for a path that does not exist, so a caller never has to test twice. */
+  isDirSync(path: string): boolean
   glob(opts: InputOptions): string[]
   readFileSync(filePath: string): string
   rmDirSync(dirPath: string): void

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/types",
-  "version": "1.33.0",
+  "version": "1.34.1",
   "description": "The types for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "ncp": "2.0.0",
     "pkg-types": "2.3.0",
     "ts-morph": "28.0.0",
-    "@bamboocss/extractor": "1.33.0"
+    "@bamboocss/extractor": "1.34.1"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",