@bamboocss/types 1.41.1 → 1.43.0

package/dist/config.d.ts

@@ -377,6 +377,11 @@ interface CssgenOptions {
   polyfill?: boolean
 }
 
+export type UnresolvedTokenSeverity = 'off' | 'warn' | 'error'
+
+/** `'auto'` hashes in production and leaves names readable in development. */
+export type HashSetting = boolean | 'auto'
+
 interface CodegenOptions {
   /**
    * Whether to only emit the `tokens` directory
@@ -385,45 +390,51 @@ interface CodegenOptions {
   emitTokensOnly?: boolean
   /**
    * Whether to hash the generated class names / css variables.
-   * This is useful if want to shorten the class names or css variables.
+   *
+   * Readable names cost nothing for most of what a project writes — `fs_14px` and `c_accent`
+   * gzip to within a rounding error of a hash, because they repeat. What does cost is an
+   * *arbitrary* value, which is escaped into the name whole: one measured project carried a
+   * complete `linear-gradient(…)` as a 105-character class, and escaped names were 20% of all
+   * class-attribute bytes. Those do not compress away, because the redundancy is inside one long
+   * token rather than across repeated short ones.
+   *
+   * `'auto'` is the answer to both: readable while you are looking at them, hashed when nobody
+   * is. The mode comes from the integration — the Vite plugin's dev server is development and
+   * everything else is production — and is fixed for the life of a context, so the emitted CSS
+   * and the compiled class literals cannot disagree about a name.
+   *
    * @default false
    */
-  hash?: boolean | { cssVar?: boolean; className?: boolean }
+  hash?: HashSetting | { cssVar?: HashSetting; className?: HashSetting }
   /**
-   * Change generated typescript definitions to be more strict for property having a token or utility.
+   * Whether this context is serving a development build.
    *
-   * Three settings, not two:
+   * Set by the integration rather than by a project — the Vite plugin's dev server is the only
+   * thing that knows — and read by `hash: 'auto'`. It is deliberately not a mode switch for
+   * anything else: a class name that differs between dev and prod is one thing, and CSS that
+   * differs is another.
    *
-   * - `false` — every property also accepts `string`, so nothing about a value is checked. A
-   *   misspelled token is a value the browser drops at compute time: the declaration ships, the
-   *   style is simply absent, and it surfaces as "this colour never applied" a long way from the
-   *   typo.
-   * - `'unknown-tokens'` — a value must be a token, a keyword the property actually enumerates,
-   *   or *shaped* like a CSS value: it starts with a digit or `#` or `-`, or it contains a space,
-   *   a comma or a function call. `'14px'`, `'100vh'`, `'1px solid red'` and `'rgb(0 0 0)'` all
-   *   pass; `'mutedd'`, `'accnt'` and `'colors.acent'` do not, because a bare identifier that is
-   *   neither a token nor a keyword is nothing else.
-   * - `true` — only tokens, and every raw value has to be written as `'[14px]'`.
+   * @default false
+   */
+  dev?: boolean
+  /**
+   * Require every style value to be a token, so a raw CSS value has to be written `'[14px]'`.
    *
-   * The middle setting exists because the other two are a day-one decision. Turning `true` on
-   * later reports every raw value in the codebase — 468 errors on one otherwise-correct app, of
-   * which 3 were the typo it was turned on for — so a project that did not start with it is
-   * realistically stuck with the unchecked default forever. `'unknown-tokens'` costs no
-   * migration and catches that class of mistake.
+   * A design-system policy rather than a correctness check: it is how a team says "everything
+   * goes through the theme", and the brackets are what make reaching outside it visible in the
+   * source. On one otherwise-correct five-page app it reports 468 values, which is what makes
+   * it a day-one decision.
    *
-   * Properties whose values *are* identifiers you invent — `animationName`, `gridArea`,
-   * `counterReset`, `containerName`, `fontFamily`, `content` and the rest — are left out of
-   * it: there is nothing to check them against, and a `@keyframes` name declared in CSS is an
-   * ordinary thing to write.
+   * A *keyword* is not a raw value. `display: 'flex'` is the only way to say that, so it is
+   * left alone — a distinction the type-level version of this could not draw, which is why it
+   * did not narrow `display` at all and let `display: 'abc'` through with it.
    *
-   * Two costs follow from the rule being about shape. A typo that is *also* a plausible value
-   * passes — `'2xll'` starts with a digit like `'2rem'` does. And a value typed `string` is
-   * rejected, since nothing distinguishes it from a misspelled token; write `` `[${value}]` ``,
-   * the same as under `true`, and note the Vite compiler rejects an open runtime value anyway.
+   * Reported by the build, graded by `validation`, and it is not what catches a misspelled
+   * token — see `unresolvedToken`, which is on by default and needs no setting.
    *
    * @default false
    */
-  strictTokens?: boolean | 'unknown-tokens'
+  strictValues?: boolean
   /**
    * Change generated typescript definitions to be more strict for built-in CSS properties to only allow valid CSS values.
    */
@@ -718,9 +729,23 @@ export interface Config
    * entrypoint's own export list rather than inferred, so there is no setting under which it
    * is what someone meant.
    *
-   * @default 'warn'
+   * Two halves, graded apart, because they are not equally certain.
+   *
+   * A property that draws from a token category — `color` from `colors`, `top` from `spacing` —
+   * makes a name that is not a token bamboo's own bookkeeping, and there is no third party to be
+   * wrong about it. That half defaults to `'error'`.
+   *
+   * Everywhere else the judge is the CSS grammar, whose data lags the spec: `containerType:
+   * 'scroll-state'` is valid CSS that the grammar has not caught up with. Sweeping every keyword
+   * csstype enumerates through it found 8 such disagreements in 10,128 pairs — 0.08%, and all 8
+   * on properties with no token category. That half defaults to `'warn'`, so a build is never
+   * failed by how fresh a grammar is.
+   *
+   * A single severity applies to both.
+   *
+   * @default { token: 'error', grammar: 'warn' }
    */
-  unresolvedToken?: 'off' | 'warn' | 'error'
+  unresolvedToken?: UnresolvedTokenSeverity | { token?: UnresolvedTokenSeverity; grammar?: UnresolvedTokenSeverity }
 }
 
 export interface Preset extends ExtendableOptions, PresetOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/types",
-  "version": "1.41.1",
+  "version": "1.43.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.41.1"
+    "@bamboocss/extractor": "1.43.0"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",