@yahoo/uds 3.156.1 → 3.157.0

package/dist/automated-config/dist/utils/index.d.cts

@@ -1,24 +1,33 @@
 
+import { AtomicState, INTERACTIVE_ATOMICS, InteractiveAtomic, MAX_MODIFIERS_PER_COMPOUND, MODIFIER_ATOMICS, ModifierAtomic, isAtomicState, isInteractiveAtomic, isModifierAtomic } from "../types/StateAxis.cjs";
 import { ArbitraryFixtures, InferArbitraryType } from "../../../fixtures/dist/index.cjs";
-import { ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, PossibleStatesWithRest, SubComponentConfig, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.cjs";
 import { ConfigurablePropertiesName, SelectedConfigurableProperty, configurableProperties } from "../properties.cjs";
+import { ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, PossibleStatesWithRest, SubComponentConfig, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.cjs";
+import { VariableState } from "../types/ConfigSchema.cjs";
 import { ComponentSchema, buildConfigSchema, findFixtureType, findFixtureTypeForValue } from "./buildConfigSchema.cjs";
+import { canonicalizeStateKey, splitStateKey } from "./canonicalizeStateKey.cjs";
 import { cartesianProduct } from "./cartesianProduct.cjs";
 import { coalesceConfigVariant } from "./coalesceConfigVariant.cjs";
 import { getConfigDefaultValue, isConfigDefaultValue } from "./defaults.cjs";
 import { generateDefaultClassName } from "./generateDefaultClassName.cjs";
 import { generateKeyFromFlatConfigPath } from "./generateKeyFromFlatConfigPath.cjs";
 import { generateSchemaKey } from "./generateSchemaKey.cjs";
+import { getConfigComponentVariant } from "./getConfigComponentVariant.cjs";
 import { getConfigVariantComponentStates, getConfigVariantComponentStatesMatrix } from "./getConfigVariantComponentStatesMatrix.cjs";
 import { getConfigVariantProperties } from "./getConfigVariantProperties.cjs";
 import { getConfigVariantPseudoStates } from "./getConfigVariantPseudoStates.cjs";
 import { getConfigVariants } from "./getConfigVariants.cjs";
 import { PaginationWidthConfig, getPaginationControlWidthPx, syncPaginationWidthVarForSize } from "./getPaginationControlWidthPx.cjs";
+import { getStateDocsClass, getStateSelector, isKnownStateAtom } from "./pseudoStateSelectors.cjs";
+import { resolvePropertyStates } from "./resolvePropertyStates.cjs";
+import { PropertyStates, StateSlot, propertyUsesPerStateEnabled, resolveSlotByCascade } from "./resolveSlotByCascade.cjs";
 import { getConfigSubcomponents } from "./subcomponents.cjs";
+import { isVariantConfigWithComponentStates, isVariantConfigWithProperties } from "./variantConfigGuards.cjs";
 
 //#region ../automated-config/dist/utils/index.d.ts
 //#region src/utils/index.d.ts
 type ThemeFn = (path: string) => string;
+type EmitMode = 'exhaustive' | 'selective';
 declare const statePseudoMapDocsMode: Record<PossibleStatesWithRest, string>;
 /**
  * Forces button borders to use box-shadow instead of border properties.
@@ -59,6 +68,15 @@ declare function generateClassName({
   layer: string;
   layerOptionalPseudoSelector?: string;
 }): string;
+/**
+ * Builds the per-state resolution map for a per-componentState OVERRIDE in
+ * exhaustive mode: the universal layer's state map with the override's ENABLED
+ * (and `rest`) slots layered on top. An unset or disabled override slot defers
+ * to the universal layer's value, so `resolveSlotByCascade` picks the
+ * most-specific *enabled* slot across both layers (override winning ties) rather
+ * than collapsing every unset state to the override's own `rest`.
+ */
+declare function mergeUniversalUnderOverride(universal: VariableState, override: VariableState): VariableState;
 declare function generateDeclaration({
   componentName,
   subComponentName,
@@ -71,10 +89,15 @@ declare function generateDeclaration({
   schema,
   propertyKey,
   originalPropertyDefinition,
+  declaredStates,
+  layerUsesAtomicStates,
   theme,
   currentStyles,
   previewOptions,
-  excludedPseudoStates
+  excludedPseudoStates,
+  emit,
+  fallbackStateMap,
+  bumpRootSpecificity
 }: {
   componentName: string;
   subComponentName?: string;
@@ -87,25 +110,39 @@ declare function generateDeclaration({
   schema: unknown;
   propertyKey: string;
   originalPropertyDefinition: SelectedConfigurableProperty<ConfigurablePropertiesName, any>;
+  declaredStates: ReadonlySet<string>;
+  layerUsesAtomicStates: boolean;
   theme: ThemeFn;
   currentStyles: Readonly<Record<string, Record<string, string>>>;
   previewOptions?: {
     generatePseudoStateClassModifier?: boolean;
   };
   excludedPseudoStates?: readonly PossibleStates[];
+  emit?: EmitMode;
+  fallbackStateMap?: VariableState;
+  bumpRootSpecificity?: boolean;
 }): Record<string, Record<string, string>>;
 declare function generateConfigStyles<C extends ComponentConfig>(config: C, schema: ComponentSchema<ComponentConfig>, theme: ThemeFn, previewOptions?: {
   generatePseudoStateClassModifier: boolean;
-}): Record<string, Record<string, string>>;
+}, emit?: EmitMode): Record<string, Record<string, string>>;
 /**
- * @param config - Component configuration (Button, IconButton, etc.)
- * @param schema - Production schema with defaults and variables
- * @param theme - Tailwind theme function to resolve design tokens
- * @param previewOptions - Options for generating preview mode class modifiers
- * @returns CSS styles object with grouped selectors for default aliases
+ * Public entry point. Generates a component's CSS, emitting each declared state
+ * as its own rule (one selector per rule) so the cascade is carried entirely by
+ * per-rule specificity — which CSS minifiers preserve.
+ *
+ * An earlier optimization merged rules sharing a declaration block into a single
+ * comma-separated selector list (to avoid repeating invariant declarations per
+ * state). It was removed: a minifier's forgiving-`:is()` rewrite — applied to a
+ * comma-separated list that contains `:has()` when targeting browsers without
+ * native `:has()` support — collapses the list to its single highest
+ * specificity, inflating the weakest selector (`rest`) above genuinely
+ * customized states and corrupting the cascade. Separate rules never form such a
+ * list, so minifiers leave their specificity intact. (gzip already collapses the
+ * repeated declaration blocks, so the shipped-size cost is minimal.)
  */
 declare const generateStyles: (config: ComponentConfig, schema: ComponentSchema<ComponentConfig>, theme: ThemeFn, previewOptions: {
   generatePseudoStateClassModifier: boolean;
+  emit?: EmitMode;
 }) => Record<string, Record<string, string>>;
 declare function createConfigurableProperty<C extends ConfigurablePropertiesName, O extends string, T extends (typeof configurableProperties)[C]['possibleFixtures'], V extends readonly (readonly unknown[])[] = readonly (readonly unknown[])[]>(prop: {
   name: C;
@@ -113,8 +150,9 @@ declare function createConfigurableProperty<C extends ConfigurablePropertiesName
   values: V;
   defaults: { [K in O]: V[number][number] | (Extract<T[number], ArbitraryFixtures> extends never ? never : InferArbitraryType<Extract<T[number], ArbitraryFixtures>>) };
   label: string;
-  skipRestState?: boolean;
+  skipRestState?: boolean; /** @deprecated Prefer layer-level `atomicStates` + `excludeAtomics`. */
   pseudoStates?: PossibleStates[];
+  excludeAtomics?: AtomicState[];
   supportsCustom?: boolean;
   layerReference?: {
     variablePath: string;
@@ -143,24 +181,36 @@ declare function createVariantConfigWithComponentStates(config: {
   default: string;
   options: readonly string[];
   componentStates: Record<string, ComponentStateConfig>;
+  layers?: {
+    root: LayerConfig;
+  } & Record<string, LayerConfig>;
 }): VariantConfigWithComponentStates;
-declare function createComponentStates(config: {
+declare function createComponentStates<T extends {
   label: string;
-  options: string[];
+  options: readonly string[];
   excludePseudoStatesForOptions?: Partial<Record<string, readonly PossibleStates[]>>;
-  layers: {
+  layers?: {
     root: LayerConfig;
   } & Record<string, LayerConfig>;
-}): ComponentStateConfig;
-declare function createLayerConfig(config: {
+}>(config: T): T;
+declare function createLayerConfig<T extends {
   label: string;
   pseudoSelector?: string;
+  /**
+   * Atomic states this layer can style. Properties on the layer pick up rest,
+   * each declared atom, and every auto-generated compound up to
+   * `MAX_MODIFIERS_PER_COMPOUND` modifiers optionally combined with one
+   * interactive (skipping pairs the browser suppresses). Properties opt out
+   * of individual atoms via `excludeAtomics`. See {@link LayerConfig} for the
+   * full breakdown.
+   */
+  atomicStates?: AtomicState[];
   properties: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
-}): LayerConfig;
+}>(config: T): T;
 declare function createSubComponentConfig(config: {
   label: string;
   description: string;
   variants: Record<string, VariantConfigWithProperties | VariantConfigWithComponentStates>;
 }): SubComponentConfig; //#endregion
 //#endregion
-export { applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, statePseudoMapDocsMode };
+export { EmitMode, applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, mergeUniversalUnderOverride, statePseudoMapDocsMode };

package/dist/automated-config/dist/utils/index.d.ts

@@ -1,24 +1,33 @@
 
+import { AtomicState, INTERACTIVE_ATOMICS, InteractiveAtomic, MAX_MODIFIERS_PER_COMPOUND, MODIFIER_ATOMICS, ModifierAtomic, isAtomicState, isInteractiveAtomic, isModifierAtomic } from "../types/StateAxis.js";
 import { ArbitraryFixtures, InferArbitraryType } from "../../../fixtures/dist/index.js";
-import { ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, PossibleStatesWithRest, SubComponentConfig, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.js";
 import { ConfigurablePropertiesName, SelectedConfigurableProperty, configurableProperties } from "../properties.js";
+import { ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, PossibleStatesWithRest, SubComponentConfig, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.js";
+import { VariableState } from "../types/ConfigSchema.js";
 import { ComponentSchema, buildConfigSchema, findFixtureType, findFixtureTypeForValue } from "./buildConfigSchema.js";
+import { canonicalizeStateKey, splitStateKey } from "./canonicalizeStateKey.js";
 import { cartesianProduct } from "./cartesianProduct.js";
 import { coalesceConfigVariant } from "./coalesceConfigVariant.js";
 import { getConfigDefaultValue, isConfigDefaultValue } from "./defaults.js";
 import { generateDefaultClassName } from "./generateDefaultClassName.js";
 import { generateKeyFromFlatConfigPath } from "./generateKeyFromFlatConfigPath.js";
 import { generateSchemaKey } from "./generateSchemaKey.js";
+import { getConfigComponentVariant } from "./getConfigComponentVariant.js";
 import { getConfigVariantComponentStates, getConfigVariantComponentStatesMatrix } from "./getConfigVariantComponentStatesMatrix.js";
 import { getConfigVariantProperties } from "./getConfigVariantProperties.js";
 import { getConfigVariantPseudoStates } from "./getConfigVariantPseudoStates.js";
 import { getConfigVariants } from "./getConfigVariants.js";
 import { PaginationWidthConfig, getPaginationControlWidthPx, syncPaginationWidthVarForSize } from "./getPaginationControlWidthPx.js";
+import { getStateDocsClass, getStateSelector, isKnownStateAtom } from "./pseudoStateSelectors.js";
+import { resolvePropertyStates } from "./resolvePropertyStates.js";
+import { PropertyStates, StateSlot, propertyUsesPerStateEnabled, resolveSlotByCascade } from "./resolveSlotByCascade.js";
 import { getConfigSubcomponents } from "./subcomponents.js";
+import { isVariantConfigWithComponentStates, isVariantConfigWithProperties } from "./variantConfigGuards.js";
 
 //#region ../automated-config/dist/utils/index.d.ts
 //#region src/utils/index.d.ts
 type ThemeFn = (path: string) => string;
+type EmitMode = 'exhaustive' | 'selective';
 declare const statePseudoMapDocsMode: Record<PossibleStatesWithRest, string>;
 /**
  * Forces button borders to use box-shadow instead of border properties.
@@ -59,6 +68,15 @@ declare function generateClassName({
   layer: string;
   layerOptionalPseudoSelector?: string;
 }): string;
+/**
+ * Builds the per-state resolution map for a per-componentState OVERRIDE in
+ * exhaustive mode: the universal layer's state map with the override's ENABLED
+ * (and `rest`) slots layered on top. An unset or disabled override slot defers
+ * to the universal layer's value, so `resolveSlotByCascade` picks the
+ * most-specific *enabled* slot across both layers (override winning ties) rather
+ * than collapsing every unset state to the override's own `rest`.
+ */
+declare function mergeUniversalUnderOverride(universal: VariableState, override: VariableState): VariableState;
 declare function generateDeclaration({
   componentName,
   subComponentName,
@@ -71,10 +89,15 @@ declare function generateDeclaration({
   schema,
   propertyKey,
   originalPropertyDefinition,
+  declaredStates,
+  layerUsesAtomicStates,
   theme,
   currentStyles,
   previewOptions,
-  excludedPseudoStates
+  excludedPseudoStates,
+  emit,
+  fallbackStateMap,
+  bumpRootSpecificity
 }: {
   componentName: string;
   subComponentName?: string;
@@ -87,25 +110,39 @@ declare function generateDeclaration({
   schema: unknown;
   propertyKey: string;
   originalPropertyDefinition: SelectedConfigurableProperty<ConfigurablePropertiesName, any>;
+  declaredStates: ReadonlySet<string>;
+  layerUsesAtomicStates: boolean;
   theme: ThemeFn;
   currentStyles: Readonly<Record<string, Record<string, string>>>;
   previewOptions?: {
     generatePseudoStateClassModifier?: boolean;
   };
   excludedPseudoStates?: readonly PossibleStates[];
+  emit?: EmitMode;
+  fallbackStateMap?: VariableState;
+  bumpRootSpecificity?: boolean;
 }): Record<string, Record<string, string>>;
 declare function generateConfigStyles<C extends ComponentConfig>(config: C, schema: ComponentSchema<ComponentConfig>, theme: ThemeFn, previewOptions?: {
   generatePseudoStateClassModifier: boolean;
-}): Record<string, Record<string, string>>;
+}, emit?: EmitMode): Record<string, Record<string, string>>;
 /**
- * @param config - Component configuration (Button, IconButton, etc.)
- * @param schema - Production schema with defaults and variables
- * @param theme - Tailwind theme function to resolve design tokens
- * @param previewOptions - Options for generating preview mode class modifiers
- * @returns CSS styles object with grouped selectors for default aliases
+ * Public entry point. Generates a component's CSS, emitting each declared state
+ * as its own rule (one selector per rule) so the cascade is carried entirely by
+ * per-rule specificity — which CSS minifiers preserve.
+ *
+ * An earlier optimization merged rules sharing a declaration block into a single
+ * comma-separated selector list (to avoid repeating invariant declarations per
+ * state). It was removed: a minifier's forgiving-`:is()` rewrite — applied to a
+ * comma-separated list that contains `:has()` when targeting browsers without
+ * native `:has()` support — collapses the list to its single highest
+ * specificity, inflating the weakest selector (`rest`) above genuinely
+ * customized states and corrupting the cascade. Separate rules never form such a
+ * list, so minifiers leave their specificity intact. (gzip already collapses the
+ * repeated declaration blocks, so the shipped-size cost is minimal.)
  */
 declare const generateStyles: (config: ComponentConfig, schema: ComponentSchema<ComponentConfig>, theme: ThemeFn, previewOptions: {
   generatePseudoStateClassModifier: boolean;
+  emit?: EmitMode;
 }) => Record<string, Record<string, string>>;
 declare function createConfigurableProperty<C extends ConfigurablePropertiesName, O extends string, T extends (typeof configurableProperties)[C]['possibleFixtures'], V extends readonly (readonly unknown[])[] = readonly (readonly unknown[])[]>(prop: {
   name: C;
@@ -113,8 +150,9 @@ declare function createConfigurableProperty<C extends ConfigurablePropertiesName
   values: V;
   defaults: { [K in O]: V[number][number] | (Extract<T[number], ArbitraryFixtures> extends never ? never : InferArbitraryType<Extract<T[number], ArbitraryFixtures>>) };
   label: string;
-  skipRestState?: boolean;
+  skipRestState?: boolean; /** @deprecated Prefer layer-level `atomicStates` + `excludeAtomics`. */
   pseudoStates?: PossibleStates[];
+  excludeAtomics?: AtomicState[];
   supportsCustom?: boolean;
   layerReference?: {
     variablePath: string;
@@ -143,24 +181,36 @@ declare function createVariantConfigWithComponentStates(config: {
   default: string;
   options: readonly string[];
   componentStates: Record<string, ComponentStateConfig>;
+  layers?: {
+    root: LayerConfig;
+  } & Record<string, LayerConfig>;
 }): VariantConfigWithComponentStates;
-declare function createComponentStates(config: {
+declare function createComponentStates<T extends {
   label: string;
-  options: string[];
+  options: readonly string[];
   excludePseudoStatesForOptions?: Partial<Record<string, readonly PossibleStates[]>>;
-  layers: {
+  layers?: {
     root: LayerConfig;
   } & Record<string, LayerConfig>;
-}): ComponentStateConfig;
-declare function createLayerConfig(config: {
+}>(config: T): T;
+declare function createLayerConfig<T extends {
   label: string;
   pseudoSelector?: string;
+  /**
+   * Atomic states this layer can style. Properties on the layer pick up rest,
+   * each declared atom, and every auto-generated compound up to
+   * `MAX_MODIFIERS_PER_COMPOUND` modifiers optionally combined with one
+   * interactive (skipping pairs the browser suppresses). Properties opt out
+   * of individual atoms via `excludeAtomics`. See {@link LayerConfig} for the
+   * full breakdown.
+   */
+  atomicStates?: AtomicState[];
   properties: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
-}): LayerConfig;
+}>(config: T): T;
 declare function createSubComponentConfig(config: {
   label: string;
   description: string;
   variants: Record<string, VariantConfigWithProperties | VariantConfigWithComponentStates>;
 }): SubComponentConfig; //#endregion
 //#endregion
-export { applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, statePseudoMapDocsMode };
+export { EmitMode, applyBoxShadowBorder, createComponentStates, createConfigurableProperty, createLayerConfig, createSubComponentConfig, createVariantConfig, createVariantConfigWithComponentStates, createVariantConfigWithProperties, generateClassName, generateConfigStyles, generateDeclaration, generateStyles, mergeUniversalUnderOverride, statePseudoMapDocsMode };