@graphprotocol/gds-css 0.0.1

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './component-registry.ts'
+export * from './css-props/index.ts'
+export * from './css-states/index.ts'
+export * from './tailwind-customizations/index.ts'
+export * from './utils/index.ts'
+export * from './design-tokens.generated.ts'

package/src/tailwind-customizations/index.ts

@@ -0,0 +1,2 @@
+export { registerUtilities } from './registerUtilities.ts'
+export { registerVariants } from './registerVariants.ts'

package/src/tailwind-customizations/registerUtilities.ts

@@ -0,0 +1,65 @@
+import type { DeepRecord } from '@graphprotocol/gds-utils'
+
+import { getRegisteredComponents } from '../component-registry.ts'
+import type { PluginAPI } from '../types.ts'
+
+/**
+ * Registers custom utilities and extends/overrides some built-in ones in the Tailwind plugin. Since
+ * Tailwind 4 it is preferable to do this in CSS, and we do it whenever we can (see
+ * `utilities.css`), but `@utility` doesn't support all use cases (e.g. advanced conditions, string
+ * manipulation, etc.).
+ */
+export function registerUtilities(api: PluginAPI) {
+  /**
+   * Apply the default "var" values for registered components, and register `var-[var=value]`
+   * utilities to override them.
+   */
+  for (const component of getRegisteredComponents()) {
+    if (!component.vars) continue
+    api.addBase({
+      '@layer components': {
+        [`.${component.className}`]: {
+          ...Object.fromEntries(
+            Object.keys(component.vars).map((varName) => {
+              return [`--gds-var-${varName}`, 'initial']
+            }),
+          ),
+          '& > *': {
+            '&': Object.entries(component.vars).flatMap(([varName, varCSS]) => {
+              function getDefaultVarRule(cssOrValue: typeof varCSS): DeepRecord<string> {
+                if (!cssOrValue) {
+                  return {}
+                }
+                if (typeof cssOrValue === 'string') {
+                  return {
+                    [`--gds-default-${varName}`]: cssOrValue,
+                  }
+                }
+                return Object.fromEntries(
+                  Object.entries(cssOrValue).map(([selector, nestedCSSOrValue]) => {
+                    return [selector || '&', getDefaultVarRule(nestedCSSOrValue)]
+                  }),
+                )
+              }
+              return [
+                getDefaultVarRule(varCSS),
+                {
+                  [`--gds-${component.kebabName}-${varName}`]: `var(--gds-var-${varName}, var(--gds-default-${varName}))`,
+                },
+              ]
+            }),
+          },
+        },
+      },
+    })
+  }
+  api.matchUtilities({
+    var: (varNameAndValue) => {
+      const [varName, ...valueParts] = varNameAndValue.split('=')
+      const value = valueParts.join('')
+      return {
+        [`--gds-var-${varName}`]: value,
+      }
+    },
+  })
+}

package/src/tailwind-customizations/registerVariants.ts

@@ -0,0 +1,296 @@
+import cssesc from 'cssesc'
+import { objectEntries } from 'ts-extras'
+
+import { getRegisteredComponents } from '../component-registry.ts'
+import { getCSSStateVariable, type CSSState } from '../css-states/states.ts'
+import type { PluginAPI } from '../types.ts'
+import { wrapSelector } from '../utils/index.ts'
+import { getComponentVariantSelectors, getVariantSelectors } from './variants.ts'
+
+/**
+ * Detect if running in VS Code's Tailwind IntelliSense extension to skip expensive variants. This
+ * dramatically improves autocomplete performance by avoiding exponential variant combinations.
+ */
+const IS_INTELLISENSE =
+  typeof process !== 'undefined' ? Boolean(process.env.VSCODE_PID) && !process.env.PRETTIER : false
+
+function getNestedSelector(modifier: string | null) {
+  const separateGroupAndNestedNames = modifier?.split('--') ?? []
+  const nestedName = separateGroupAndNestedNames[1] ?? separateGroupAndNestedNames[0]
+  return `.${cssesc(nestedName ? `nested/${nestedName}` : 'nested', { isIdentifier: true })}`
+}
+
+function getGroupSelector(modifier: string | null) {
+  const groupName = modifier?.split('--')[0]
+  return `.${cssesc(groupName ? `group/${groupName}` : 'group', { isIdentifier: true })}`
+}
+
+function getPeerSelector(modifier: string | null) {
+  return `.${cssesc(modifier ? `peer/${modifier}` : 'peer', { isIdentifier: true })}`
+}
+
+function addSimpleVariant(
+  api: PluginAPI,
+  variant: string,
+  selector: string,
+  supportsArbitrary: boolean,
+) {
+  if (supportsArbitrary) {
+    api.matchVariant(
+      variant,
+      (value, { modifier }) => {
+        if (modifier !== null) return []
+        return value ? `&${selector}${wrapSelector(':is', value)}` : `&${selector}`
+      },
+      { values: { DEFAULT: '' } },
+    )
+  } else {
+    api.addVariant(variant, `&${selector}`)
+  }
+}
+
+/**
+ * Registers custom variants in the Tailwind plugin. Since Tailwind 4 it is preferable to do this in
+ * CSS, and we do it whenever we can (see `variants.css`), but `@custom-variant` doesn't support
+ * dynamic variants or modifiers.
+ */
+export function registerVariants(api: PluginAPI) {
+  const variantSelectors = getVariantSelectors()
+  const registeredComponents = getRegisteredComponents()
+  const componentKebabNames = new Set(registeredComponents.map((component) => component.kebabName))
+  const componentVariantSelectors = getComponentVariantSelectors({
+    includeStates: !IS_INTELLISENSE,
+    includePositional: !IS_INTELLISENSE,
+  })
+
+  /** Register the base variants, including some overrides required by the CSS States system. */
+  for (const [variant, selector] of objectEntries(variantSelectors)) {
+    addSimpleVariant(api, variant, selector, variant === 'clickable')
+  }
+
+  /** Register component variants. */
+  for (const [variant, selector] of objectEntries(componentVariantSelectors)) {
+    const isPlainComponentVariant = componentKebabNames.has(variant)
+    addSimpleVariant(api, variant, selector, isPlainComponentVariant)
+  }
+
+  /**
+   * Register `(group-)(not-)has-nested(-not)(-has)-{variant}/{name}` variants to style the current
+   * element based on a nested element's presence or state.
+   */
+  for (const groupPrefix of ['group-', ''] as const) {
+    for (const notPrefix of ['not-', ''] as const) {
+      // Register `(group-)(not-)has-nested-not-*` variant
+      api.matchVariant(
+        `${groupPrefix}${notPrefix}has-nested-not`,
+        (value, { modifier }) => {
+          if (!value || modifier === '') return []
+          const selector = wrapSelector(
+            notPrefix === 'not-' ? ':not' : ':is',
+            `:has(${getNestedSelector(modifier)}${wrapSelector(':not', value)})`,
+          )
+          return groupPrefix === 'group-'
+            ? `&:is(${getGroupSelector(modifier)}${selector} *)`
+            : `&${selector}`
+        },
+        { values: variantSelectors },
+      )
+      // Register `(group-)(not-)has-nested-*` variant
+      api.matchVariant(
+        `${groupPrefix}${notPrefix}has-nested`,
+        (value, { modifier }) => {
+          if (modifier === '') return []
+          const selector = wrapSelector(
+            notPrefix === 'not-' ? ':not' : ':is',
+            `:has(${getNestedSelector(modifier)}${wrapSelector(':is', value)})`,
+          )
+          return groupPrefix === 'group-'
+            ? `&:is(${getGroupSelector(modifier)}${selector} *)`
+            : `&${selector}`
+        },
+        { values: { DEFAULT: '', ...variantSelectors } },
+      )
+      // Register `(group-)(not-)has-nested-not-has-*` variant
+      api.matchVariant(
+        `${groupPrefix}${notPrefix}has-nested-not-has`,
+        (value, { modifier }) => {
+          if (!value || modifier === '') return []
+          const selector = wrapSelector(
+            notPrefix === 'not-' ? ':not' : ':is',
+            `:has(${getNestedSelector(modifier)}):not(:has(${getNestedSelector(modifier)} ${wrapSelector(':is', value)}))`,
+          )
+          return groupPrefix === 'group-'
+            ? `&:is(${getGroupSelector(modifier)}${selector} *)`
+            : `&${selector}`
+        },
+        { values: { ...variantSelectors, ...componentVariantSelectors } },
+      )
+      // Register `(group-)(not-)has-nested-has-*` variant
+      api.matchVariant(
+        `${groupPrefix}${notPrefix}has-nested-has`,
+        (value, { modifier }) => {
+          if (!value || modifier === '') return []
+          const selector = wrapSelector(
+            notPrefix === 'not-' ? ':not' : ':is',
+            `:has(${getNestedSelector(modifier)} ${wrapSelector(':is', value)})`,
+          )
+          return groupPrefix === 'group-'
+            ? `&:is(${getGroupSelector(modifier)}${selector} *)`
+            : `&${selector}`
+        },
+        { values: { ...variantSelectors, ...componentVariantSelectors } },
+      )
+    }
+  }
+
+  /** Register `(not-)in-group/{group}` variants. */
+  for (const notPrefix of ['not-', ''] as const) {
+    api.matchVariant(
+      `${notPrefix}in-group`,
+      (value, { modifier }) => {
+        if (value || modifier === '') return []
+        return wrapSelector(
+          notPrefix === 'not-' ? ':not' : ':is',
+          `${getGroupSelector(modifier)} *`,
+        )
+      },
+      { values: { DEFAULT: '' } },
+    )
+  }
+
+  /** Register `(not-)preceded-by-peer/{peer}` and `(not-)followed-by-peer/{peer}` variants. */
+  for (const notPrefix of ['not-', ''] as const) {
+    api.matchVariant(
+      `${notPrefix}preceded-by-peer`,
+      (value, { modifier }) => {
+        if (value || modifier === '') return []
+        const selector = wrapSelector(
+          notPrefix === 'not-' ? ':not' : ':is',
+          `${getPeerSelector(modifier)} + *`,
+        )
+        return `&${selector}`
+      },
+      { values: { DEFAULT: '' } },
+    )
+    api.matchVariant(
+      `${notPrefix}followed-by-peer`,
+      (value, { modifier }) => {
+        if (value || modifier === '') return []
+        const selector = wrapSelector(
+          notPrefix === 'not-' ? ':not' : ':is',
+          `:has(+ ${getPeerSelector(modifier)})`,
+        )
+        return `&${selector}`
+      },
+      { values: { DEFAULT: '' } },
+    )
+  }
+
+  /** Register `(not-)nearest-clickable-*` variants. */
+  for (const notPrefix of ['not-', ''] as const) {
+    for (const nearestClickableState of [
+      'open',
+      'current',
+      'checked',
+      'indeterminate',
+      'unchecked',
+      'hocus-visible',
+      'hover',
+      'focus-visible',
+      'active',
+      'enabled',
+      'disabled',
+    ] as const satisfies (CSSState | 'hocus-visible' | 'focus-visible')[]) {
+      const states: CSSState[] =
+        nearestClickableState === 'hocus-visible'
+          ? ['hover', 'active', 'focus']
+          : nearestClickableState === 'hover'
+            ? ['hover', 'active']
+            : nearestClickableState === 'focus-visible'
+              ? ['focus']
+              : [nearestClickableState]
+      const stateVariables = states.map((state) => getCSSStateVariable(state))
+      const selectors = [
+        `@container ${notPrefix === 'not-' ? 'not' : ''} (${stateVariables
+          .map(
+            (stateVariable) =>
+              `style(--gds-clickable-${stateVariable.name}: ${stateVariable.value})`,
+          )
+          .join(' or ')})`,
+      ]
+      // Fallback selector for browsers without style query support; see `css-props/registerCSSProps.ts` for more details
+      const onlyEnabledClickables =
+        states.includes('hover') || states.includes('active') || states.includes('focus')
+      selectors.push(
+        `@supports (not (view-transition-name: none)) or (-moz-orient: inline) { &${notPrefix === 'not-' ? ':not' : ':is'}(${variantSelectors[onlyEnabledClickables ? 'clickable' : 'any-clickable']}:where(${stateVariables
+          .map(
+            (stateVariable) =>
+              `[data-gds-state-polyfill-${stateVariable.name}${stateVariable.value ? `=${cssesc(stateVariable.value, { isIdentifier: true })}` : ''}]`,
+          )
+          .join(', ')}) *) }`,
+      )
+      api.addVariant(`${notPrefix}nearest-clickable-${nearestClickableState}`, selectors)
+    }
+  }
+
+  /** Register a `style-group/{group}` variant to apply styles to an element from a descendant. */
+  api.matchVariant(
+    'style-group',
+    (value, { modifier }) => {
+      if (value || modifier === '') return []
+      return `${getGroupSelector(modifier)}:has(&)`
+    },
+    { values: { DEFAULT: '' } },
+  )
+
+  /** Register `style-(previous|next)-peer(s)` variants to apply styles to peers. */
+  api.matchVariant(
+    'style-previous-peer',
+    (value, { modifier }) => {
+      if (value || modifier === '') return []
+      return `${getPeerSelector(modifier)}:has(+ &)`
+    },
+    { values: { DEFAULT: '' } },
+  )
+  api.matchVariant(
+    'style-previous-peers',
+    (value, { modifier }) => {
+      if (value || modifier === '') return []
+      return `${getPeerSelector(modifier)}:has(~ &)`
+    },
+    { values: { DEFAULT: '' } },
+  )
+  api.matchVariant(
+    'style-next-peer',
+    (value, { modifier }) => {
+      if (value || modifier === '') return []
+      return `& + ${getPeerSelector(modifier)}`
+    },
+    { values: { DEFAULT: '' } },
+  )
+  api.matchVariant(
+    'style-next-peers',
+    (value, { modifier }) => {
+      if (value || modifier === '') return []
+      return `& ~ ${getPeerSelector(modifier)}`
+    },
+    { values: { DEFAULT: '' } },
+  )
+
+  /** Register a `style-nested/{name}` variant to apply styles to nested elements. */
+  api.matchVariant(
+    'style-nested',
+    (value, { modifier }) => {
+      if (value || !modifier) return []
+      return `${getNestedSelector(modifier)}:is(& *)`
+    },
+    { values: { DEFAULT: '' } },
+  )
+
+  /** Register a style query variant (e.g. `@style-[--prop-name=value]/optional-container-name`). */
+  api.matchVariant(
+    '@style',
+    (condition, { modifier }) =>
+      `@container ${modifier ?? ''} style(${condition.replace(/(?<![<>])=/g, ':')})`,
+  )
+}

package/src/tailwind-customizations/variants.ts

@@ -0,0 +1,190 @@
+import { getRegisteredComponents } from '../component-registry.ts'
+import { cssStates, cssStateSelectors, getFocusStateSelector } from '../css-states/states.ts'
+import { wrapSelector } from '../utils/index.ts'
+
+function getClickableSelector(enabled: boolean | 'any' = true) {
+  return `:where(
+    :any-link,
+    button,
+    input:is([type='button'], [type='submit'], [type='reset']),
+    summary,
+    [role='button'],
+    [role='link'],
+    [role='menuitem'],
+    [role='menuitemcheckbox'],
+    [role='menuitemradio'],
+    [role='option'],
+    [role='tab'],
+    .gds-checkable-label
+  )${enabled !== 'any' ? (enabled ? cssStateSelectors.enabled : cssStateSelectors.disabled) : ''}`
+}
+
+/**
+ * Static list of Tailwind's built-in variants and our own custom ones. Maintains the same order as
+ * `https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/src/variants.ts`
+ */
+const staticVariantSelectors = {
+  // Positional
+  first: ':first-child',
+  last: ':last-child',
+  only: ':only-child',
+  odd: ':nth-child(odd)',
+  even: ':nth-child(even)',
+  'first-of-type': ':first-of-type',
+  'last-of-type': ':last-of-type',
+  'only-of-type': ':only-of-type',
+
+  // State
+  visited: ':visited',
+  target: ':target',
+  open: cssStateSelectors.open,
+
+  // Forms
+  current: cssStateSelectors.current, // custom CSS state
+  default: ':default',
+  checked: cssStateSelectors.checked,
+  indeterminate: cssStateSelectors.indeterminate,
+  unchecked: cssStateSelectors.unchecked, // custom CSS state, different from `not-checked` which can still be indeterminate
+  'placeholder-shown': ':placeholder-shown',
+  autofill: ':autofill',
+  optional: ':optional',
+  required: ':required',
+  valid: ':valid',
+  invalid: ':invalid',
+  'user-valid': ':user-valid',
+  'user-invalid': ':user-invalid',
+  'in-range': ':in-range',
+  'out-of-range': ':out-of-range',
+  'read-only': cssStateSelectors['read-only'],
+
+  // Content
+  empty: ':empty',
+  blank: cssStateSelectors.blank, // custom CSS state
+
+  // Interactive
+  idle: cssStateSelectors.idle, // custom CSS state
+  'focus-within': getFocusStateSelector(false, true),
+  'hocus-visible': `:is(${cssStateSelectors.hover}, ${getFocusStateSelector(true, false)})`, // custom
+  hover: cssStateSelectors.hover,
+  focus: getFocusStateSelector(false, false),
+  'focus-visible': getFocusStateSelector(true, false),
+  active: cssStateSelectors.active,
+  enabled: cssStateSelectors.enabled,
+  disabled: cssStateSelectors.disabled,
+
+  // Other
+  inert: ':is([inert], [inert] *)',
+
+  // Clickable (all custom)
+  'any-clickable': getClickableSelector('any'),
+  clickable: getClickableSelector(),
+  'any-clickable-open': `${getClickableSelector('any')}${cssStateSelectors.open}`,
+  'clickable-open': `${getClickableSelector()}${cssStateSelectors.open}`,
+  'any-clickable-current': `${getClickableSelector('any')}${cssStateSelectors.current}`,
+  'clickable-current': `${getClickableSelector()}${cssStateSelectors.current}`,
+  'any-clickable-checked': `${getClickableSelector('any')}${cssStateSelectors.checked}`,
+  'clickable-checked': `${getClickableSelector()}${cssStateSelectors.checked}`,
+  'any-clickable-indeterminate': `${getClickableSelector('any')}${cssStateSelectors.indeterminate}`,
+  'clickable-indeterminate': `${getClickableSelector()}${cssStateSelectors.indeterminate}`,
+  'any-clickable-unchecked': `${getClickableSelector('any')}${cssStateSelectors.unchecked}`,
+  'clickable-unchecked': `${getClickableSelector()}${cssStateSelectors.unchecked}`,
+  'clickable-idle': `${getClickableSelector()}${cssStateSelectors.idle}`,
+  'clickable-focus-within': `${getClickableSelector()}${getFocusStateSelector(false, true)}`,
+  'clickable-hocus-visible': `:is(${getClickableSelector()}${cssStateSelectors.hover}, ${getClickableSelector()}${getFocusStateSelector(true, false)})`,
+  'clickable-hover': `${getClickableSelector()}${cssStateSelectors.hover}`,
+  'clickable-focus': `${getClickableSelector()}${getFocusStateSelector(false, false)}`,
+  'clickable-focus-visible': `${getClickableSelector()}${getFocusStateSelector(true, false)}`,
+  'clickable-active': `${getClickableSelector()}${cssStateSelectors.active}`,
+  'clickable-disabled': getClickableSelector(false),
+}
+
+const positionalVariants = ['first', 'last', 'only', 'odd', 'even', 'inert'] as const
+
+/** Generate positional variant selectors (`{prefix}-first`, `{prefix}-last`, etc.) */
+function generatePositionalVariantSelectors(prefix: string, baseSelector: string) {
+  return {
+    ...positionalVariants.reduce(
+      (result, variant) => {
+        result[`${prefix}-not-${variant}`] =
+          `${baseSelector}${wrapSelector(':not', staticVariantSelectors[variant])}`
+        return result
+      },
+      {} as Record<string, string>,
+    ),
+    ...positionalVariants.reduce(
+      (result, variant) => {
+        result[`${prefix}-${variant}`] = `${baseSelector}${staticVariantSelectors[variant]}`
+        return result
+      },
+      {} as Record<string, string>,
+    ),
+  }
+}
+
+/** Get all variant selectors including dynamically generated ones based on registered components. */
+export function getVariantSelectors() {
+  const dynamicVariantSelectors: Record<string, string> = {}
+
+  // Add `addon-compatible` and `addon-compatible-{variant}` variants if there are addon-compatible components
+  const addonCompatibleComponents = getRegisteredComponents().filter(
+    (component) => component.addonCompatible,
+  )
+  if (addonCompatibleComponents.length > 0) {
+    const addonCompatibleSelector = `:is(${addonCompatibleComponents.map((component) => `.${component.className}`).join(', ')})`
+    dynamicVariantSelectors['addon-compatible'] = addonCompatibleSelector
+    Object.assign(
+      dynamicVariantSelectors,
+      generatePositionalVariantSelectors('addon-compatible', addonCompatibleSelector),
+    )
+  }
+
+  return {
+    ...staticVariantSelectors,
+    ...dynamicVariantSelectors,
+  }
+}
+
+/**
+ * Get component variant selectors for all registered components. These include plain component
+ * selectors, state-based selectors, and positional ones.
+ */
+export function getComponentVariantSelectors(
+  options: {
+    includePlain?: boolean
+    includeStates?: boolean
+    includePositional?: boolean
+  } = {},
+) {
+  const { includePlain = true, includeStates = true, includePositional = true } = options
+  const componentVariantSelectors: Record<string, string> = {}
+
+  for (const component of getRegisteredComponents()) {
+    // Plain `{component}` variant
+    if (includePlain) {
+      componentVariantSelectors[component.kebabName] = `.${component.className}`
+    }
+
+    // CSS state variants (`{component}-state` and `{component}-not-state`)
+    if (includeStates) {
+      for (const state of cssStates) {
+        // Skip `not-*` states for `{component}-not-*` to prevent `{component}-not-not-*`
+        if (!state.startsWith('not-')) {
+          componentVariantSelectors[`${component.kebabName}-not-${state}`] =
+            `.${component.className}${wrapSelector(':not', cssStateSelectors[state])}`
+        }
+        componentVariantSelectors[`${component.kebabName}-${state}`] =
+          `.${component.className}${cssStateSelectors[state]}`
+      }
+    }
+
+    // Positional variants (`{component}-first`, `{component}-last`, etc.)
+    if (includePositional) {
+      Object.assign(
+        componentVariantSelectors,
+        generatePositionalVariantSelectors(component.kebabName, `.${component.className}`),
+      )
+    }
+  }
+
+  return componentVariantSelectors
+}

package/src/tailwind-plugin.ts

@@ -0,0 +1,14 @@
+import createPlugin from 'tailwindcss/plugin'
+
+import { registerCSSProps } from './css-props/registerCSSProps.ts'
+import { registerCSSStates } from './css-states/registerCSSStates.ts'
+import { registerUtilities, registerVariants } from './tailwind-customizations/index.ts'
+
+const gdsTailwindPlugin: ReturnType<typeof createPlugin> = createPlugin((api) => {
+  registerUtilities(api)
+  registerVariants(api)
+  registerCSSStates(api)
+  registerCSSProps(api)
+})
+
+export default gdsTailwindPlugin

package/src/types.ts

@@ -0,0 +1,4 @@
+import type createPlugin from 'tailwindcss/plugin'
+
+/** Types for Tailwind CSS plugin API. */
+export type PluginAPI = Parameters<Parameters<typeof createPlugin>[0]>[0]

package/src/utils/cssUnescape.ts

@@ -0,0 +1,49 @@
+/**
+ * Unescapes CSS-escaped strings, reversing the escaping done by libraries like `cssesc`.
+ *
+ * Handles three types of CSS escapes:
+ *
+ * 1. Hex escapes: `\20` or `\00020 ` → space character.
+ * 2. Character escapes: `\.` → `.`
+ * 3. Line continuations: `\<newline>` → (removed)
+ *
+ * @example
+ *
+ *     cssUnescape('foo\.bar') // 'foo.bar'
+ *     cssUnescape('hello\20world') // 'hello world'
+ *     cssUnescape('test\2d case') // 'test-case'
+ *
+ * @param input - The CSS-escaped string to unescape.
+ * @returns The unescaped string.
+ */
+export function cssUnescape(input: string): string {
+  // Matches: hex escapes | line continuations | single char escapes
+  const escapePattern = /\\([0-9a-f]{1,6}[ \t\r\n\f]?|$)|\\(\r?\n|\r|\f)|\\(.)/gi
+
+  return input.replace(escapePattern, (_match, hex, newline, char) => {
+    // Single character escape: "\." → "."
+    if (char) {
+      return char
+    }
+
+    // Line continuation: backslash followed by newline is removed
+    if (newline) {
+      return ''
+    }
+
+    // Lone backslash at end of string
+    if (!hex) {
+      return '\uFFFD' // Replacement character
+    }
+
+    // Hex escape: parse the hex digits (trim removes optional trailing whitespace)
+    const codePoint = Number.parseInt(hex.trim(), 16)
+
+    // Invalid code points: null, surrogates, or out of Unicode range
+    if (codePoint === 0 || codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+      return '\uFFFD' // Replacement character
+    }
+
+    return String.fromCodePoint(codePoint)
+  })
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export { cssUnescape } from './cssUnescape.ts'
+export { pxToTw } from './pxToTw.ts'
+export { twToPx } from './twToPx.ts'
+export { twToRem } from './twToRem.ts'
+export { wrapSelector } from './wrapSelector.ts'

package/src/utils/pxToTw.ts

@@ -0,0 +1,4 @@
+/** Converts a value in CSS pixels to a Tailwind length. */
+export function pxToTw(px: number): number {
+  return px * 0.25 // 1px = 0.25 tw unit, 4px = 1 tw unit
+}

package/src/utils/twToPx.ts

@@ -0,0 +1,4 @@
+/** Converts a Tailwind length to `px`. */
+export function twToPx(tw: number): number {
+  return tw * 4 // 1 tw unit = 4px
+}

package/src/utils/twToRem.ts

@@ -0,0 +1,4 @@
+/** Converts a Tailwind length to `rem`. */
+export function twToRem(tw: number): number {
+  return tw * 0.25 // 1 tw unit = 0.25rem (4px at 16px base)
+}