@graphprotocol/gds-css 0.0.1

package/src/css-states/registerCSSStates.ts

@@ -0,0 +1,136 @@
+import cssesc from 'cssesc'
+import { objectFromEntries } from 'ts-extras'
+
+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:
+ *
+ * - 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
+ *   actually on a nested element (e.g. `group-has-checkbox-checked`), thanks to
+ *   `variants/plugin.ts` overriding some of Tailwind's built-in variants.
+ * - Allow setting and reading custom states for DRY purposes (e.g. `active:state-[highlighted]` and
+ *   `data-[highlighted]:state-[highlighted]` on a parent element and
+ *   `@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.
+ */
+export function registerCSSStates(api: PluginAPI) {
+  /**
+   * Register a couple custom properties for each 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.
+   */
+  for (const [variableName, { values, defaultValue }] of Object.entries(cssStateVariables)) {
+    api.addBase({
+      [`@property --gds-exposed-${variableName}`]: {
+        syntax: "'*'",
+        inherits: 'false',
+        'initial-value': '',
+      },
+      [`@property --gds-state-${variableName}`]: {
+        syntax: "'*'",
+        inherits: 'false',
+      },
+      [`@property --gds-observed-${variableName}`]: {
+        syntax: `'${[...new Set<typeof defaultValue>([...Object.values(values), defaultValue])].map((value) => String(value)).join(' | ')}'`,
+        inherits: 'false',
+        'initial-value': String(defaultValue),
+      },
+    })
+  }
+
+  /**
+   * Register `expose-{state}` utilities for components to use internally to expose their current
+   * state if the root element doesn't already do so (e.g. by being a button with the expected
+   * attributes on it), as well as `state-{state}` utilities for consumers to trigger the
+   * hover/focus/etc. state of components that support it.
+   */
+  api.matchUtilities(
+    {
+      expose: (state) => {
+        const stateVariable = getCSSStateVariable(state)
+        return {
+          [`--gds-exposed-${stateVariable.name}`]: stateVariable.value,
+          [`--gds-state-${stateVariable.name}`]: stateVariable.value,
+          [`--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,
+        }
+      },
+    },
+    { values: Object.fromEntries(cssStates.map((state) => [state, state])) },
+  )
+
+  /** Register `@state-*` and `@state-not-*` variants for components to use internally. */
+  for (const variant of ['@state-not', '@state'] as const) {
+    api.matchVariant(
+      variant,
+      (state, { modifier }) => {
+        const containerName = modifier !== null ? `gds-${modifier}` : ''
+        const stateVariables = [getCSSStateVariable(state)]
+        // Make sure that `@state-hover` utilities are also applied on the active state
+        if (state === 'hover') {
+          stateVariables.push(getCSSStateVariable('active'))
+        }
+        const selectors = [
+          `@container ${containerName} ${variant === '@state-not' ? 'not' : ''} (${stateVariables
+            .flatMap((stateVariable) => {
+              const conditions = [
+                `style(--gds-state-${stateVariable.name}${stateVariable.value ? `: ${stateVariable.value}` : ''})`,
+              ]
+              if (stateVariable.isDefault) {
+                conditions.push(`(not style(--gds-state-${stateVariable.name}))`)
+              }
+              return conditions
+            })
+            .join(' or ')})`,
+        ]
+        if (containerName) {
+          // Fallback selector for browsers without style query support; see `css-props/registerCSSProps.ts` for more details
+          selectors.push(
+            `@supports (not (view-transition-name: none)) or (-moz-orient: inline) { &:where(.${containerName}${variant === '@state-not' ? ':not' : ':is'}(${stateVariables
+              .map(
+                (stateVariable) =>
+                  `[data-gds-state-polyfill-${stateVariable.name}${stateVariable.value ? `=${cssesc(stateVariable.value, { isIdentifier: true })}` : ''}]`,
+              )
+              .join(', ')}) *) }`,
+          )
+        }
+        return selectors
+      },
+      {
+        values: objectFromEntries(
+          cssStates
+            .filter((state) => {
+              // Prevent creating `@state-not-not-*` variants
+              if (variant === '@state-not' && state.startsWith('not-')) return false
+              return true
+            })
+            .map((state) => [state, state]),
+        ),
+      },
+    )
+  }
+}

package/src/css-states/states.ts

@@ -0,0 +1,160 @@
+import { wrapSelector } from '../utils/index.ts'
+
+export const cssStates = [
+  'open',
+  'not-open',
+  'current',
+  'not-current',
+  'checked',
+  'indeterminate',
+  'unchecked',
+  'read-only',
+  'blank',
+  'not-blank',
+  'idle',
+  'hover',
+  'focus',
+  'not-focus',
+  'active',
+  'enabled',
+  'disabled',
+] as const
+
+export type CSSState = (typeof cssStates)[number]
+export type CSSStateValue = string | boolean
+
+function createCSSStateVariable<
+  K extends CSSState,
+  V extends CSSStateValue,
+  T extends Partial<Record<K, V>>,
+>(variable: { values: T & Record<K, V>; defaultValue: T[keyof T] }) {
+  return variable
+}
+
+export const cssStateVariables = {
+  pointer: createCSSStateVariable({
+    values: {
+      idle: 'idle',
+      hover: 'hover',
+      active: 'active',
+    },
+    defaultValue: 'idle',
+  }),
+  focus: createCSSStateVariable({
+    values: {
+      focus: true,
+      'not-focus': false,
+    },
+    defaultValue: false,
+  }),
+  checked: createCSSStateVariable({
+    values: {
+      checked: true,
+      indeterminate: 'indeterminate',
+      unchecked: false,
+    },
+    defaultValue: false,
+  }),
+  disabled: createCSSStateVariable({
+    values: {
+      enabled: false,
+      disabled: true,
+      'read-only': 'read-only',
+    },
+    defaultValue: false,
+  }),
+  open: createCSSStateVariable({
+    values: {
+      open: true,
+      'not-open': false,
+    },
+    defaultValue: false,
+  }),
+  current: createCSSStateVariable({
+    values: {
+      current: true,
+      'not-current': false,
+    },
+    defaultValue: false,
+  }),
+  blank: createCSSStateVariable({
+    values: {
+      blank: true,
+      'not-blank': false,
+    },
+    defaultValue: false,
+  }),
+}
+
+function isCSSState(state: unknown): state is CSSState {
+  return cssStates.includes(state as CSSState)
+}
+
+const cssStateVariableEntries = Object.entries(cssStateVariables)
+
+export function getCSSStateVariable(state: string) {
+  if (isCSSState(state)) {
+    for (const [variableName, { values, defaultValue }] of cssStateVariableEntries) {
+      if (state in values) {
+        const value = (values as Record<CSSState, CSSStateValue>)[state]
+        return {
+          name: variableName,
+          value: String(value),
+          isDefault: value === defaultValue,
+        }
+      }
+    }
+  }
+  // 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 }
+}
+
+export function getPointerStateSelector(state: 'idle' | 'hover' | 'active') {
+  return `:is(${state === 'hover' ? '[data-gds-exposed-pointer=hover], [data-gds-exposed-pointer=active]' : `[data-gds-exposed-pointer=${state}]`}, :not([data-gds-exposed-pointer]):where(${state === 'idle' ? ':not(:hover, :active)' : state === 'hover' ? ':hover' : ':is(:hover:active, [data-gds-active] :active)'}))`
+}
+
+export function getFocusStateSelector(visible: boolean, within: boolean) {
+  return `${within ? ':has' : ':is'}([data-gds-exposed-focus=true], :not([data-gds-exposed-focus]):where(${visible ? ':focus-visible' : ':focus'}))`
+}
+
+export function getCheckedStateSelector(checked: boolean | 'indeterminate') {
+  return `:is([data-gds-exposed-checked=${checked === 'indeterminate' ? 'indeterminate' : checked}], :not([data-gds-exposed-checked]):where(${checked !== 'indeterminate' ? `${checked ? ':checked' : ':not(:checked)'}:not([aria-checked], [aria-pressed], [aria-selected]), ` : ''}[aria-checked=${checked === 'indeterminate' ? 'mixed' : checked}], [aria-pressed=${checked === 'indeterminate' ? 'mixed' : checked}]${checked !== 'indeterminate' ? `, [aria-selected=${checked}]` : ''}))`
+}
+
+export function getDisabledStateSelector(disabled: boolean | 'read-only') {
+  return `:is([data-gds-exposed-disabled=${disabled === 'read-only' ? 'read-only' : disabled}], :not([data-gds-exposed-disabled]):where(${disabled === true ? ':is' : ':not'}(:disabled, [aria-disabled=true])${disabled !== true ? `${disabled === 'read-only' ? ':is' : ':not'}(input:not([type=hidden], [type=range], [type=color], [type=checkbox], [type=radio], [type=button], [type=submit], [type=reset], [type=image]):read-only, textarea:read-only, [aria-readonly=true])` : ''}))`
+}
+
+export function getOpenStateSelector(open: boolean) {
+  return `${open ? ':is' : ':not'}([data-gds-exposed-open=true], :not([data-gds-exposed-open]):where([open], :popover-open, :open, [aria-expanded=true]))`
+}
+
+export function getCurrentStateSelector(current: boolean) {
+  return `${current ? ':is' : ':not'}([data-gds-exposed-current=true], :not([data-gds-exposed-current]):where([aria-current]:not([aria-current=''], [aria-current=false])))`
+}
+
+export function getBlankStateSelector(blank: boolean) {
+  // Should use `:blank` instead of `:placeholder-shown`, but no browser supports it
+  return `${blank ? ':is' : ':not'}([data-gds-exposed-blank=true], :not([data-gds-exposed-blank]):where(input:placeholder-shown, textarea:placeholder-shown, :not(input, textarea)[data-placeholder-shown]))`
+}
+
+export const cssStateSelectors: Record<CSSState, string> = {
+  open: getOpenStateSelector(true),
+  'not-open': getOpenStateSelector(false),
+  current: getCurrentStateSelector(true),
+  'not-current': getCurrentStateSelector(false),
+  checked: getCheckedStateSelector(true),
+  indeterminate: getCheckedStateSelector('indeterminate'),
+  unchecked: getCheckedStateSelector(false),
+  'read-only': getDisabledStateSelector('read-only'),
+  blank: getBlankStateSelector(true),
+  'not-blank': getBlankStateSelector(false),
+  idle: getPointerStateSelector('idle'),
+  hover: getPointerStateSelector('hover'),
+  focus: getFocusStateSelector(true, false),
+  'not-focus': wrapSelector(':not', getFocusStateSelector(true, false)),
+  active: getPointerStateSelector('active'),
+  enabled: getDisabledStateSelector(false),
+  disabled: getDisabledStateSelector(true),
+}