@graphprotocol/gds-css 0.1.1 → 0.2.0

package/src/component-registry.ts

@@ -1,5 +1,3 @@
-import { objectEntries } from 'ts-extras'
-
 import { camelToKebab, type DeepRecord } from '@graphprotocol/gds-utils'
 
 import type {
@@ -14,45 +12,85 @@ import type {
 
 export type CSSPropsConfig = Record<string, CSSPropDefinition>
 
-type CSSProp<T extends CSSPropDefinition = CSSPropDefinition> = T & {
+type CSSProp<Def extends CSSPropDefinition = CSSPropDefinition> = Def & {
   readonly name: string
   readonly kebabName: string
-  readonly initialValue: CSSPropType<T>
+  /** The container name to use in style queries for this prop. */
+  readonly containerName: string
+  /** The CSS custom property that holds this prop's value (e.g. `--gds-button-size`). */
+  readonly cssProperty: string
+  /** The initial value of this prop's CSS custom property. */
+  readonly initialValue: CSSPropType<Def>
+  /** Whether this prop is defined or overridden in this component (not inherited via `extends`). */
+  readonly own: boolean
+  /** The data attribute used by `useCSSPropsPolyfill` (e.g. `data-gds-prop-polyfill-size`). */
+  readonly polyfillAttribute: string
 }
 
-type CSSProps<P extends CSSPropsConfig> = {
-  readonly [K in keyof P]: P[K] & CSSProp<P[K]>
+type CSSProps<Props extends CSSPropsConfig> = {
+  readonly [K in keyof Props]: Props[K] & CSSProp<Props[K]>
 }
 
-type VarsConfig = Record<string, VarCSS>
+type IsolateOption = true | 'allow-inheritance' | false
+
 type VarCSS = string | DeepRecord<string>
+type VarsConfig = Record<string, VarCSS>
 
-export class GDSComponent<P extends CSSPropsConfig = CSSPropsConfig, A extends boolean = boolean> {
+export class GDSComponent<
+  Props extends CSSPropsConfig = CSSPropsConfig,
+  AddonCompatible extends boolean = boolean,
+> {
   readonly name: string
   readonly kebabName: string
   readonly className: string
-  readonly containerName: string | null
-  readonly addonCompatible: A
-  readonly cssProps: CSSProps<P>
+  readonly containerName: string
+  readonly extends: GDSComponent | undefined
+  readonly isolate: IsolateOption
+  readonly addonCompatible: AddonCompatible
+  readonly cssProps: CSSProps<Props>
   readonly vars: VarsConfig | undefined
 
   constructor(
     name: string,
     config?: {
-      containerName?: string | null | undefined
-      addonCompatible?: A | undefined
-      cssProps?: P | undefined
+      extends?: GDSComponent | undefined
+      isolate?: IsolateOption | undefined
+      addonCompatible?: AddonCompatible | undefined
+      cssProps?: Props | undefined
       vars?: VarsConfig | undefined
     },
   ) {
     this.name = name
     this.kebabName = camelToKebab(name)
     this.className = `gds-${this.kebabName}`
-    this.containerName = config?.containerName !== undefined ? config.containerName : this.className
-    this.addonCompatible = (config?.addonCompatible ?? false) as A
+    this.containerName = `gds-${this.kebabName}`
+    this.extends = config?.extends
+    this.isolate = config?.isolate ?? (this.extends ? false : true)
+    this.addonCompatible = (config?.addonCompatible ?? false) as AddonCompatible
+    this.vars = config?.vars
+
+    // Merge `cssProps` from parent with own, allowing `null` to remove inherited props
+    const parentCSSProps = this.extends?.cssProps ?? {}
+    const ownCSSProps = (config?.cssProps ?? {}) as Props
+    const ownPropNames = new Set(Object.keys(ownCSSProps))
+    const mergedCSSProps = new Map<string, CSSPropDefinition>()
+    for (const [propName, prop] of Object.entries(parentCSSProps)) {
+      if (ownCSSProps[propName] !== null) {
+        mergedCSSProps.set(propName, prop)
+      }
+    }
+    for (const [propName, prop] of Object.entries(ownCSSProps)) {
+      if (prop !== null) {
+        mergedCSSProps.set(propName, prop)
+      }
+    }
+
     this.cssProps = Object.freeze(
       Object.fromEntries(
-        objectEntries(config?.cssProps ?? ({} as P)).map(([propName, prop]) => {
+        [...mergedCSSProps.entries()].map(([propName, prop]) => {
+          const kebabName = camelToKebab(propName)
+          const own = ownPropNames.has(propName)
+          const parentProp = parentCSSProps[propName]
           const initialValue =
             prop.defaultValue ??
             (() => {
@@ -74,21 +112,35 @@ export class GDSComponent<P extends CSSPropsConfig = CSSPropsConfig, A extends b
             {
               ...prop,
               name: propName,
-              kebabName: camelToKebab(propName),
+              kebabName,
+              // Inherited props keep their parent's `containerName` and `cssProperty`
+              containerName: (!own && parentProp?.containerName) || this.containerName,
+              cssProperty:
+                (!own && parentProp?.cssProperty) || `--gds-${this.kebabName}-${kebabName}`,
               initialValue,
+              own,
+              polyfillAttribute: `data-gds-prop-polyfill-${kebabName}`,
             },
           ]
         }),
       ),
-    ) as CSSProps<P>
-    this.vars = config?.vars
+    ) as unknown as CSSProps<Props>
   }
 
-  getCSSPropByName<T extends keyof P & string>(name: T): CSSProps<P>[T] {
-    const prop = this.cssProps[name]
-    if (!prop) {
-      throw new Error(`Unknown CSS prop "${name}" for component "${this.name}"`)
+  /** Returns the chain of container names from the `extends` hierarchy as an array. */
+  getContainerNameChain() {
+    const containerNames = [this.containerName]
+    let parent = this.extends
+    while (parent) {
+      containerNames.unshift(parent.containerName)
+      parent = parent.extends
     }
+    return containerNames
+  }
+
+  getCSSPropByName<Name extends keyof Props & string>(name: Name): CSSProps<Props>[Name] {
+    const prop = this.cssProps[name]
+    if (!prop) throw new Error(`Unknown CSS prop "${name}" for component "${this.name}"`)
     return prop
   }
 
@@ -102,81 +154,163 @@ export class GDSComponent<P extends CSSPropsConfig = CSSPropsConfig, A extends b
   }
 }
 
-/** Type to validate CSS prop definitions. */
-type ValidateCSSPropDefinition<P> = P extends {
+/**
+ * Validates a CSS prop definition. Ensures:
+ *
+ * - `values` type props have at least one value.
+ * - `defaultValue` (if provided) is one of the `values`
+ */
+type ValidateCSSPropDefinition<Def> = Def extends {
   type: 'values'
-  values: readonly unknown[]
+  values: readonly [unknown, ...unknown[]]
+  defaultValue: infer Default
 }
-  ? P['values'] extends readonly [unknown, ...unknown[]]
-    ? P extends {
-        defaultValue?: unknown
-      }
-      ? P['defaultValue'] extends P['values'][number]
-        ? P
-        : never
-      : P
-    : never
-  : P
-
-/** Type to validate all CSS props in an object. */
-type ValidateCSSPropsConfig<P extends Record<string, unknown>> = {
-  [K in keyof P]: ValidateCSSPropDefinition<P[K]>
+  ? Default extends Def['values'][number]
+    ? Def
+    : Omit<Def, 'defaultValue'> & { defaultValue: Def['values'][number] }
+  : Def extends { type: 'values'; values: readonly [] }
+    ? never
+    : Def
+
+/** Validates all CSS props in an object. Allows `null` to remove inherited props. */
+type ValidateCSSPropsConfig<Config extends Record<string, unknown>> = {
+  [K in keyof Config]: Config[K] extends null ? null : ValidateCSSPropDefinition<Config[K]>
+}
+
+/** Validates that `vars` names don't conflict with `cssProps` names. */
+type ValidateVarsConfig<CSSPropsKeys, Vars extends VarsConfig> = {
+  [K in keyof Vars]: K extends CSSPropsKeys
+    ? `Var "${K & string}" conflicts with cssProps. Choose a different name.`
+    : Vars[K]
 }
 
-/** Type to validate that vars don't conflict with cssProps names. */
-type ValidateVarsConfig<P extends CSSPropsConfig, V extends VarsConfig> = {} extends P
-  ? V
+/**
+ * Merges parent `cssProps` with own. Own props override parent props, `null` removes inherited
+ * props.
+ */
+type MergeCSSProps<
+  ParentProps extends CSSPropsConfig | undefined,
+  OwnProps extends Record<string, CSSPropDefinition | null>,
+> = ParentProps extends CSSPropsConfig
+  ? {
+      // Keys from parent that aren't overridden with `null`
+      [K in keyof ParentProps as K extends keyof OwnProps
+        ? OwnProps[K] extends null
+          ? never
+          : K
+        : K]: K extends keyof OwnProps
+        ? OwnProps[K] extends CSSPropDefinition
+          ? OwnProps[K]
+          : ParentProps[K]
+        : ParentProps[K]
+    } & {
+      // Keys from own that aren't in parent and aren't `null`
+      [K in keyof OwnProps as K extends keyof ParentProps
+        ? never
+        : OwnProps[K] extends null
+          ? never
+          : K]: OwnProps[K] extends CSSPropDefinition ? OwnProps[K] : never
+    }
   : {
-      [K in keyof V]: K extends keyof P
-        ? `Var "${K & string}" conflicts with cssProps. Choose a different name.`
-        : V[K]
+      [K in keyof OwnProps as OwnProps[K] extends null
+        ? never
+        : K]: OwnProps[K] extends CSSPropDefinition ? OwnProps[K] : never
     }
 
+/** Computed merged `cssProps` type for `createComponent`. */
+type MergedCSSProps<
+  Extends extends GDSComponent | undefined,
+  OwnProps extends Record<string, CSSPropDefinition | null>,
+> = MergeCSSProps<
+  Extends extends GDSComponent<infer ParentProps> ? ParentProps : undefined,
+  OwnProps
+>
+
+/**
+ * Empty object type without index signature (unlike `Record<string, never>` which has `keyof
+ * Record<string, never>` = `string`, not `never`).
+ */
+type EmptyObject = { [K in never]: never }
+
 /** Helper function to create a `GDSComponent` instance with proper type inference. */
 export function createComponent<
-  const P extends CSSPropsConfig,
-  const V extends VarsConfig,
-  const A extends boolean,
+  const Extends extends GDSComponent | undefined = undefined,
+  const OwnCSSProps extends Record<string, CSSPropDefinition | null> = EmptyObject,
+  const Vars extends VarsConfig = EmptyObject,
+  const AddonCompatible extends boolean = false,
 >(
   name: string,
-  config?: ConstructorParameters<typeof GDSComponent<P>>[1] & {
-    addonCompatible?: A
-    cssProps?: ValidateCSSPropsConfig<P>
-    vars?: ValidateVarsConfig<P, V>
+  config?: {
+    /**
+     * The parent component that this component extends. When set:
+     *
+     * - The component inherits all parent container names for CSS container queries (e.g. if
+     *   `Checkbox` extends `Checkable`, the following CSS will be generated: `.gds-checkbox {
+     *   container-name: gds-checkable gds-checkbox; }`).
+     * - The component inherits all parent `cssProps`, which can be overridden or removed (with
+     *   `null`).
+     * - The `isolate` option defaults to `false` since the parent already handles isolation (if not,
+     *   it can be set to `true` or `'allow-inheritance'`, but `isolate: false` will not cancel/undo
+     *   the parent's isolation).
+     */
+    extends?: Extends
+    /**
+     * - `true`: add `isolation: isolate` and reset all inherited font/text properties.
+     * - `'allow-inheritance'`: only add `isolation: isolate` (keep inheriting font/text properties).
+     * - `false`: do nothing.
+     *
+     * @default true // or if `extends` is set, `false`
+     */
+    isolate?: IsolateOption
+    /**
+     * Whether the component can be used as an addon (e.g. `<Button addonBefore={Component}>`).
+     * Setting this to `true` also includes this component's class in the selector generated by the
+     * `addon-compatible` custom variant.
+     *
+     * @default false
+     */
+    addonCompatible?: AddonCompatible
+    cssProps?: ValidateCSSPropsConfig<OwnCSSProps>
+    vars?: ValidateVarsConfig<keyof MergedCSSProps<Extends, OwnCSSProps>, Vars>
   },
-): GDSComponent<P, A> {
-  return new GDSComponent(name, config)
+) {
+  return new GDSComponent(
+    name,
+    config as ConstructorParameters<typeof GDSComponent>[1],
+  ) as unknown as GDSComponent<MergedCSSProps<Extends, OwnCSSProps>, AddonCompatible>
 }
 
-/** Helper type to extract the CSS props config type from a `GDSComponent` instance. */
-export type ComponentCSSPropsConfig<C extends GDSComponent> =
-  C extends GDSComponent<infer P> ? P : never
+/** Extracts the CSS props config type from a `GDSComponent` instance. */
+export type ComponentCSSPropsConfig<Component extends GDSComponent> =
+  Component extends GDSComponent<infer Props> ? Props : never
 
 /**
- * Helper type to extract CSS props types from components created with `createComponent`. Props
- * without a `defaultValue` are required, while those with a `defaultValue` are optional. Explicitly
- * includes `undefined` in the type to work with `exactOptionalPropertyTypes`.
+ * Extracts CSS props types from a component for use in React props. Props without a `defaultValue`
+ * are required, those with a `defaultValue` are optional. Explicitly includes `undefined` in the
+ * type to work with `exactOptionalPropertyTypes`.
  */
-export type ComponentCSSProps<C extends GDSComponent> = {
-  [K in keyof ComponentCSSPropsConfig<C> as string extends K
+export type ComponentCSSProps<Component extends GDSComponent> = {
+  // Required props (no `defaultValue`)
+  [K in keyof ComponentCSSPropsConfig<Component> as string extends K
     ? never
-    : 'defaultValue' extends keyof ComponentCSSPropsConfig<C>[K]
+    : 'defaultValue' extends keyof ComponentCSSPropsConfig<Component>[K]
       ? never
-      : K]: CSSPropType<ComponentCSSPropsConfig<C>[K]>
+      : K]: CSSPropType<ComponentCSSPropsConfig<Component>[K]>
 } & {
-  [K in keyof ComponentCSSPropsConfig<C> as string extends K
+  // Optional props (have `defaultValue`)
+  [K in keyof ComponentCSSPropsConfig<Component> as string extends K
     ? never
-    : 'defaultValue' extends keyof ComponentCSSPropsConfig<C>[K]
+    : 'defaultValue' extends keyof ComponentCSSPropsConfig<Component>[K]
       ? K
-      : never]?: CSSPropType<ComponentCSSPropsConfig<C>[K]> | undefined
+      : never]?: CSSPropType<ComponentCSSPropsConfig<Component>[K]> | undefined
 }
 
 /**
  * Combined props type for GDS components. Includes CSS props and, for addon-compatible components,
  * a hidden prop to mark them as such.
  */
-export type GDSComponentProps<C extends GDSComponent> = ComponentCSSProps<C> &
-  (C extends GDSComponent<CSSPropsConfig, true>
+export type GDSComponentProps<Component extends GDSComponent> = ComponentCSSProps<Component> &
+  (Component extends GDSComponent<CSSPropsConfig, true>
     ? { __addonCompatible?: undefined }
     : { __addonCompatible?: never })
 

package/src/css-props/index.ts

@@ -1,4 +1,4 @@
 export * from './types.ts'
 export { getCSSPropRawValue } from './getCSSPropRawValue.ts'
 export { parseCSSPropValue } from './parseCSSPropValue.ts'
-export { registerCSSProps } from './registerCSSProps.ts'
+export { setupCSSProps } from './setupCSSProps.ts'

package/src/css-props/parseCSSPropValue.ts

@@ -47,7 +47,7 @@ export function parseCSSPropValue<P extends CSSPropDefinition>(
         const numberValue = parseNumber(rawValue.slice(0, -2)) // Remove 'px'
         return pxToTw(numberValue ?? 0) satisfies CSSPropLength as CSSPropType<P>
       }
-      // Otherwise keep as-is (e.g., "1rem", "100%")
+      // Otherwise keep as-is (e.g. '1rem' or '100%')
       return rawValue as CSSPropLength as CSSPropType<P>
     }
     case 'color': {

package/src/css-props/{registerCSSProps.ts → setupCSSProps.ts}

@@ -12,10 +12,10 @@ import { getCSSPropRawValue } from './getCSSPropRawValue.ts'
 import type { CSSPropColor } from './types.ts'
 
 /**
- * Registers CSS Props functionality in the Tailwind plugin. This includes custom properties,
- * utilities, and variants for prop-based styling.
+ * Sets up the CSS props system via the Tailwind plugin. This includes custom properties, utilities,
+ * and variants for prop-based styling.
  */
-export function registerCSSProps(api: PluginAPI) {
+export function setupCSSProps(api: PluginAPI) {
   const componentsByCSSProp = getRegisteredComponents(true).reduce((outerMap, component) => {
     for (const cssProp of Object.values(component.cssProps)) {
       const innerMap =
@@ -46,9 +46,13 @@ export function registerCSSProps(api: PluginAPI) {
     })
   }
 
-  /** Register a custom property for each component-prop pair to restrict the allowed values. */
   for (const component of getRegisteredComponents()) {
-    for (const cssProp of Object.values(component.cssProps)) {
+    // Only process own props (not inherited via `extends`); inherited props are handled by the parent component
+    const ownCSSProps = Object.values(component.cssProps).filter((cssProp) => cssProp.own)
+    if (ownCSSProps.length === 0) continue
+
+    /** Register a custom property for each component-prop pair to restrict the allowed values. */
+    for (const cssProp of ownCSSProps) {
       const syntax = (() => {
         switch (cssProp.type) {
           case 'values':
@@ -66,7 +70,7 @@ export function registerCSSProps(api: PluginAPI) {
         }
       })()
       api.addBase({
-        [`@property --gds-${component.kebabName}-${cssProp.kebabName}`]: {
+        [`@property ${cssProp.cssProperty}`]: {
           syntax,
           /**
            * We only need this property to inherit if the type is not `values`, because `values` CSS
@@ -89,26 +93,20 @@ export function registerCSSProps(api: PluginAPI) {
     }
 
     /**
-     * Base styles for each component, including defining the default value of each CSS prop and
-     * applying the value passed via the React prop, if any. See `getCSSPropsAttributes` for details
-     * on how each prop type is handled.
+     * Add base styles for each component-prop pair, defining the default value of each CSS prop and
+     * applying the value passed via the React prop, if any. See `getCSSPropRawValue` for details on
+     * how each prop type is handled.
      */
     api.addBase({
       '@layer components': {
-        [`.${component.className}`]: {
-          '--tw-sort': 'container-type',
-          ...(component.containerName ? { 'container-name': component.containerName } : {}),
-          ...Object.values(component.cssProps).reduce(
-            (rules, cssProp) => {
-              return {
-                ...rules,
-                [`--gds-passed-or-default-${cssProp.kebabName}`]: `var(--gds-passed-${cssProp.kebabName}, var(--gds-default-${cssProp.kebabName}, ${getCSSPropRawValue(cssProp, cssProp.initialValue)}))`,
-                [`--gds-${component.kebabName}-${cssProp.kebabName}`]: `var(--gds-prop-${cssProp.kebabName}, var(--gds-passed-or-default-${cssProp.kebabName}))`,
-              }
-            },
-            {} as Record<string, string>,
-          ),
-        },
+        [`.${component.className}`]: ownCSSProps.reduce<Record<string, string>>(
+          (rules, cssProp) => ({
+            ...rules,
+            [`--gds-passed-or-default-${cssProp.kebabName}`]: `var(--gds-passed-${cssProp.kebabName}, var(--gds-default-${cssProp.kebabName}, ${getCSSPropRawValue(cssProp, cssProp.initialValue)}))`,
+            [cssProp.cssProperty]: `var(--gds-prop-${cssProp.kebabName}, var(--gds-passed-or-default-${cssProp.kebabName}))`,
+          }),
+          {},
+        ),
       },
     })
   }
@@ -200,19 +198,12 @@ export function registerCSSProps(api: PluginAPI) {
       variant,
       (cssPropKebabNameAndValue, { modifier: componentKebabName }) => {
         /**
-         * If the modifier is explicitly `dummy`, consider the variant invalid by returning an empty
-         * selector list (no CSS will be generated for it).
-         */
-        if (componentKebabName === 'dummy') return []
-        /**
-         * Default a missing modifier to `dummy` instead of considering the variant invalid so that
-         * it's suggested by Tailwind IntelliSense.
-         */
-        const component = getRegisteredComponent(componentKebabName ?? 'dummy')
-        /**
-         * If no component is found (i.e. the modifier is not a valid component name), consider the
-         * variant invalid.
+         * If the modifier is missing, return some dummy CSS so that the variant is suggested by
+         * Tailwind IntelliSense. If a modifier is present but is not a valid component name, then
+         * return an empty array (no CSS is generated and the variant is considered invalid).
          */
+        if (componentKebabName === null) return '@container dummy'
+        const component = getRegisteredComponent(componentKebabName)
         if (!component) return []
         try {
           const { cssPropKebabName, value } = JSON.parse(cssPropKebabNameAndValue)
@@ -223,20 +214,14 @@ export function registerCSSProps(api: PluginAPI) {
             return []
           const cssProp = component.findCSSPropByKebabName(cssPropKebabName)
           /**
-           * Only consider the variant valid if the prop exists on the component and is of type
-           * `values`, and the value is valid for it (unless the component is `dummy`, which is used
-           * to list all variants in IntelliSense regardless of the component).
+           * If no such prop exists on the component, or if one exists but is not of type `values`
+           * or doesn't support the specified value, consider the variant invalid.
            */
-          if (
-            (!cssProp || cssProp.type !== 'values' || !cssProp.values.includes(value)) &&
-            component.kebabName !== 'dummy'
-          ) {
-            return []
-          }
+          if (!cssProp || cssProp.type !== 'values' || !cssProp.values.includes(value)) return []
           const rawValue = cssProp ? getCSSPropRawValue(cssProp, value) : String(value)
           return [
             /** Style query selector for modern browsers. */
-            `@container ${component.containerName} ${variant === '@prop-not' ? 'not' : ''} style(--gds-${component.kebabName}-${cssPropKebabName}: ${rawValue})`,
+            `@container ${cssProp.containerName} ${variant === '@prop-not' ? 'not' : ''} style(${cssProp.cssProperty}: ${rawValue})`,
             /**
              * Fallback selector for browsers without style query support, which unfortunately
              * cannot be queried, but happens to be the same browsers that don't support view
@@ -246,7 +231,7 @@ export function registerCSSProps(api: PluginAPI) {
              * polyfill attributes are present even when the polyfill is not needed (see
              * `useCSSPropsPolyfill` for an explanation why).
              */
-            `@supports (not (view-transition-name: none)) or (-moz-orient: inline) { &:where(.${component.className}${variant === '@prop-not' ? ':not' : ':is'}([data-gds-prop-polyfill-${cssPropKebabName}=${cssesc(rawValue, { isIdentifier: true })}]) *) }`,
+            `@supports (not (view-transition-name: none)) or (-moz-orient: inline) { &:where(.${component.className}${variant === '@prop-not' ? ':not' : ':is'}([${cssProp.polyfillAttribute}=${cssesc(rawValue, { isIdentifier: true })}]) *) }`,
           ]
         } catch {
           /**

package/src/css-states/index.ts

@@ -1,2 +1,2 @@
 export { cssStates, cssStateVariables, type CSSState, type CSSStateValue } from './states.ts'
-export { registerCSSStates } from './registerCSSStates.ts'
+export { setupCSSStates } from './setupCSSStates.ts'

package/src/css-states/{registerCSSStates.ts → setupCSSStates.ts}

@@ -5,9 +5,8 @@ import type { PluginAPI } from '../types.ts'
 import { cssStates, cssStateVariables, getCSSStateVariable } from './states.ts'
 
 /**
- * Registers CSS States functionality in the Tailwind plugin.
- *
- * This system abstracts away CSS's native states in order to:
+ * Sets up the CSS states system via the Tailwind plugin. This system abstracts away CSS's native
+ * states in order to:
  *
  * - Allow overriding the state of components (e.g. `<Button className="state-active" />`).
  * - Allow reading the state of components from their root element even when the native state is
@@ -18,24 +17,24 @@ import { cssStates, cssStateVariables, getCSSStateVariable } from './states.ts'
  *   `@state-[highlighted]:bg-strong` on a child; also supports key-values like `state-[foo=bar]
  *   lg:state-[foo=baz]`).
  *
- * While this system is separate from the CSS Props one, it also leverages style queries and relies
- * on the fact that component classes (e.g. `gds-button`) establish a container that can be queried.
- * Furthermore, it uses some of the same techniques in the fallback implementation (querying by data
- * attribute, `view-transition-name` to target browsers that don't support style queries, etc.),
- * though the CSS props polyfill is not used. See `useCSSState` for more details.
+ * Like CSS props, this system leverages style queries and uses a similar fallback mechanism
+ * (querying by data attribute + using `view-transition-name` to target browsers that don't support
+ * style queries), though the CSS props polyfill is not used. See `useCSSState` for more details.
  */
-export function registerCSSStates(api: PluginAPI) {
+export function setupCSSStates(api: PluginAPI) {
   /**
-   * Register a couple custom properties for each state variable.
+   * Register a couple custom properties for each non-arbitrary state variable.
    *
    * - All of them are non-inherited to prevent leaking.
    * - Normally, we would only need `--gds-exposed-*` and `--gds-state-*` (with no `initial-value` on
    *   `--gds-exposed-*`), but due to a limitation in the `style-observer` library
    *   (https://github.com/LeaVerou/style-observer/issues/133), we need to set an `initial-value` on
-   *   any custom property we want to observe in JS. But we also need `--gds-state-*` to NOT have an
-   *   initial value so that we can define a fallback when a state is not set at all (see
-   *   `--gds-clickable-*`). So we register an additional `--gds-observed-*` property that is
-   *   guaranteed to have a valid value and can be observed.
+   *   any custom property we want to observe in JS (and we want to observe both in `useCSSState`).
+   *   But we also need `--gds-state-*` to NOT have an initial value so that we can define a
+   *   fallback when a state is not set at all (see `--gds-clickable-*`). So we register an
+   *   additional `--gds-observed-*` property that is guaranteed to have a valid value and can be
+   *   observed. Note that non-registered `--gds-state-*` properties (i.e. arbitrary states) don't
+   *   have this problem, so arbitrary state utilities don't need to set `--gds-observed-*`.
    */
   for (const [variableName, { values, defaultValue }] of Object.entries(cssStateVariables)) {
     api.addBase({
@@ -69,14 +68,18 @@ export function registerCSSStates(api: PluginAPI) {
         return {
           [`--gds-exposed-${stateVariable.name}`]: stateVariable.value,
           [`--gds-state-${stateVariable.name}`]: stateVariable.value,
-          [`--gds-observed-${stateVariable.name}`]: stateVariable.value,
+          ...(!stateVariable.isArbitrary && {
+            [`--gds-observed-${stateVariable.name}`]: stateVariable.value,
+          }),
         }
       },
       state: (state) => {
         const stateVariable = getCSSStateVariable(state)
         return {
           [`--gds-state-${stateVariable.name}`]: stateVariable.value,
-          [`--gds-observed-${stateVariable.name}`]: stateVariable.value,
+          ...(!stateVariable.isArbitrary && {
+            [`--gds-observed-${stateVariable.name}`]: stateVariable.value,
+          }),
         }
       },
     },
@@ -108,7 +111,7 @@ export function registerCSSStates(api: PluginAPI) {
             .join(' or ')})`,
         ]
         if (containerName) {
-          // Fallback selector for browsers without style query support; see `css-props/registerCSSProps.ts` for more details
+          // Fallback selector for browsers without style query support; see `setupCSSProps` for more details
           selectors.push(
             `@supports (not (view-transition-name: none)) or (-moz-orient: inline) { &:where(.${containerName}${variant === '@state-not' ? ':not' : ':is'}(${stateVariables
               .map(

package/src/css-states/states.ts

@@ -101,13 +101,14 @@ export function getCSSStateVariable(state: string) {
           name: variableName,
           value: String(value),
           isDefault: value === defaultValue,
+          isArbitrary: false,
         }
       }
     }
   }
   // Support arbitrary states in the format `state-[foo]` or `state-[foo=bar]`
   const [stateName, stateValue] = state.split('=')
-  return { name: stateName!, value: stateValue ?? 'true', isDefault: false }
+  return { name: stateName!, value: stateValue ?? 'true', isDefault: false, isArbitrary: true }
 }
 
 export function getPointerStateSelector(state: 'idle' | 'hover' | 'active') {