@codeleap/styles 6.3.0 → 6.8.0

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.3.0",
-  "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"
-  }
-}