@styleframe/theme 2.4.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @styleframe/theme
 
+## 3.0.0
+
+### Major Changes
+
+- [#117](https://github.com/styleframe-dev/styleframe/pull/117) [`ffe6764`](https://github.com/styleframe-dev/styleframe/commit/ffe6764a2e6c84d5b3cfdf431bf11f17a3f3f118) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Introduce global Styleframe single-instance architecture. Extension files (`*.styleframe.ts`) now share the same instance created in `styleframe.config.ts` instead of creating independent instances. This is a breaking change that affects how styles are imported and composed across files.
+
+### Minor Changes
+
+- [#81](https://github.com/styleframe-dev/styleframe/pull/81) [`266f961`](https://github.com/styleframe-dev/styleframe/commit/266f96143e9ffb47e0e6326d0e5e7cc9d974ab83) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add Badge recipe with createUseRecipe factory
+  - Add `useBadgeRecipe` and `useBadgeRecipeBase` recipe composables with color, variant, and size variants
+  - Add `createUseRecipe` factory utility for building reusable, customizable recipe presets
+  - Add `3xs` and `2xs` font-size values
+
+### Patch Changes
+
+- Updated dependencies [[`266f961`](https://github.com/styleframe-dev/styleframe/commit/266f96143e9ffb47e0e6326d0e5e7cc9d974ab83), [`ffe6764`](https://github.com/styleframe-dev/styleframe/commit/ffe6764a2e6c84d5b3cfdf431bf11f17a3f3f118)]:
+  - @styleframe/core@3.0.0
+
+## 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

@@ -1,11 +1,14 @@
 import { CamelCase } from 'scule';
 import { ModifierFactory } from '@styleframe/core';
+import { Recipe } 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';
+import { VariantDeclarationsBlock } from '@styleframe/core';
 
 /**
  * Default align-content utility values matching Tailwind CSS.
@@ -392,6 +395,99 @@ 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;
+    /** Optional namespace for token references (e.g., "spacing" makes "@sm" resolve to ref("spacing.sm")) */
+    namespace?: string | string[];
+}
+
+export declare function createUseRecipe<Name extends string, Variants extends Record<string, Record<string, VariantDeclarationsBlock>>, Config extends RecipeConfig<Variants>>(name: Name, defaults: Config): (s: Styleframe, options?: DeepPartial<Config>) => Recipe<Name, Variants>;
+
+/**
+ * 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;
+    /**
+     * Optional namespace for token references in autogenerate.
+     * When set, "@sm" in array syntax resolves to ref("namespace.sm").
+     */
+    namespace?: string;
+}
+
 /**
  * Creates a generic composable function for a CSS utility.
  *
@@ -427,6 +523,11 @@ export declare interface CreateUseUtilityOptions<Defaults extends Record<string,
     defaults?: Defaults;
     /** Whether to merge user values with defaults (true) or replace them (false) */
     mergeDefaults?: boolean;
+    /**
+     * Optional namespace for token references in autogenerate.
+     * When set, "@sm" in array syntax resolves to ref("namespace.sm").
+     */
+    namespace?: string | string[];
 }
 
 /**
@@ -517,6 +618,10 @@ export declare const cursorValues: {
     "zoom-out": string;
 };
 
+export declare type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
 declare type DefaultBorderRadius = typeof borderRadiusValues;
 
 declare type DefaultBorderStyle = typeof borderStyleValues;
@@ -776,6 +881,8 @@ export declare const fontFamilyValues: {
 
 export declare const fontSizeValues: {
     default: string;
+    "3xs": string;
+    "2xs": string;
     xs: string;
     sm: string;
     md: string;
@@ -876,6 +983,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.
  */
@@ -1133,6 +1253,20 @@ export declare const positionValues: {
     sticky: string;
 };
 
+export declare type RecipeConfig<Variants extends Record<string, Record<string, VariantDeclarationsBlock>> = Record<string, Record<string, VariantDeclarationsBlock>>> = {
+    base?: VariantDeclarationsBlock;
+    variants?: Variants;
+    defaultVariants?: {
+        [K in keyof Variants]?: keyof Variants[K] & string;
+    };
+    compoundVariants?: Array<{
+        match: {
+            [K in keyof Variants]?: keyof Variants[K] & string;
+        };
+        css: VariantDeclarationsBlock;
+    }>;
+};
+
 /**
  * Default resize utility values matching Tailwind CSS.
  */
@@ -1626,6 +1760,151 @@ export declare const useBackgroundSizeUtility: <T extends Record<string, TokenVa
  */
 export declare const useBackgroundUtility: <T extends Record<string, TokenValue> = Record<string, TokenValue>>(s: Styleframe, values?: T | undefined, modifiers?: ModifierFactory[]) => UtilityCreatorFn;
 
+/**
+ * Full badge recipe with color, variant, and size variants.
+ * Includes all Nuxt UI-inspired styling options.
+ */
+export declare const useBadgeRecipe: (s: Styleframe, options?: DeepPartial<    {
+base: {
+display: string;
+alignItems: string;
+fontWeight: string;
+borderWidth: string;
+borderStyle: string;
+borderColor: string;
+};
+variants: {
+color: {
+primary: {};
+secondary: {};
+success: {};
+info: {};
+warning: {};
+danger: {};
+};
+variant: {
+solid: {};
+outline: {};
+soft: {};
+subtle: {};
+};
+size: {
+xs: {
+fontSize: string;
+lineHeight: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+gap: string;
+borderRadius: string;
+};
+sm: {
+fontSize: string;
+lineHeight: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+gap: string;
+borderRadius: string;
+};
+md: {
+fontSize: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+gap: string;
+borderRadius: string;
+};
+lg: {
+fontSize: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+gap: string;
+borderRadius: string;
+};
+xl: {
+fontSize: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+gap: string;
+borderRadius: string;
+};
+};
+};
+compoundVariants: ({
+match: {
+color: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+variant: "solid";
+};
+css: {
+background: string;
+color: string;
+borderColor?: undefined;
+};
+} | {
+match: {
+color: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+variant: "outline";
+};
+css: {
+color: string;
+borderColor: string;
+background?: undefined;
+};
+} | {
+match: {
+color: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+variant: "soft";
+};
+css: {
+background: string;
+color: string;
+borderColor?: undefined;
+};
+} | {
+match: {
+color: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+variant: "subtle";
+};
+css: {
+background: string;
+color: string;
+borderColor: string;
+};
+})[];
+defaultVariants: {
+color: "primary";
+variant: "solid";
+size: "sm";
+};
+}> | undefined) => Recipe<"badge", Record<string, Record<string, VariantDeclarationsBlock>>>;
+
+/**
+ * Base badge styling - core appearance without variants.
+ * Use this when you want to define your own custom variants.
+ */
+export declare const useBadgeRecipeBase: (s: Styleframe, options?: DeepPartial<    {
+base: {
+display: string;
+alignItems: string;
+fontWeight: string;
+fontSize: string;
+lineHeight: string;
+paddingTop: string;
+paddingBottom: string;
+paddingLeft: string;
+paddingRight: string;
+borderRadius: string;
+};
+}> | undefined) => Recipe<"badge", Record<string, Record<string, VariantDeclarationsBlock>>>;
+
 /**
  * Create blur utility classes.
  *
@@ -2766,6 +3045,8 @@ export declare const useFontFamilyUtility: <T extends Record<string, TokenValue>
  */
 export declare const useFontSize: <T extends Record<string, TokenValue> = {
     default: string;
+    "3xs": string;
+    "2xs": string;
     xs: string;
     sm: string;
     md: string;
@@ -2954,23 +3235,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 +3655,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 +3983,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 +4407,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 +4430,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;