@styleframe/theme 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @styleframe/theme
 
+## 2.5.0
+
+### Minor Changes
+
+- [#105](https://github.com/styleframe-dev/styleframe/pull/105) [`b109ac1`](https://github.com/styleframe-dev/styleframe/commit/b109ac148d837ae0a060c34f0236338bf4deca36) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add multiplier support to spacing utilities (margin, padding, gap, space) with @-prefixed numeric values that generate calc() expressions based on a base spacing variable
+
 ## 2.4.0
 
 ### Minor Changes

package/dist/theme.d.ts

@@ -3,6 +3,7 @@ import { ModifierFactory } from '@styleframe/core';
 import { Reference } from '@styleframe/core';
 import { Styleframe } from '@styleframe/core';
 import { TokenValue } from '@styleframe/core';
+import { UtilityAutogenerateFn } from '@styleframe/core';
 import { UtilityCallbackFn } from '@styleframe/core';
 import { UtilityCreatorFn } from '@styleframe/core';
 import { Variable } from '@styleframe/core';
@@ -392,6 +393,90 @@ export declare const colorValues: {
  */
 declare type ColorVariationsForKey<K> = K extends string ? ExportKeys<`color.${K}`, DefaultLightnessLevels, "-"> & ExportKeys<`color.${K}-shade`, DefaultShadeLevels, "-"> & ExportKeys<`color.${K}-tint`, DefaultTintLevels, "-"> : never;
 
+/**
+ * Creates an autogenerate function that handles @-prefixed numeric multiplier values.
+ *
+ * When a value like "@1.5" is detected (@ prefix + numeric), it generates:
+ * - key: the numeric value as string (e.g., "1.5")
+ * - value: calc(var(--baseVariable, fallback) * multiplier)
+ *
+ * Non-multiplier values fall back to the default transformUtilityKey behavior.
+ *
+ * @example
+ * ```typescript
+ * const autogenerate = createMultiplierAutogenerate({
+ *     s,
+ *     baseVariable: "spacing",
+ *     fallback: "1rem",
+ * });
+ *
+ * // Usage with utility:
+ * const createMargin = s.utility("margin", ({ value }) => ({ margin: value }), { autogenerate });
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing, 1rem) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing, 1rem) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing, 1rem) * -1); }
+ * ```
+ */
+export declare function createMultiplierAutogenerate(options: CreateMultiplierAutogenerateOptions): UtilityAutogenerateFn;
+
+export declare interface CreateMultiplierAutogenerateOptions {
+    /** The Styleframe instance (required for css template literal) */
+    s: Styleframe;
+    /** The base variable to multiply against (variable object or variable name string) */
+    baseVariable: Variable | string;
+    /** Fallback value if the base variable is not defined (e.g., "1rem") */
+    fallback?: string;
+    /** Optional key replacer function for non-multiplier values */
+    replacer?: (key: string) => string;
+}
+
+/**
+ * Creates a composable function for spacing-based CSS utilities with multiplier support.
+ *
+ * This is similar to createUseUtility but adds automatic multiplier generation:
+ * - @-prefixed numeric values like "@1.5" become: calc(var(--spacing) * 1.5)
+ * - Named values and references work as normal
+ *
+ * @example
+ * ```typescript
+ * export const useMarginUtility = createUseSpacingUtility(
+ *     'margin',
+ *     ({ value }) => ({ margin: value })
+ * );
+ *
+ * // Usage:
+ * const s = styleframe();
+ * const createMargin = useMarginUtility(s, { sm: ref(spacingSm) });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing) * -1); }
+ * ```
+ */
+export declare function createUseSpacingUtility<UtilityName extends string, Defaults extends Record<string, TokenValue> = Record<string, TokenValue>>(utilityName: UtilityName, factory: UtilityCallbackFn, options?: CreateUseSpacingUtilityOptions<Defaults>): <T extends Record<string, TokenValue> = Defaults>(s: Styleframe, values?: T, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
+
+export declare interface CreateUseSpacingUtilityOptions<Defaults extends Record<string, TokenValue>> {
+    /** Default values for the utility */
+    defaults?: Defaults;
+    /** Whether to merge user values with defaults (true) or replace them (false) */
+    mergeDefaults?: boolean;
+    /**
+     * The base spacing variable name or Variable object.
+     * Defaults to "spacing" which references var(--spacing).
+     */
+    baseVariable?: string | Variable;
+    /**
+     * Fallback value if the base variable is not defined.
+     * Only used when baseVariable is a string. Defaults to "1rem".
+     */
+    fallback?: string;
+}
+
 /**
  * Creates a generic composable function for a CSS utility.
  *
@@ -876,6 +961,19 @@ export declare const hyphensValues: {
 
 export declare function isKeyReferenceValue(value: unknown): value is `@${string}`;
 
+/**
+ * Check if a value is a numeric string or number (including negative numbers and decimals).
+ *
+ * @example
+ * isNumericValue(1) // true
+ * isNumericValue("1.5") // true
+ * isNumericValue("-0.5") // true
+ * isNumericValue(".5") // true
+ * isNumericValue("sm") // false
+ * isNumericValue("1rem") // false
+ */
+export declare function isNumericValue(value: unknown): value is string | number;
+
 /**
  * Default isolation utility values matching Tailwind CSS.
  */
@@ -2954,23 +3052,29 @@ export declare const useForcedColorAdjustUtility: <T extends Record<string, Toke
 }>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create gap utility classes.
+ * Create gap utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useGapUtility(s, { '0': '0', '1': '0.25rem', '2': '0.5rem' });
+ * const createGap = useGapUtility(s, { '0': '0', '1': '0.25rem', '2': '0.5rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createGap(["@1.5", "@2"]);
+ * // Generates:
+ * // ._gap:1.5 { gap: calc(var(--spacing) * 1.5); }
+ * // ._gap:2 { gap: calc(var(--spacing) * 2); }
  * ```
  */
 export declare const useGapUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create column-gap utility classes.
+ * Create column-gap utility classes with multiplier support.
  */
 export declare const useGapXUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create row-gap utility classes.
+ * Create row-gap utility classes with multiplier support.
  */
 export declare const useGapYUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
@@ -3368,13 +3472,19 @@ export declare const useMarginRightUtility: <T extends Record<string, TokenValue
 export declare const useMarginTopUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create margin utility classes.
+ * Create margin utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useMarginUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem', auto: 'auto' });
- * // Generates: ._margin:sm, ._margin:md, ._margin:lg, ._margin:auto
+ * const createMargin = useMarginUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem', auto: 'auto' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createMargin(["@1.5", "@2", "@-1"]);
+ * // Generates:
+ * // ._margin:1.5 { margin: calc(var(--spacing) * 1.5); }
+ * // ._margin:2 { margin: calc(var(--spacing) * 2); }
+ * // ._margin:-1 { margin: calc(var(--spacing) * -1); }
  * ```
  */
 export declare const useMarginUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -3690,13 +3800,18 @@ export declare const usePaddingRightUtility: <T extends Record<string, TokenValu
 export declare const usePaddingTopUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create padding utility classes.
+ * Create padding utility classes with multiplier support.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * usePaddingUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem' });
- * // Generates: ._padding:sm, ._padding:md, ._padding:lg
+ * const createPadding = usePaddingUtility(s, { sm: '0.5rem', md: '1rem', lg: '1.5rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createPadding(["@1.5", "@2"]);
+ * // Generates:
+ * // ._padding:1.5 { padding: calc(var(--spacing) * 1.5); }
+ * // ._padding:2 { padding: calc(var(--spacing) * 2); }
  * ```
  */
 export declare const usePaddingUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -4109,14 +4224,18 @@ export declare const useSkewYUtility: <T extends Record<string, TokenValue> = Re
 export declare const useSpaceXReverseUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create space-x utility classes (horizontal space between children).
+ * Create space-x utility classes with multiplier support (horizontal space between children).
  * Uses the "lobotomized owl" selector to add margin-left to all but the first child.
  *
  * @example
  * ```typescript
  * const s = styleframe();
- * useSpaceXUtility(s, { sm: '0.5rem', md: '1rem' });
- * // Generates: ._space-x:sm > * + *, ._space-x:md > * + *
+ * const createSpaceX = useSpaceXUtility(s, { sm: '0.5rem', md: '1rem' });
+ *
+ * // Add multiplier values (with @ prefix):
+ * createSpaceX(["@1.5", "@2"]);
+ * // Generates:
+ * // ._space-x:1.5 > * + * { margin-left: calc(var(--spacing) * 1.5); }
  * ```
  */
 export declare const useSpaceXUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
@@ -4128,7 +4247,7 @@ export declare const useSpaceXUtility: <T extends Record<string, TokenValue> = R
 export declare const useSpaceYReverseUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
 /**
- * Create space-y utility classes (vertical space between children).
+ * Create space-y utility classes with multiplier support (vertical space between children).
  * Uses the "lobotomized owl" selector to add margin-top to all but the first child.
  */
 export declare const useSpaceYUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;