@tenphi/tasty 0.1.0

package/dist/properties/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/properties/index.ts"],"sourcesContent":["/**\n * Properties Utilities\n *\n * Utilities for extracting and processing CSS @property definitions in styles.\n * Unlike keyframes, properties are permanent once registered and don't need cleanup.\n *\n * Property names use tasty token syntax:\n * - `$name` for regular properties → `--name`\n * - `#name` for color properties → `--name-color` (auto-sets syntax: '<color>')\n */\n\nimport type { PropertyDefinition } from '../injector/types';\nimport type { Styles } from '../styles/types';\nimport { getRgbValuesFromRgbaString, strToRgb } from '../utils/styles';\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst PROPERTIES_KEY = '@properties';\n\n/**\n * Valid CSS custom property name pattern (after the -- prefix).\n * Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.\n */\nconst VALID_PROPERTY_NAME_PATTERN = /^[a-z_][a-z0-9-_]*$/i;\n\n// ============================================================================\n// Validation Functions\n// ============================================================================\n\n/**\n * Validate a CSS custom property name (the part after --).\n * Returns true if the name is valid for use as a CSS custom property.\n */\nexport function isValidPropertyName(name: string): boolean {\n  return VALID_PROPERTY_NAME_PATTERN.test(name);\n}\n\n/**\n * Result of parsing a property token.\n */\nexport interface ParsedPropertyToken {\n  /** The CSS custom property name (e.g., '--my-prop') */\n  cssName: string;\n  /** Whether this is a color property */\n  isColor: boolean;\n  /** Whether the token was valid */\n  isValid: boolean;\n  /** Error message if invalid */\n  error?: string;\n}\n\n// ============================================================================\n// Extraction Functions\n// ============================================================================\n\n/**\n * Check if styles object has local @properties definition.\n * Fast path: single property lookup.\n */\nexport function hasLocalProperties(styles: Styles): boolean {\n  return PROPERTIES_KEY in styles;\n}\n\n/**\n * Extract local @properties from styles object.\n * Returns null if no local properties (fast path).\n */\nexport function extractLocalProperties(\n  styles: Styles,\n): Record<string, PropertyDefinition> | null {\n  const properties = styles[PROPERTIES_KEY];\n  if (!properties || typeof properties !== 'object') {\n    return null;\n  }\n  return properties as Record<string, PropertyDefinition>;\n}\n\n// ============================================================================\n// Token Parsing Functions\n// ============================================================================\n\n/**\n * Parse a property token name and return the CSS property name and whether it's a color.\n * Supports tasty token syntax and validates the property name.\n *\n * Token formats:\n * - `$name` → { cssName: '--name', isColor: false }\n * - `#name` → { cssName: '--name-color', isColor: true }\n * - `--name` → { cssName: '--name', isColor: false } (legacy, auto-detect color by suffix)\n * - `name` → { cssName: '--name', isColor: false } (legacy)\n *\n * @param token - The property token to parse\n * @returns Parsed result with cssName, isColor, isValid, and optional error\n */\nexport function parsePropertyToken(token: string): ParsedPropertyToken {\n  if (!token || typeof token !== 'string') {\n    return {\n      cssName: '',\n      isColor: false,\n      isValid: false,\n      error: 'Property token must be a non-empty string',\n    };\n  }\n\n  let name: string;\n  let isColor: boolean;\n\n  if (token.startsWith('$')) {\n    // Regular property token: $name → --name\n    name = token.slice(1);\n    isColor = false;\n  } else if (token.startsWith('#')) {\n    // Color property token: #name → --name-color\n    name = token.slice(1);\n    isColor = true;\n  } else if (token.startsWith('--')) {\n    // Legacy format with -- prefix\n    name = token.slice(2);\n    isColor = token.endsWith('-color');\n  } else {\n    // Legacy format without prefix\n    name = token;\n    isColor = token.endsWith('-color');\n  }\n\n  // Validate the name\n  if (!name) {\n    return {\n      cssName: '',\n      isColor,\n      isValid: false,\n      error: 'Property name cannot be empty',\n    };\n  }\n\n  if (!isValidPropertyName(name)) {\n    return {\n      cssName: '',\n      isColor,\n      isValid: false,\n      error: `Invalid property name \"${name}\". Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.`,\n    };\n  }\n\n  // Build the CSS custom property name\n  // For #name tokens, we add -color suffix\n  // For legacy formats (--name-color or name-color), the name already includes -color\n  let cssName: string;\n  if (token.startsWith('#')) {\n    // Color token: #name → --name-color\n    cssName = `--${name}-color`;\n  } else {\n    // All other formats: just add -- prefix\n    cssName = `--${name}`;\n  }\n\n  return {\n    cssName,\n    isColor,\n    isValid: true,\n  };\n}\n\n// ============================================================================\n// Normalization Functions\n// ============================================================================\n\n/**\n * Normalize a property name to the CSS custom property format.\n *\n * @deprecated Use parsePropertyToken instead for proper token handling\n */\nexport function normalizePropertyName(name: string): string {\n  const result = parsePropertyToken(name);\n  return result.isValid ? result.cssName : `--${name}`;\n}\n\n/**\n * Normalize a property definition to a consistent string representation.\n * Used for comparing definitions to detect changes/conflicts.\n *\n * Keys are sorted alphabetically to ensure consistent comparison:\n * { inherits: true, syntax: '<color>' } === { syntax: '<color>', inherits: true }\n */\nexport function normalizePropertyDefinition(def: PropertyDefinition): string {\n  const normalized: Record<string, unknown> = {};\n\n  // Add properties in alphabetical order\n  if (def.inherits !== undefined) {\n    normalized.inherits = def.inherits;\n  }\n  if (def.initialValue !== undefined) {\n    normalized.initialValue = String(def.initialValue);\n  }\n  if (def.syntax !== undefined) {\n    normalized.syntax = def.syntax;\n  }\n\n  return JSON.stringify(normalized);\n}\n\n/**\n * Result of getEffectiveDefinition.\n */\nexport interface EffectiveDefinitionResult {\n  /** The CSS custom property name */\n  cssName: string;\n  /** The effective property definition */\n  definition: PropertyDefinition;\n  /** Whether this is a color property */\n  isColor: boolean;\n  /** Whether the token was valid */\n  isValid: boolean;\n  /** Error message if invalid */\n  error?: string;\n}\n\n/**\n * Get the effective property definition for a token.\n * For color tokens (#name), auto-sets syntax to '<color>' and defaults initialValue to 'transparent'.\n *\n * @param token - Property token ($name, #name, --name, or plain name)\n * @param userDefinition - User-provided definition options\n * @returns Effective definition with cssName, definition, isValid, and optional error\n */\nexport function getEffectiveDefinition(\n  token: string,\n  userDefinition: PropertyDefinition,\n): EffectiveDefinitionResult {\n  const parsed = parsePropertyToken(token);\n\n  if (!parsed.isValid) {\n    return {\n      cssName: '',\n      definition: userDefinition,\n      isColor: false,\n      isValid: false,\n      error: parsed.error,\n    };\n  }\n\n  if (parsed.isColor) {\n    // Color properties have fixed syntax and default initialValue\n    return {\n      cssName: parsed.cssName,\n      definition: {\n        syntax: '<color>', // Always '<color>' for color tokens, cannot be overridden\n        inherits: userDefinition.inherits, // Allow inherits to be customized\n        initialValue: userDefinition.initialValue ?? 'transparent', // Default to transparent\n      },\n      isColor: true,\n      isValid: true,\n    };\n  }\n\n  // Regular properties use the definition as-is\n  return {\n    cssName: parsed.cssName,\n    definition: userDefinition,\n    isColor: false,\n    isValid: true,\n  };\n}\n\n// ============================================================================\n// Color RGB Companion Helpers\n// ============================================================================\n\n/**\n * Extract RGB triplet string from a color initial value.\n * Used when auto-creating the companion `-rgb` property for color @property definitions.\n *\n * @param initialValue - The color property's initial value (e.g., 'rgb(255 255 255)', 'transparent', '#fff')\n * @returns Space-separated RGB triplet (e.g., '255 255 255'), defaults to '0 0 0'\n */\nexport function colorInitialValueToRgb(initialValue?: string | number): string {\n  if (initialValue == null) return '0 0 0';\n\n  const str = String(initialValue).trim();\n  if (!str || str === 'transparent') return '0 0 0';\n\n  const rgba = strToRgb(str);\n  if (rgba) {\n    const values = getRgbValuesFromRgbaString(rgba);\n    if (values.length >= 3) return values.slice(0, 3).join(' ');\n  }\n\n  return '0 0 0';\n}\n"],"mappings":";;;AAmBA,MAAM,iBAAiB;;;;;AAMvB,MAAM,8BAA8B;;;;;AAUpC,SAAgB,oBAAoB,MAAuB;AACzD,QAAO,4BAA4B,KAAK,KAAK;;;;;;AAyB/C,SAAgB,mBAAmB,QAAyB;AAC1D,QAAO,kBAAkB;;;;;;AAO3B,SAAgB,uBACd,QAC2C;CAC3C,MAAM,aAAa,OAAO;AAC1B,KAAI,CAAC,cAAc,OAAO,eAAe,SACvC,QAAO;AAET,QAAO;;;;;;;;;;;;;;;AAoBT,SAAgB,mBAAmB,OAAoC;AACrE,KAAI,CAAC,SAAS,OAAO,UAAU,SAC7B,QAAO;EACL,SAAS;EACT,SAAS;EACT,SAAS;EACT,OAAO;EACR;CAGH,IAAI;CACJ,IAAI;AAEJ,KAAI,MAAM,WAAW,IAAI,EAAE;AAEzB,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU;YACD,MAAM,WAAW,IAAI,EAAE;AAEhC,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU;YACD,MAAM,WAAW,KAAK,EAAE;AAEjC,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU,MAAM,SAAS,SAAS;QAC7B;AAEL,SAAO;AACP,YAAU,MAAM,SAAS,SAAS;;AAIpC,KAAI,CAAC,KACH,QAAO;EACL,SAAS;EACT;EACA,SAAS;EACT,OAAO;EACR;AAGH,KAAI,CAAC,oBAAoB,KAAK,CAC5B,QAAO;EACL,SAAS;EACT;EACA,SAAS;EACT,OAAO,0BAA0B,KAAK;EACvC;CAMH,IAAI;AACJ,KAAI,MAAM,WAAW,IAAI,CAEvB,WAAU,KAAK,KAAK;KAGpB,WAAU,KAAK;AAGjB,QAAO;EACL;EACA;EACA,SAAS;EACV;;;;;;;;;AAwBH,SAAgB,4BAA4B,KAAiC;CAC3E,MAAM,aAAsC,EAAE;AAG9C,KAAI,IAAI,aAAa,OACnB,YAAW,WAAW,IAAI;AAE5B,KAAI,IAAI,iBAAiB,OACvB,YAAW,eAAe,OAAO,IAAI,aAAa;AAEpD,KAAI,IAAI,WAAW,OACjB,YAAW,SAAS,IAAI;AAG1B,QAAO,KAAK,UAAU,WAAW;;;;;;;;;;AA2BnC,SAAgB,uBACd,OACA,gBAC2B;CAC3B,MAAM,SAAS,mBAAmB,MAAM;AAExC,KAAI,CAAC,OAAO,QACV,QAAO;EACL,SAAS;EACT,YAAY;EACZ,SAAS;EACT,SAAS;EACT,OAAO,OAAO;EACf;AAGH,KAAI,OAAO,QAET,QAAO;EACL,SAAS,OAAO;EAChB,YAAY;GACV,QAAQ;GACR,UAAU,eAAe;GACzB,cAAc,eAAe,gBAAgB;GAC9C;EACD,SAAS;EACT,SAAS;EACV;AAIH,QAAO;EACL,SAAS,OAAO;EAChB,YAAY;EACZ,SAAS;EACT,SAAS;EACV;;;;;;;;;AAcH,SAAgB,uBAAuB,cAAwC;AAC7E,KAAI,gBAAgB,KAAM,QAAO;CAEjC,MAAM,MAAM,OAAO,aAAa,CAAC,MAAM;AACvC,KAAI,CAAC,OAAO,QAAQ,cAAe,QAAO;CAE1C,MAAM,OAAO,SAAS,IAAI;AAC1B,KAAI,MAAM;EACR,MAAM,SAAS,2BAA2B,KAAK;AAC/C,MAAI,OAAO,UAAU,EAAG,QAAO,OAAO,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI;;AAG7D,QAAO"}

package/dist/properties/index.mjs

@@ -0,0 +1,141 @@
+import { getRgbValuesFromRgbaString, strToRgb } from "../utils/styles.mjs";
+
+//#region src/properties/index.ts
+/**
+* Valid CSS custom property name pattern (after the -- prefix).
+* Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.
+*/
+const VALID_PROPERTY_NAME_PATTERN = /^[a-z_][a-z0-9-_]*$/i;
+/**
+* Validate a CSS custom property name (the part after --).
+* Returns true if the name is valid for use as a CSS custom property.
+*/
+function isValidPropertyName(name) {
+	return VALID_PROPERTY_NAME_PATTERN.test(name);
+}
+/**
+* Parse a property token name and return the CSS property name and whether it's a color.
+* Supports tasty token syntax and validates the property name.
+*
+* Token formats:
+* - `$name` → { cssName: '--name', isColor: false }
+* - `#name` → { cssName: '--name-color', isColor: true }
+* - `--name` → { cssName: '--name', isColor: false } (legacy, auto-detect color by suffix)
+* - `name` → { cssName: '--name', isColor: false } (legacy)
+*
+* @param token - The property token to parse
+* @returns Parsed result with cssName, isColor, isValid, and optional error
+*/
+function parsePropertyToken(token) {
+	if (!token || typeof token !== "string") return {
+		cssName: "",
+		isColor: false,
+		isValid: false,
+		error: "Property token must be a non-empty string"
+	};
+	let name;
+	let isColor;
+	if (token.startsWith("$")) {
+		name = token.slice(1);
+		isColor = false;
+	} else if (token.startsWith("#")) {
+		name = token.slice(1);
+		isColor = true;
+	} else if (token.startsWith("--")) {
+		name = token.slice(2);
+		isColor = token.endsWith("-color");
+	} else {
+		name = token;
+		isColor = token.endsWith("-color");
+	}
+	if (!name) return {
+		cssName: "",
+		isColor,
+		isValid: false,
+		error: "Property name cannot be empty"
+	};
+	if (!isValidPropertyName(name)) return {
+		cssName: "",
+		isColor,
+		isValid: false,
+		error: `Invalid property name "${name}". Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.`
+	};
+	let cssName;
+	if (token.startsWith("#")) cssName = `--${name}-color`;
+	else cssName = `--${name}`;
+	return {
+		cssName,
+		isColor,
+		isValid: true
+	};
+}
+/**
+* Normalize a property definition to a consistent string representation.
+* Used for comparing definitions to detect changes/conflicts.
+*
+* Keys are sorted alphabetically to ensure consistent comparison:
+* { inherits: true, syntax: '<color>' } === { syntax: '<color>', inherits: true }
+*/
+function normalizePropertyDefinition(def) {
+	const normalized = {};
+	if (def.inherits !== void 0) normalized.inherits = def.inherits;
+	if (def.initialValue !== void 0) normalized.initialValue = String(def.initialValue);
+	if (def.syntax !== void 0) normalized.syntax = def.syntax;
+	return JSON.stringify(normalized);
+}
+/**
+* Get the effective property definition for a token.
+* For color tokens (#name), auto-sets syntax to '<color>' and defaults initialValue to 'transparent'.
+*
+* @param token - Property token ($name, #name, --name, or plain name)
+* @param userDefinition - User-provided definition options
+* @returns Effective definition with cssName, definition, isValid, and optional error
+*/
+function getEffectiveDefinition(token, userDefinition) {
+	const parsed = parsePropertyToken(token);
+	if (!parsed.isValid) return {
+		cssName: "",
+		definition: userDefinition,
+		isColor: false,
+		isValid: false,
+		error: parsed.error
+	};
+	if (parsed.isColor) return {
+		cssName: parsed.cssName,
+		definition: {
+			syntax: "<color>",
+			inherits: userDefinition.inherits,
+			initialValue: userDefinition.initialValue ?? "transparent"
+		},
+		isColor: true,
+		isValid: true
+	};
+	return {
+		cssName: parsed.cssName,
+		definition: userDefinition,
+		isColor: false,
+		isValid: true
+	};
+}
+/**
+* Extract RGB triplet string from a color initial value.
+* Used when auto-creating the companion `-rgb` property for color @property definitions.
+*
+* @param initialValue - The color property's initial value (e.g., 'rgb(255 255 255)', 'transparent', '#fff')
+* @returns Space-separated RGB triplet (e.g., '255 255 255'), defaults to '0 0 0'
+*/
+function colorInitialValueToRgb(initialValue) {
+	if (initialValue == null) return "0 0 0";
+	const str = String(initialValue).trim();
+	if (!str || str === "transparent") return "0 0 0";
+	const rgba = strToRgb(str);
+	if (rgba) {
+		const values = getRgbValuesFromRgbaString(rgba);
+		if (values.length >= 3) return values.slice(0, 3).join(" ");
+	}
+	return "0 0 0";
+}
+
+//#endregion
+export { colorInitialValueToRgb, getEffectiveDefinition, normalizePropertyDefinition };
+//# sourceMappingURL=index.mjs.map

package/dist/properties/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/properties/index.ts"],"sourcesContent":["/**\n * Properties Utilities\n *\n * Utilities for extracting and processing CSS @property definitions in styles.\n * Unlike keyframes, properties are permanent once registered and don't need cleanup.\n *\n * Property names use tasty token syntax:\n * - `$name` for regular properties → `--name`\n * - `#name` for color properties → `--name-color` (auto-sets syntax: '<color>')\n */\n\nimport type { PropertyDefinition } from '../injector/types';\nimport type { Styles } from '../styles/types';\nimport { getRgbValuesFromRgbaString, strToRgb } from '../utils/styles';\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst PROPERTIES_KEY = '@properties';\n\n/**\n * Valid CSS custom property name pattern (after the -- prefix).\n * Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.\n */\nconst VALID_PROPERTY_NAME_PATTERN = /^[a-z_][a-z0-9-_]*$/i;\n\n// ============================================================================\n// Validation Functions\n// ============================================================================\n\n/**\n * Validate a CSS custom property name (the part after --).\n * Returns true if the name is valid for use as a CSS custom property.\n */\nexport function isValidPropertyName(name: string): boolean {\n  return VALID_PROPERTY_NAME_PATTERN.test(name);\n}\n\n/**\n * Result of parsing a property token.\n */\nexport interface ParsedPropertyToken {\n  /** The CSS custom property name (e.g., '--my-prop') */\n  cssName: string;\n  /** Whether this is a color property */\n  isColor: boolean;\n  /** Whether the token was valid */\n  isValid: boolean;\n  /** Error message if invalid */\n  error?: string;\n}\n\n// ============================================================================\n// Extraction Functions\n// ============================================================================\n\n/**\n * Check if styles object has local @properties definition.\n * Fast path: single property lookup.\n */\nexport function hasLocalProperties(styles: Styles): boolean {\n  return PROPERTIES_KEY in styles;\n}\n\n/**\n * Extract local @properties from styles object.\n * Returns null if no local properties (fast path).\n */\nexport function extractLocalProperties(\n  styles: Styles,\n): Record<string, PropertyDefinition> | null {\n  const properties = styles[PROPERTIES_KEY];\n  if (!properties || typeof properties !== 'object') {\n    return null;\n  }\n  return properties as Record<string, PropertyDefinition>;\n}\n\n// ============================================================================\n// Token Parsing Functions\n// ============================================================================\n\n/**\n * Parse a property token name and return the CSS property name and whether it's a color.\n * Supports tasty token syntax and validates the property name.\n *\n * Token formats:\n * - `$name` → { cssName: '--name', isColor: false }\n * - `#name` → { cssName: '--name-color', isColor: true }\n * - `--name` → { cssName: '--name', isColor: false } (legacy, auto-detect color by suffix)\n * - `name` → { cssName: '--name', isColor: false } (legacy)\n *\n * @param token - The property token to parse\n * @returns Parsed result with cssName, isColor, isValid, and optional error\n */\nexport function parsePropertyToken(token: string): ParsedPropertyToken {\n  if (!token || typeof token !== 'string') {\n    return {\n      cssName: '',\n      isColor: false,\n      isValid: false,\n      error: 'Property token must be a non-empty string',\n    };\n  }\n\n  let name: string;\n  let isColor: boolean;\n\n  if (token.startsWith('$')) {\n    // Regular property token: $name → --name\n    name = token.slice(1);\n    isColor = false;\n  } else if (token.startsWith('#')) {\n    // Color property token: #name → --name-color\n    name = token.slice(1);\n    isColor = true;\n  } else if (token.startsWith('--')) {\n    // Legacy format with -- prefix\n    name = token.slice(2);\n    isColor = token.endsWith('-color');\n  } else {\n    // Legacy format without prefix\n    name = token;\n    isColor = token.endsWith('-color');\n  }\n\n  // Validate the name\n  if (!name) {\n    return {\n      cssName: '',\n      isColor,\n      isValid: false,\n      error: 'Property name cannot be empty',\n    };\n  }\n\n  if (!isValidPropertyName(name)) {\n    return {\n      cssName: '',\n      isColor,\n      isValid: false,\n      error: `Invalid property name \"${name}\". Must start with a letter or underscore, followed by letters, digits, hyphens, or underscores.`,\n    };\n  }\n\n  // Build the CSS custom property name\n  // For #name tokens, we add -color suffix\n  // For legacy formats (--name-color or name-color), the name already includes -color\n  let cssName: string;\n  if (token.startsWith('#')) {\n    // Color token: #name → --name-color\n    cssName = `--${name}-color`;\n  } else {\n    // All other formats: just add -- prefix\n    cssName = `--${name}`;\n  }\n\n  return {\n    cssName,\n    isColor,\n    isValid: true,\n  };\n}\n\n// ============================================================================\n// Normalization Functions\n// ============================================================================\n\n/**\n * Normalize a property name to the CSS custom property format.\n *\n * @deprecated Use parsePropertyToken instead for proper token handling\n */\nexport function normalizePropertyName(name: string): string {\n  const result = parsePropertyToken(name);\n  return result.isValid ? result.cssName : `--${name}`;\n}\n\n/**\n * Normalize a property definition to a consistent string representation.\n * Used for comparing definitions to detect changes/conflicts.\n *\n * Keys are sorted alphabetically to ensure consistent comparison:\n * { inherits: true, syntax: '<color>' } === { syntax: '<color>', inherits: true }\n */\nexport function normalizePropertyDefinition(def: PropertyDefinition): string {\n  const normalized: Record<string, unknown> = {};\n\n  // Add properties in alphabetical order\n  if (def.inherits !== undefined) {\n    normalized.inherits = def.inherits;\n  }\n  if (def.initialValue !== undefined) {\n    normalized.initialValue = String(def.initialValue);\n  }\n  if (def.syntax !== undefined) {\n    normalized.syntax = def.syntax;\n  }\n\n  return JSON.stringify(normalized);\n}\n\n/**\n * Result of getEffectiveDefinition.\n */\nexport interface EffectiveDefinitionResult {\n  /** The CSS custom property name */\n  cssName: string;\n  /** The effective property definition */\n  definition: PropertyDefinition;\n  /** Whether this is a color property */\n  isColor: boolean;\n  /** Whether the token was valid */\n  isValid: boolean;\n  /** Error message if invalid */\n  error?: string;\n}\n\n/**\n * Get the effective property definition for a token.\n * For color tokens (#name), auto-sets syntax to '<color>' and defaults initialValue to 'transparent'.\n *\n * @param token - Property token ($name, #name, --name, or plain name)\n * @param userDefinition - User-provided definition options\n * @returns Effective definition with cssName, definition, isValid, and optional error\n */\nexport function getEffectiveDefinition(\n  token: string,\n  userDefinition: PropertyDefinition,\n): EffectiveDefinitionResult {\n  const parsed = parsePropertyToken(token);\n\n  if (!parsed.isValid) {\n    return {\n      cssName: '',\n      definition: userDefinition,\n      isColor: false,\n      isValid: false,\n      error: parsed.error,\n    };\n  }\n\n  if (parsed.isColor) {\n    // Color properties have fixed syntax and default initialValue\n    return {\n      cssName: parsed.cssName,\n      definition: {\n        syntax: '<color>', // Always '<color>' for color tokens, cannot be overridden\n        inherits: userDefinition.inherits, // Allow inherits to be customized\n        initialValue: userDefinition.initialValue ?? 'transparent', // Default to transparent\n      },\n      isColor: true,\n      isValid: true,\n    };\n  }\n\n  // Regular properties use the definition as-is\n  return {\n    cssName: parsed.cssName,\n    definition: userDefinition,\n    isColor: false,\n    isValid: true,\n  };\n}\n\n// ============================================================================\n// Color RGB Companion Helpers\n// ============================================================================\n\n/**\n * Extract RGB triplet string from a color initial value.\n * Used when auto-creating the companion `-rgb` property for color @property definitions.\n *\n * @param initialValue - The color property's initial value (e.g., 'rgb(255 255 255)', 'transparent', '#fff')\n * @returns Space-separated RGB triplet (e.g., '255 255 255'), defaults to '0 0 0'\n */\nexport function colorInitialValueToRgb(initialValue?: string | number): string {\n  if (initialValue == null) return '0 0 0';\n\n  const str = String(initialValue).trim();\n  if (!str || str === 'transparent') return '0 0 0';\n\n  const rgba = strToRgb(str);\n  if (rgba) {\n    const values = getRgbValuesFromRgbaString(rgba);\n    if (values.length >= 3) return values.slice(0, 3).join(' ');\n  }\n\n  return '0 0 0';\n}\n"],"mappings":";;;;;;;AAyBA,MAAM,8BAA8B;;;;;AAUpC,SAAgB,oBAAoB,MAAuB;AACzD,QAAO,4BAA4B,KAAK,KAAK;;;;;;;;;;;;;;;AA4D/C,SAAgB,mBAAmB,OAAoC;AACrE,KAAI,CAAC,SAAS,OAAO,UAAU,SAC7B,QAAO;EACL,SAAS;EACT,SAAS;EACT,SAAS;EACT,OAAO;EACR;CAGH,IAAI;CACJ,IAAI;AAEJ,KAAI,MAAM,WAAW,IAAI,EAAE;AAEzB,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU;YACD,MAAM,WAAW,IAAI,EAAE;AAEhC,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU;YACD,MAAM,WAAW,KAAK,EAAE;AAEjC,SAAO,MAAM,MAAM,EAAE;AACrB,YAAU,MAAM,SAAS,SAAS;QAC7B;AAEL,SAAO;AACP,YAAU,MAAM,SAAS,SAAS;;AAIpC,KAAI,CAAC,KACH,QAAO;EACL,SAAS;EACT;EACA,SAAS;EACT,OAAO;EACR;AAGH,KAAI,CAAC,oBAAoB,KAAK,CAC5B,QAAO;EACL,SAAS;EACT;EACA,SAAS;EACT,OAAO,0BAA0B,KAAK;EACvC;CAMH,IAAI;AACJ,KAAI,MAAM,WAAW,IAAI,CAEvB,WAAU,KAAK,KAAK;KAGpB,WAAU,KAAK;AAGjB,QAAO;EACL;EACA;EACA,SAAS;EACV;;;;;;;;;AAwBH,SAAgB,4BAA4B,KAAiC;CAC3E,MAAM,aAAsC,EAAE;AAG9C,KAAI,IAAI,aAAa,OACnB,YAAW,WAAW,IAAI;AAE5B,KAAI,IAAI,iBAAiB,OACvB,YAAW,eAAe,OAAO,IAAI,aAAa;AAEpD,KAAI,IAAI,WAAW,OACjB,YAAW,SAAS,IAAI;AAG1B,QAAO,KAAK,UAAU,WAAW;;;;;;;;;;AA2BnC,SAAgB,uBACd,OACA,gBAC2B;CAC3B,MAAM,SAAS,mBAAmB,MAAM;AAExC,KAAI,CAAC,OAAO,QACV,QAAO;EACL,SAAS;EACT,YAAY;EACZ,SAAS;EACT,SAAS;EACT,OAAO,OAAO;EACf;AAGH,KAAI,OAAO,QAET,QAAO;EACL,SAAS,OAAO;EAChB,YAAY;GACV,QAAQ;GACR,UAAU,eAAe;GACzB,cAAc,eAAe,gBAAgB;GAC9C;EACD,SAAS;EACT,SAAS;EACV;AAIH,QAAO;EACL,SAAS,OAAO;EAChB,YAAY;EACZ,SAAS;EACT,SAAS;EACV;;;;;;;;;AAcH,SAAgB,uBAAuB,cAAwC;AAC7E,KAAI,gBAAgB,KAAM,QAAO;CAEjC,MAAM,MAAM,OAAO,aAAa,CAAC,MAAM;AACvC,KAAI,CAAC,OAAO,QAAQ,cAAe,QAAO;CAE1C,MAAM,OAAO,SAAS,IAAI;AAC1B,KAAI,MAAM;EACR,MAAM,SAAS,2BAA2B,KAAK;AAC/C,MAAI,OAAO,UAAU,EAAG,QAAO,OAAO,MAAM,GAAG,EAAE,CAAC,KAAK,IAAI;;AAG7D,QAAO"}

package/dist/states/index.d.ts

@@ -0,0 +1,45 @@
+import "../styles/types.js";
+
+//#region src/states/index.d.ts
+/**
+ * Parsed advanced state information
+ */
+interface ParsedAdvancedState {
+  type: 'media' | 'container' | 'root' | 'own' | 'starting' | 'predefined' | 'modifier';
+  condition: string;
+  containerName?: string;
+  raw: string;
+  mediaType?: string;
+}
+/**
+ * Context for state parsing operations
+ */
+interface StateParserContext {
+  localPredefinedStates: Record<string, string>;
+  globalPredefinedStates: Record<string, string>;
+  isSubElement?: boolean;
+}
+/**
+ * At-rule context for CSS generation
+ */
+interface AtRuleContext {
+  media?: string[];
+  container?: {
+    name?: string;
+    condition: string;
+  }[];
+  startingStyle?: boolean;
+  rootStates?: string[];
+  negatedRootStates?: string[];
+}
+/**
+ * Configure global predefined states
+ */
+declare function setGlobalPredefinedStates(states: Record<string, string>): void;
+/**
+ * Get global predefined states
+ */
+declare function getGlobalPredefinedStates(): Record<string, string>;
+//#endregion
+export { AtRuleContext, ParsedAdvancedState, StateParserContext, getGlobalPredefinedStates, setGlobalPredefinedStates };
+//# sourceMappingURL=index.d.ts.map

package/dist/states/index.js

@@ -0,0 +1,389 @@
+import { isDevEnv } from "../utils/is-dev-env.js";
+import { hasStylesGenerated } from "../config.js";
+
+//#region src/states/index.ts
+/**
+* Advanced State Mapping - Predefined States Management
+*
+* This module handles global and local predefined states for the Tasty styling system.
+* See ADVANCED_STATE_MAPPING.md for full specification.
+*/
+const BUILTIN_STATES = new Set([
+	"@starting",
+	"@keyframes",
+	"@properties",
+	"@supports",
+	"@inherit"
+]);
+const RESERVED_PREFIXES = [
+	"@media",
+	"@root",
+	"@own",
+	"@(",
+	"@starting",
+	"@keyframes",
+	"@properties",
+	"@supports",
+	"@inherit"
+];
+let globalPredefinedStates = {};
+const emittedWarnings = /* @__PURE__ */ new Set();
+const devMode = isDevEnv();
+/**
+* Emit a warning only once
+*/
+function warnOnce(key, message) {
+	if (devMode && !emittedWarnings.has(key)) {
+		emittedWarnings.add(key);
+		console.warn(message);
+	}
+}
+/**
+* Configure global predefined states
+*/
+function setGlobalPredefinedStates(states) {
+	if (hasStylesGenerated()) {
+		const newStateNames = Object.keys(states).join(", ");
+		warnOnce(`dynamic-states:${newStateNames}`, `[Tasty] Cannot update predefined states after styles have been generated.\nThe new definition(s) for ${newStateNames} will be ignored.`);
+		return;
+	}
+	for (const [name, value] of Object.entries(states)) {
+		if (!/^@[A-Za-z][A-Za-z0-9-]*$/.test(name)) {
+			warnOnce(`invalid-state-name:${name}`, `[Tasty] Invalid predefined state name '${name}'. Must start with '@' followed by a letter.`);
+			continue;
+		}
+		if (BUILTIN_STATES.has(name)) {
+			warnOnce(`reserved-state:${name}`, `[Tasty] Cannot define predefined state '${name}'. This name is reserved for built-in functionality.`);
+			continue;
+		}
+		if (name === "@media" || name === "@root" || name === "@own" || name.startsWith("@(")) {
+			warnOnce(`reserved-prefix:${name}`, `[Tasty] Cannot define predefined state '${name}'. This prefix is reserved for built-in functionality.`);
+			continue;
+		}
+		const crossRefs = extractPredefinedStateRefs(value);
+		if (crossRefs.length > 0) {
+			warnOnce(`cross-ref:${name}`, `[Tasty] Predefined state '${name}' references another predefined state '${crossRefs[0]}'.\nPredefined states cannot reference each other. Use the full definition instead.`);
+			continue;
+		}
+		if (globalPredefinedStates[name] && globalPredefinedStates[name] !== value) warnOnce(`duplicate-state:${name}`, `[Tasty] Duplicate predefined state '${name}' in configure(). The last definition will be used.`);
+		globalPredefinedStates[name] = value;
+	}
+}
+/**
+* Get global predefined states
+*/
+function getGlobalPredefinedStates() {
+	return globalPredefinedStates;
+}
+/**
+* Regex to match predefined state references in a string
+* Matches @name that is NOT followed by ( or : and is a complete word
+* Uses word boundary and negative lookahead
+*/
+const PREDEFINED_STATE_PATTERN = /@([A-Za-z][A-Za-z0-9-]*)(?![A-Za-z0-9-:(])/g;
+/**
+* Extract predefined state references from a string
+*/
+function extractPredefinedStateRefs(value) {
+	const matches = value.matchAll(PREDEFINED_STATE_PATTERN);
+	const refs = [];
+	for (const match of matches) {
+		const stateName = "@" + match[1];
+		if (!BUILTIN_STATES.has(stateName) && !refs.includes(stateName)) refs.push(stateName);
+	}
+	return refs;
+}
+/**
+* Check if a state key is a predefined state reference
+*/
+function isPredefinedStateRef(stateKey) {
+	if (!stateKey.startsWith("@")) return false;
+	if (BUILTIN_STATES.has(stateKey)) return false;
+	for (const prefix of RESERVED_PREFIXES) if (stateKey === prefix || stateKey.startsWith(prefix)) {
+		if (stateKey === "@media" || stateKey.startsWith("@media(") || stateKey.startsWith("@media:")) return false;
+		if (stateKey === "@root" || stateKey.startsWith("@root(")) return false;
+		if (stateKey === "@own" || stateKey.startsWith("@own(")) return false;
+		if (stateKey.startsWith("@(")) return false;
+	}
+	return /^@[A-Za-z][A-Za-z0-9-]*$/.test(stateKey);
+}
+/**
+* Extract local predefined states from a styles object
+* Local predefined states are top-level keys starting with @ that have string values
+* and are valid predefined state names (not built-in like @media, @root, etc.)
+*/
+function extractLocalPredefinedStates(styles) {
+	const localStates = {};
+	if (!styles || typeof styles !== "object") return localStates;
+	for (const [key, value] of Object.entries(styles)) if (key.startsWith("@") && typeof value === "string") {
+		if (!/^@[A-Za-z][A-Za-z0-9-]*$/.test(key)) continue;
+		if (BUILTIN_STATES.has(key)) continue;
+		if (key === "@media" || key === "@root" || key === "@own" || key.startsWith("@(")) continue;
+		const crossRefs = extractPredefinedStateRefs(value);
+		if (crossRefs.length > 0) {
+			warnOnce(`local-cross-ref:${key}`, `[Tasty] Predefined state '${key}' references another predefined state '${crossRefs[0]}'.\nPredefined states cannot reference each other. Use the full definition instead.`);
+			continue;
+		}
+		localStates[key] = value;
+	}
+	return localStates;
+}
+/**
+* Create a state parser context from styles
+*/
+function createStateParserContext(styles, isSubElement) {
+	return {
+		localPredefinedStates: styles ? extractLocalPredefinedStates(styles) : {},
+		globalPredefinedStates: getGlobalPredefinedStates(),
+		isSubElement
+	};
+}
+/**
+* Resolve a predefined state reference to its value
+* Returns the resolved value or null if not found
+*/
+function resolvePredefinedState(stateKey, ctx) {
+	if (ctx.localPredefinedStates[stateKey]) return ctx.localPredefinedStates[stateKey];
+	if (ctx.globalPredefinedStates[stateKey]) return ctx.globalPredefinedStates[stateKey];
+	warnOnce(`undefined-state:${stateKey}`, `[Tasty] Undefined predefined state '${stateKey}'.\nDefine it in configure({ states: { '${stateKey}': '...' } }) or in the component's styles.`);
+	return null;
+}
+/**
+* Expand dimension shorthands in a condition string
+* w -> width, h -> height, is -> inline-size, bs -> block-size
+*/
+function expandDimensionShorthands(condition) {
+	let result = condition;
+	result = result.replace(/\bw\b/g, "width");
+	result = result.replace(/\bh\b/g, "height");
+	result = result.replace(/\bis\b/g, "inline-size");
+	result = result.replace(/\bbs\b/g, "block-size");
+	return result;
+}
+/**
+* Convert tasty units in a string (e.g., 40x -> calc(var(--gap) * 40))
+*/
+function expandTastyUnits(value) {
+	return value.replace(/(\d+(?:\.\d+)?)\s*x\b/g, (_, num) => {
+		return `calc(var(--gap) * ${num})`;
+	});
+}
+/**
+* Parse an advanced state key and return its type and components
+*/
+function parseAdvancedState(stateKey, ctx) {
+	const raw = stateKey;
+	if (stateKey === "@starting") return {
+		type: "starting",
+		condition: "",
+		raw
+	};
+	if (stateKey.startsWith("@media:")) {
+		const mediaType = stateKey.slice(7);
+		if (![
+			"all",
+			"screen",
+			"print",
+			"speech"
+		].includes(mediaType)) warnOnce(`unknown-media-type:${mediaType}`, `[Tasty] Unknown media type '${mediaType}'. Valid types: all, screen, print, speech.`);
+		return {
+			type: "media",
+			condition: "",
+			mediaType,
+			raw
+		};
+	}
+	if (stateKey.startsWith("@media(")) {
+		const endParen = findMatchingParen(stateKey, 6);
+		if (endParen === -1) {
+			warnOnce(`unclosed-media:${stateKey}`, `[Tasty] Unclosed media query '${stateKey}'. Missing closing parenthesis.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		let condition = stateKey.slice(7, endParen);
+		if (!condition.trim()) {
+			warnOnce(`empty-media:${stateKey}`, `[Tasty] Empty media query condition '${stateKey}'.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		condition = expandDimensionShorthands(condition);
+		condition = expandTastyUnits(condition);
+		return {
+			type: "media",
+			condition,
+			raw
+		};
+	}
+	if (stateKey.startsWith("@root(")) {
+		const endParen = findMatchingParen(stateKey, 5);
+		if (endParen === -1) {
+			warnOnce(`unclosed-root:${stateKey}`, `[Tasty] Unclosed root state '${stateKey}'. Missing closing parenthesis.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		const condition = stateKey.slice(6, endParen);
+		if (!condition.trim()) {
+			warnOnce(`empty-root:${stateKey}`, `[Tasty] Empty root state condition '${stateKey}'.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		return {
+			type: "root",
+			condition,
+			raw
+		};
+	}
+	if (stateKey.startsWith("@own(")) {
+		const endParen = findMatchingParen(stateKey, 4);
+		if (endParen === -1) {
+			warnOnce(`unclosed-own:${stateKey}`, `[Tasty] Unclosed own state '${stateKey}'. Missing closing parenthesis.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		const condition = stateKey.slice(5, endParen);
+		if (!condition.trim()) {
+			warnOnce(`empty-own:${stateKey}`, `[Tasty] Empty own state condition '${stateKey}'.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		if (!ctx.isSubElement) {
+			warnOnce(`own-outside-subelement:${stateKey}`, `[Tasty] @own(${condition}) used outside sub-element context.\n@own() is equivalent to '${condition}' at the root level. Did you mean to use it inside a sub-element?`);
+			return {
+				type: "modifier",
+				condition,
+				raw
+			};
+		}
+		return {
+			type: "own",
+			condition,
+			raw
+		};
+	}
+	if (stateKey.startsWith("@(")) {
+		const endParen = findMatchingParen(stateKey, 1);
+		if (endParen === -1) {
+			warnOnce(`unclosed-container:${stateKey}`, `[Tasty] Unclosed container query '${stateKey}'. Missing closing parenthesis.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		const content = stateKey.slice(2, endParen);
+		if (!content.trim()) {
+			warnOnce(`empty-container:${stateKey}`, `[Tasty] Empty container query '${stateKey}'.`);
+			return {
+				type: "modifier",
+				condition: stateKey,
+				raw
+			};
+		}
+		const commaIndex = findTopLevelComma(content);
+		let containerName;
+		let condition;
+		if (commaIndex !== -1) {
+			containerName = content.slice(0, commaIndex).trim();
+			condition = content.slice(commaIndex + 1).trim();
+		} else condition = content.trim();
+		if (condition.startsWith("$")) {
+			const styleCondition = parseStyleQuery(condition);
+			if (!styleCondition) {
+				warnOnce(`invalid-style-query:${stateKey}`, `[Tasty] Invalid style query '${condition}' in container query.`);
+				return {
+					type: "modifier",
+					condition: stateKey,
+					raw
+				};
+			}
+			condition = styleCondition;
+		} else if (/^[a-zA-Z][\w-]*\s*\(/.test(condition)) {} else {
+			condition = expandDimensionShorthands(condition);
+			condition = expandTastyUnits(condition);
+		}
+		return {
+			type: "container",
+			condition,
+			containerName,
+			raw
+		};
+	}
+	if (isPredefinedStateRef(stateKey)) {
+		const resolved = resolvePredefinedState(stateKey, ctx);
+		if (resolved) return {
+			...parseAdvancedState(resolved, ctx),
+			raw
+		};
+		return {
+			type: "modifier",
+			condition: stateKey,
+			raw
+		};
+	}
+	return {
+		type: "modifier",
+		condition: stateKey,
+		raw
+	};
+}
+/**
+* Parse a style query condition (e.g., $compact, $variant=compact, $variant="very compact")
+*/
+function parseStyleQuery(condition) {
+	const query = condition.slice(1);
+	if (/[<>]/.test(query)) {
+		warnOnce(`style-query-comparison:${condition}`, `[Tasty] Style queries only support equality. '${condition}' is invalid. Use '${condition.split(/[<>]/)[0]}=...' instead.`);
+		return null;
+	}
+	const eqIndex = query.indexOf("=");
+	if (eqIndex === -1) return `style(--${query})`;
+	const propName = query.slice(0, eqIndex).trim();
+	let value = query.slice(eqIndex + 1).trim();
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) {} else value = `"${value}"`;
+	value = expandTastyUnits(value);
+	return `style(--${propName}: ${value})`;
+}
+/**
+* Find the index of the first comma at parentheses depth 0.
+* Returns -1 if no top-level comma is found.
+* This prevents splitting on commas inside function calls like scroll-state(a, b).
+*/
+function findTopLevelComma(s) {
+	let depth = 0;
+	for (let i = 0; i < s.length; i++) if (s[i] === "(") depth++;
+	else if (s[i] === ")") depth--;
+	else if (s[i] === "," && depth === 0) return i;
+	return -1;
+}
+function findMatchingParen(str, startIndex) {
+	let depth = 1;
+	let i = startIndex + 1;
+	while (i < str.length && depth > 0) {
+		if (str[i] === "(") depth++;
+		else if (str[i] === ")") depth--;
+		i++;
+	}
+	return depth === 0 ? i - 1 : -1;
+}
+
+//#endregion
+export { createStateParserContext, expandDimensionShorthands, expandTastyUnits, extractLocalPredefinedStates, extractPredefinedStateRefs, findTopLevelComma, getGlobalPredefinedStates, parseAdvancedState, resolvePredefinedState, setGlobalPredefinedStates };
+//# sourceMappingURL=index.js.map