@bamboocss/types 1.32.0 → 1.34.0

package/dist/config.d.ts

@@ -267,12 +267,65 @@ interface FileSystemOptions {
   logFilter?: string
 }
 
+export interface PreflightOptions {
+  /**
+   * A selector the reset is confined to, so it does not style the whole document.
+   */
+  scope?: string
+  /**
+   * Where the scope is written. `parent` gives `.app table`, `element` gives `table.app`.
+   * @default 'parent'
+   */
+  level?: 'element' | 'parent'
+  /**
+   * Whether to drop the parts of the reset that style elements your source never renders.
+   *
+   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
+   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
+   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
+   * another's, of which 13% and 34% respectively is for elements those projects never render.
+   *
+   * A selector list loses only the parts naming unrendered elements, so a rule shared between
+   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
+   * are never removed.
+   *
+   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
+   * passes there is nothing to prove this against: an element rendered by a dependency's
+   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
+   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
+   * Reach for it when you control the markup and have measured that it pays.
+   *
+   * The blind spot to check first is your own entry template. The scan reads `include`, and
+   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
+   * does not match `index.html`, so an element appearing only there is dropped. Add the
+   * template to `include` to cover it — the scan reads any file listed, not only ones the
+   * parser understands, and reads it from disk rather than from the build's parsed copy, so
+   * a single-file component's markup survives the transform to tsx.
+   *
+   * A scoped reset is handled: `preflight: { scope: '.app', prune: true }` writes `.app table`,
+   * and the scope is stripped before an element is read out. `bamboo cssgen preflight` prunes
+   * too.
+   *
+   * @default false
+   */
+  prune?: boolean
+}
+
 interface CssgenOptions {
   /**
-   * Whether to include css reset styles in the generated css.
+   * Whether to include css reset styles in the generated css, and how.
+   *
+   * `true` is shorthand for `{}` — on, with the defaults. `false` is the only form that means
+   * off, so it has no object spelling.
+   *
+   * `prune` used to be `prune.preflight`, a second key of the same name one level away, so a
+   * config could ask for a reset in one place and reshape it in another. It lives here because
+   * everything it needs is here: pruning a scoped reset means stripping `scope` before an
+   * element can be read out of a selector.
+   *
    * @default false
    */
-  preflight?: boolean | { scope: string; level?: 'element' | 'parent' }
+  preflight?: boolean | PreflightOptions
   /**
    * The namespace prefix for the generated css classes and css variables.
    * @default ''
@@ -354,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'
@@ -562,46 +643,24 @@ 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
    */
   keyframes?: boolean
-  /**
-   * Whether to drop the parts of the reset that style elements your source never renders.
-   *
-   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
-   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
-   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
-   * another's, of which 13% and 34% respectively is for elements those projects never render.
-   *
-   * A selector list loses only the parts naming unrendered elements, so a rule shared between
-   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
-   * are never removed.
-   *
-   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
-   * passes there is nothing to prove this against: an element rendered by a dependency's
-   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
-   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
-   * Reach for it when you control the markup and have measured that it pays.
-   *
-   * The blind spot to check first is your own entry template. The scan reads `include`, and
-   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
-   * does not match `index.html`, so an element appearing only there is dropped. Add the
-   * template to `include` to cover it — the scan reads any file listed, not only ones the
-   * parser understands, and reads it from disk rather than from the build's parsed copy, so
-   * a single-file component's markup survives the transform to tsx.
-   *
-   * A scoped reset is handled: `preflight: { scope: '.app' }` writes `.app table`, and the
-   * scope is stripped before an element is read out. `bamboo cssgen preflight` prunes too.
-   *
-   * @default false
-   */
-  preflight?: boolean
 }
 
 export interface Config
@@ -628,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.32.0",
+  "version": "1.34.0",
   "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.32.0"
+    "@bamboocss/extractor": "1.34.0"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",