@bamboocss/types 1.11.1 → 1.11.3

package/dist/hooks-api.d.ts

@@ -0,0 +1,61 @@
+import type { UserConfig } from './config'
+import type { RecipeDefinition, RecipeVariantRecord, SlotRecipeDefinition, SlotRecipeVariantRecord } from './recipe'
+import type { AtomicStyleResult, GroupedResult, RecipeBaseResult } from './style-rules'
+import type { SystemStyleObject } from './system-types'
+
+export interface BaseRule {
+  getClassNames: () => string[]
+  toCss: () => string
+}
+
+export interface AtomicRule extends BaseRule {
+  styles: SystemStyleObject
+}
+
+export interface GroupedRule extends BaseRule {
+  styles: SystemStyleObject
+}
+
+export interface AtomicRecipeRule extends BaseRule {
+  config: RecipeDefinition<any> | SlotRecipeDefinition<string, any>
+}
+
+export interface RecipeVariantsRule extends BaseRule {
+  variants: RecipeVariantRecord
+}
+
+export interface ProcessorInterface {
+  css(styles: SystemStyleObject): AtomicRule
+  grouped(styles: SystemStyleObject): GroupedRule
+  cva(recipeConfig: RecipeDefinition<RecipeVariantRecord>): AtomicRecipeRule
+  sva(recipeConfig: SlotRecipeDefinition<string, SlotRecipeVariantRecord<string>>): AtomicRecipeRule
+  recipe(name: string, variants?: RecipeVariantRecord): RecipeVariantsRule | undefined
+}
+
+export interface HooksApiInterface {
+  /**
+   * The resolved config (after all the presets are loaded and merged)
+   */
+  config: UserConfig
+  /**
+   * The path to the config file
+   */
+  configPath: string
+  /**
+   * The list of all the config dependencies (direct/transitive imports) filepaths
+   */
+  configDependencies: string[]
+  //
+  /**
+   * The processor can be used to generate atomic or recipe classes
+   */
+  processor: ProcessorInterface
+  /**
+   * Map that contains all the utility classNames
+   */
+  classNames: Map<string, string>
+  /**
+   * Map that contains all the classNames found (and therefore generated) in the app code
+   */
+  generatedClassNames: Map<string, AtomicStyleResult | RecipeBaseResult | GroupedResult>
+}

package/dist/hooks.d.ts

@@ -0,0 +1,237 @@
+import type { Artifact, ArtifactId, DiffConfigResult } from './artifact'
+import type { LoadConfigResult, UserConfig } from './config'
+import type { HooksApiInterface } from './hooks-api'
+import type { LoggerInterface } from './logger'
+import type { ParserResultInterface, ResultItem } from './parser'
+
+export interface BambooHooks {
+  /**
+   * Called when the config is resolved, after all the presets are loaded and merged.
+   * This is the first hook called, you can use it to tweak the config before the context is created.
+   */
+  'config:resolved': (args: ConfigResolvedHookArgs) => MaybeAsyncReturn<void | ConfigResolvedHookArgs['config']>
+  /**
+   * Called when each preset is resolved, allowing modification of individual presets.
+   * This hook is called for each preset during the resolution process, before they are merged together.
+   */
+  'preset:resolved': (args: PresetResolvedHookArgs) => MaybeAsyncReturn<void | PresetResolvedHookArgs['preset']>
+  /**
+   * Called when the token engine has been created
+   */
+  'tokens:created': (args: TokenCreatedHookArgs) => MaybeAsyncReturn
+  /**
+   * Called when the classname engine has been created
+   */
+  'utility:created': (args: UtilityCreatedHookArgs) => MaybeAsyncReturn
+  /**
+   * Called when the Bamboo context has been created and the API is ready to be used.
+   */
+  'context:created': (args: ContextCreatedHookArgs) => void
+  /**
+   * Called when the config file or one of its dependencies (imports) has changed.
+   */
+  'config:change': (args: ConfigChangeHookArgs) => MaybeAsyncReturn
+  /**
+   * Called after reading the file content but before parsing it.
+   * You can use this hook to transform the file content to a tsx-friendly syntax so that Bamboo's parser can parse it.
+   * You can also use this hook to parse the file's content on your side using a custom parser, in this case you don't have to return anything.
+   */
+  'parser:before': (args: ParserResultBeforeHookArgs) => string | void
+  /**
+   * @private USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING
+   */
+  'parser:preprocess': JsxFactoryResultTransform['transform']
+  /**
+   * Called after the file styles are extracted and processed into the resulting ParserResult object.
+   * You can also use this hook to add your own extraction results from your custom parser to the ParserResult object.
+   */
+  'parser:after': (args: ParserResultAfterHookArgs) => void
+  /**
+   * Called right before writing the codegen files to disk.
+   * You can use this hook to tweak the codegen files before they are written to disk.
+   */
+  'codegen:prepare': (args: CodegenPrepareHookArgs) => MaybeAsyncReturn<void | Artifact[]>
+  /**
+   * Called after the codegen is completed
+   */
+  'codegen:done': (args: CodegenDoneHookArgs) => MaybeAsyncReturn
+  /**
+   * Called right before adding the design-system CSS (global, static, preflight, tokens, keyframes) to the final CSS
+   * Called right before writing/injecting the final CSS (styles.css) that contains the design-system CSS and the parser CSS
+   * You can use it to tweak the CSS content before it's written to disk or injected through the postcss plugin.
+   */
+  'cssgen:done': (args: CssgenDoneHookArgs) => string | void
+  /**
+   * Called when CSS needs to be optimized. Use this hook to replace the default PostCSS-based optimizer
+   * with a custom one (e.g. LightningCSS).
+   * Return the optimized CSS string, or void to fall through to the default PostCSS optimizer.
+   */
+  'css:optimize': (args: CssOptimizeHookArgs) => string | void
+}
+
+type MaybeAsyncReturn<T = void> = Promise<T> | T
+
+/* -----------------------------------------------------------------------------
+ * Token hooks
+ * -----------------------------------------------------------------------------*/
+
+interface TokenCssVarOptions {
+  fallback?: string
+  prefix?: string
+  hash?: boolean
+}
+
+interface TokenCssVar {
+  var: `--${string}`
+  ref: string
+}
+
+export interface TokenConfigureOptions {
+  formatTokenName?: (path: string[]) => string
+  formatCssVar?: (path: string[], options: TokenCssVarOptions) => TokenCssVar
+}
+
+export interface TokenCreatedHookArgs {
+  configure(opts: TokenConfigureOptions): void
+}
+
+/* -----------------------------------------------------------------------------
+ * Utility hooks
+ * -----------------------------------------------------------------------------*/
+
+export interface UtilityConfigureOptions {
+  toHash?(path: string[], toHash: (str: string) => string): string
+}
+
+export interface UtilityCreatedHookArgs {
+  configure(opts: UtilityConfigureOptions): void
+}
+
+/* -----------------------------------------------------------------------------
+ * Config hooks
+ * -----------------------------------------------------------------------------*/
+
+interface CallbackItem {
+  value: any
+  path: string
+  depth: number
+  parent: any[] | Record<string, unknown>
+  key: string
+}
+
+type CallbackFn = (args: CallbackItem) => void
+
+interface TraverseOptions {
+  separator: string
+  maxDepth?: number | undefined
+}
+
+interface TraverseFn {
+  (obj: any, callback: CallbackFn, options?: TraverseOptions): void
+}
+
+interface ConfigResolvedHookUtils {
+  omit: <T, K extends keyof T | (string & {})>(obj: T, paths: K[]) => Omit<T, K>
+  pick: <T, K extends keyof T | (string & {})>(obj: T, paths: K[]) => Partial<T>
+  traverse: TraverseFn
+}
+
+export interface ConfigResolvedHookArgs {
+  config: LoadConfigResult['config']
+  path: string
+  dependencies: string[]
+  utils: ConfigResolvedHookUtils
+  original?: LoadConfigResult['config']
+}
+
+export interface ConfigChangeHookArgs {
+  config: UserConfig
+  changes: DiffConfigResult
+}
+
+export interface PresetResolvedHookArgs {
+  preset: LoadConfigResult['config']
+  name: string
+  utils: ConfigResolvedHookUtils
+  original?: LoadConfigResult['config']
+}
+
+/* -----------------------------------------------------------------------------
+ * Parser hooks
+ * -----------------------------------------------------------------------------*/
+
+export interface ParserResultConfigureOptions {
+  matchTag?: (tag: string, isBambooComponent: boolean) => boolean
+  matchTagMode?: 'extend' | 'override'
+  matchTagProp?: (tag: string, prop: string) => boolean
+}
+
+export interface ParserResultBeforeHookArgs {
+  filePath: string
+  content: string
+  configure: (opts: ParserResultConfigureOptions) => void
+  original?: string
+}
+
+export interface JsxFactoryResultTransform {
+  transform: (result: { type: 'jsx-factory'; data: ResultItem['data'] }) => ResultItem['data']
+}
+
+export interface ParserResultAfterHookArgs {
+  filePath: string
+  result: ParserResultInterface | undefined
+}
+
+/* -----------------------------------------------------------------------------
+ * Codegen hooks
+ * -----------------------------------------------------------------------------*/
+
+export interface CodegenPrepareHookArgs {
+  artifacts: Artifact[]
+  /**
+   * The original state of the artifacts, as it was generated by Bamboo, without any modification from other preset hooks
+   */
+  original?: Artifact[]
+  changed: ArtifactId[] | undefined
+}
+export interface CodegenDoneHookArgs {
+  changed: ArtifactId[] | undefined
+}
+
+/* -----------------------------------------------------------------------------
+ * Cssgen hooks
+ * -----------------------------------------------------------------------------*/
+
+type CssgenArtifact = 'global' | 'static' | 'reset' | 'tokens' | 'keyframes' | 'styles.css'
+
+export interface CssgenDoneHookArgs {
+  artifact: CssgenArtifact
+  /**
+   * The current state of the CSS, if any other preset hook has modified the CSS, this will be the modified state
+   */
+  content: string
+  /**
+   * The original state of the CSS, as it was generated by Bamboo, without any modification from other preset hooks
+   */
+  original?: string
+}
+
+/* -----------------------------------------------------------------------------
+ * CSS optimize hooks
+ * -----------------------------------------------------------------------------*/
+
+export interface CssOptimizeHookArgs {
+  css: string
+  minify?: boolean
+  browserslist?: string[]
+  original?: string
+}
+
+/* -----------------------------------------------------------------------------
+ * Context hooks
+ * -----------------------------------------------------------------------------*/
+
+export interface ContextCreatedHookArgs {
+  ctx: HooksApiInterface
+  logger: LoggerInterface
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type * from './artifact'
+export type * from './composition'
+export type * from './conditions'
+export type * from './config'
+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'
+export type * from './runtime'
+export type * from './shared'
+export type * from './spec'
+export type * from './static-css'
+export type * from './style-rules'
+export type * from './system-types'
+export type * from './theme'
+export type * from './tokens'
+export type * from './utility'

package/dist/logger.d.ts

@@ -0,0 +1,28 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
+
+export interface LogEntry {
+  level: LogLevel | null
+  msg: string
+  [key: string]: any
+}
+
+export interface LoggerInterface {
+  level: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  print(data: any): void
+  onLog?: (entry: LogEntry) => void
+  warn: (type: string, data: any) => void
+  info: (type: string, data: any) => void
+  debug: (type: string, data: any) => void
+  error: (type: string, data: any) => void
+  /**
+   * Log a caught error with context. Extracts the message for the error level,
+   * and logs the full stack at debug level.
+   */
+  caughtError: (type: string, context: string, error: unknown) => void
+  log: (data: string) => void
+  time: {
+    info: (msg: string) => (_msg?: string) => void
+    debug: (msg: string) => (_msg?: string) => void
+  }
+  isDebug: boolean
+}

package/dist/parser.d.ts

@@ -0,0 +1,43 @@
+import type { BoxNodeArray, BoxNodeLiteral, BoxNodeMap, Unboxed } from '@bamboocss/extractor'
+
+export interface ResultItem {
+  name?: string
+  data: Array<Unboxed['raw']>
+  type?: 'css' | 'cva' | 'sva' | 'token' | 'pattern' | 'recipe' | 'jsx-factory' | 'jsx-pattern' | 'jsx-recipe' | 'jsx'
+  box?: BoxNodeMap | BoxNodeLiteral | BoxNodeArray
+}
+
+export interface ParserResultInterface {
+  all: Array<ResultItem>
+  jsx: Set<ResultItem>
+  css: Set<ResultItem>
+  cva: Set<ResultItem>
+  sva: Set<ResultItem>
+  token: Set<ResultItem>
+  recipe: Map<string, Set<ResultItem>>
+  pattern: Map<string, Set<ResultItem>>
+  filePath: string | undefined
+  isEmpty: () => boolean
+  toArray: () => Array<ResultItem>
+  set: (name: 'cva' | 'css' | 'sva' | 'token', result: ResultItem) => void
+  setCss: (result: ResultItem) => void
+  setCva: (result: ResultItem) => void
+  setSva: (result: ResultItem) => void
+  setToken: (result: ResultItem) => void
+  setJsx: (result: ResultItem) => void
+  setPattern: (name: string, result: ResultItem) => void
+  setRecipe: (name: string, result: ResultItem) => void
+}
+
+export interface EncoderJson {
+  schemaVersion: string
+  styles: {
+    atomic?: string[]
+    recipes?: {
+      [name: string]: string[]
+    }
+    grouped?: {
+      [groupId: string]: string[]
+    }
+  }
+}

package/dist/parts.d.ts

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

package/dist/pattern.d.ts

@@ -0,0 +1,77 @@
+import type { CssProperty, SystemStyleObject } from './system-types'
+import type { TokenCategory } from './tokens'
+
+type Primitive = string | number | boolean | null | undefined
+type LiteralUnion<T, K extends Primitive = string> = T | (K & Record<never, never>)
+
+export type PatternProperty =
+  | { type: 'property'; value: CssProperty; description?: string }
+  | { type: 'enum'; value: string[]; description?: string }
+  | { type: 'token'; value: TokenCategory; property?: CssProperty; description?: string }
+  | { type: 'string' | 'boolean' | 'number'; description?: string }
+
+export interface PatternHelpers {
+  map: (value: any, fn: (value: string) => string | undefined) => any
+  isCssUnit: (value: any) => boolean
+  isCssVar: (value: any) => boolean
+  isCssFunction: (value: any) => boolean
+}
+
+export interface PatternProperties {
+  [key: string]: PatternProperty
+}
+
+type InferProps<T> = Record<LiteralUnion<keyof T>, any>
+
+export type PatternDefaultValue<T> = Partial<InferProps<T>>
+
+export type PatternDefaultValueFn<T> = (props: InferProps<T>) => PatternDefaultValue<T>
+
+export interface PatternConfig<T extends PatternProperties = PatternProperties> {
+  /**
+   * The description of the pattern. This will be used in the JSDoc comment.
+   */
+  description?: string
+  /**
+   * The JSX element rendered by the pattern
+   * @default 'div'
+   */
+  jsxElement?: string
+  /**
+   * The properties of the pattern.
+   */
+  properties?: T
+  /**
+   * The default values of the pattern.
+   */
+  defaultValues?: PatternDefaultValue<T> | PatternDefaultValueFn<T>
+  /**
+   * The css object this pattern will generate.
+   */
+  transform?: (props: InferProps<T>, helpers: PatternHelpers) => SystemStyleObject
+  /**
+   * Whether the pattern is deprecated.
+   */
+  deprecated?: boolean | string
+  /**
+   * The jsx element name this pattern will generate.
+   */
+  jsxName?: string
+  /**
+   * The jsx elements to track for this pattern. Can be string or Regexp.
+   *
+   * @default capitalize(pattern.name)
+   * @example ['Button', 'Link', /Button$/]
+   */
+  jsx?: Array<string | RegExp>
+  /**
+   * Whether to only generate types for the specified properties.
+   * This will disallow css properties
+   */
+  strict?: boolean
+  /**
+   * @experimental
+   * Disallow certain css properties for this pattern
+   */
+  blocklist?: LiteralUnion<CssProperty>[]
+}

package/dist/prop-type.d.ts

@@ -0,0 +1,14 @@
+import type { ConditionalValue } from './conditions'
+import type { CssProperties } from './system-types'
+
+/* -----------------------------------------------------------------------------
+ * Shadowed export (in CLI): DO NOT REMOVE
+ * -----------------------------------------------------------------------------*/
+
+export interface PropertyTypes {}
+
+export type PropertyValue<K extends string> = K extends keyof PropertyTypes
+  ? ConditionalValue<PropertyTypes[K]>
+  : K extends keyof CssProperties
+    ? ConditionalValue<CssProperties[K]>
+    : never

package/dist/recipe.d.ts

@@ -0,0 +1,181 @@
+import type { RecipeRule } from './static-css'
+import type { SystemStyleObject, DistributiveOmit, Pretty } from './system-types'
+
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T
+
+export type RecipeVariantRecord = Record<any, Record<any, SystemStyleObject>>
+
+export type RecipeSelection<T extends RecipeVariantRecord> = keyof any extends keyof T
+  ? {}
+  : {
+      [K in keyof T]?: StringToBoolean<keyof T[K]> | undefined
+    }
+
+export type RecipeVariantFn<T extends RecipeVariantRecord> = (props?: RecipeSelection<T>) => string
+
+/**
+ * Extract the variant as optional props from a `cva` function.
+ * Intended to be used with a JSX component, prefer `RecipeVariant` for a more strict type.
+ */
+export type RecipeVariantProps<
+  T extends RecipeVariantFn<RecipeVariantRecord> | SlotRecipeVariantFn<string, SlotRecipeVariantRecord<string>>,
+> = Pretty<Parameters<T>[0]>
+
+/**
+ * Extract the variants from a `cva` function.
+ */
+export type RecipeVariant<
+  T extends RecipeVariantFn<RecipeVariantRecord> | SlotRecipeVariantFn<string, SlotRecipeVariantRecord<string>>,
+> = Exclude<Pretty<Required<RecipeVariantProps<T>>>, undefined>
+
+type RecipeVariantMap<T extends RecipeVariantRecord> = {
+  [K in keyof T]: Array<keyof T[K]>
+}
+
+/* -----------------------------------------------------------------------------
+ * Recipe / Standard
+ * -----------------------------------------------------------------------------*/
+
+export interface RecipeRuntimeFn<T extends RecipeVariantRecord> extends RecipeVariantFn<T> {
+  __type: RecipeSelection<T>
+  variantKeys: (keyof T)[]
+  variantMap: RecipeVariantMap<T>
+  raw: (props?: RecipeSelection<T>) => SystemStyleObject
+  config: RecipeConfig<T>
+  splitVariantProps<Props extends RecipeSelection<T>>(
+    props: Props,
+  ): [RecipeSelection<T>, Pretty<DistributiveOmit<Props, keyof T>>]
+  getVariantProps: (props?: RecipeSelection<T>) => RecipeSelection<T>
+}
+
+type OneOrMore<T> = T | Array<T>
+
+export type RecipeCompoundSelection<T> = {
+  [K in keyof T]?: OneOrMore<StringToBoolean<keyof T[K]>> | undefined
+}
+
+export type RecipeCompoundVariant<T> = T & {
+  css: SystemStyleObject
+}
+
+export interface RecipeDefinition<T extends RecipeVariantRecord = RecipeVariantRecord> {
+  /**
+   * The base styles of the recipe.
+   */
+  base?: SystemStyleObject
+  /**
+   * Whether the recipe is deprecated.
+   */
+  deprecated?: boolean | string
+  /**
+   * The multi-variant styles of the recipe.
+   */
+  variants?: T
+  /**
+   * The default variants of the recipe.
+   */
+  defaultVariants?: RecipeSelection<T>
+  /**
+   * The styles to apply when a combination of variants is selected.
+   */
+  compoundVariants?: Pretty<RecipeCompoundVariant<RecipeCompoundSelection<T>>>[]
+}
+
+export type RecipeCreatorFn = <T extends RecipeVariantRecord>(config: RecipeDefinition<T>) => RecipeRuntimeFn<T>
+
+interface RecipeConfigMeta {
+  /**
+   * The class name of the recipe.
+   */
+  className: string
+  /**
+   * The description of the recipe. This will be used in the JSDoc comment.
+   */
+  description?: string
+  /**
+   * The jsx elements to track for this recipe. Can be string or Regexp.
+   *
+   * @default capitalize(recipe.name)
+   * @example ['Button', 'Link', /Button$/]
+   */
+  jsx?: Array<string | RegExp>
+  /**
+   * Variants to pre-generate, will be include in the final `config.staticCss`
+   */
+  staticCss?: RecipeRule[]
+}
+
+export interface RecipeConfig<T extends RecipeVariantRecord = RecipeVariantRecord>
+  extends RecipeDefinition<T>, RecipeConfigMeta {}
+
+/* -----------------------------------------------------------------------------
+ * Recipe / Slot
+ * -----------------------------------------------------------------------------*/
+
+type SlotRecord<S extends string, T> = Partial<Record<S, T>>
+
+export type SlotRecipeVariantRecord<S extends string> = Record<any, Record<any, SlotRecord<S, SystemStyleObject>>>
+
+export type SlotRecipeVariantFn<S extends string, T extends RecipeVariantRecord> = (
+  props?: RecipeSelection<T>,
+) => SlotRecord<S, string>
+
+export interface SlotRecipeRuntimeFn<
+  S extends string,
+  T extends SlotRecipeVariantRecord<S>,
+> extends SlotRecipeVariantFn<S, T> {
+  raw: (props?: RecipeSelection<T>) => Record<S, SystemStyleObject>
+  variantKeys: (keyof T)[]
+  variantMap: RecipeVariantMap<T>
+  splitVariantProps<Props extends RecipeSelection<T>>(
+    props: Props,
+  ): [RecipeSelection<T>, Pretty<DistributiveOmit<Props, keyof T>>]
+  getVariantProps: (props?: RecipeSelection<T>) => RecipeSelection<T>
+}
+
+export type SlotRecipeCompoundVariant<S extends string, T> = T & {
+  css: SlotRecord<S, SystemStyleObject>
+}
+
+export interface SlotRecipeDefinition<
+  S extends string = string,
+  T extends SlotRecipeVariantRecord<S> = SlotRecipeVariantRecord<S>,
+> {
+  /**
+   * An optional class name that can be used to target slots in the DOM.
+   */
+  className?: string
+  /**
+   * Whether the recipe is deprecated.
+   */
+  deprecated?: boolean | string
+  /**
+   * The parts/slots of the recipe.
+   */
+  slots: S[] | Readonly<S[]>
+  /**
+   * The base styles of the recipe.
+   */
+  base?: SlotRecord<S, SystemStyleObject>
+  /**
+   * The multi-variant styles of the recipe.
+   */
+  variants?: T
+  /**
+   * The default variants of the recipe.
+   */
+  defaultVariants?: RecipeSelection<T>
+  /**
+   * The styles to apply when a combination of variants is selected.
+   */
+  compoundVariants?: Pretty<SlotRecipeCompoundVariant<S, RecipeCompoundSelection<T>>>[]
+}
+
+export type SlotRecipeCreatorFn = <S extends string, T extends SlotRecipeVariantRecord<S>>(
+  config: SlotRecipeDefinition<S, T>,
+) => SlotRecipeRuntimeFn<S, T>
+
+export type SlotRecipeConfig<
+  S extends string = string,
+  T extends SlotRecipeVariantRecord<S> = SlotRecipeVariantRecord<S>,
+> = SlotRecipeDefinition<S, T> & RecipeConfigMeta