@codeleap/styles 6.2.3 → 6.8.0

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)
 

package/src/variants/defaultVariants.ts

@@ -1,11 +1,22 @@
 import { ICSS } from '../types'
 
+/**
+ * Static built-in style variants available to every component without any registration.
+ * These are merged as the lowest-priority layer in `commonVariants`, so app-defined
+ * variants and dynamic variants can override them.
+ *
+ * Notable entries:
+ * - `grow` — sets `flex: 1` (not `display: flex`; use `row`/`column` for flex containers).
+ * - `inset` — shorthand for `{ top:0, bottom:0, left:0, right:0 }` (useful with `absolute`).
+ * - `insetX` / `insetY` — pin to horizontal or vertical edges only.
+ * - `centerChildren` — centers children via `alignItems`/`justifyContent`; requires a flex container.
+ * - `'visibility:hidden'` / `'display:none'` — use quoted keys in style arrays.
+ */
 export const defaultVariants = {
   block: {
     display: 'block',
   },
-  flex: {
-    display: 'flex',
+  grow: {
     flex: 1,
   },
   absolute: {
@@ -28,9 +39,7 @@ export const defaultVariants = {
     top: 0,
     bottom: 0,
   },
-  hidden: {
-    display: 'none',
-  },
+
   full: {
     width: '100%',
     height: '100%',
@@ -44,7 +53,7 @@ export const defaultVariants = {
   fullHeight: {
     height: '100%',
   },
-  whole: {
+  inset: {
     top: 0,
     bottom: 0,
     left: 0,
@@ -60,9 +69,10 @@ export const defaultVariants = {
     flexDirection: 'row',
   },
   column: {
+    display: 'flex',
     flexDirection: 'column',
   },
-  center: {
+  centerChildren: {
     alignItems: 'center',
     justifyContent: 'center',
   },
@@ -114,9 +124,19 @@ export const defaultVariants = {
   textCenter: {
     textAlign: 'center',
   },
-  wrap: {
+  flexWrap: {
     flexWrap: 'wrap',
   },
+  'visibility:hidden': {
+    visibility: 'hidden'
+  },
+  'visibility:visible': {
+    visibility: 'visible'
+  },
+  'display:none': {
+    display:'none'
+  }
 } as const
 
+/** Typed record mapping every built-in variant name to an `ICSS` value. */
 export type DefaultVariants = Record<keyof typeof defaultVariants, ICSS>

package/src/variants/dynamicVariants.ts

@@ -1,15 +1,22 @@
-import { IBorderRadius, IColors, IEffects } from '../types'
+import { IBorderRadius, IColors, IEffects, ISizes, ITheme } from '../types'
 import { capitalize } from '../utils'
 
+/** Callback shape for a variant that receives a raw value and returns a style fragment. */
 export type VariantFunction = (value: any) => any
 
+/** CSS properties that accept a color token: `backgroundColor` and `color`. */
 export const colorVariants = ['backgroundColor', 'color'] as const
 
+/** Horizontal border directions used when generating per-corner radius variants. */
 export const borderXDirection = ['left', 'right'] as const
+/** Vertical border directions used when generating per-corner radius variants. */
 export const borderYDirection = ['bottom', 'top'] as const
+/** All four border directions plus the un-suffixed (all-sides) form. */
 export const borderDirection = [...borderYDirection, ...borderXDirection, ''] as const
+/** Border sub-properties generated for each direction. */
 export const borderProperties = ['color', 'radius', 'width'] as const
 
+/** CSS cursor values surfaced as `cursor:<value>` style variants. */
 export const cursorTypes = [
   'not-allowed',
   'help',
@@ -18,35 +25,58 @@ export const cursorTypes = [
   '',
 ] as const
 
+/** Numeric value or the empty-string terminator used in `scale:` variant templates. */
 export type Value =
   | number
   | ''
 
-// @note
-// Typing has been removed because figma's new color organization is extremely heavy, 
-// perhaps in a future typescript update
-type Color = string // keyof IColors
+type MatchKeysByValue<
+  T extends Record<string, any>,
+  Values
+> = { [K in keyof T]: T[K] extends Values ? K : never }[keyof T]
 
+// @note
+// Adding the baseColors here make it extremely heavy,
+// perhaps in a future typescript update it will be better. We exclude any non-string keys because those are namespaces (usually components)
+type Color = MatchKeysByValue<IColors, string>// keyof IColors
+
+type Sizes = keyof ISizes
+
+/**
+ * Union of all parametric variant strings resolved at runtime by looking up the
+ * provided value in the theme. Examples: `"color:primary"`, `"bg:neutral"`,
+ * `"borderRadius:sm"`, `"cursor:pointer"`, `"scale:0.95"`, `"size:icon"`.
+ * The part before `:` is the variant name; the part after is the token key or raw value.
+ */
 export type DynamicVariants =
   `color:${Color}` |
   `border${Capitalize<typeof borderDirection[number]>}Width:${keyof IBorderRadius}` |
   `border${Capitalize<typeof borderDirection[number]>}Color:${Color}` |
   `borderRadius:${keyof IBorderRadius}` |
   `border${Capitalize<typeof borderYDirection[number]>}${Capitalize<typeof borderXDirection[number]>}Radius:${keyof IBorderRadius}` |
+  `border${Capitalize<typeof borderYDirection[number]>}Radius:${keyof IBorderRadius}` |
+  `border${Capitalize<typeof borderXDirection[number]>}Radius:${keyof IBorderRadius}` |
   `cursor:${typeof cursorTypes[number]}` |
   `bg:${Color}` |
   `br:${keyof IBorderRadius}` |
-  `scale:${Value}`
-
+  `scale:${Value}` |
+  `size:${Sizes}`
+
+/**
+ * Builds the dynamic variant registry object at module initialisation time.
+ * Each entry is a function `(theme, value) => ICSS` keyed by the variant name
+ * (the part before `:` in the variant string). The registry is consumed by
+ * `CodeleapStyleRegistry.computeCommonVariantStyle`.
+ */
 export const createDynamicVariants = () => {
-  const dynamicVariants = {}
+  const dynamicVariants: Record<string, any> = {}
 
   function createVariant(variantName: string, variantReturn: any) {
     dynamicVariants[variantName] = variantReturn
   }
 
   colorVariants.forEach(variant => {
-    createVariant(variant, (theme, color: Color) => ({
+    createVariant(variant, (theme: ITheme & Record<string, any>, color: Color) => ({
       [variant]: theme.colors[color],
     }))
   })
@@ -56,42 +86,70 @@ export const createDynamicVariants = () => {
       borderXDirection.forEach(y => {
         const variant = `border${capitalize(direction)}${capitalize(y)}Radius`
 
-        createVariant(variant, (theme, value: keyof IBorderRadius) => ({
+        createVariant(variant, (theme: ITheme & Record<string, any>, value: keyof IBorderRadius) => ({
           [variant]: theme.radius[value],
         }))
       })
     }
 
+
+
     borderProperties.forEach(property => {
       const variant = `border${capitalize(direction)}${capitalize(property)}`
 
-      createVariant(variant, (theme, value: string) => ({
-        [variant]: property == 'color' ? theme.colors[value] : theme.radius[value],
+      createVariant(variant, (theme: ITheme & Record<string, any>, value: string) => ({
+        [variant]: property == 'color' ? (theme.colors as Record<string, any>)[value] : (theme.radius as Record<string, any>)[value],
       }))
     })
   })
 
-  createVariant('cursor', (theme, cursor: typeof cursorTypes[number]) => ({ cursor }))
+  borderXDirection.forEach(x => {
+    const variant = `border${capitalize(x)}Radius`
+
+    createVariant(variant, (theme: ITheme & Record<string, any>, value: keyof IBorderRadius) => ({
+      [variant]: theme.radius[value],
+    }))
+  })
+
+  borderYDirection.forEach(y => {
+    const variant = `border${capitalize(y)}Radius`
+
+    createVariant(variant, (theme: ITheme & Record<string, any>, value: keyof IBorderRadius) => ({
+      [variant]: theme.radius[value],
+    }))
+  })
+
+
+  createVariant('cursor', (theme: ITheme & Record<string, any>, cursor: typeof cursorTypes[number]) => ({ cursor }))
 
-  createVariant('bg', (theme, color: Color) => ({
+  createVariant('bg', (theme: ITheme & Record<string, any>, color: Color) => ({
     backgroundColor: theme.colors[color],
   }))
 
-  createVariant('effect', (theme, effect: keyof IEffects) => theme.effects[effect])
+  createVariant('effect', (theme: ITheme & Record<string, any>, effect: keyof IEffects) => theme.effects[effect])
 
-  createVariant('scale', (theme, value: any) => ({
+  createVariant('scale', (theme: ITheme & Record<string, any>, value: any) => ({
     transform: theme.isBrowser ? `scale(${value})` : [{ 'scale': Number(value) }],
   }))
 
-  createVariant('br', (theme, value: keyof IBorderRadius) => ({
+  createVariant('br', (theme: ITheme & Record<string, any>, value: keyof IBorderRadius) => ({
     borderRadius: theme.radius[value],
   }))
 
-  createVariant('borderRadius', (theme, value: keyof IBorderRadius) => ({
+  createVariant('borderRadius', (theme: ITheme & Record<string, any>, value: keyof IBorderRadius) => ({
     borderRadius: theme.radius[value],
   }))
 
+  createVariant('size', (theme: ITheme & Record<string, any>, value: keyof ISizes) => ({
+    height: theme.size[value],
+    width: theme.size[value],
+  }))
+
   return dynamicVariants
 }
 
+/**
+ * Pre-built dynamic variant registry used by the `CodeleapStyleRegistry`.
+ * Created once at module load; re-creation would lose the closed-over variant map.
+ */
 export const dynamicVariants = createDynamicVariants()

package/src/variants/mediaQuery.ts

@@ -1,5 +1,13 @@
 import { Breakpoint } from '../types'
 
+/**
+ * The four directional media-query helpers. Each returns a complete `@media` string
+ * that can be used as a nested style key.
+ * - `up` — `min-width` (at and above the breakpoint).
+ * - `down` — `max-width` (at and below the breakpoint).
+ * - `is` — exact match (`min-width` AND `max-width` at the same value).
+ * - `not` — negated exact match.
+ */
 export type Queries = {
   up: (breakpoint: string) => string
   down: (breakpoint: Breakpoint) => string
@@ -7,6 +15,11 @@ export type Queries = {
   not: (breakpoint: string) => string
 }
 
+/**
+ * Extends `Queries` with `renderToPlatformQuery`, which inverts the query direction
+ * for React Native's platform-query rendering: `up` becomes `down`, `is` becomes `not`,
+ * etc. This is how responsive styles declared for web are translated to RN media conditions.
+ */
 export type MediaQueries = Queries & {
   renderToPlatformQuery: (props: Record<keyof Queries, any>) => string
 }
@@ -19,6 +32,11 @@ function getBreakpointValue(breakpoint: any, breakpoints: any) {
   return Infinity
 }
 
+/**
+ * Produces a `MediaQueries` object bound to the provided `breakpoints` map.
+ * Unknown breakpoints (not in the map) fall back to `Infinity`, making `up(unknown)`
+ * match all widths and `down(unknown)` match none.
+ */
 export function createMediaQueries<T extends any>(breakpoints: T): MediaQueries {
   function getBreakpoint(breakpoint: any) {
     return getBreakpointValue(breakpoint, breakpoints)

package/src/variants/spacing.ts

@@ -1,8 +1,14 @@
 import { ICSS } from '../types'
 import { spacingVariants, spacingShortVariants, SpacingVariants, SpacingShortVariants } from '../types/spacing'
 
+/** Function returned by a spacing factory entry; accepts a multiplier and returns a style fragment. */
 export type MultiplierFunction = (multiplier: number | string) => ICSS
 
+/**
+ * Typed shape of the spacing object produced by `spacingFactory` for a given property.
+ * When `S` is `boolean`, the direction variants are long-form (`SpacingVariants`);
+ * when `S` is `string`, they are short-form (`SpacingShortVariants`).
+ */
 export type Spacings<T extends string, S = boolean> = {
   [Property in (S extends boolean ? SpacingVariants : SpacingShortVariants) as `${T}${string & Property}`]: MultiplierFunction;
 } & {
@@ -31,6 +37,14 @@ const shortPositionMap = {
   'b': 'Bottom'
 }
 
+/**
+ * Builds a spacing variant map for a CSS property (`'padding'`, `'margin'`, `'p'`, `'m'`).
+ * Each key in the returned object is a callable that multiplies its argument by `base`.
+ * Passing `isShort = true` uses single-letter direction suffixes and maps them to their
+ * long-form equivalents before producing the CSS property name.
+ * The `'Horizontal'` and `'Vertical'` (or `'x'`/`'y'`) directions expand to two
+ * properties each; the empty-string direction produces all four sides at once.
+ */
 export function spacingFactory<T extends string>(
   base: number,
   spacingProperty: T,
@@ -39,7 +53,7 @@ export function spacingFactory<T extends string>(
   const baseProperty = isShort ? shortMapValues[spacingProperty as keyof typeof shortMapValues] : spacingProperty
   const positions = isShort ? spacingShortVariants : spacingVariants
 
-  const spacings = {
+  const spacings: Record<string, (n: number | string) => Record<string, any>> = {
     [`${spacingProperty}`]: (n: number | string) => {
       if (n === 'auto') {
         return { [baseProperty]: 'auto' }

package/package.json.bak

@@ -1,30 +0,0 @@
-{
-  "name": "@codeleap/styles",
-  "version": "6.2.3",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/styles"
-  },
-  "devDependencies": {
-    "@codeleap/config": "workspace:*",
-    "ts-node-dev": "^1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "react": "19.1.0",
-    "typescript": "5.5.2"
-  },
-  "dependencies": {
-    "@fastify/deepmerge": "3.1.0",
-    "@nanostores/react": "1.0.0",
-    "js-sha256": "0.11.1",
-    "lz-string": "1.5.0",
-    "nanostores": "1.0.1",
-    "rfdc": "1.4.1"
-  }
-}