typewritingclass 0.2.0

package/src/index.ts

@@ -0,0 +1,137 @@
+// Core API
+export { cx } from './cx.ts'
+export { dcx } from './dcx.ts'
+export { when } from './when.ts'
+export { css } from './css.ts'
+export { dynamic, isDynamic } from './dynamic.ts'
+export { layer } from './layer.ts'
+export { generateCSS } from './registry.ts'
+
+// Types
+export type { StyleRule, Utility, Modifier, DynamicResult } from './types.ts'
+export type {
+  Brand, CSSColor, CSSLength, CSSShadow, CSSFontWeight,
+  ColorInput, SpacingInput, SizeInput, RadiusInput, ShadowInput,
+} from './types.ts'
+export type { DynamicValue } from './dynamic.ts'
+
+// Theme creation & switching
+export { createTheme } from './theme/createTheme.ts'
+export type { ThemeConfig, ThemeResult, ThemeVars } from './theme/createTheme.ts'
+export { injectTheme, setTheme } from './theme/inject-theme.ts'
+
+// Utilities
+export {
+  // Spacing
+  p, px, py, pt, pr, pb, pl,
+  m, mx, my, mt, mr, mb, ml,
+  gap, gapX, gapY,
+  ps, pe, ms, me,
+  spaceX, spaceY, spaceXReverse, spaceYReverse,
+  // Colors
+  bg, textColor, borderColor,
+  // Typography
+  text, font, tracking, leading, textAlign,
+  fontFamily, antialiased, subpixelAntialiased,
+  italic, notItalic, truncate,
+  normalNums, ordinal, slashedZero, liningNums, oldstyleNums,
+  proportionalNums, tabularNums, diagonalFractions, stackedFractions,
+  lineClamp, listStyleImage, listStylePosition, listStyleType,
+  textDecoration, textDecorationColor, textDecorationStyle, textDecorationThickness,
+  textUnderlineOffset, textTransform, textOverflow, textWrap, textIndent,
+  verticalAlign, whitespace, wordBreak, hyphens, content_,
+  // Layout
+  flex, flexCol, flexRow, flexWrap, inlineFlex,
+  grid, gridCols, gridRows,
+  w, h, size, minW, minH, maxW, maxH,
+  display, items, justify, self,
+  overflow, overflowX, overflowY,
+  relative, absolute, fixed, sticky,
+  top, right, bottom, left, inset,
+  z,
+  aspectRatio, columns, breakAfter, breakBefore, breakInside,
+  boxDecorationBreak, boxSizing, float_, clear_, isolate, isolationAuto,
+  objectFit, objectPosition, overscrollBehavior, overscrollX, overscrollY,
+  static_, insetX, insetY, start, end,
+  visible, invisible, collapse_,
+  flexBasis, flexRowReverse, flexColReverse, flexWrapReverse, flexNowrap,
+  flex1, flexAuto, flexInitial, flexNone,
+  grow, shrink, order,
+  colSpan, colStart, colEnd, rowSpan, rowStart, rowEnd,
+  gridFlow, autoCols, autoRows,
+  justifyItems, justifySelf, alignContent, placeContent, placeItems, placeSelf,
+  container,
+  // Borders
+  rounded, roundedT, roundedB, roundedL, roundedR,
+  roundedTL, roundedTR, roundedBR, roundedBL,
+  roundedSS, roundedSE, roundedEE, roundedES,
+  border, borderT, borderR, borderB, borderL,
+  borderX, borderY, borderS, borderE, borderStyle,
+  ring, ringColor, ringOffsetWidth, ringOffsetColor, ringInset,
+  outlineWidth, outlineColor, outlineStyle, outlineOffset, outline, outlineNone,
+  divideX, divideY, divideColor, divideStyle, divideXReverse, divideYReverse,
+  // Effects
+  shadow, opacity, backdrop,
+  shadowColor, mixBlendMode, bgBlendMode,
+  // Interactivity
+  cursor, select, pointerEvents,
+  accentColor, appearance, caretColor, resize,
+  scrollBehavior, scrollMargin, scrollMarginX, scrollMarginY,
+  scrollMarginT, scrollMarginR, scrollMarginB, scrollMarginL,
+  scrollPadding, scrollPaddingX, scrollPaddingY,
+  scrollPaddingT, scrollPaddingR, scrollPaddingB, scrollPaddingL,
+  snapAlign, snapStop, snapType, touchAction, willChange,
+  // Filters
+  blur, brightness, contrast, dropShadow, grayscale, hueRotate, invert, saturate, sepia,
+  backdropBlur, backdropBrightness, backdropContrast, backdropGrayscale, backdropHueRotate,
+  backdropInvert, backdropOpacity, backdropSaturate, backdropSepia,
+  // Transforms
+  scale, scaleX, scaleY, rotate, translateX, translateY, skewX, skewY, transformOrigin, transformGpu, transformNone,
+  // Transitions
+  transition, transitionAll, transitionColors, transitionOpacity, transitionShadow, transitionTransform, transitionNone,
+  duration, ease, delay, animate,
+  // Tables
+  borderCollapse, borderSeparate, borderSpacing, borderSpacingX, borderSpacingY, tableLayout, captionSide,
+  // SVG
+  fill, stroke, strokeWidth,
+  // Accessibility
+  srOnly, notSrOnly, forcedColorAdjust,
+  // Backgrounds
+  bgAttachment, bgClip, bgOrigin, bgPosition, bgRepeat, bgSize, bgImage, bgGradient,
+  gradientFrom, gradientVia, gradientTo,
+} from './utilities/index.ts'
+
+// Modifiers
+export {
+  // Pseudo-classes
+  hover, focus, active, disabled, focusVisible, focusWithin, firstChild, lastChild,
+  visited, checked, indeterminate, default_, required_, valid, invalid,
+  inRange, outOfRange, placeholderShown, autofill, readOnly, empty,
+  even, odd, firstOfType, lastOfType, onlyChild, onlyOfType, target, open_,
+  has_,
+  // Responsive
+  sm, md, lg, xl, _2xl,
+  maxSm, maxMd, maxLg, maxXl, max2xl,
+  // Color scheme
+  dark,
+  // Media
+  motionReduce, motionSafe, print_, portrait, landscape, contrastMore, contrastLess, forcedColors,
+  // Pseudo-elements
+  before, after, placeholder_, file_, marker, selection_, firstLine, firstLetter, backdrop_,
+  // ARIA
+  ariaChecked, ariaDisabled, ariaExpanded, ariaHidden, ariaPressed, ariaReadonly, ariaRequired, ariaSelected, aria,
+  // Data
+  data,
+  // Supports
+  supports,
+  // Group
+  groupHover, groupFocus, groupActive, groupFocusVisible, groupFocusWithin,
+  groupDisabled, groupChecked, groupEmpty, groupFirst, groupLast, groupOdd, groupEven,
+  groupOpen, groupVisited, groupHas,
+  // Peer
+  peerHover, peerFocus, peerActive, peerFocusVisible, peerDisabled,
+  peerChecked, peerInvalid, peerRequired, peerPlaceholderShown,
+  peerFocusWithin, peerEmpty, peerFirst, peerLast, peerOdd, peerEven, peerOpen, peerVisited, peerHas,
+  // Direction
+  rtl, ltr,
+} from './modifiers/index.ts'

package/src/inject.ts

@@ -0,0 +1,86 @@
+/**
+ * Runtime style injection module.
+ *
+ * This module automatically creates a `<style id="twc">` element in the
+ * document head and keeps it synchronised with the {@link registry}. Whenever
+ * a new rule is registered, a microtask is scheduled to regenerate the full
+ * CSS and update the style element.
+ *
+ * The module self-initialises on import. In non-browser environments (e.g., SSR)
+ * the initialisation is silently skipped.
+ *
+ * @internal
+ * @module
+ */
+
+import { generateCSS, onChange } from './registry.ts'
+
+/**
+ * Cached reference to the `<style id="twc">` element managed by this module.
+ *
+ * @internal
+ */
+let styleEl: HTMLStyleElement | null = null
+
+/**
+ * Whether a CSS update microtask is already scheduled.
+ *
+ * @internal
+ */
+let pending = false
+
+/**
+ * Writes the latest generated CSS into the `<style>` element.
+ *
+ * Called as a microtask callback. Resets the `pending` flag so that
+ * subsequent registry changes will schedule a new update.
+ *
+ * @internal
+ */
+function flush(): void {
+  pending = false
+  if (!styleEl) return
+  styleEl.textContent = generateCSS()
+}
+
+/**
+ * Schedules a CSS update on the next microtask if one is not already pending.
+ *
+ * Multiple synchronous rule registrations are batched into a single DOM write,
+ * avoiding redundant style recalculations.
+ *
+ * @internal
+ */
+function scheduleUpdate(): void {
+  if (pending) return
+  pending = true
+  queueMicrotask(flush)
+}
+
+/**
+ * Initialises the runtime style injection.
+ *
+ * - Looks for an existing `<style id="twc">` element or creates one.
+ * - Subscribes to registry changes via {@link onChange}.
+ * - Triggers an initial CSS flush.
+ *
+ * This function is a no-op in non-browser environments (SSR-safe).
+ *
+ * @internal
+ */
+function init(): void {
+  if (typeof document === 'undefined') return
+  if (styleEl) return
+
+  styleEl = document.getElementById('twc') as HTMLStyleElement | null
+  if (!styleEl) {
+    styleEl = document.createElement('style')
+    styleEl.id = 'twc'
+    document.head.appendChild(styleEl)
+  }
+
+  onChange(scheduleUpdate)
+  scheduleUpdate()
+}
+
+init()

package/src/layer.ts

@@ -0,0 +1,81 @@
+/**
+ * Monotonically increasing counter used to assign a unique ordering layer
+ * to each style rule. This controls the order rules appear in the generated
+ * CSS, ensuring that later-declared utilities override earlier ones.
+ *
+ * @internal
+ */
+let globalLayer = 0
+
+/**
+ * Returns the next layer number and increments the global counter.
+ *
+ * Each call returns a value one greater than the previous call, starting
+ * from `0`. The layer number is embedded into each registered rule to
+ * control CSS source order: rules with lower layer numbers appear first.
+ *
+ * @internal
+ * @returns The next sequential layer number.
+ *
+ * @example
+ * ```ts
+ * nextLayer() // 0
+ * nextLayer() // 1
+ * nextLayer() // 2
+ * ```
+ */
+export function nextLayer(): number {
+  return globalLayer++
+}
+
+/**
+ * Assigns an explicit layer priority to a style rule.
+ *
+ * By default, rules receive auto-incremented layer numbers based on
+ * declaration order. Use `layer()` to override this and force a rule
+ * to a specific priority level. Higher numbers = higher priority
+ * (overrides lower).
+ *
+ * @param priority - The explicit layer number to assign.
+ * @returns A function that accepts style rules and wraps them with the given layer.
+ *
+ * @example Force a reset to lowest priority
+ * ```ts
+ * import { cx, layer, p, bg } from 'typewritingclass'
+ *
+ * cx(layer(0)(bg('white')), p(4))
+ * // bg('white') is forced to layer 0, p(4) gets auto-assigned layer 1
+ * // p(4) overrides any conflicting property from bg('white')
+ * ```
+ *
+ * @example Force an override to highest priority
+ * ```ts
+ * cx(p(4), layer(1000)(p(8)))
+ * // p(8) at layer 1000 always overrides p(4)
+ * ```
+ */
+export function layer(priority: number): (...rules: import('./types.ts').StyleRule[]) => import('./types.ts').StyleRule {
+  return (...rules) => {
+    const combined = rules.length === 1
+      ? rules[0]
+      : {
+          _tag: 'StyleRule' as const,
+          declarations: Object.assign({}, ...rules.map(r => r.declarations)),
+          selectors: [...new Set(rules.flatMap(r => r.selectors))],
+          mediaQueries: [...new Set(rules.flatMap(r => r.mediaQueries))],
+          ...(rules.some(r => r.dynamicBindings) ? {
+            dynamicBindings: Object.assign({}, ...rules.filter(r => r.dynamicBindings).map(r => r.dynamicBindings)),
+          } : {}),
+        }
+    return { ...combined, _layer: priority } as any
+  }
+}
+
+/**
+ * Resets the global layer counter back to `0`.
+ *
+ * @internal Exposed for testing only. Do not call in production code.
+ */
+export function _resetLayer(): void {
+  globalLayer = 0
+}

package/src/modifiers/aria.ts

@@ -0,0 +1,15 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelector } from '../rule.ts'
+
+export const ariaChecked: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-checked="true"]')
+export const ariaDisabled: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-disabled="true"]')
+export const ariaExpanded: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-expanded="true"]')
+export const ariaHidden: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-hidden="true"]')
+export const ariaPressed: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-pressed="true"]')
+export const ariaReadonly: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-readonly="true"]')
+export const ariaRequired: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-required="true"]')
+export const ariaSelected: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[aria-selected="true"]')
+
+export function aria(attr: string): Modifier {
+  return (rule: StyleRule) => wrapWithSelector(rule, `[aria-${attr}]`)
+}

package/src/modifiers/colorScheme.ts

@@ -0,0 +1,32 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithMediaQuery } from '../rule.ts'
+
+/**
+ * Applies styles only when the user's operating system or browser is set to a dark color scheme.
+ *
+ * Use with {@link when} to conditionally apply style rules inside a
+ * `@media (prefers-color-scheme: dark)` query. This responds to the user's
+ * system-level preference, not a manual theme toggle. For manual theme switching,
+ * see {@link setTheme} and the theme API.
+ *
+ * @param rule - The style rule to apply in dark mode.
+ * @returns A new {@link StyleRule} wrapped in the `prefers-color-scheme: dark` media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, bg, color, when, dark } from 'typewritingclass'
+ *
+ * cx(
+ *   bg('#ffffff'),
+ *   color('#111827'),
+ *   when(dark)(bg('#111827')),
+ *   when(dark)(color('#f9fafb')),
+ * )
+ * // CSS: .abc { background-color: #ffffff; }
+ * //      .def { color: #111827; }
+ * //      @media (prefers-color-scheme: dark) { .ghi { background-color: #111827; } }
+ * //      @media (prefers-color-scheme: dark) { .jkl { color: #f9fafb; } }
+ * ```
+ */
+export const dark: Modifier = (rule: StyleRule) =>
+  wrapWithMediaQuery(rule, '(prefers-color-scheme: dark)')

package/src/modifiers/data.ts

@@ -0,0 +1,6 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelector } from '../rule.ts'
+
+export function data(attr: string): Modifier {
+  return (rule: StyleRule) => wrapWithSelector(rule, `[data-${attr}]`)
+}

package/src/modifiers/direction.ts

@@ -0,0 +1,5 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelectorTemplate } from '../rule.ts'
+
+export const rtl: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '[dir="rtl"] &')
+export const ltr: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '[dir="ltr"] &')

package/src/modifiers/group.ts

@@ -0,0 +1,21 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelectorTemplate } from '../rule.ts'
+
+export const groupHover: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:hover &')
+export const groupFocus: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:focus &')
+export const groupActive: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:active &')
+export const groupFocusVisible: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:focus-visible &')
+export const groupFocusWithin: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:focus-within &')
+export const groupDisabled: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:disabled &')
+export const groupChecked: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:checked &')
+export const groupEmpty: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:empty &')
+export const groupFirst: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:first-child &')
+export const groupLast: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:last-child &')
+export const groupOdd: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:nth-child(odd) &')
+export const groupEven: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:nth-child(even) &')
+export const groupOpen: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group[open] &')
+export const groupVisited: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.group:visited &')
+
+export function groupHas(selector: string): Modifier {
+  return (rule: StyleRule) => wrapWithSelectorTemplate(rule, `.group:has(${selector}) &`)
+}

package/src/modifiers/index.ts

@@ -0,0 +1,17 @@
+export {
+  hover, focus, active, disabled, focusVisible, focusWithin, firstChild, lastChild,
+  visited, checked, indeterminate, default_, required_, valid, invalid,
+  inRange, outOfRange, placeholderShown, autofill, readOnly, empty,
+  even, odd, firstOfType, lastOfType, onlyChild, onlyOfType, target, open_,
+  has_,
+} from './pseudo.ts'
+export { sm, md, lg, xl, _2xl, maxSm, maxMd, maxLg, maxXl, max2xl } from './responsive.ts'
+export { dark } from './colorScheme.ts'
+export { motionReduce, motionSafe, print_, portrait, landscape, contrastMore, contrastLess, forcedColors } from './media.ts'
+export { before, after, placeholder_, file_, marker, selection_, firstLine, firstLetter, backdrop_ } from './pseudoElements.ts'
+export { ariaChecked, ariaDisabled, ariaExpanded, ariaHidden, ariaPressed, ariaReadonly, ariaRequired, ariaSelected, aria } from './aria.ts'
+export { data } from './data.ts'
+export { supports } from './supports.ts'
+export { groupHover, groupFocus, groupActive, groupFocusVisible, groupFocusWithin, groupDisabled, groupChecked, groupEmpty, groupFirst, groupLast, groupOdd, groupEven, groupOpen, groupVisited, groupHas } from './group.ts'
+export { peerHover, peerFocus, peerActive, peerFocusVisible, peerDisabled, peerChecked, peerInvalid, peerRequired, peerPlaceholderShown, peerFocusWithin, peerEmpty, peerFirst, peerLast, peerOdd, peerEven, peerOpen, peerVisited, peerHas } from './peer.ts'
+export { rtl, ltr } from './direction.ts'

package/src/modifiers/media.ts

@@ -0,0 +1,11 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithMediaQuery } from '../rule.ts'
+
+export const motionReduce: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(prefers-reduced-motion: reduce)')
+export const motionSafe: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(prefers-reduced-motion: no-preference)')
+export const print_: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, 'print')
+export const portrait: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(orientation: portrait)')
+export const landscape: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(orientation: landscape)')
+export const contrastMore: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(prefers-contrast: more)')
+export const contrastLess: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(prefers-contrast: less)')
+export const forcedColors: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(forced-colors: active)')

package/src/modifiers/peer.ts

@@ -0,0 +1,24 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelectorTemplate } from '../rule.ts'
+
+export const peerHover: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:hover ~ &')
+export const peerFocus: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:focus ~ &')
+export const peerActive: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:active ~ &')
+export const peerFocusVisible: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:focus-visible ~ &')
+export const peerDisabled: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:disabled ~ &')
+export const peerChecked: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:checked ~ &')
+export const peerInvalid: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:invalid ~ &')
+export const peerRequired: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:required ~ &')
+export const peerPlaceholderShown: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:placeholder-shown ~ &')
+export const peerFocusWithin: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:focus-within ~ &')
+export const peerEmpty: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:empty ~ &')
+export const peerFirst: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:first-child ~ &')
+export const peerLast: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:last-child ~ &')
+export const peerOdd: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:nth-child(odd) ~ &')
+export const peerEven: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:nth-child(even) ~ &')
+export const peerOpen: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer[open] ~ &')
+export const peerVisited: Modifier = (rule: StyleRule) => wrapWithSelectorTemplate(rule, '.peer:visited ~ &')
+
+export function peerHas(selector: string): Modifier {
+  return (rule: StyleRule) => wrapWithSelectorTemplate(rule, `.peer:has(${selector}) ~ &`)
+}

package/src/modifiers/pseudo.ts

@@ -0,0 +1,183 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelector } from '../rule.ts'
+
+/**
+ * Applies styles only when the element is hovered.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:hover`.
+ *
+ * @param rule - The style rule to apply on hover.
+ * @returns A new {@link StyleRule} scoped to the `:hover` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, bg, when, hover } from 'typewritingclass'
+ *
+ * cx(bg('#3b82f6'), when(hover)(bg('#2563eb')))
+ * // CSS: .abc { background-color: #3b82f6; }
+ * //      .def:hover { background-color: #2563eb; }
+ * ```
+ */
+export const hover: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':hover')
+
+/**
+ * Applies styles only when the element has keyboard or pointer focus.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:focus`.
+ *
+ * @param rule - The style rule to apply on focus.
+ * @returns A new {@link StyleRule} scoped to the `:focus` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, borderColor, when, focus } from 'typewritingclass'
+ *
+ * cx(borderColor('#d1d5db'), when(focus)(borderColor('#3b82f6')))
+ * // CSS: .abc { border-color: #d1d5db; }
+ * //      .def:focus { border-color: #3b82f6; }
+ * ```
+ */
+export const focus: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':focus')
+
+/**
+ * Applies styles only when the element is being actively pressed.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:active`.
+ *
+ * @param rule - The style rule to apply while the element is active.
+ * @returns A new {@link StyleRule} scoped to the `:active` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, bg, when, active } from 'typewritingclass'
+ *
+ * cx(bg('#3b82f6'), when(active)(bg('#1d4ed8')))
+ * // CSS: .abc { background-color: #3b82f6; }
+ * //      .def:active { background-color: #1d4ed8; }
+ * ```
+ */
+export const active: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':active')
+
+/**
+ * Applies styles only when the element is disabled.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:disabled`.
+ * Commonly used for form controls such as buttons and inputs.
+ *
+ * @param rule - The style rule to apply when disabled.
+ * @returns A new {@link StyleRule} scoped to the `:disabled` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, opacity, when, disabled } from 'typewritingclass'
+ *
+ * cx(opacity('1'), when(disabled)(opacity('0.5')))
+ * // CSS: .abc { opacity: 1; }
+ * //      .def:disabled { opacity: 0.5; }
+ * ```
+ */
+export const disabled: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':disabled')
+
+/**
+ * Applies styles only when the element has visible focus (typically keyboard focus).
+ *
+ * Use with {@link when} to conditionally apply style rules on `:focus-visible`.
+ * Unlike {@link focus}, this only matches when the user agent determines that
+ * focus should be visibly indicated (e.g., keyboard navigation, not mouse clicks).
+ *
+ * @param rule - The style rule to apply on visible focus.
+ * @returns A new {@link StyleRule} scoped to the `:focus-visible` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, outline, when, focusVisible } from 'typewritingclass'
+ *
+ * cx(when(focusVisible)(outline('2px solid #3b82f6')))
+ * // CSS: .abc:focus-visible { outline: 2px solid #3b82f6; }
+ * ```
+ */
+export const focusVisible: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':focus-visible')
+
+/**
+ * Applies styles when the element or any of its descendants has focus.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:focus-within`.
+ * Useful for styling a parent container when a child input receives focus.
+ *
+ * @param rule - The style rule to apply when focus is within the element.
+ * @returns A new {@link StyleRule} scoped to the `:focus-within` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, borderColor, when, focusWithin } from 'typewritingclass'
+ *
+ * cx(borderColor('#d1d5db'), when(focusWithin)(borderColor('#3b82f6')))
+ * // CSS: .abc { border-color: #d1d5db; }
+ * //      .def:focus-within { border-color: #3b82f6; }
+ * ```
+ */
+export const focusWithin: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':focus-within')
+
+/**
+ * Applies styles only when the element is the first child of its parent.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:first-child`.
+ *
+ * @param rule - The style rule to apply to the first child.
+ * @returns A new {@link StyleRule} scoped to the `:first-child` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, mt, when, firstChild } from 'typewritingclass'
+ *
+ * cx(mt('1rem'), when(firstChild)(mt('0')))
+ * // CSS: .abc { margin-top: 1rem; }
+ * //      .def:first-child { margin-top: 0; }
+ * ```
+ */
+export const firstChild: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':first-child')
+
+/**
+ * Applies styles only when the element is the last child of its parent.
+ *
+ * Use with {@link when} to conditionally apply style rules on `:last-child`.
+ *
+ * @param rule - The style rule to apply to the last child.
+ * @returns A new {@link StyleRule} scoped to the `:last-child` pseudo-class.
+ *
+ * @example
+ * ```ts
+ * import { cx, mb, when, lastChild } from 'typewritingclass'
+ *
+ * cx(mb('1rem'), when(lastChild)(mb('0')))
+ * // CSS: .abc { margin-bottom: 1rem; }
+ * //      .def:last-child { margin-bottom: 0; }
+ * ```
+ */
+export const lastChild: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':last-child')
+
+export const visited: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':visited')
+export const checked: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':checked')
+export const indeterminate: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':indeterminate')
+export const default_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':default')
+export const required_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':required')
+export const valid: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':valid')
+export const invalid: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':invalid')
+export const inRange: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':in-range')
+export const outOfRange: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':out-of-range')
+export const placeholderShown: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':placeholder-shown')
+export const autofill: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':autofill')
+export const readOnly: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':read-only')
+export const empty: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':empty')
+export const even: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':nth-child(even)')
+export const odd: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':nth-child(odd)')
+export const firstOfType: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':first-of-type')
+export const lastOfType: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':last-of-type')
+export const onlyChild: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':only-child')
+export const onlyOfType: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':only-of-type')
+export const target: Modifier = (rule: StyleRule) => wrapWithSelector(rule, ':target')
+export const open_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '[open]')
+
+export function has_(selector: string): Modifier {
+  return (rule: StyleRule) => wrapWithSelector(rule, `:has(${selector})`)
+}

package/src/modifiers/pseudoElements.ts

@@ -0,0 +1,26 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSelector } from '../rule.ts'
+
+export const before: Modifier = (rule: StyleRule) => {
+  const result = wrapWithSelector(rule, '::before')
+  if (!result.declarations.content) {
+    result.declarations = { content: '""', ...result.declarations }
+  }
+  return result
+}
+
+export const after: Modifier = (rule: StyleRule) => {
+  const result = wrapWithSelector(rule, '::after')
+  if (!result.declarations.content) {
+    result.declarations = { content: '""', ...result.declarations }
+  }
+  return result
+}
+
+export const placeholder_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::placeholder')
+export const file_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::file-selector-button')
+export const marker: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::marker')
+export const selection_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::selection')
+export const firstLine: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::first-line')
+export const firstLetter: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::first-letter')
+export const backdrop_: Modifier = (rule: StyleRule) => wrapWithSelector(rule, '::backdrop')