@codeleap/styles 6.3.0 → 7.0.0

package/src/types/cache.ts

@@ -1,2 +1,12 @@
 
+/**
+ * Discriminant union identifying the six cache buckets managed by `StyleCache`.
+ * Each bucket stores a different stage of the style-resolution pipeline:
+ * - `variants` — per-component variant merge results (persisted)
+ * - `common` — shared/common variant lookups (persisted)
+ * - `components` — final merged component output (persisted)
+ * - `styles` — `createStyles` call results (in-memory)
+ * - `compositions` — composition style resolution (in-memory)
+ * - `responsive` — responsive breakpoint style resolution (in-memory)
+ */
 export type CacheType = 'variants' | 'common' | 'styles' | 'compositions' | 'responsive' | 'components'

package/src/types/component.ts

@@ -1,7 +1,24 @@
-import { AnyRecord, IJSX } from './core'
+import { AnyRecord, ICSS, IJSX } from './core'
 import { StyleProp, VariantStyleSheet } from './style'
 import React, { JSX } from 'react'
 
+/**
+ * Injects a typed `style` prop onto a component based on the composition keys
+ * inferred from the variant stylesheet. Primarily used when a component's style
+ * prop shape must mirror its variant composition keys exactly.
+ */
+export type StyledProps<VariantStyles extends AnyRecord> = {
+  style?: StyleProp<
+   VariantStyles[keyof VariantStyles] extends Partial<Record<infer K, any>> ? K extends string ? K : never : never,
+    keyof VariantStyles
+  >
+}
+
+/**
+ * Merges external `Props` with variant-aware `style`. If `Props` already declares a
+ * `style` prop whose inner composition type can be inferred, that composition is
+ * preserved; otherwise the composition is derived from `VariantStyles`.
+ */
 export type PropsWithVariants<Props extends AnyRecord, VariantStyles extends AnyRecord> = Omit<Props, 'style'> & {
   style?: StyleProp<
     Extract<keyof Props, 'style'> extends never ? VariantStyles[keyof VariantStyles] : (
@@ -11,11 +28,18 @@ export type PropsWithVariants<Props extends AnyRecord, VariantStyles extends Any
   >
 }
 
+/** Unconstrained function type used for variant callbacks and other callbacks. */
 export type AnyFunction = (...args: any[]) => any
 
-export type StyledComponentProps<Props extends AnyRecord, VariantStyles> = PropsWithVariants<Props, VariantStyles>
+/** Resolved props type for a component that has been bound to a variant stylesheet. */
+export type StyledComponentProps<Props extends AnyRecord, VariantStyles extends AnyRecord> = PropsWithVariants<Props, VariantStyles>
 
-export type StyledComponent<VariantStyles, Props extends AnyRecord = AnyRecord> = (
+/**
+ * A component function that accepts variant-aware style props, plus the registry
+ * metadata fields (`styleRegistryName`, `elements`, `rootElement`) used by the
+ * `CodeleapStyleRegistry` to resolve composition and responsive styles.
+ */
+export type StyledComponent<VariantStyles extends AnyRecord, Props extends AnyRecord = AnyRecord> = (
   (props: StyledComponentProps<Props, VariantStyles>) => IJSX
 ) & {
   styleRegistryName?: string
@@ -23,19 +47,31 @@ export type StyledComponent<VariantStyles, Props extends AnyRecord = AnyRecord>
   rootElement?: string
 }
 
-export type GenericStyledComponentAttributes<Props> = {
+/**
+ * Static attributes attached to every component created by the style system.
+ * `withVariantTypes` narrows the component's style prop to a specific variant stylesheet
+ * without changing the runtime behaviour — it is a TypeScript-only helper.
+ */
+export type GenericStyledComponentAttributes<Props extends AnyRecord> = {
   styleRegistryName?: string
   withVariantTypes?: <VariantStyles extends VariantStyleSheet>(variants: VariantStyles) => StyledComponent<VariantStyles, Props>
   elements?: string[]
   rootElement?: string
 }
 
+/**
+ * A component that hasn't been bound to a specific variant stylesheet yet but carries
+ * the registry metadata needed for the style system to work at runtime.
+ */
 export type GenericStyledComponent<
   Props extends AnyRecord
 > = ((props: Props) => IJSX) & GenericStyledComponentAttributes<Props>
 
+/** Escape-hatch alias for `GenericStyledComponent<any>` used in registry maps. */
 export type AnyStyledComponent = GenericStyledComponent<any>
 
+/** Component function type that optionally accepts `defaultProps` — mirrors React's pattern. */
 export type ComponentWithDefaultProps<P> = ((props: P) => JSX.Element) & { defaultProps?: Partial<P> }
 
-export type StyledComponentWithProps<Props> = ComponentWithDefaultProps<Props> & GenericStyledComponentAttributes<Props>
+/** Combines `ComponentWithDefaultProps` with the style-registry metadata attributes. */
+export type StyledComponentWithProps<Props extends AnyRecord> = ComponentWithDefaultProps<Props> & GenericStyledComponentAttributes<Props>

package/src/types/core.ts

@@ -1,40 +1,100 @@
-
 /* eslint-disable @typescript-eslint/no-empty-interface */
+
+/**
+ * Declaration-merging target for the app's CSS/style property bag.
+ * Platform packages (`@codeleap/web`, `@codeleap/mobile`) augment this interface
+ * with the actual CSS or React Native style properties they support.
+ */
 export interface ICSS {
 
 }
 
+/**
+ * Declaration-merging target for the resolved `AppTheme` object available at runtime.
+ * Consumer apps augment this so that `useTheme()` returns a fully typed theme without
+ * explicit generics at every callsite.
+ */
 export interface ITheme {
 
 }
 
+/**
+ * Declaration-merging target for the JSX element type used by the platform.
+ * Web augments this with `React.ReactElement`; mobile augments with React Native's
+ * equivalent. Allows cross-platform component return types to be typed correctly.
+ */
 export interface IJSX {
 
 }
+
+/**
+ * Declaration-merging target for the app's named breakpoint map.
+ * Augment with `{ sm: unknown; md: unknown; lg: unknown }` (or your own breakpoints)
+ * so that `Breakpoint` and the responsive style API become fully typed.
+ */
 export interface IBreakpoints {
 
 }
 
+/**
+ * Declaration-merging target for the app's color token map.
+ * Augment with the flattened color keys from your theme (e.g., `{ primary: string }`)
+ * so that `color:`, `bg:`, and `borderColor:` variants are narrowed to valid tokens.
+ */
 export interface IColors {
-  
+
 }
 
+/**
+ * Declaration-merging target for the app's border-radius token map.
+ * Augment with keys from `theme.radius` so that `borderRadius:` and `br:` variants
+ * accept only the defined radius tokens.
+ */
 export interface IBorderRadius {
-  
+
 }
 
+/**
+ * Declaration-merging target for app-defined style variants registered via
+ * `createAppVariants`. Augment so that custom variant names are accepted by `StyleProp`.
+ */
 export interface IAppVariants {
-  
+
 }
 
+/**
+ * Declaration-merging target for the app's named size tokens (from `theme.size`).
+ * Augment so that the `size:` dynamic variant is narrowed to valid size keys.
+ */
+export interface ISizes {
+
+}
+
+/**
+ * Declaration-merging target for a single effect object (e.g., a shadow or filter
+ * definition). Shape is platform-specific; augmented by platform packages.
+ */
 export interface IEffect {
-  
+
 }
 
+/**
+ * Declaration-merging target for the named effects map (`theme.effects`).
+ * Augment with `{ shadow: IEffect; ... }` so that `effect:` variants are narrowed.
+ */
 export interface IEffects {
-  
+
 }
 
+/** Convenience alias for an unconstrained key-value record. */
 export type AnyRecord = Record<string, any>
 
+/** Union of all breakpoint names defined via `IBreakpoints` augmentation. */
 export type Breakpoint = keyof IBreakpoints
+
+/**
+ * Runtime context passed to context-aware style factories created with
+ * `createStylesWithContext`. Keys are feature flags or numeric state values
+ * (e.g., `{ isDisabled: true, tabIndex: 2 }`).
+ */
+export type ComponentContext = Record<string, boolean|number>

package/src/types/icon.ts

@@ -1,8 +1,19 @@
 /* eslint-disable @typescript-eslint/no-empty-interface */
 
+/**
+ * Declaration-merging target for the app's named icon set.
+ * Augment with `{ arrowLeft: unknown; close: unknown; ... }` to produce a typed
+ * `AppIcon` union. Shapes are platform-defined; only the keys matter for typing.
+ */
 export interface AppIcons {
 
 }
+
+/** Union of all named icon keys declared in `AppIcons`. Resolves to `never` if not augmented. */
 export type AppIcon = keyof AppIcons
 
+/**
+ * Accepted value for any `icon` prop: either a named `AppIcon` key or an inline
+ * URL in the form `url:<href>` (e.g., `"url:https://example.com/icon.svg"`).
+ */
 export type IconProp = AppIcon | `url:${string}`

package/src/types/spacing.ts

@@ -1,3 +1,7 @@
+/**
+ * Long-form spacing direction suffixes used with `margin` and `padding`.
+ * The empty string `''` represents the un-suffixed property (e.g., `padding`).
+ */
 export const spacingVariants = [
   'Vertical',
   'Horizontal',
@@ -8,6 +12,11 @@ export const spacingVariants = [
   '',
 ] as const
 
+/**
+ * Short-form spacing direction suffixes used with `m` and `p`.
+ * Maps to the long-form via `shortPositionMap` inside `spacingFactory`.
+ * The empty string `''` represents the un-suffixed property (e.g., `p`).
+ */
 export const spacingShortVariants = [
   'y',
   'x',
@@ -18,15 +27,27 @@ export const spacingShortVariants = [
   '',
 ] as const
 
+/** Union of all long-form direction suffixes (e.g., `'Vertical'`, `''`). */
 export type SpacingVariants = typeof spacingVariants[number]
 
+/** Union of all short-form direction suffixes (e.g., `'x'`, `''`). */
 export type SpacingShortVariants = typeof spacingShortVariants[number]
 
+/**
+ * Valid multiplier values for spacing and inset variant strings.
+ * `'auto'` maps to the CSS `auto` keyword; a number is scaled by `baseSpacing`;
+ * `''` is the empty-string terminator used in template literal unions.
+ */
 export type Multiplier =
   | 'auto'
   | number
   | ''
 
+/**
+ * All valid spacing variant strings accepted by `StyleProp`.
+ * Examples: `"paddingVertical:2"`, `"mt:1"`, `"gap:auto"`.
+ * The numeric part is multiplied by `baseSpacing` at resolution time.
+ */
 export type Spacing =
   | `padding${SpacingVariants}:${Multiplier}`
   | `margin${SpacingVariants}:${Multiplier}`

package/src/types/store.ts

@@ -1,3 +1,9 @@
+/**
+ * Minimal key-value storage contract used by `StylePersistor` and `Cache`.
+ * Designed to be implemented by any synchronous store (e.g., MMKV, AsyncStorage
+ * adapters, or `localStorage` wrappers). `getItem` must return `null` (not `undefined`)
+ * when the key is absent — callers use `?? null` guards based on that assumption.
+ */
 export interface StateStorage {
   getItem: (name: string) => any | null
   setItem: (name: string, value: any) => void

package/src/types/style.ts

@@ -10,6 +10,12 @@ type Inset =
   | `left:${Multiplier}`
   | `right:${Multiplier}`
 
+/**
+ * Union of all built-in variant string literals accepted anywhere a style variant
+ * name is valid: spacing shorthands, inset offsets, dynamic token variants (color,
+ * border, cursor, etc.), the static `defaultVariants` keys, app-defined variants,
+ * and named effect tokens.
+ */
 export type CommonVariants =
   Spacing |
   Inset |
@@ -18,12 +24,13 @@ export type CommonVariants =
   keyof IAppVariants |
   `effect:${keyof IEffects}`
 
-type StyleAtom<Composition = AnyRecord, Variants = string, HasBreakpoints = string, HasComposition = string> =
+type StyleAtom<Composition extends string = string, Variants = string, HasBreakpoints = string, HasComposition = string> =
   ICSS |
   Variants |
   CommonVariants |
   boolean |
   null |
+  undefined |
   '' |
 
   (HasBreakpoints extends string ? {
@@ -35,29 +42,49 @@ type StyleAtom<Composition = AnyRecord, Variants = string, HasBreakpoints = stri
   } : null) |
   (HasComposition extends string ?
       Partial<Record<
-        keyof Composition,
-        StyleAtom<AnyRecord, Variants, boolean, boolean> |
-        StyleAtom<AnyRecord, Variants, boolean, boolean>[]
+        Composition,
+        StyleAtom<Composition, Variants, boolean, boolean> |
+        StyleAtom<Composition, Variants, boolean, boolean>[]
       >>
       : null
   )
   | Array<Variants | ICSS | Partial<
     Record<
-      keyof Composition,
-      StyleAtom<AnyRecord, Variants, boolean, boolean> |
-      StyleAtom<AnyRecord, Variants, boolean, boolean>[]
+      Composition,
+      StyleAtom<Composition, Variants, boolean, boolean> |
+      StyleAtom<Composition, Variants, boolean, boolean>[]
     >
   >>
 
+/**
+ * The value accepted by any component's `style` prop. Supports:
+ * - A raw `ICSS` object applied to the root element.
+ * - A variant string (or array of strings) resolved through the registry.
+ * - A composition object mapping sub-element names to their own `StyleAtom`.
+ * - A `{ breakpoints: { [key]: StyleAtom } }` object for responsive overrides.
+ * - An array mixing any of the above — processed left-to-right, last write wins.
+ */
 export type StyleProp<
-  Composition = AnyRecord,
+  Composition extends string = string,
   Variants = string
 > = StyleAtom<Composition, Variants> | StyleAtom<Composition, Variants>[]
 
+/**
+ * Loosely typed variant stylesheet — a record mapping variant names to their style
+ * definitions. Used as the input to `createStyles` and `registerVariants`.
+ */
 export type VariantStyleSheet = Record<string, any>
 
-export type StyledProp<T extends string> = StyleProp<Record<T, ICSS>>
+/** Alias for `StyleProp<T>` scoped to a specific set of composition keys. */
+export type StyledProp<T extends string> = StyleProp<T>
 
+/**
+ * Post-processing function that receives the merged theme and fully resolved variant
+ * styles and returns a (potentially transformed) style record. Useful for injecting
+ * cross-variant logic such as conditional overrides that depend on multiple variant
+ * states simultaneously.
+ */
 export type StyleAggregator<T extends string = any> = (theme: ITheme, style: Record< T, ICSS>) => Record< T, ICSS>
 
-export type StyleRecord<K extends string> = Record<K, ICSS>
+/** Typed record mapping composition/element keys to their resolved `ICSS` values. */
+export type StyleRecord<K extends string> = Record<K, ICSS>

package/src/types/theme.ts

@@ -8,18 +8,34 @@ type AnyMap = {
   [key: string]: any
 }
 
+/**
+ * Flat or nested color token map passed to `createTheme`.
+ * This type is intentionally empty so that `validateTheme` and the CSS-var
+ * machinery can accept any shape; strong typing comes via `IColors` augmentation.
+ */
 export type ColorMap = {
-  [key: string]: string
+
 }
 
+/**
+ * Maps breakpoint names to pixel widths. Used by `createMediaQueries` to generate
+ * `@media screen and (min/max-width: <N>px)` strings. Breakpoints not in this map
+ * fall back to `Infinity` (treated as unbounded).
+ */
 type BreakpointMap = {
   [key: string]: number
 }
 
+/** Map of named effect tokens (shadows, filters, etc.) to their effect shapes. */
 type EffectsMap = {
   [key: string]: IEffect
 }
 
+/**
+ * The full spacing API attached to every `AppTheme`. Combines the long-form
+ * (`margin`, `padding` with variant suffixes) and short-form (`m`, `p`) factories,
+ * plus `gap`. Each property is a `MultiplierFunction` that scales by `baseSpacing`.
+ */
 export type SpacingMap =
   Spacings<'margin'> &
   Spacings<'padding'> &
@@ -29,6 +45,10 @@ export type SpacingMap =
     gap: MultiplierFunction
   }
 
+/**
+ * Position-offset functions (`top`, `bottom`, `left`, `right`) attached to `AppTheme`.
+ * Each function multiplies its argument by `baseSpacing` and returns an `ICSS` object.
+ */
 export type InsetMap =
   {
     bottom: MultiplierFunction
@@ -37,6 +57,16 @@ export type InsetMap =
     right: MultiplierFunction
   }
 
+/**
+ * Raw theme definition passed to `createTheme`. After processing, the resolved object
+ * is an `AppTheme<T>` with additional runtime methods (`setColorScheme`, `spacing`, etc.).
+ *
+ * - `baseColors` — primitive palette tokens merged into both `colors` and every alternate scheme.
+ * - `colors` — semantic/alias tokens for the default color scheme.
+ * - `alternateColors` — named overrides; each must supply all keys present in `colors`.
+ * - `baseSpacing` — the multiplier used by spacing/inset factories (default: 1).
+ * - `isBrowser` — when `true`, enables CSS custom-property mode for colors and browser-only styles.
+ */
 export type Theme = {
   baseColors: ColorMap
   colors: ColorMap
@@ -44,6 +74,7 @@ export type Theme = {
     [key: string]: ColorMap
   }
   breakpoints?: BreakpointMap
+
   baseSpacing?: number
   presets?: AnyMap
   radius?: AnyMap
@@ -56,14 +87,17 @@ export type Theme = {
   isBrowser?: boolean
 }
 
+/** The reserved name for the primary (non-alternate) color scheme. */
 export type DefaultColorSchemeName = 'default'
 
+/** Union of `'default'` and all keys defined in `T['alternateColors']`. */
 export type ColorScheme<T extends Theme = Theme> = DefaultColorSchemeName | keyof T['alternateColors']
 
 type PredefinedThemeDerivedValues<T extends Theme> = {
   baseColors: T['baseColors']
   colors: T['colors']
   breakpoints: T['breakpoints']
+
   presets: DefaultVariants & T['presets']
   radius: T['radius']
   stroke: T['stroke']
@@ -79,6 +113,8 @@ type PredefinedAppTheme<T extends Theme> = PredefinedThemeDerivedValues<T> & {
   currentColorScheme: () => ColorScheme<T>
   injectColorScheme: (name: string, colorMap: ColorMap) => void
   ejectColorScheme: (name: string) => void
+  getCssVariables: (schemeName?: string) => Record<string, string>
+  currentSchemeColors: T['colors']
   spacing: SpacingMap
   media: MediaQueries
   border: BorderCreator

package/src/utils.ts

@@ -2,12 +2,21 @@ import { ICSS, StyledProp } from './types'
 import { spacingShortVariants, spacingVariants } from './types/spacing'
 import { deepmerge } from './tools'
 
+/**
+ * Uppercases (or lowercases when `reverse = true`) the first character of a string.
+ * Returns the input unchanged when it is falsy or empty.
+ */
 export function capitalize(str: string, reverse = false) {
-  if (!str.length) return str
+  if (!str?.length) return str
   const firstChar = reverse ? str[0].toLowerCase() : str[0].toUpperCase()
   return firstChar + str.substring(1)
 }
 
+/**
+ * Complete list of CSS/RN spacing-related property names that the style registry treats
+ * specially (resolved via the spacing factory rather than passed through as raw ICSS).
+ * Built eagerly at module load time by iterating `spacingVariants` and `spacingShortVariants`.
+ */
 export const spacingKeys = [
   'gap',
   'top',
@@ -28,14 +37,21 @@ for (const shortProperty of ['p', 'm']) {
   }
 }
 
+/** Returns `true` if `key` is one of the pre-built spacing property names. */
 export function isSpacingKey(key: string) {
   if (!key) return false
 
   return spacingKeys?.includes(key)
 }
 
+/**
+ * Extracts all entries whose key starts with `match`, stripping the prefix and
+ * lowercasing the first character of the remainder. Used by composition hooks to
+ * slice a flat `{ wrapperText: ..., wrapperIcon: ... }` record into a nested
+ * `{ text: ..., icon: ... }` map for a single composition element.
+ */
 export function getNestedStylesByKey<T extends string>(match: string, styles: Partial<Record<T, ICSS>>) {
-  const stylesByKey = {}
+  const stylesByKey: Record<string, any> = {}
 
   for (const [key, value] of Object.entries(styles)) {
     if (key.startsWith(match)) {
@@ -47,13 +63,22 @@ export function getNestedStylesByKey<T extends string>(match: string, styles: Pa
   return stylesByKey
 }
 
+/**
+ * Merges an array of style objects into one using `@fastify/deepmerge` with `all: true`.
+ * Falsy entries are filtered out before merging. Later entries overwrite earlier ones.
+ */
 export const mergeStyles = (styles: Array<any>) => {
   const style = styles?.filter(s => !!s)
 
   return deepmerge({ all: true })(...style)
 }
 
-// @note these words are reserved by css
+/**
+ * Style property names that collide with CSS keywords and must not be treated as
+ * composition-element prefixes by the registry. Without this list, a style object
+ * like `{ textAlign: 'center' }` would be misidentified as a composition key starting
+ * with `text`.
+ */
 export const ignoredStyleKeys = [
   'textAlign',
   'textDecoration',
@@ -64,9 +89,14 @@ export const ignoredStyleKeys = [
   'bottom',
 ]
 
+/**
+ * Flattens nested arrays of `StyledProp` into a single flat array. Useful when
+ * assembling the final `style` prop from multiple sources (e.g., variant defaults
+ * plus overrides), without losing the order-dependent merge semantics of `StyleProp`.
+ */
 export const concatStyles = <T extends string>(styles: Array<StyledProp<T>>): StyledProp<T> => {
   const results = []
-  
+
   for (const style of styles) {
     if (Array.isArray(style)) {
       results.push(...style)

package/src/variants/borderCreator.ts

@@ -3,16 +3,25 @@ import { borderDirection } from './dynamicVariants'
 import { themeStore } from '../theme'
 import { capitalize } from '../utils'
 
+/** Arguments for `borderCreator`. */
 type BorderCreatorArgs = {
   color: keyof IColors | (string & {})
   width?: number | string
   directions?: typeof borderDirection[number][]
-  // @ts-expect-error borderStyle not exists
-  style?: ICSS['borderStyle']
+  style?: "dashed" | "dotted" | "double" | "groove" | "hidden" | "inset" | "none" | "outset" | "ridge" | "solid";
 }
 
+/** Function signature of the `border` helper attached to `AppTheme`. */
 export type BorderCreator = (args: BorderCreatorArgs) => ICSS
 
+/**
+ * Resolves `color` from `theme.colors` (falls back to the raw string if not found),
+ * then emits `border{Direction}Color`, `border{Direction}Width`, and — on web only —
+ * `border{Direction}Style` for each requested direction.
+ * Defaults: all four sides, width 1, style `'solid'`.
+ * `borderStyle` is omitted on React Native because RN requires it on individual sides
+ * and `isBrowser` guards that path.
+ */
 export const borderCreator: BorderCreator = (args) => {
   const {
     color: colorKey,
@@ -23,9 +32,9 @@ export const borderCreator: BorderCreator = (args) => {
 
   const theme = themeStore.themeTyped
 
-  const color = theme?.colors?.[colorKey] ?? colorKey
+  const color = (theme?.colors as Record<string, any>)?.[colorKey] ?? colorKey
 
-  let borderStyles: ICSS = {}
+  let borderStyles: Record<string, any> = {}
 
   for (const direction of directions) {
     const property = `border${capitalize(direction)}`
@@ -35,5 +44,5 @@ export const borderCreator: BorderCreator = (args) => {
     if (theme?.isBrowser) borderStyles[`${property}Style`] = style
   }
 
-  return borderStyles
+  return borderStyles as ICSS
 }

package/src/variants/createAppVariants.ts

@@ -5,6 +5,17 @@ type AppVariantsMap = {
   [x: string]: ICSS | ((theme: ITheme) => ICSS)
 }
 
+/**
+ * Registers app-specific style variants with the global `themeStore`.
+ * Call this once during app initialisation (before any component mounts) with the
+ * variants object that extends the base variant set. The variants are merged into
+ * `commonVariants` when `CodeleapStyleRegistry` initialises.
+ *
+ * Each entry can be either a static `ICSS` object (applied unconditionally) or a
+ * function `(theme: ITheme) => ICSS` (resolved lazily using the current theme).
+ *
+ * @returns The same `variants` object — useful for typing augmentation of `IAppVariants`.
+ */
 export function createAppVariants<T extends AppVariantsMap>(variants: T) {
   themeStore.setVariants(variants)