@bamboocss/types 1.31.0 → 1.32.0

package/dist/composition.d.ts

@@ -1,4 +1,5 @@
-import type { CompositionStyleObject } from './system-types'
+import type { Nested } from './conditions'
+import type { CssVarProperties, SystemProperties } from './style-props'
 
 interface Token<T> {
   value: T
@@ -10,217 +11,34 @@ interface Recursive<T> {
 }
 
 /* -----------------------------------------------------------------------------
- * Text styles
+ * Mixins
  * -----------------------------------------------------------------------------*/
 
-type TextStyleProperty =
-  | 'color'
-  | 'direction'
-  | 'font'
-  | 'fontFamily'
-  | 'fontFeatureSettings'
-  | 'fontKerning'
-  | 'fontLanguageOverride'
-  | 'fontOpticalSizing'
-  | 'fontPalette'
-  | 'fontSize'
-  | 'fontSizeAdjust'
-  | 'fontStretch'
-  | 'fontStyle'
-  | 'fontSynthesis'
-  | 'fontVariant'
-  | 'fontVariantAlternates'
-  | 'fontVariantCaps'
-  | 'fontVariantLigatures'
-  | 'fontVariantNumeric'
-  | 'fontVariantPosition'
-  | 'fontVariationSettings'
-  | 'fontWeight'
-  | 'hangingPunctuation'
-  | 'hyphens'
-  | 'hyphenateCharacter'
-  | 'hyphenateLimitChars'
-  | 'letterSpacing'
-  | 'lineBreak'
-  | 'lineHeight'
-  | 'quotes'
-  | 'overflowWrap'
-  | 'tabSize'
-  | 'textAlign'
-  | 'textAlignLast'
-  | 'textBox'
-  | 'textBoxEdge'
-  | 'textBoxTrim'
-  | 'textCombineUpright'
-  | 'textDecoration'
-  | 'textDecorationColor'
-  | 'textDecorationLine'
-  | 'textDecorationSkip'
-  | 'textDecorationSkipBox'
-  | 'textDecorationSkipInk'
-  | 'textDecorationSkipInset'
-  | 'textDecorationStyle'
-  | 'textDecorationThickness'
-  | 'textEmphasis'
-  | 'textEmphasisColor'
-  | 'textEmphasisPosition'
-  | 'textEmphasisStyle'
-  | 'textIndent'
-  | 'textJustify'
-  | 'textOrientation'
-  | 'textOverflow'
-  | 'textRendering'
-  | 'textShadow'
-  | 'textStroke'
-  | 'textStrokeColor'
-  | 'textStrokeWidth'
-  | 'textTransform'
-  | 'textUnderlineOffset'
-  | 'textUnderlinePosition'
-  | 'textWrap'
-  | 'textWrapMode'
-  | 'textWrapStyle'
-  | 'unicodeBidi'
-  | 'verticalAlign'
-  | 'whiteSpace'
-  | 'wordBreak'
-  | 'wordSpacing'
-  | 'writingMode'
-
-export type TextStyle = CompositionStyleObject<TextStyleProperty>
-
-export type TextStyles = Recursive<Token<TextStyle>>
-
-/* -----------------------------------------------------------------------------
- * Layer styles
- * -----------------------------------------------------------------------------*/
-
-type LogicalPlacement = 'Inline' | 'Block' | 'InlineStart' | 'InlineEnd' | 'BlockStart' | 'BlockEnd'
-
-type PhysicalPlacement = 'Top' | 'Right' | 'Bottom' | 'Left'
-
-type Placement = PhysicalPlacement | LogicalPlacement
-
-type Radius =
-  | `Top${'Right' | 'Left'}`
-  | `Bottom${'Right' | 'Left'}`
-  | `Start${'Start' | 'End'}`
-  | `End${'Start' | 'End'}`
-
-type LayerStyleProperty =
-  | 'aspectRatio'
-  | 'background'
-  | 'backgroundColor'
-  | 'backgroundImage'
-  | 'border'
-  | 'borderColor'
-  | 'borderImage'
-  | 'borderImageOutset'
-  | 'borderImageRepeat'
-  | 'borderImageSlice'
-  | 'borderImageSource'
-  | 'borderImageWidth'
-  | 'borderRadius'
-  | 'borderStyle'
-  | 'borderWidth'
-  | `border${Placement}`
-  | `border${Placement}Color`
-  | `border${Placement}Style`
-  | `border${Placement}Width`
-  | 'borderRadius'
-  | `border${Radius}Radius`
-  | 'boxShadow'
-  | 'boxShadowColor'
-  | 'clipPath'
-  | 'color'
-  | 'contain'
-  | 'content'
-  | 'contentVisibility'
-  | 'cursor'
-  | 'display'
-  | 'filter'
-  | 'backdropFilter'
-  | 'height'
-  | 'width'
-  | 'minHeight'
-  | 'minWidth'
-  | 'maxHeight'
-  | 'maxWidth'
-  | `margin${Placement}`
-  | 'inset'
-  | `inset${LogicalPlacement}`
-  | Lowercase<PhysicalPlacement>
-  | 'isolation'
-  | 'mask'
-  | 'maskClip'
-  | 'maskComposite'
-  | 'maskImage'
-  | 'maskMode'
-  | 'maskOrigin'
-  | 'maskPosition'
-  | 'maskRepeat'
-  | 'maskSize'
-  | 'mixBlendMode'
-  | 'objectFit'
-  | 'objectPosition'
-  | 'opacity'
-  | 'outline'
-  | 'outlineColor'
-  | 'outlineOffset'
-  | 'outlineStyle'
-  | 'outlineWidth'
-  | 'overflow'
-  | 'overflowX'
-  | 'overflowY'
-  | 'padding'
-  | `padding${Placement}`
-  | 'pointerEvents'
-  | 'position'
-  | 'resize'
-  | 'transform'
-  | 'transition'
-  | 'visibility'
-  | 'willChange'
-  | 'zIndex'
-  | 'backgroundBlendMode'
-  | 'backgroundAttachment'
-  | 'backgroundClip'
-  | 'backgroundOrigin'
-  | 'backgroundPosition'
-  | 'backgroundRepeat'
-  | 'backgroundSize'
-
-export type LayerStyle = CompositionStyleObject<LayerStyleProperty>
-
-export type LayerStyles = Recursive<Token<LayerStyle>>
-
-/* -----------------------------------------------------------------------------
- * Motion styles
- * -----------------------------------------------------------------------------*/
-
-type AnimationStyleProperty =
-  | 'animation'
-  | 'animationComposition'
-  | 'animationDelay'
-  | 'animationDirection'
-  | 'animationDuration'
-  | 'animationFillMode'
-  | 'animationIterationCount'
-  | 'animationName'
-  | 'animationPlayState'
-  | 'animationTimingFunction'
-  | 'animationRange'
-  | 'animationRangeStart'
-  | 'animationRangeEnd'
-  | 'animationTimeline'
-  | 'transformOrigin'
-
-export type AnimationStyle = CompositionStyleObject<AnimationStyleProperty>
-
-export type AnimationStyles = Recursive<Token<AnimationStyle>>
+/**
+ * A named bundle of declarations, applied by name through the `mixin` style property.
+ *
+ * This was three theme keys — `textStyles`, `layerStyles` and `animationStyles` — with three
+ * `define*` helpers, three spec artifacts and three style properties, all running through the
+ * same registration and differing only in which css properties the value was allowed to set.
+ *
+ * That partition was not a guard worth three concepts. It was arbitrary at the edges (`color`
+ * was legal in both a text style and a layer style, `transform` in a layer style but
+ * `transformOrigin` only in an animation style), and it cost something real in the middle: a
+ * bundle wanting a font *and* a border had to be split across two keys and applied twice,
+ * because neither key would accept the other's half.
+ *
+ * What the three allowlists did buy was rejecting a property that does not exist, and that is
+ * kept here rather than thrown away with them — which is why this is not simply
+ * `SystemStyleObject`. That type unions in an index signature so a style object can carry an
+ * arbitrary selector or at-rule, and an index signature accepts anything, including a typo.
+ * `TextStyleProperty` once listed `hypens` instead of `hyphens` and nothing could notice; under
+ * an index signature nothing would notice again. Conditions and nested selectors still work,
+ * because `Nested` supplies those keys itself.
+ */
+export type Mixin = Nested<SystemProperties & CssVarProperties>
+
+export type Mixins = Recursive<Token<Mixin>>
 
 export interface CompositionStyles {
-  textStyles: TextStyles
-  layerStyles: LayerStyles
-  animationStyles: AnimationStyles
+  mixins: Mixins
 }

package/dist/conditions.d.ts

@@ -58,7 +58,6 @@ export type Condition = string
 
 export type ConditionalValue<V> =
   | V
-  | Array<V | null>
   | {
       [K in keyof Conditions]?: ConditionalValue<V>
     }

package/dist/config.d.ts

@@ -400,12 +400,19 @@ interface PresetOptions {
   presets?: (string | Preset | Promise<Preset>)[]
 }
 
-export interface HooksOptions {
-  hooks?: Partial<BambooHooks>
-}
-
-export interface BambooPlugin extends HooksOptions {
+/**
+ * A named set of hooks.
+ *
+ * The name is the point. Hooks used to be registrable two ways — here, and as a bare
+ * `hooks` key on the config — with the config's own set treated as a nameless plugin
+ * appended last. That gave one mechanism two spellings and an ordering rule you had to
+ * know, while every diagnostic about a hook had a name to print for one of them and not
+ * the other. Your own hooks are now a plugin like any other, so ordering is just the order
+ * of this array.
+ */
+export interface BambooPlugin {
   name: string
+  hooks?: Partial<BambooHooks>
 }
 
 export interface PluginsOptions {
@@ -443,13 +450,19 @@ export interface PruneOptions {
    * `unresolvedPath` exists, and why setting it to `error` is what makes `accounted` worth
    * asking for: it guarantees you are shipping the exact set rather than the fallback.
    *
+   * A template literal is bounded rather than declined: `` token(`colors.${shade}`) `` cannot
+   * say which token it wants, but it says which it *cannot*, so the `colors` category is kept
+   * and nothing else. That covers the commonest dynamic read outright. What it does not cover
+   * is a path with no static head — `token(key)`, `token('colors.' + shade)` — and there
+   * `keepTokens` is the answer.
+   *
    * Three things stay invisible to `accounted`: a token named by a path assembled from a
    * value that only exists at runtime, one referenced only from a stylesheet outside
    * `include`, and one used by a separate package consuming the output as design tokens. The
    * scan reads `include`, which scopes style extraction rather than everything that may
    * import — so a script, a config, or a sibling workspace package that calls `token()` is
-   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Use
-   * `staticCss` to keep those.
+   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Name
+   * them with `keepTokens`.
    *
    * A custom property declared by `global.css` or `global.vars` is not one of these cases:
    * the declaration ships whether or not anything in the stylesheet reads it, so whatever it
@@ -458,12 +471,54 @@ export interface PruneOptions {
    * @default 'reachable'
    */
   tokens?: 'off' | 'reachable' | 'accounted'
+  /**
+   * Token paths to keep whatever the build can see, as exact names or `*` patterns.
+   *
+   * ```ts
+   * prune: { tokens: 'accounted', keepTokens: ['colors.*'] }
+   * ```
+   *
+   * This is the bound the build could not infer, written by hand. It exists because the
+   * fallback is otherwise total: **one** reference the accounting cannot follow keeps every
+   * declaration in the project, so a codebase with a single `token(key)` in it gets the same
+   * stylesheet as one that never prunes — and the codebases that reach for `token()` most are
+   * exactly the ones that end up there. Naming the category those dynamic reads land in is a
+   * far smaller answer than keeping everything, and it is the same answer the build already
+   * derives for itself from a template literal's static head.
+   *
+   * So under `accounted` this does two things: it keeps what it matches, and it stands in for
+   * what could not be followed, in place of the blanket keep. Saying `keepTokens: ['colors.*']`
+   * is saying *the reads you cannot follow land in `colors`* — an assertion about your own
+   * code, which is why nothing infers it for you. Declines are still reported, so you can see
+   * what you are covering; `unresolvedPath: 'error'` still fails, because asserting every path
+   * resolves and declaring a bound for the ones that do not are contradictory requests.
+   *
+   * Under `reachable` it is additive only, for a token nothing in the stylesheet references
+   * and no javascript here reads — one consumed by a sibling package, or by css outside
+   * `include`. It is inert under `tokens: 'off'`, which keeps everything already.
+   *
+   * Patterns match the dotted token *path*, anchored and case-sensitively, with `*` standing
+   * for any run of characters and a leading `!` excluding. `colors.*` keeps every colour,
+   * `colors.brand.*` one palette, `colors.red.300` one token, `['colors.*', '!colors.legacy.*']`
+   * every colour but one palette.
+   *
+   * The path, not the css variable: a token is `fontSizes.3xl` and its declaration is
+   * `--font-sizes-3xl`, so `font-sizes.*` — the natural thing to write after reading
+   * `styles.css` — matches nothing at all. A pattern matching no token is reported, and names
+   * the spelling that would have worked, because keeping nothing is otherwise silent in a build
+   * whose whole job here is dropping things.
+   *
+   * This replaces `staticCss` as the way to keep a category alive. `staticCss` emits utility
+   * *classes* — keeping the colours meant shipping a rule per colour to hold the declarations
+   * up, which is a larger stylesheet than the pruning saved.
+   */
+  keepTokens?: string[]
   /**
    * What to do about a token path `accounted` cannot follow.
    *
    * A path spelled at the call resolves; one assembled at runtime does not. An unfollowable
-   * path is what forces `accounted` back onto the blanket keep, so this decides whether that
-   * happens quietly, loudly, or not at all.
+   * path is what forces `accounted` back onto the blanket keep — unless `keepTokens` names
+   * the bound — so this decides whether that happens quietly, loudly, or not at all.
    *
    * - `off` falls back and says nothing.
    * - `warn` falls back and reports what it could not follow.
@@ -471,6 +526,10 @@ export interface PruneOptions {
    *
    * Inert under `tokens: 'off'` and `tokens: 'reachable'`, which run no accounting pass.
    *
+   * `error` and `keepTokens` do not combine: one asserts every path resolves, the other
+   * declares where the ones that do not will land. A project that cannot make the first
+   * assertion wants `warn`, which still prints every reference being covered.
+   *
    * Named for what it checks rather than `strict`, which already means something unrelated
    * here: `strictTokens` and `strictPropertyValues` narrow generated *typescript*, and
    * neither implies nor is implied by this.
@@ -546,14 +605,7 @@ export interface PruneOptions {
 }
 
 export interface Config
-  extends
-    ExtendableOptions,
-    CssgenOptions,
-    CodegenOptions,
-    FileSystemOptions,
-    PresetOptions,
-    HooksOptions,
-    PluginsOptions {
+  extends ExtendableOptions, CssgenOptions, CodegenOptions, FileSystemOptions, PresetOptions, PluginsOptions {
   /**
    * What to do when the config does not validate.
    *
@@ -561,10 +613,17 @@ export interface Config
    * - `warn` logs what failed.
    * - `error` throws.
    *
-   * A retired spelling is checked ahead of this and is not silenceable by it — that is
-   * output which is already broken rather than an opinion about a config that still
-   * builds. Neither is a removed option: `off` used to switch off the one mechanism that
-   * tells an upgrader their setting is no longer read.
+   * This grades opinions about a config that still builds. Two checks are not that, run
+   * ahead of it, and answer to nothing here: a retired token spelling, which is output that
+   * is already broken; and an option that has been removed, which is proof the config
+   * predates the version reading it. Both throw at any setting, including `off`.
+   *
+   * A removed option throws rather than warns because a warning is not a signal anything
+   * acts on. Removals ship in minor versions, so a warning is what an automated dependency
+   * upgrade merges without a person reading it — while the option itself is silent in every
+   * other way, reverting to the default and taking the assertion it asked for with it. An
+   * unknown key is a different case and still tolerated: it may be forward-compatible, a
+   * setting for a version not installed yet. A *removed* key can only be backward.
    *
    * @default 'warn'
    */

package/dist/index.d.ts

@@ -6,7 +6,6 @@ export type * from './hooks'
 export type * from './hooks-api'
 export type * from './logger'
 export type * from './parser'
-export type * from './parts'
 export type * from './pattern'
 export type * from './recipe'
 export type * from './reporter'

package/dist/recipe.d.ts

@@ -38,7 +38,7 @@ type RecipeVariantMap<T extends RecipeVariantRecord> = {
 
 export interface RecipeRuntimeFn<T extends RecipeVariantRecord> extends RecipeVariantFn<T> {
   __type: RecipeSelection<T>
-  variantKeys: (keyof T)[]
+  /** Each variant and the values it accepts. `Object.keys` it for the variant names. */
   variantMap: RecipeVariantMap<T>
   raw: (props?: RecipeSelection<T>) => SystemStyleObject
   config: RecipeConfig<T>
@@ -138,7 +138,7 @@ export interface SlotRecipeRuntimeFn<
   T extends SlotRecipeVariantRecord<S>,
 > extends SlotRecipeVariantFn<S, T> {
   raw: (props?: RecipeSelection<T>) => Record<S, SystemStyleObject>
-  variantKeys: (keyof T)[]
+  /** Each variant and the values it accepts. `Object.keys` it for the variant names. */
   variantMap: RecipeVariantMap<T>
   /** The config this recipe was created from. */
   config: SlotRecipeDefinition<S, T>

package/dist/spec.d.ts

@@ -5,9 +5,7 @@ export type SpecType =
   | 'conditions'
   | 'keyframes'
   | 'semantic-tokens'
-  | 'text-styles'
-  | 'layer-styles'
-  | 'animation-styles'
+  | 'mixins'
   | 'color-palette'
   | 'themes'
 
@@ -103,34 +101,14 @@ export interface KeyframeSpec {
   data: KeyframeSpecDefinition[]
 }
 
-export interface TextStyleSpecDefinition extends Examples {
+export interface MixinSpecDefinition extends Examples {
   name: string
   description?: string
 }
 
-export interface TextStyleSpec {
-  type: 'text-styles'
-  data: TextStyleSpecDefinition[]
-}
-
-export interface LayerStyleSpecDefinition extends Examples {
-  name: string
-  description?: string
-}
-
-export interface LayerStyleSpec {
-  type: 'layer-styles'
-  data: LayerStyleSpecDefinition[]
-}
-
-export interface AnimationStyleSpecDefinition extends Examples {
-  name: string
-  description?: string
-}
-
-export interface AnimationStyleSpec {
-  type: 'animation-styles'
-  data: AnimationStyleSpecDefinition[]
+export interface MixinSpec {
+  type: 'mixins'
+  data: MixinSpecDefinition[]
 }
 
 export interface ColorPaletteSpec {
@@ -173,9 +151,7 @@ export type SpecFile =
   | PatternSpec
   | ConditionSpec
   | KeyframeSpec
-  | TextStyleSpec
-  | LayerStyleSpec
-  | AnimationStyleSpec
+  | MixinSpec
   | ColorPaletteSpec
   | ThemesSpec
 
@@ -186,9 +162,7 @@ export interface SpecTypeMap {
   patterns: PatternSpec
   conditions: ConditionSpec
   keyframes: KeyframeSpec
-  'text-styles': TextStyleSpec
-  'layer-styles': LayerStyleSpec
-  'animation-styles': AnimationStyleSpec
+  mixins: MixinSpec
   'color-palette': ColorPaletteSpec
   themes: ThemesSpec
 }

package/dist/style-props.d.ts

@@ -1,5 +1,5 @@
 import type { ConditionalValue } from './conditions'
-import type { PropertiesFallback } from './csstype'
+import type { Properties } from './csstype'
 import type { PropertyValue } from './prop-type'
 
 type String = string & {}
@@ -9,7 +9,7 @@ type Number = number & {}
  * Shadowed export (in CLI): DO NOT REMOVE
  * -----------------------------------------------------------------------------*/
 
-type CssProperties = PropertiesFallback<String | Number>
+type CssProperties = Properties<String | Number>
 
 export type CssVarProperties = {
   [key in `--${string}`]?: ConditionalValue<string | number>

package/dist/system-types.d.ts

@@ -1,5 +1,5 @@
 import type { ConditionalValue, Nested } from './conditions'
-import type { AtRule, Globals, PropertiesFallback } from './csstype'
+import type { AtRule, Globals, Properties } from './csstype'
 import type { SystemProperties, CssVarProperties } from './style-props'
 
 type String = string & {}
@@ -63,9 +63,9 @@ export interface ModernCssProperties {
     | String
 }
 
-export type CssProperty = keyof PropertiesFallback
+export type CssProperty = keyof Properties
 
-export interface CssProperties extends PropertiesFallback<String | Number>, CssVarProperties, ModernCssProperties {}
+export interface CssProperties extends Properties<String | Number>, CssVarProperties, ModernCssProperties {}
 
 export interface CssKeyframes {
   [name: string]: {

package/dist/theme.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationStyles, LayerStyles, TextStyles } from './composition'
+import type { Mixins } from './composition'
 import type { RecipeConfig, SlotRecipeConfig } from './recipe'
 import type { CssKeyframes } from './system-types'
 import type { SemanticTokens, Tokens } from './tokens'
@@ -39,17 +39,9 @@ export interface Theme {
    */
   semanticTokens?: SemanticTokens
   /**
-   * The typography styles for your project.
+   * Named bundles of declarations, applied by name through the `mixin` style property.
    */
-  textStyles?: TextStyles
-  /**
-   * The layer styles for your project.
-   */
-  layerStyles?: LayerStyles
-  /**
-   * The animation styles for your project.
-   */
-  animationStyles?: AnimationStyles
+  mixins?: Mixins
   /**
    * Multi-variant style definitions for your project.
    * Useful for defining component styles.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/types",
-  "version": "1.31.0",
+  "version": "1.32.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.31.0"
+    "@bamboocss/extractor": "1.32.0"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",

package/dist/parts.d.ts

@@ -1,7 +0,0 @@
-export interface Part {
-  selector: string
-}
-
-export interface Parts {
-  [key: string]: Part
-}