@tenphi/tasty 0.14.1 → 0.15.0

package/dist/tasty.js

@@ -43,8 +43,8 @@ function createSubElement(elementName, definition) {
 	const defaultQaVal = config.qaVal;
 	const SubElement = forwardRef((props, ref) => {
 		const { qa, qaVal, mods, tokens, isDisabled, isHidden, isChecked, className, style, ...htmlProps } = props;
-		let modProps;
-		if (mods) modProps = _modAttrs(mods);
+		let modDataAttrs;
+		if (mods) modDataAttrs = _modAttrs(mods);
 		const tokenStyle = tokens ? processTokens(tokens) : void 0;
 		let mergedStyle;
 		if (tokenStyle || style) mergedStyle = tokenStyle && style ? {
@@ -55,7 +55,7 @@ function createSubElement(elementName, definition) {
 			"data-element": elementName,
 			"data-qa": qa ?? defaultQa,
 			"data-qaval": qaVal ?? defaultQaVal,
-			...modProps || {},
+			...modDataAttrs || {},
 			...htmlProps,
 			className,
 			style: mergedStyle,
@@ -103,7 +103,7 @@ function tastyWrap(Component, options) {
 	return _WrappedComponent;
 }
 function tastyElement(tastyOptions) {
-	const { as: originalAs = "div", element: defaultElement, styles: defaultStyles, styleProps, variants, tokens: defaultTokens, elements, ...defaultProps } = tastyOptions;
+	const { as: originalAs = "div", element: defaultElement, styles: defaultStyles, styleProps, modProps: modPropsDef, variants, tokens: defaultTokens, elements, ...defaultProps } = tastyOptions;
 	let variantStylesMap;
 	if (variants) {
 		let baseStyles = defaultStyles;
@@ -128,6 +128,7 @@ function tastyElement(tastyOptions) {
 	}
 	const { qa: defaultQa, qaVal: defaultQaVal, ...otherDefaultProps } = defaultProps ?? {};
 	const propsToCheck = styleProps ? styleProps.concat(BASE_STYLES) : BASE_STYLES;
+	const modPropsKeys = modPropsDef ? Array.isArray(modPropsDef) ? modPropsDef : Object.keys(modPropsDef) : void 0;
 	const _TastyComponent = forwardRef((allProps, ref) => {
 		const { as, styles: rawStyles, variant, mods, element, qa, qaVal, className: userClassName, tokens, style, ...otherProps } = allProps;
 		let styles = rawStyles;
@@ -185,15 +186,27 @@ function tastyElement(tastyOptions) {
 				...style
 			};
 		}, [processedTokenStyle, style]);
-		let modProps;
-		if (mods) modProps = _modAttrs(mods);
+		let propMods;
+		if (modPropsKeys) {
+			for (const key of modPropsKeys) if (key in otherProps) {
+				if (!propMods) propMods = {};
+				propMods[key] = otherProps[key];
+				delete otherProps[key];
+			}
+		}
+		const mergedMods = propMods ? {
+			...mods,
+			...propMods
+		} : mods;
+		let modDataAttrs;
+		if (mergedMods) modDataAttrs = _modAttrs(mergedMods);
 		const finalClassName = [userClassName || "", stylesClassName].filter(Boolean).join(" ");
 		const elementProps = {
 			"data-element": element || defaultElement,
 			"data-qa": qa || defaultQa,
 			"data-qaval": qaVal || defaultQaVal,
 			...otherDefaultProps,
-			...modProps || {},
+			...modDataAttrs || {},
 			...otherProps,
 			className: finalClassName,
 			style: mergedStyle,

package/dist/tasty.js.map

@@ -1 +1 @@
-{"version":3,"file":"tasty.js","names":["modAttrs"],"sources":["../src/tasty.tsx"],"sourcesContent":["import type {\n  AllHTMLAttributes,\n  ComponentType,\n  ForwardRefExoticComponent,\n  JSX,\n  PropsWithoutRef,\n  RefAttributes,\n} from 'react';\nimport { createElement, forwardRef, useMemo, useRef } from 'react';\nimport { useStyles } from './hooks/useStyles';\nimport { BASE_STYLES } from './styles/list';\nimport type { Styles, StylesInterface } from './styles/types';\nimport type {\n  AllBaseProps,\n  BaseProps,\n  BaseStyleProps,\n  Mods,\n  Props,\n  Tokens,\n} from './types';\nimport { getDisplayName } from './utils/get-display-name';\nimport { isValidElementType } from './utils/is-valid-element-type';\nimport { mergeStyles } from './utils/merge-styles';\nimport { isSelector } from './pipeline';\nimport { hasKeys } from './utils/has-keys';\nimport { modAttrs } from './utils/mod-attrs';\nimport { processTokens, stringifyTokens } from './utils/process-tokens';\n\nimport type { StyleValue, StyleValueStateMap } from './utils/styles';\n\n/**\n * Mapping of is* properties to their corresponding HTML attributes\n */\nconst IS_PROPERTIES_MAP = {\n  isDisabled: 'disabled',\n  isHidden: 'hidden',\n  isChecked: 'checked',\n} as const;\n\n/**\n * Precalculated entries for performance optimization\n */\nconst IS_PROPERTIES_ENTRIES = Object.entries(IS_PROPERTIES_MAP);\n\n/**\n * Helper function to handle is* properties consistently\n * Transforms is* props to HTML attributes and adds corresponding data-* attributes\n */\nfunction handleIsProperties(props: Record<string, unknown>) {\n  for (const [isProperty, targetAttribute] of IS_PROPERTIES_ENTRIES) {\n    if (isProperty in props) {\n      props[targetAttribute] = props[isProperty];\n      delete props[isProperty];\n    }\n\n    // Add data-* attribute if target attribute is truthy and doesn't already exist\n    const dataAttribute = `data-${targetAttribute}`;\n    if (!(dataAttribute in props) && props[targetAttribute]) {\n      props[dataAttribute] = '';\n    }\n  }\n}\n\n/**\n * Creates a sub-element component for compound component patterns.\n * Sub-elements are lightweight components with data-element attribute for CSS targeting.\n */\nfunction createSubElement<Tag extends keyof JSX.IntrinsicElements>(\n  elementName: string,\n  definition: SubElementDefinition<Tag>,\n): ForwardRefExoticComponent<\n  PropsWithoutRef<SubElementProps<Tag>> & RefAttributes<unknown>\n> {\n  // Normalize definition to object form\n  const config =\n    typeof definition === 'string'\n      ? { as: definition as Tag }\n      : (definition as { as?: Tag; qa?: string; qaVal?: string | number });\n\n  const tag = config.as ?? ('div' as Tag);\n  const defaultQa = config.qa;\n  const defaultQaVal = config.qaVal;\n\n  const SubElement = forwardRef<unknown, SubElementProps<Tag>>((props, ref) => {\n    const {\n      qa,\n      qaVal,\n      mods,\n      tokens,\n      isDisabled,\n      isHidden,\n      isChecked,\n      className,\n      style,\n      ...htmlProps\n    } = props as SubElementProps<Tag> & {\n      className?: string;\n      style?: Record<string, unknown>;\n    };\n\n    // Build mod attributes\n    let modProps: Record<string, unknown> | undefined;\n    if (mods) {\n      modProps = modAttrs(mods as Mods) as Record<string, unknown>;\n    }\n\n    // Process tokens into inline style properties\n    const tokenStyle = tokens\n      ? (processTokens(tokens) as Record<string, unknown>)\n      : undefined;\n\n    // Merge token styles with explicit style prop (style has priority)\n    let mergedStyle: Record<string, unknown> | undefined;\n    if (tokenStyle || style) {\n      mergedStyle =\n        tokenStyle && style\n          ? { ...tokenStyle, ...style }\n          : ((tokenStyle ?? style) as Record<string, unknown>);\n    }\n\n    const elementProps = {\n      'data-element': elementName,\n      'data-qa': qa ?? defaultQa,\n      'data-qaval': qaVal ?? defaultQaVal,\n      ...(modProps || {}),\n      ...htmlProps,\n      className,\n      style: mergedStyle,\n      isDisabled,\n      isHidden,\n      isChecked,\n      ref,\n    } as Record<string, unknown>;\n\n    // Handle is* properties (isDisabled -> disabled + data-disabled, etc.)\n    handleIsProperties(elementProps);\n\n    // Clean up undefined data attributes\n    if (elementProps['data-qa'] === undefined) delete elementProps['data-qa'];\n    if (elementProps['data-qaval'] === undefined)\n      delete elementProps['data-qaval'];\n\n    return createElement(tag, elementProps);\n  });\n\n  SubElement.displayName = `SubElement(${elementName})`;\n\n  return SubElement as ForwardRefExoticComponent<\n    PropsWithoutRef<SubElementProps<Tag>> & RefAttributes<unknown>\n  >;\n}\n\ntype StyleList = readonly (keyof {\n  [key in keyof StylesInterface]: StylesInterface[key];\n})[];\n\nexport type PropsWithStyles = {\n  styles?: Styles;\n} & Omit<Props, 'styles'>;\n\nexport type VariantMap = Record<string, Styles>;\n\nexport interface WithVariant<V extends VariantMap> {\n  variant?: keyof V;\n}\n\n// ============================================================================\n// Sub-element types for compound components\n// ============================================================================\n\n/**\n * Definition for a sub-element. Can be either:\n * - A tag name string (e.g., 'div', 'span')\n * - An object with configuration options\n */\nexport type SubElementDefinition<\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n> =\n  | Tag\n  | {\n      as?: Tag;\n      qa?: string;\n      qaVal?: string | number;\n    };\n\n/**\n * Map of sub-element definitions.\n * Keys become the sub-component names (e.g., { Icon: 'span' } -> Component.Icon)\n */\nexport type ElementsDefinition = Record<\n  string,\n  SubElementDefinition<keyof JSX.IntrinsicElements>\n>;\n\n/**\n * Resolves the tag from a SubElementDefinition\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype ResolveElementTag<T extends SubElementDefinition<any>> = T extends string\n  ? T\n  : T extends { as?: infer Tag }\n    ? Tag extends keyof JSX.IntrinsicElements\n      ? Tag\n      : 'div'\n    : 'div';\n\n/**\n * Props for sub-element components.\n * Combines HTML attributes with tasty-specific props (qa, qaVal, mods, tokens, isDisabled, etc.)\n */\nexport type SubElementProps<Tag extends keyof JSX.IntrinsicElements = 'div'> =\n  Omit<\n    JSX.IntrinsicElements[Tag],\n    'ref' | 'color' | 'content' | 'translate'\n  > & {\n    qa?: string;\n    qaVal?: string | number;\n    mods?: Mods;\n    tokens?: Tokens;\n    isDisabled?: boolean;\n    isHidden?: boolean;\n    isChecked?: boolean;\n  };\n\n/**\n * Generates the sub-element component types from an ElementsDefinition\n */\ntype SubElementComponents<E extends ElementsDefinition> = {\n  [K in keyof E]: ForwardRefExoticComponent<\n    PropsWithoutRef<SubElementProps<ResolveElementTag<E[K]>>> &\n      RefAttributes<\n        ResolveElementTag<E[K]> extends keyof HTMLElementTagNameMap\n          ? HTMLElementTagNameMap[ResolveElementTag<E[K]>]\n          : Element\n      >\n  >;\n};\n\n/**\n * Base type containing common properties shared between TastyProps and TastyElementOptions.\n * Separated to avoid code duplication while allowing different type constraints.\n */\ntype TastyBaseProps<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n> = {\n  /** Default styles of the element. */\n  styles?: Styles;\n  /** The list of styles that can be provided by props */\n  styleProps?: K;\n  element?: BaseProps['element'];\n  variants?: V;\n  /** Default tokens for inline CSS custom properties */\n  tokens?: Tokens;\n  /** Sub-element definitions for compound components */\n  elements?: E;\n} & Pick<BaseProps, 'qa' | 'qaVal'> &\n  WithVariant<V>;\n\nexport type TastyProps<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  DefaultProps = Props,\n> = TastyBaseProps<K, V, E> & {\n  /** The tag name of the element or a React component. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  as?: string | ComponentType<any>;\n} & Partial<Omit<DefaultProps, 'as' | 'styles' | 'styleProps' | 'tokens'>>;\n\n/**\n * TastyElementOptions is used for the element-creation overload of tasty().\n * It includes a Tag generic that allows TypeScript to infer the correct\n * HTML element type from the `as` prop.\n *\n * Note: Uses a separate index signature with `unknown` instead of inheriting\n * from Props (which has `any`) to ensure strict type checking for styles.\n */\nexport type TastyElementOptions<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n> = TastyBaseProps<K, V, E> & {\n  /** The tag name of the element or a React component. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  as?: Tag | ComponentType<any>;\n} & Record<string, unknown>;\n\nexport type AllBasePropsWithMods<K extends StyleList> = AllBaseProps & {\n  [key in K[number]]?:\n    | StyleValue<StylesInterface[key]>\n    | StyleValueStateMap<StylesInterface[key]>;\n} & BaseStyleProps;\n\n/**\n * Keys from BasePropsWithoutChildren that should be omitted from HTML attributes.\n * This excludes event handlers so they can be properly typed from JSX.IntrinsicElements.\n */\ntype TastySpecificKeys =\n  | 'as'\n  | 'qa'\n  | 'qaVal'\n  | 'element'\n  | 'styles'\n  | 'breakpoints'\n  | 'block'\n  | 'inline'\n  | 'mods'\n  | 'isHidden'\n  | 'isDisabled'\n  | 'css'\n  | 'style'\n  | 'theme'\n  | 'tokens'\n  | 'ref'\n  | 'color';\n\n/**\n * Props type for tasty elements that combines:\n * - AllBasePropsWithMods for style props with strict tokens type\n * - HTML attributes for flexibility (properly typed based on tag)\n * - Variant support\n *\n * Uses AllHTMLAttributes as base for common attributes (like disabled),\n * but overrides event handlers with tag-specific types from JSX.IntrinsicElements.\n */\nexport type TastyElementProps<\n  K extends StyleList,\n  V extends VariantMap,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n> = AllBasePropsWithMods<K> &\n  WithVariant<V> &\n  Omit<\n    Omit<AllHTMLAttributes<HTMLElement>, keyof JSX.IntrinsicElements[Tag]> &\n      JSX.IntrinsicElements[Tag],\n    TastySpecificKeys | K[number]\n  >;\n\ntype TastyComponentPropsWithDefaults<\n  Props extends PropsWithStyles,\n  DefaultProps extends Partial<Props>,\n> = keyof DefaultProps extends never\n  ? Props\n  : {\n      [key in Extract<keyof Props, keyof DefaultProps>]?: Props[key];\n    } & {\n      [key in keyof Omit<Props, keyof DefaultProps>]: Props[key];\n    };\n\nexport function tasty<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n>(\n  options: TastyElementOptions<K, V, E, Tag>,\n  secondArg?: never,\n): ForwardRefExoticComponent<\n  PropsWithoutRef<TastyElementProps<K, V, Tag>> & RefAttributes<unknown>\n> &\n  SubElementComponents<E>;\nexport function tasty<\n  Props extends PropsWithStyles,\n  DefaultProps extends Partial<Props> = Partial<Props>,\n>(\n  Component: ComponentType<Props>,\n  options?: TastyProps<never, never, Record<string, never>, Props>,\n): ComponentType<TastyComponentPropsWithDefaults<Props, DefaultProps>>;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n// Implementation\nexport function tasty<\n  K extends StyleList,\n  V extends VariantMap,\n  _C = Record<string, unknown>,\n>(Component: any, options?: any) {\n  if (isValidElementType(Component)) {\n    return tastyWrap(Component as ComponentType<any>, options);\n  }\n\n  return tastyElement(Component as TastyProps<K, V>);\n}\n\nfunction tastyWrap<\n  P extends PropsWithStyles,\n  DefaultProps extends Partial<P> = Partial<P>,\n>(\n  Component: ComponentType<P>,\n  options?: TastyProps<never, never, P>,\n): ComponentType<TastyComponentPropsWithDefaults<P, DefaultProps>> {\n  const {\n    as: extendTag,\n    element: extendElement,\n    ...defaultProps\n  } = (options ?? {}) as TastyProps<never, never, P>;\n\n  const propsWithStyles = ['styles'].concat(\n    Object.keys(defaultProps).filter((prop) => prop.endsWith('Styles')),\n  );\n\n  const _WrappedComponent = forwardRef<any, any>((props, ref) => {\n    const { as, element, ...restProps } = props as Record<string, unknown>;\n    const propsWithStylesValues = propsWithStyles.map(\n      (prop) => (props as any)[prop],\n    );\n\n    const mergedStylesMap: Styles | undefined = useMemo(() => {\n      return propsWithStyles.reduce((map, prop) => {\n        const restValue = (restProps as any)[prop];\n        const defaultValue = (defaultProps as any)[prop];\n\n        if (restValue != null && defaultValue != null) {\n          (map as any)[prop] = mergeStyles(defaultValue, restValue);\n        } else {\n          (map as any)[prop] = restValue ?? defaultValue;\n        }\n\n        return map;\n      }, {} as Styles);\n    }, [propsWithStylesValues]);\n\n    const elementProps = {\n      ...(defaultProps as unknown as Record<string, unknown>),\n      ...(restProps as unknown as Record<string, unknown>),\n      ...(mergedStylesMap as unknown as Record<string, unknown>),\n      as: (as as string | undefined) ?? extendTag,\n      element: (element as string | undefined) || extendElement,\n      ref,\n    } as unknown as P;\n\n    return createElement(Component as ComponentType<P>, elementProps);\n  });\n\n  _WrappedComponent.displayName = `TastyWrappedComponent(${getDisplayName(\n    Component,\n    (defaultProps as any).qa ?? (extendTag as any) ?? 'Anonymous',\n  )})`;\n\n  return _WrappedComponent as unknown as ComponentType<\n    TastyComponentPropsWithDefaults<P, DefaultProps>\n  >;\n}\n\nfunction tastyElement<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition,\n>(tastyOptions: TastyProps<K, V, E>) {\n  const {\n    as: originalAs = 'div',\n    element: defaultElement,\n    styles: defaultStyles,\n    styleProps,\n    variants,\n    tokens: defaultTokens,\n    elements,\n    ...defaultProps\n  } = tastyOptions;\n\n  // Pre-compute merged styles for each variant (if variants are defined)\n  // This avoids creating separate component instances per variant\n  let variantStylesMap: Record<string, Styles | undefined> | undefined;\n  if (variants) {\n    // Split defaultStyles: extend-mode state maps (no '' key, non-selector)\n    // are pulled out and applied AFTER variant merge so they survive\n    // replace-mode maps in variants.\n    let baseStyles = defaultStyles;\n    let extensionStyles: Styles | undefined;\n\n    if (defaultStyles) {\n      for (const key of Object.keys(defaultStyles)) {\n        if (isSelector(key)) continue;\n\n        const value = (defaultStyles as Record<string, unknown>)[key];\n\n        if (\n          typeof value === 'object' &&\n          value !== null &&\n          !Array.isArray(value) &&\n          !('' in value)\n        ) {\n          if (!extensionStyles) {\n            baseStyles = { ...defaultStyles } as Styles;\n            extensionStyles = {} as Styles;\n          }\n          (extensionStyles as Record<string, unknown>)[key] = value;\n          delete (baseStyles as Record<string, unknown>)[key];\n        }\n      }\n    }\n\n    const variantEntries = Object.entries(variants) as [string, Styles][];\n    variantStylesMap = variantEntries.reduce(\n      (map, [variant, variantStyles]) => {\n        map[variant] = extensionStyles\n          ? mergeStyles(baseStyles, variantStyles, extensionStyles)\n          : mergeStyles(baseStyles, variantStyles);\n        return map;\n      },\n      {} as Record<string, Styles | undefined>,\n    );\n    // Ensure 'default' variant always exists\n    if (!variantStylesMap['default']) {\n      variantStylesMap['default'] = defaultStyles;\n    }\n  }\n\n  const {\n    qa: defaultQa,\n    qaVal: defaultQaVal,\n    ...otherDefaultProps\n  } = defaultProps ?? {};\n\n  const propsToCheck = styleProps\n    ? (styleProps as StyleList).concat(BASE_STYLES)\n    : BASE_STYLES;\n\n  const _TastyComponent = forwardRef<\n    unknown,\n    AllBasePropsWithMods<K> & WithVariant<V>\n  >((allProps, ref) => {\n    const {\n      as,\n      styles: rawStyles,\n      variant,\n      mods,\n      element,\n      qa,\n      qaVal,\n      className: userClassName,\n      tokens,\n      style,\n      ...otherProps\n    } = allProps as Record<string, unknown> as AllBasePropsWithMods<K> &\n      WithVariant<V> & {\n        className?: string;\n        tokens?: Tokens;\n        style?: Record<string, unknown>;\n      };\n\n    let styles = rawStyles;\n\n    let propStyles: Styles | null = null;\n    let propStylesKey = '';\n\n    for (const prop of propsToCheck) {\n      const key = prop as unknown as string;\n\n      if (key in otherProps) {\n        if (!propStyles) propStyles = {};\n        const value = (otherProps as any)[key];\n        (propStyles as any)[key] = value;\n        delete (otherProps as any)[key];\n        propStylesKey += key + '\\0' + value + '\\0';\n      }\n    }\n\n    if (!styles || (styles && !hasKeys(styles as Record<string, unknown>))) {\n      styles = undefined as unknown as Styles;\n    }\n\n    // Stabilize propStyles reference: only update when content actually changes\n    const propStylesRef = useRef<{ key: string; styles: Styles | null }>({\n      key: '',\n      styles: null,\n    });\n    if (propStylesRef.current.key !== propStylesKey) {\n      propStylesRef.current = { key: propStylesKey, styles: propStyles };\n    }\n\n    // Determine base styles: use variant styles if available, otherwise default styles\n    const baseStyles = variantStylesMap\n      ? (variantStylesMap[(variant as string) || 'default'] ??\n        variantStylesMap['default'])\n      : defaultStyles;\n\n    // Merge base styles with instance styles and prop styles\n    const allStyles = useMemo(() => {\n      const currentPropStyles = propStylesRef.current.styles;\n      const hasStyleProps =\n        styles && hasKeys(styles as Record<string, unknown>);\n      const hasPropStyles = currentPropStyles && hasKeys(currentPropStyles);\n\n      if (!hasStyleProps && !hasPropStyles) {\n        return baseStyles;\n      }\n\n      return mergeStyles(\n        baseStyles,\n        styles as Styles,\n        currentPropStyles as Styles,\n      );\n    }, [baseStyles, styles, propStylesKey]);\n\n    // Use the useStyles hook for style generation and injection\n    const { className: stylesClassName } = useStyles(allStyles);\n\n    // Merge default tokens with instance tokens (instance overrides defaults)\n    const tokensKey = stringifyTokens(tokens as Tokens | undefined);\n    const mergedTokens = useMemo(() => {\n      if (!defaultTokens && !tokens) return undefined;\n      if (!defaultTokens) return tokens as Tokens;\n      if (!tokens) return defaultTokens;\n      return { ...defaultTokens, ...tokens } as Tokens;\n    }, [tokensKey]);\n\n    // Process merged tokens into inline style properties\n    const processedTokenStyle = useMemo(() => {\n      return processTokens(mergedTokens);\n    }, [mergedTokens]);\n\n    // Merge processed tokens with explicit style prop (style has priority)\n    const mergedStyle = useMemo(() => {\n      if (!processedTokenStyle && !style) return undefined;\n      if (!processedTokenStyle) return style;\n      if (!style) return processedTokenStyle;\n      return { ...processedTokenStyle, ...style };\n    }, [processedTokenStyle, style]);\n\n    let modProps: Record<string, unknown> | undefined;\n    if (mods) {\n      const modsObject = mods as unknown as Record<string, unknown>;\n      modProps = modAttrs(modsObject as any) as Record<string, unknown>;\n    }\n\n    // Merge user className with generated className\n    const finalClassName = [(userClassName as string) || '', stylesClassName]\n      .filter(Boolean)\n      .join(' ');\n\n    const elementProps = {\n      'data-element': (element as string | undefined) || defaultElement,\n      'data-qa': (qa as string | undefined) || defaultQa,\n      'data-qaval': (qaVal as string | undefined) || defaultQaVal,\n      ...(otherDefaultProps as unknown as Record<string, unknown>),\n      ...(modProps || {}),\n      ...(otherProps as unknown as Record<string, unknown>),\n      className: finalClassName,\n      style: mergedStyle,\n      ref,\n    } as Record<string, unknown>;\n\n    // Apply the helper to handle is* properties\n    handleIsProperties(elementProps);\n\n    const renderedElement = createElement(\n      (as as string | 'div') ?? originalAs,\n      elementProps,\n    );\n\n    return renderedElement;\n  });\n\n  _TastyComponent.displayName = `TastyComponent(${\n    (defaultProps as any).qa || originalAs\n  })`;\n\n  // Attach sub-element components if elements are defined\n  if (elements) {\n    const subElements = Object.entries(elements).reduce(\n      (acc, [name, definition]) => {\n        acc[name] = createSubElement(\n          name,\n          definition as SubElementDefinition<keyof JSX.IntrinsicElements>,\n        );\n        return acc;\n      },\n      {} as Record<string, ForwardRefExoticComponent<any>>,\n    );\n\n    return Object.assign(_TastyComponent, subElements);\n  }\n\n  return _TastyComponent;\n}\n\nexport const Element = tasty({});\n"],"mappings":"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"}
+{"version":3,"file":"tasty.js","names":["modAttrs"],"sources":["../src/tasty.tsx"],"sourcesContent":["import type {\n  AllHTMLAttributes,\n  ComponentType,\n  ForwardRefExoticComponent,\n  JSX,\n  PropsWithoutRef,\n  RefAttributes,\n} from 'react';\nimport { createElement, forwardRef, useMemo, useRef } from 'react';\nimport { useStyles } from './hooks/useStyles';\nimport { BASE_STYLES } from './styles/list';\nimport type { Styles, StylesInterface } from './styles/types';\nimport type {\n  AllBaseProps,\n  BaseProps,\n  BaseStyleProps,\n  ModValue,\n  Mods,\n  Props,\n  Tokens,\n} from './types';\nimport { getDisplayName } from './utils/get-display-name';\nimport { isValidElementType } from './utils/is-valid-element-type';\nimport { mergeStyles } from './utils/merge-styles';\nimport { isSelector } from './pipeline';\nimport { hasKeys } from './utils/has-keys';\nimport { modAttrs } from './utils/mod-attrs';\nimport { processTokens, stringifyTokens } from './utils/process-tokens';\n\nimport type { StyleValue, StyleValueStateMap } from './utils/styles';\n\n/**\n * Mapping of is* properties to their corresponding HTML attributes\n */\nconst IS_PROPERTIES_MAP = {\n  isDisabled: 'disabled',\n  isHidden: 'hidden',\n  isChecked: 'checked',\n} as const;\n\n/**\n * Precalculated entries for performance optimization\n */\nconst IS_PROPERTIES_ENTRIES = Object.entries(IS_PROPERTIES_MAP);\n\n/**\n * Helper function to handle is* properties consistently\n * Transforms is* props to HTML attributes and adds corresponding data-* attributes\n */\nfunction handleIsProperties(props: Record<string, unknown>) {\n  for (const [isProperty, targetAttribute] of IS_PROPERTIES_ENTRIES) {\n    if (isProperty in props) {\n      props[targetAttribute] = props[isProperty];\n      delete props[isProperty];\n    }\n\n    // Add data-* attribute if target attribute is truthy and doesn't already exist\n    const dataAttribute = `data-${targetAttribute}`;\n    if (!(dataAttribute in props) && props[targetAttribute]) {\n      props[dataAttribute] = '';\n    }\n  }\n}\n\n/**\n * Creates a sub-element component for compound component patterns.\n * Sub-elements are lightweight components with data-element attribute for CSS targeting.\n */\nfunction createSubElement<Tag extends keyof JSX.IntrinsicElements>(\n  elementName: string,\n  definition: SubElementDefinition<Tag>,\n): ForwardRefExoticComponent<\n  PropsWithoutRef<SubElementProps<Tag>> & RefAttributes<unknown>\n> {\n  // Normalize definition to object form\n  const config =\n    typeof definition === 'string'\n      ? { as: definition as Tag }\n      : (definition as { as?: Tag; qa?: string; qaVal?: string | number });\n\n  const tag = config.as ?? ('div' as Tag);\n  const defaultQa = config.qa;\n  const defaultQaVal = config.qaVal;\n\n  const SubElement = forwardRef<unknown, SubElementProps<Tag>>((props, ref) => {\n    const {\n      qa,\n      qaVal,\n      mods,\n      tokens,\n      isDisabled,\n      isHidden,\n      isChecked,\n      className,\n      style,\n      ...htmlProps\n    } = props as SubElementProps<Tag> & {\n      className?: string;\n      style?: Record<string, unknown>;\n    };\n\n    // Build mod attributes\n    let modDataAttrs: Record<string, unknown> | undefined;\n    if (mods) {\n      modDataAttrs = modAttrs(mods as Mods) as Record<string, unknown>;\n    }\n\n    // Process tokens into inline style properties\n    const tokenStyle = tokens\n      ? (processTokens(tokens) as Record<string, unknown>)\n      : undefined;\n\n    // Merge token styles with explicit style prop (style has priority)\n    let mergedStyle: Record<string, unknown> | undefined;\n    if (tokenStyle || style) {\n      mergedStyle =\n        tokenStyle && style\n          ? { ...tokenStyle, ...style }\n          : ((tokenStyle ?? style) as Record<string, unknown>);\n    }\n\n    const elementProps = {\n      'data-element': elementName,\n      'data-qa': qa ?? defaultQa,\n      'data-qaval': qaVal ?? defaultQaVal,\n      ...(modDataAttrs || {}),\n      ...htmlProps,\n      className,\n      style: mergedStyle,\n      isDisabled,\n      isHidden,\n      isChecked,\n      ref,\n    } as Record<string, unknown>;\n\n    // Handle is* properties (isDisabled -> disabled + data-disabled, etc.)\n    handleIsProperties(elementProps);\n\n    // Clean up undefined data attributes\n    if (elementProps['data-qa'] === undefined) delete elementProps['data-qa'];\n    if (elementProps['data-qaval'] === undefined)\n      delete elementProps['data-qaval'];\n\n    return createElement(tag, elementProps);\n  });\n\n  SubElement.displayName = `SubElement(${elementName})`;\n\n  return SubElement as ForwardRefExoticComponent<\n    PropsWithoutRef<SubElementProps<Tag>> & RefAttributes<unknown>\n  >;\n}\n\ntype StyleList = readonly (keyof {\n  [key in keyof StylesInterface]: StylesInterface[key];\n})[];\n\n// ============================================================================\n// Mod props types — expose modifier keys as top-level component props\n// ============================================================================\n\n/** Type descriptor for a single mod prop: a JS constructor or an enum array. */\nexport type ModPropDef =\n  | BooleanConstructor\n  | StringConstructor\n  | NumberConstructor\n  | readonly string[];\n\n/** Array form: list of mod key names (types default to ModValue). */\ntype ModPropsList = readonly string[];\n\n/** Object form: map of mod key names to type descriptors. */\ntype ModPropsMap = Readonly<Record<string, ModPropDef>>;\n\n/** Either array or object form accepted by `modProps` option. */\nexport type ModPropsInput = ModPropsList | ModPropsMap;\n\n/** Resolve a single ModPropDef to its TypeScript type. */\nexport type ResolveModPropDef<T> = T extends BooleanConstructor\n  ? boolean\n  : T extends StringConstructor\n    ? string\n    : T extends NumberConstructor\n      ? number\n      : T extends readonly (infer U)[]\n        ? U\n        : ModValue;\n\n/** Resolve an entire `modProps` definition to the component prop types it adds. */\nexport type ResolveModProps<M extends ModPropsInput> =\n  M extends readonly (infer K)[]\n    ? Partial<Record<K & string, ModValue>>\n    : M extends Record<string, ModPropDef>\n      ? { [key in keyof M & string]?: ResolveModPropDef<M[key]> }\n      : // eslint-disable-next-line @typescript-eslint/no-empty-object-type\n        {};\n\nexport type PropsWithStyles = {\n  styles?: Styles;\n} & Omit<Props, 'styles'>;\n\nexport type VariantMap = Record<string, Styles>;\n\nexport interface WithVariant<V extends VariantMap> {\n  variant?: keyof V;\n}\n\n// ============================================================================\n// Sub-element types for compound components\n// ============================================================================\n\n/**\n * Definition for a sub-element. Can be either:\n * - A tag name string (e.g., 'div', 'span')\n * - An object with configuration options\n */\nexport type SubElementDefinition<\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n> =\n  | Tag\n  | {\n      as?: Tag;\n      qa?: string;\n      qaVal?: string | number;\n    };\n\n/**\n * Map of sub-element definitions.\n * Keys become the sub-component names (e.g., { Icon: 'span' } -> Component.Icon)\n */\nexport type ElementsDefinition = Record<\n  string,\n  SubElementDefinition<keyof JSX.IntrinsicElements>\n>;\n\n/**\n * Resolves the tag from a SubElementDefinition\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype ResolveElementTag<T extends SubElementDefinition<any>> = T extends string\n  ? T\n  : T extends { as?: infer Tag }\n    ? Tag extends keyof JSX.IntrinsicElements\n      ? Tag\n      : 'div'\n    : 'div';\n\n/**\n * Props for sub-element components.\n * Combines HTML attributes with tasty-specific props (qa, qaVal, mods, tokens, isDisabled, etc.)\n */\nexport type SubElementProps<Tag extends keyof JSX.IntrinsicElements = 'div'> =\n  Omit<\n    JSX.IntrinsicElements[Tag],\n    'ref' | 'color' | 'content' | 'translate'\n  > & {\n    qa?: string;\n    qaVal?: string | number;\n    mods?: Mods;\n    tokens?: Tokens;\n    isDisabled?: boolean;\n    isHidden?: boolean;\n    isChecked?: boolean;\n  };\n\n/**\n * Generates the sub-element component types from an ElementsDefinition\n */\ntype SubElementComponents<E extends ElementsDefinition> = {\n  [K in keyof E]: ForwardRefExoticComponent<\n    PropsWithoutRef<SubElementProps<ResolveElementTag<E[K]>>> &\n      RefAttributes<\n        ResolveElementTag<E[K]> extends keyof HTMLElementTagNameMap\n          ? HTMLElementTagNameMap[ResolveElementTag<E[K]>]\n          : Element\n      >\n  >;\n};\n\n/**\n * Base type containing common properties shared between TastyProps and TastyElementOptions.\n * Separated to avoid code duplication while allowing different type constraints.\n */\ntype TastyBaseProps<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  M extends ModPropsInput = readonly string[],\n> = {\n  /** Default styles of the element. */\n  styles?: Styles;\n  /** The list of styles that can be provided by props */\n  styleProps?: K;\n  /** Modifier keys exposed as top-level component props (array or typed object form). */\n  modProps?: M;\n  element?: BaseProps['element'];\n  variants?: V;\n  /** Default tokens for inline CSS custom properties */\n  tokens?: Tokens;\n  /** Sub-element definitions for compound components */\n  elements?: E;\n} & Pick<BaseProps, 'qa' | 'qaVal'> &\n  WithVariant<V>;\n\nexport type TastyProps<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  DefaultProps = Props,\n  M extends ModPropsInput = readonly string[],\n> = TastyBaseProps<K, V, E, M> & {\n  /** The tag name of the element or a React component. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  as?: string | ComponentType<any>;\n} & Partial<\n    Omit<DefaultProps, 'as' | 'styles' | 'styleProps' | 'modProps' | 'tokens'>\n  >;\n\n/**\n * TastyElementOptions is used for the element-creation overload of tasty().\n * It includes a Tag generic that allows TypeScript to infer the correct\n * HTML element type from the `as` prop.\n *\n * Note: Uses a separate index signature with `unknown` instead of inheriting\n * from Props (which has `any`) to ensure strict type checking for styles.\n */\nexport type TastyElementOptions<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n  M extends ModPropsInput = readonly string[],\n> = TastyBaseProps<K, V, E, M> & {\n  /** The tag name of the element or a React component. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  as?: Tag | ComponentType<any>;\n} & Record<string, unknown>;\n\nexport type AllBasePropsWithMods<\n  K extends StyleList,\n  M extends ModPropsInput = readonly string[],\n> = AllBaseProps & {\n  [key in K[number]]?:\n    | StyleValue<StylesInterface[key]>\n    | StyleValueStateMap<StylesInterface[key]>;\n} & BaseStyleProps &\n  ResolveModProps<M>;\n\n/**\n * Keys from BasePropsWithoutChildren that should be omitted from HTML attributes.\n * This excludes event handlers so they can be properly typed from JSX.IntrinsicElements.\n */\ntype TastySpecificKeys =\n  | 'as'\n  | 'qa'\n  | 'qaVal'\n  | 'element'\n  | 'styles'\n  | 'breakpoints'\n  | 'block'\n  | 'inline'\n  | 'mods'\n  | 'isHidden'\n  | 'isDisabled'\n  | 'css'\n  | 'style'\n  | 'theme'\n  | 'tokens'\n  | 'ref'\n  | 'color';\n\n/**\n * Props type for tasty elements that combines:\n * - AllBasePropsWithMods for style props with strict tokens type\n * - HTML attributes for flexibility (properly typed based on tag)\n * - Variant support\n *\n * Uses AllHTMLAttributes as base for common attributes (like disabled),\n * but overrides event handlers with tag-specific types from JSX.IntrinsicElements.\n */\nexport type TastyElementProps<\n  K extends StyleList,\n  V extends VariantMap,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n  M extends ModPropsInput = readonly string[],\n> = AllBasePropsWithMods<K, M> &\n  WithVariant<V> &\n  Omit<\n    Omit<AllHTMLAttributes<HTMLElement>, keyof JSX.IntrinsicElements[Tag]> &\n      JSX.IntrinsicElements[Tag],\n    TastySpecificKeys | K[number]\n  >;\n\ntype TastyComponentPropsWithDefaults<\n  Props extends PropsWithStyles,\n  DefaultProps extends Partial<Props>,\n> = keyof DefaultProps extends never\n  ? Props\n  : {\n      [key in Extract<keyof Props, keyof DefaultProps>]?: Props[key];\n    } & {\n      [key in keyof Omit<Props, keyof DefaultProps>]: Props[key];\n    };\n\nexport function tasty<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition = Record<string, never>,\n  Tag extends keyof JSX.IntrinsicElements = 'div',\n  M extends ModPropsInput = readonly string[],\n>(\n  options: TastyElementOptions<K, V, E, Tag, M>,\n  secondArg?: never,\n): ForwardRefExoticComponent<\n  PropsWithoutRef<TastyElementProps<K, V, Tag, M>> & RefAttributes<unknown>\n> &\n  SubElementComponents<E>;\nexport function tasty<\n  Props extends PropsWithStyles,\n  DefaultProps extends Partial<Props> = Partial<Props>,\n>(\n  Component: ComponentType<Props>,\n  options?: TastyProps<never, never, Record<string, never>, Props>,\n): ComponentType<TastyComponentPropsWithDefaults<Props, DefaultProps>>;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n// Implementation\nexport function tasty<\n  K extends StyleList,\n  V extends VariantMap,\n  _C = Record<string, unknown>,\n>(Component: any, options?: any) {\n  if (isValidElementType(Component)) {\n    return tastyWrap(Component as ComponentType<any>, options);\n  }\n\n  return tastyElement(Component as TastyProps<K, V>);\n}\n\nfunction tastyWrap<\n  P extends PropsWithStyles,\n  DefaultProps extends Partial<P> = Partial<P>,\n>(\n  Component: ComponentType<P>,\n  options?: TastyProps<never, never, P>,\n): ComponentType<TastyComponentPropsWithDefaults<P, DefaultProps>> {\n  const {\n    as: extendTag,\n    element: extendElement,\n    ...defaultProps\n  } = (options ?? {}) as TastyProps<never, never, P>;\n\n  const propsWithStyles = ['styles'].concat(\n    Object.keys(defaultProps).filter((prop) => prop.endsWith('Styles')),\n  );\n\n  const _WrappedComponent = forwardRef<any, any>((props, ref) => {\n    const { as, element, ...restProps } = props as Record<string, unknown>;\n    const propsWithStylesValues = propsWithStyles.map(\n      (prop) => (props as any)[prop],\n    );\n\n    const mergedStylesMap: Styles | undefined = useMemo(() => {\n      return propsWithStyles.reduce((map, prop) => {\n        const restValue = (restProps as any)[prop];\n        const defaultValue = (defaultProps as any)[prop];\n\n        if (restValue != null && defaultValue != null) {\n          (map as any)[prop] = mergeStyles(defaultValue, restValue);\n        } else {\n          (map as any)[prop] = restValue ?? defaultValue;\n        }\n\n        return map;\n      }, {} as Styles);\n    }, [propsWithStylesValues]);\n\n    const elementProps = {\n      ...(defaultProps as unknown as Record<string, unknown>),\n      ...(restProps as unknown as Record<string, unknown>),\n      ...(mergedStylesMap as unknown as Record<string, unknown>),\n      as: (as as string | undefined) ?? extendTag,\n      element: (element as string | undefined) || extendElement,\n      ref,\n    } as unknown as P;\n\n    return createElement(Component as ComponentType<P>, elementProps);\n  });\n\n  _WrappedComponent.displayName = `TastyWrappedComponent(${getDisplayName(\n    Component,\n    (defaultProps as any).qa ?? (extendTag as any) ?? 'Anonymous',\n  )})`;\n\n  return _WrappedComponent as unknown as ComponentType<\n    TastyComponentPropsWithDefaults<P, DefaultProps>\n  >;\n}\n\nfunction tastyElement<\n  K extends StyleList,\n  V extends VariantMap,\n  E extends ElementsDefinition,\n>(tastyOptions: TastyProps<K, V, E>) {\n  const {\n    as: originalAs = 'div',\n    element: defaultElement,\n    styles: defaultStyles,\n    styleProps,\n    modProps: modPropsDef,\n    variants,\n    tokens: defaultTokens,\n    elements,\n    ...defaultProps\n  } = tastyOptions;\n\n  // Pre-compute merged styles for each variant (if variants are defined)\n  // This avoids creating separate component instances per variant\n  let variantStylesMap: Record<string, Styles | undefined> | undefined;\n  if (variants) {\n    // Split defaultStyles: extend-mode state maps (no '' key, non-selector)\n    // are pulled out and applied AFTER variant merge so they survive\n    // replace-mode maps in variants.\n    let baseStyles = defaultStyles;\n    let extensionStyles: Styles | undefined;\n\n    if (defaultStyles) {\n      for (const key of Object.keys(defaultStyles)) {\n        if (isSelector(key)) continue;\n\n        const value = (defaultStyles as Record<string, unknown>)[key];\n\n        if (\n          typeof value === 'object' &&\n          value !== null &&\n          !Array.isArray(value) &&\n          !('' in value)\n        ) {\n          if (!extensionStyles) {\n            baseStyles = { ...defaultStyles } as Styles;\n            extensionStyles = {} as Styles;\n          }\n          (extensionStyles as Record<string, unknown>)[key] = value;\n          delete (baseStyles as Record<string, unknown>)[key];\n        }\n      }\n    }\n\n    const variantEntries = Object.entries(variants) as [string, Styles][];\n    variantStylesMap = variantEntries.reduce(\n      (map, [variant, variantStyles]) => {\n        map[variant] = extensionStyles\n          ? mergeStyles(baseStyles, variantStyles, extensionStyles)\n          : mergeStyles(baseStyles, variantStyles);\n        return map;\n      },\n      {} as Record<string, Styles | undefined>,\n    );\n    // Ensure 'default' variant always exists\n    if (!variantStylesMap['default']) {\n      variantStylesMap['default'] = defaultStyles;\n    }\n  }\n\n  const {\n    qa: defaultQa,\n    qaVal: defaultQaVal,\n    ...otherDefaultProps\n  } = defaultProps ?? {};\n\n  const propsToCheck = styleProps\n    ? (styleProps as StyleList).concat(BASE_STYLES)\n    : BASE_STYLES;\n\n  const modPropsKeys: string[] | undefined = modPropsDef\n    ? ((Array.isArray(modPropsDef)\n        ? modPropsDef\n        : Object.keys(modPropsDef)) as string[])\n    : undefined;\n\n  const _TastyComponent = forwardRef<\n    unknown,\n    AllBasePropsWithMods<K> & WithVariant<V>\n  >((allProps, ref) => {\n    const {\n      as,\n      styles: rawStyles,\n      variant,\n      mods,\n      element,\n      qa,\n      qaVal,\n      className: userClassName,\n      tokens,\n      style,\n      ...otherProps\n    } = allProps as Record<string, unknown> as AllBasePropsWithMods<K> &\n      WithVariant<V> & {\n        className?: string;\n        tokens?: Tokens;\n        style?: Record<string, unknown>;\n      };\n\n    let styles = rawStyles;\n\n    let propStyles: Styles | null = null;\n    let propStylesKey = '';\n\n    for (const prop of propsToCheck) {\n      const key = prop as unknown as string;\n\n      if (key in otherProps) {\n        if (!propStyles) propStyles = {};\n        const value = (otherProps as any)[key];\n        (propStyles as any)[key] = value;\n        delete (otherProps as any)[key];\n        propStylesKey += key + '\\0' + value + '\\0';\n      }\n    }\n\n    if (!styles || (styles && !hasKeys(styles as Record<string, unknown>))) {\n      styles = undefined as unknown as Styles;\n    }\n\n    // Stabilize propStyles reference: only update when content actually changes\n    const propStylesRef = useRef<{ key: string; styles: Styles | null }>({\n      key: '',\n      styles: null,\n    });\n    if (propStylesRef.current.key !== propStylesKey) {\n      propStylesRef.current = { key: propStylesKey, styles: propStyles };\n    }\n\n    // Determine base styles: use variant styles if available, otherwise default styles\n    const baseStyles = variantStylesMap\n      ? (variantStylesMap[(variant as string) || 'default'] ??\n        variantStylesMap['default'])\n      : defaultStyles;\n\n    // Merge base styles with instance styles and prop styles\n    const allStyles = useMemo(() => {\n      const currentPropStyles = propStylesRef.current.styles;\n      const hasStyleProps =\n        styles && hasKeys(styles as Record<string, unknown>);\n      const hasPropStyles = currentPropStyles && hasKeys(currentPropStyles);\n\n      if (!hasStyleProps && !hasPropStyles) {\n        return baseStyles;\n      }\n\n      return mergeStyles(\n        baseStyles,\n        styles as Styles,\n        currentPropStyles as Styles,\n      );\n    }, [baseStyles, styles, propStylesKey]);\n\n    // Use the useStyles hook for style generation and injection\n    const { className: stylesClassName } = useStyles(allStyles);\n\n    // Merge default tokens with instance tokens (instance overrides defaults)\n    const tokensKey = stringifyTokens(tokens as Tokens | undefined);\n    const mergedTokens = useMemo(() => {\n      if (!defaultTokens && !tokens) return undefined;\n      if (!defaultTokens) return tokens as Tokens;\n      if (!tokens) return defaultTokens;\n      return { ...defaultTokens, ...tokens } as Tokens;\n    }, [tokensKey]);\n\n    // Process merged tokens into inline style properties\n    const processedTokenStyle = useMemo(() => {\n      return processTokens(mergedTokens);\n    }, [mergedTokens]);\n\n    // Merge processed tokens with explicit style prop (style has priority)\n    const mergedStyle = useMemo(() => {\n      if (!processedTokenStyle && !style) return undefined;\n      if (!processedTokenStyle) return style;\n      if (!style) return processedTokenStyle;\n      return { ...processedTokenStyle, ...style };\n    }, [processedTokenStyle, style]);\n\n    let propMods: Record<string, ModValue> | undefined;\n    if (modPropsKeys) {\n      for (const key of modPropsKeys) {\n        if (key in otherProps) {\n          if (!propMods) propMods = {};\n          propMods[key] = (otherProps as Record<string, unknown>)[\n            key\n          ] as ModValue;\n          delete (otherProps as Record<string, unknown>)[key];\n        }\n      }\n    }\n\n    const mergedMods = propMods\n      ? { ...(mods as Record<string, ModValue>), ...propMods }\n      : (mods as Record<string, ModValue> | undefined);\n\n    let modDataAttrs: Record<string, unknown> | undefined;\n    if (mergedMods) {\n      modDataAttrs = modAttrs(mergedMods as unknown as Mods) as Record<\n        string,\n        unknown\n      >;\n    }\n\n    // Merge user className with generated className\n    const finalClassName = [(userClassName as string) || '', stylesClassName]\n      .filter(Boolean)\n      .join(' ');\n\n    const elementProps = {\n      'data-element': (element as string | undefined) || defaultElement,\n      'data-qa': (qa as string | undefined) || defaultQa,\n      'data-qaval': (qaVal as string | undefined) || defaultQaVal,\n      ...(otherDefaultProps as unknown as Record<string, unknown>),\n      ...(modDataAttrs || {}),\n      ...(otherProps as unknown as Record<string, unknown>),\n      className: finalClassName,\n      style: mergedStyle,\n      ref,\n    } as Record<string, unknown>;\n\n    // Apply the helper to handle is* properties\n    handleIsProperties(elementProps);\n\n    const renderedElement = createElement(\n      (as as string | 'div') ?? originalAs,\n      elementProps,\n    );\n\n    return renderedElement;\n  });\n\n  _TastyComponent.displayName = `TastyComponent(${\n    (defaultProps as any).qa || originalAs\n  })`;\n\n  // Attach sub-element components if elements are defined\n  if (elements) {\n    const subElements = Object.entries(elements).reduce(\n      (acc, [name, definition]) => {\n        acc[name] = createSubElement(\n          name,\n          definition as SubElementDefinition<keyof JSX.IntrinsicElements>,\n        );\n        return acc;\n      },\n      {} as Record<string, ForwardRefExoticComponent<any>>,\n    );\n\n    return Object.assign(_TastyComponent, subElements);\n  }\n\n  return _TastyComponent;\n}\n\nexport const Element = tasty({});\n"],"mappings":"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"}

package/docs/README.md

@@ -1,6 +1,6 @@
 # Tasty Docs
 
-Tasty is a styling engine for design systems that turns component state into deterministic CSS by compiling state maps into mutually exclusive selectors. Use this hub to choose the right guide once you know whether you are evaluating the model, adopting it in a design system, or implementing with it day to day.
+Tasty is a styling engine for design systems that turns component state into deterministic CSS by compiling state maps into mutually exclusive selectors. Use this hub to choose the right guide once you know whether you are evaluating the model, adopting it in a design system, or implementing reusable, stateful components day to day.
 
 ## Start Here
 

package/docs/adoption.md

@@ -1,6 +1,6 @@
 # Adoption Guide
 
-Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**: what the comparison guide calls a house styling language. That means adoption usually starts where styling has already become a composition problem, not with an all-at-once rewrite.
+Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**: what the comparison guide calls a house styling language. That means adoption usually starts where styling for reusable, stateful components has already become a composition problem, not with an all-at-once rewrite.
 
 This guide is for design-system maintainers and platform engineers evaluating Tasty or introducing it into an existing codebase. Use this document for rollout strategy and adoption sequencing; use the [Comparison guide](comparison.md) when the open question is whether Tasty is the right tool in the first place.
 

package/docs/comparison.md

@@ -16,7 +16,7 @@ Most styling tools focus on one of these layers:
 - utility composition
 - atomic CSS generation
 
-Tasty's house styling language can include tokens, state semantics, style props, recipes, custom units, and sub-element rules.
+Tasty's house styling language can include tokens, state semantics, style props, recipes, custom units, and sub-element rules. In other words, it is a governed styling model, not just another syntax for writing CSS.
 
 That is why syntax-level comparisons are often shallow. The more meaningful comparison is about:
 

package/docs/design-system.md

@@ -333,13 +333,19 @@ A design system works best when the rules for customization are explicit. Tasty
 <Space flow="row" gap="3x" padding="2x">
 ```
 
-2. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
+2. **Use modProps** — control component states through typed props instead of `mods`:
+
+```tsx
+<Button isLoading size="large">Submit</Button>
+```
+
+3. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
 
 ```tsx
 <ProgressBar tokens={{ '$progress': `${percent}%` }} />
 ```
 
-3. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`:
+4. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`:
 
 ```tsx
 const DangerButton = tasty(Button, {

package/docs/dsl.md

@@ -36,6 +36,46 @@ styles: { Title: { preset: 'h3' } }
 // Targets: <div data-element="Title">
 ```
 
+#### Selector Affix (`$`)
+
+Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
+
+| Pattern | Result | Description |
+|---------|--------|-------------|
+| *(none)* | ` [el]` | Descendant (default) |
+| `>` | `> [el]` | Direct child |
+| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
+| `h1` | ` h1` | Tag selector (no key injection) |
+| `h1 >` | ` h1 > [el]` | Key is direct child of tag |
+| `h1 *` | ` h1 *` | Any descendant of tag |
+| `*` | ` *` | All descendants |
+| `::before` | `::before` | Root pseudo (no key) |
+| `@::before` | `[el]::before` | Pseudo on the sub-element |
+| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
+| `>@.active` | `> [el].active` | Class on the sub-element |
+
+Rules for key injection (`[data-element="..."]`):
+
+- **Trailing combinator** (`>`, `+`, `~`) — key is injected after it
+- **Uppercase element name** (`Body`, `Row`) — key is injected as descendant
+- **HTML tag** (`h1`, `a`, `span`) — no key injection; the tag IS the selector
+- **Universal selector** (`*`) — no key injection
+- **Pseudo / class / attribute** — no key injection
+
+The `@` placeholder marks exactly where `[data-element="..."]` is injected, allowing you to attach pseudo-classes, pseudo-elements, or class selectors directly to the sub-element instead of the root:
+
+```jsx
+const List = tasty({
+  styles: {
+    Item: {
+      $: '>@:last-child',
+      border: 'none',
+    },
+  },
+});
+// → .t0 > [data-element="Item"]:last-child { border: none }
+```
+
 ### Color Token
 
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
@@ -53,6 +93,8 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
+Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+
 ---
 
 ## Color Tokens & Opacity

package/docs/methodology.md

@@ -163,6 +163,61 @@ Exposing every CSS property as a prop defeats the purpose of a design system. Th
 
 ---
 
+## modProps and mods
+
+`modProps` expose modifier keys as top-level component props — the modifier equivalent of `styleProps`. Use them when a component has a fixed set of known state modifiers.
+
+```tsx
+const Card = tasty({
+  modProps: {
+    isLoading: Boolean,
+    isSelected: Boolean,
+  },
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+// Clean prop API — no mods object needed
+<Card isLoading isSelected>Content</Card>
+```
+
+### When to use which
+
+| Pattern | Use when |
+|---|---|
+| `modProps` | The component has a fixed set of known boolean/string states that drive styles. Provides TypeScript autocomplete and a cleaner JSX API. |
+| `mods` prop | The component needs arbitrary or dynamic modifiers that aren't known at definition time. |
+| Both | Combine `modProps` for the known states and `mods` for ad-hoc overrides. Mod props take precedence. |
+| `styleProps` | Exposing CSS properties (layout, sizing) for customization — different from modifiers. |
+
+### Typed modProps vs array form
+
+The object form gives precise TypeScript types using JS constructors (`Boolean`, `String`, `Number`) or enum arrays:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,
+    size: ['small', 'medium', 'large'] as const,
+  },
+  // ...
+});
+
+// TypeScript knows: isLoading?: boolean, size?: 'small' | 'medium' | 'large'
+```
+
+The array form is simpler but types all values as `ModValue`:
+
+```tsx
+modProps: ['isLoading', 'isSelected'] as const,
+```
+
+For the full API reference, see [Runtime — Mod Props](runtime.md#mod-props).
+
+---
+
 ## tokens prop for dynamic values
 
 Every Tasty component accepts a `tokens` prop that renders as inline CSS custom properties on the element. This is the mechanism for per-instance dynamic values.
@@ -402,8 +457,9 @@ See [Configuration](configuration.md) for the full `configure()` API.
 - **Use semantic transition names** (`transition: 'theme 0.3s'`) instead of listing CSS properties
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
+- **Use `modProps`** to expose known modifier states as clean component props
 - **Use `tokens` prop** for per-instance dynamic values (progress, user color)
-- **Use modifiers** (`mods`) for state-driven style changes instead of runtime `styles` prop changes
+- **Use modifiers** (`mods` or `modProps`) for state-driven style changes instead of runtime `styles` prop changes
 
 ### Avoid
 
@@ -441,11 +497,19 @@ Tasty's enhanced properties provide concise syntax, better composability, and si
 // Bad: styles object changes every render
 <Card styles={{ padding: isCompact ? '2x' : '4x' }} />
 
-// Good: use modifiers
-<Card mods={{ compact: isCompact }} />
+// Good: use modifiers via modProps
+<Card isCompact={isCompact} />
+
+// Or via mods object
+<Card mods={{ isCompact }} />
 
 // In the component definition:
-padding: { '': '4x', compact: '2x' },
+const Card = tasty({
+  modProps: ['isCompact'] as const,
+  styles: {
+    padding: { '': '4x', isCompact: '2x' },
+  },
+});
 ```
 
 Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS.

package/docs/runtime.md

@@ -74,6 +74,86 @@ For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_ST
 
 ---
 
+## Mod Props
+
+Use `modProps` to expose modifier keys as direct component props instead of requiring the `mods` object:
+
+```jsx
+// Before: mods object
+<Button mods={{ isLoading: true, size: 'large' }}>Submit</Button>
+
+// After: mod props
+<Button isLoading size="large">Submit</Button>
+```
+
+### Array form
+
+List modifier key names. Types default to `ModValue` (`boolean | string | number | undefined | null`):
+
+```jsx
+const Button = tasty({
+  modProps: ['isLoading', 'isSelected'] as const,
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+<Button isLoading isSelected>Submit</Button>
+// Renders: <button data-is-loading="" data-is-selected="">Submit</button>
+```
+
+### Object form (typed)
+
+Map modifier names to type descriptors for precise TypeScript types:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,   // isLoading?: boolean
+    isSelected: Boolean,  // isSelected?: boolean
+    size: ['small', 'medium', 'large'] as const,  // size?: 'small' | 'medium' | 'large'
+  },
+  styles: {
+    padding: { '': '2x 4x', 'size=small': '1x 2x', 'size=large': '3x 6x' },
+    fill: { '': '#surface', isLoading: '#surface.5' },
+  },
+});
+
+<Button isLoading size="large">Submit</Button>
+// Renders: <button data-is-loading="" data-size="large">Submit</button>
+```
+
+Available type descriptors:
+
+| Descriptor | TypeScript type | Example |
+|---|---|---|
+| `Boolean` | `boolean` | `isLoading: Boolean` |
+| `String` | `string` | `label: String` |
+| `Number` | `number` | `count: Number` |
+| `['a', 'b'] as const` | `'a' \| 'b'` | `size: ['sm', 'md', 'lg'] as const` |
+
+### Merge with `mods`
+
+Mod props and the `mods` object can be used together. Mod props take precedence:
+
+```jsx
+<Button mods={{ isLoading: false, extra: true }} isLoading>
+// isLoading=true wins (from mod prop), extra=true preserved from mods
+```
+
+### When to use `modProps` vs `mods`
+
+| Use case | Recommendation |
+|---|---|
+| Component has a fixed set of known modifiers | `modProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic modifiers | `mods` — open-ended `Record<string, ModValue>` |
+| Both fixed and dynamic | Combine: `modProps` for known keys, `mods` for ad-hoc |
+
+For architecture guidance on when to use modifiers vs `styleProps`, see [Methodology — modProps and mods](methodology.md#modprops-and-mods).
+
+---
+
 ## Variants
 
 Define named style variations. Only CSS for variants actually used at runtime is injected:
@@ -178,31 +258,7 @@ const Card = tasty({
 
 ### Selector Affix (`$`)
 
-Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
-
-| Pattern | Result | Description |
-|---------|--------|-------------|
-| *(none)* | ` [el]` | Descendant (default) |
-| `>` | `> [el]` | Direct child |
-| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
-| `::before` | `::before` | Root pseudo (no key) |
-| `@::before` | `[el]::before` | Pseudo on the sub-element |
-| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
-| `>@.active` | `> [el].active` | Class on the sub-element |
-
-The `@` placeholder marks exactly where the `[data-element="..."]` selector is injected, allowing you to attach pseudo-classes, pseudo-elements, or class selectors directly to the sub-element instead of the root:
-
-```jsx
-const List = tasty({
-  styles: {
-    Item: {
-      $: '>@:last-child',
-      border: 'none',
-    },
-  },
-});
-// → .t0 > [data-element="Item"]:last-child { border: none }
-```
+The `$` property inside a sub-element's styles controls how its selector attaches to the root selector — combinators, HTML tags, pseudo-elements, the `@` placeholder, and more. For the full reference table and injection rules, see [DSL — Selector Affix](dsl.md#selector-affix-).
 
 For the mental model behind sub-elements — how they share root state context and how this differs from BEM — see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 

package/docs/styles.md

@@ -146,37 +146,39 @@ Individual props `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marg
 
 ### `width`
 
-Element width with min/max control.
+Element width with min/max control. One, two, or three values set `min-width`, `width`, and `max-width` together.
 
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
+**Positional syntax:**
 
-**Modifiers:** `min`, `max`, `fixed`
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"10x"` | initial | `10x` | initial |
+| `"1x 10x"` | `1x` | auto | `10x` |
+| `"1x 5x 10x"` | `1x` | `5x` | `10x` |
+| `"0 100% 800px"` | `0` | `100%` | `800px` |
+| `"initial 100% 1400px"` | initial | `100%` | `1400px` |
+
+**Modifier syntax:**
+
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"min 2x"` | `2x` | auto | initial |
+| `"max 100%"` | initial | auto | `100%` |
+| `"fixed 200px"` | `200px` | `200px` | `200px` |
 
 **Keywords:** `stretch`, `max-content`, `min-content`, `fit-content`
 
 | Value | Effect |
 |-------|--------|
-| `"10x"` | Width `10x`, min `initial`, max `initial` |
-| `"1x 10x"` | Width `auto`, min `1x`, max `10x` |
-| `"1x 5x 10x"` | Min `1x`, width `5x`, max `10x` |
-| `"min 2x"` | Min-width `2x`, width `auto`, max `initial` |
-| `"max 100%"` | Max-width `100%`, width `auto`, min `initial` |
-| `"fixed 200px"` | Min, width, and max all set to `200px` |
 | `"stretch"` | Fill available space (cross-browser) |
-| `true` | Width `auto`, min `initial`, max `initial` |
+| `true` | Reset to `auto` / `initial` / `initial` |
 | Number | Converted to `px` |
 
 Separate `minWidth` and `maxWidth` props are supported and override values from the `width` syntax.
 
 ### `height`
 
-Element height. Same syntax and modifiers as `width`.
-
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
-
-**Modifiers:** `min`, `max`, `fixed`
-
-**Keywords:** `max-content`, `min-content`, `fit-content`
+Element height. Same syntax, modifiers, and positional patterns as `width`.
 
 Separate `minHeight` and `maxHeight` props are supported and override values from the `height` syntax.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",