typewritingclass 0.2.0

package/src/modifiers/responsive.ts

@@ -0,0 +1,110 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithMediaQuery } from '../rule.ts'
+
+/**
+ * Applies styles at the **small** breakpoint and above (`min-width: 640px`).
+ *
+ * Use with {@link when} to make style rules responsive. Wraps the rule in a
+ * `@media (min-width: 640px)` query.
+ *
+ * @param rule - The style rule to apply at `>=640px`.
+ * @returns A new {@link StyleRule} wrapped in the small-breakpoint media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, p, when, sm } from 'typewritingclass'
+ *
+ * cx(p('1rem'), when(sm)(p('2rem')))
+ * // CSS: .abc { padding: 1rem; }
+ * //      @media (min-width: 640px) { .def { padding: 2rem; } }
+ * ```
+ */
+export const sm: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(min-width: 640px)')
+
+/**
+ * Applies styles at the **medium** breakpoint and above (`min-width: 768px`).
+ *
+ * Use with {@link when} to make style rules responsive. Wraps the rule in a
+ * `@media (min-width: 768px)` query.
+ *
+ * @param rule - The style rule to apply at `>=768px`.
+ * @returns A new {@link StyleRule} wrapped in the medium-breakpoint media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, grid, gridCols, when, md } from 'typewritingclass'
+ *
+ * cx(gridCols('1'), when(md)(gridCols('2')))
+ * // CSS: .abc { grid-template-columns: 1; }
+ * //      @media (min-width: 768px) { .def { grid-template-columns: 2; } }
+ * ```
+ */
+export const md: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(min-width: 768px)')
+
+/**
+ * Applies styles at the **large** breakpoint and above (`min-width: 1024px`).
+ *
+ * Use with {@link when} to make style rules responsive. Wraps the rule in a
+ * `@media (min-width: 1024px)` query.
+ *
+ * @param rule - The style rule to apply at `>=1024px`.
+ * @returns A new {@link StyleRule} wrapped in the large-breakpoint media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, maxW, when, lg } from 'typewritingclass'
+ *
+ * cx(maxW('100%'), when(lg)(maxW('1024px')))
+ * // CSS: .abc { max-width: 100%; }
+ * //      @media (min-width: 1024px) { .def { max-width: 1024px; } }
+ * ```
+ */
+export const lg: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(min-width: 1024px)')
+
+/**
+ * Applies styles at the **extra-large** breakpoint and above (`min-width: 1280px`).
+ *
+ * Use with {@link when} to make style rules responsive. Wraps the rule in a
+ * `@media (min-width: 1280px)` query.
+ *
+ * @param rule - The style rule to apply at `>=1280px`.
+ * @returns A new {@link StyleRule} wrapped in the extra-large-breakpoint media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, maxW, when, xl } from 'typewritingclass'
+ *
+ * cx(maxW('100%'), when(xl)(maxW('1280px')))
+ * // CSS: .abc { max-width: 100%; }
+ * //      @media (min-width: 1280px) { .def { max-width: 1280px; } }
+ * ```
+ */
+export const xl: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(min-width: 1280px)')
+
+/**
+ * Applies styles at the **2x-large** breakpoint and above (`min-width: 1536px`).
+ *
+ * Use with {@link when} to make style rules responsive. Wraps the rule in a
+ * `@media (min-width: 1536px)` query.
+ *
+ * Exported as `_2xl` because identifiers cannot start with a digit in JavaScript.
+ *
+ * @param rule - The style rule to apply at `>=1536px`.
+ * @returns A new {@link StyleRule} wrapped in the 2xl-breakpoint media query.
+ *
+ * @example
+ * ```ts
+ * import { cx, maxW, when, _2xl } from 'typewritingclass'
+ *
+ * cx(maxW('100%'), when(_2xl)(maxW('1536px')))
+ * // CSS: .abc { max-width: 100%; }
+ * //      @media (min-width: 1536px) { .def { max-width: 1536px; } }
+ * ```
+ */
+export const _2xl: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(min-width: 1536px)')
+
+export const maxSm: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(max-width: 639px)')
+export const maxMd: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(max-width: 767px)')
+export const maxLg: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(max-width: 1023px)')
+export const maxXl: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(max-width: 1279px)')
+export const max2xl: Modifier = (rule: StyleRule) => wrapWithMediaQuery(rule, '(max-width: 1535px)')

package/src/modifiers/supports.ts

@@ -0,0 +1,6 @@
+import type { StyleRule, Modifier } from '../types.ts'
+import { wrapWithSupportsQuery } from '../rule.ts'
+
+export function supports(query: string): Modifier {
+  return (rule: StyleRule) => wrapWithSupportsQuery(rule, query)
+}

package/src/registry.ts

@@ -0,0 +1,171 @@
+import type { StyleRule } from './types.ts'
+
+/**
+ * An entry in the style registry, pairing a {@link StyleRule} with its
+ * layer ordering number.
+ *
+ * @internal
+ */
+interface RegistryEntry {
+  /** The style rule containing CSS declarations, selectors, and media queries. */
+  rule: StyleRule
+  /** The layer number determining the order this rule appears in the generated CSS. Lower numbers come first. */
+  layer: number
+}
+
+/**
+ * Global map of generated class names to their {@link RegistryEntry}.
+ * Each unique class name is registered at most once.
+ *
+ * @internal
+ */
+const registry = new Map<string, RegistryEntry>()
+
+/**
+ * List of callbacks invoked whenever a new rule is registered.
+ *
+ * @internal
+ */
+const listeners: Array<() => void> = []
+
+/**
+ * Registers a style rule under a generated class name.
+ *
+ * If the class name is already registered, the call is a no-op (first-write-wins).
+ * After a successful registration, all listeners registered via {@link onChange}
+ * are notified synchronously.
+ *
+ * @internal
+ * @param className - The unique hashed class name (e.g., `'_a1b2c'`).
+ * @param rule - The {@link StyleRule} to associate with the class name.
+ * @param layer - The layer ordering number from {@link nextLayer}, controlling
+ *   the position of this rule in the final CSS output.
+ *
+ * @example
+ * ```ts
+ * register('_a1b2c', createRule({ padding: '1rem' }), 0)
+ * ```
+ */
+export function register(className: string, rule: StyleRule, layer: number): void {
+  if (registry.has(className)) return
+  registry.set(className, { rule, layer })
+  for (const cb of listeners) cb()
+}
+
+/**
+ * Subscribes a callback to be invoked whenever a new rule is registered.
+ *
+ * This is used by the runtime style injection module ({@link inject}) to
+ * schedule CSS updates when new rules appear.
+ *
+ * @internal
+ * @param callback - A function to call on each new registration.
+ * @returns An unsubscribe function that removes the listener when called.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = onChange(() => {
+ *   console.log('New rule registered, CSS may need updating')
+ * })
+ *
+ * // Later, stop listening:
+ * unsubscribe()
+ * ```
+ */
+export function onChange(callback: () => void): () => void {
+  listeners.push(callback)
+  return () => {
+    const idx = listeners.indexOf(callback)
+    if (idx >= 0) listeners.splice(idx, 1)
+  }
+}
+
+/**
+ * Renders a single registry entry into a CSS rule string.
+ *
+ * Builds the selector from the class name and any pseudo-class/attribute
+ * selectors, then wraps the result in `@media` blocks for each media query.
+ *
+ * @internal
+ * @param className - The hashed class name.
+ * @param rule - The {@link StyleRule} to render.
+ * @returns A complete CSS rule string, potentially wrapped in media queries.
+ */
+function renderRule(className: string, rule: StyleRule): string {
+  const decls = Object.entries(rule.declarations)
+    .map(([prop, val]) => `  ${prop}: ${val};`)
+    .join('\n')
+
+  let selector: string
+  if (rule.selectorTemplate) {
+    selector = rule.selectorTemplate.replace(/&/g, `.${className}`)
+  } else {
+    selector = `.${className}`
+    if (rule.selectors.length > 0) {
+      selector += rule.selectors.join('')
+    }
+  }
+
+  let css = `${selector} {\n${decls}\n}`
+
+  for (const sq of rule.supportsQueries) {
+    css = `@supports ${sq} {\n${css}\n}`
+  }
+
+  for (const mq of rule.mediaQueries) {
+    css = `@media ${mq} {\n${css}\n}`
+  }
+
+  return css
+}
+
+/**
+ * Generates a complete CSS stylesheet string from all registered rules.
+ *
+ * Rules are sorted by their layer number (ascending) so that later-declared
+ * utilities naturally override earlier ones in the cascade. Rules are
+ * separated by blank lines.
+ *
+ * @internal
+ * @returns The full CSS string for all registered style rules, or an empty
+ *   string if no rules have been registered.
+ *
+ * @example
+ * ```ts
+ * register('_a', createRule({ padding: '1rem' }), 0)
+ * register('_b', createRule({ margin: '0' }), 1)
+ *
+ * generateCSS()
+ * // "._a {\n  padding: 1rem;\n}\n\n._b {\n  margin: 0;\n}"
+ * ```
+ */
+export function generateCSS(): string {
+  const entries = [...registry.entries()].sort((a, b) => a[1].layer - b[1].layer)
+  const rules = entries.map(([className, { rule }]) => renderRule(className, rule))
+  if (rules.length === 0) return ''
+  return rules.join('\n\n')
+}
+
+/**
+ * Returns a read-only view of the internal style registry.
+ *
+ * Useful for debugging and testing to inspect which rules have been registered.
+ *
+ * @internal
+ * @returns A `ReadonlyMap` mapping class names to their {@link RegistryEntry}.
+ */
+export function getRegistry(): ReadonlyMap<string, RegistryEntry> {
+  return registry
+}
+
+/**
+ * Removes all entries from the style registry.
+ *
+ * Primarily used in tests to reset state between test cases. Does **not**
+ * notify change listeners.
+ *
+ * @internal
+ */
+export function clearRegistry(): void {
+  registry.clear()
+}

package/src/rule.ts

@@ -0,0 +1,202 @@
+import type { StyleRule } from './types.ts'
+
+/**
+ * Creates a static {@link StyleRule} from a set of CSS declarations.
+ *
+ * This is the lowest-level rule constructor. The returned rule has no
+ * selectors, media queries, or dynamic bindings attached.
+ *
+ * @internal
+ * @param declarations - A record of CSS property-value pairs
+ *   (e.g., `{ 'background-color': '#3b82f6' }`).
+ * @returns A new {@link StyleRule} with the given declarations and empty
+ *   `selectors` and `mediaQueries` arrays.
+ *
+ * @example
+ * ```ts
+ * const rule = createRule({ 'padding': '1rem', 'margin': '0' })
+ * // { _tag: 'StyleRule', declarations: { padding: '1rem', margin: '0' }, selectors: [], mediaQueries: [] }
+ * ```
+ */
+export function createRule(declarations: Record<string, string>): StyleRule {
+  return {
+    _tag: 'StyleRule',
+    declarations,
+    selectors: [],
+    mediaQueries: [],
+    supportsQueries: [],
+  }
+}
+
+/**
+ * Creates a {@link StyleRule} that includes dynamic CSS custom property bindings.
+ *
+ * Dynamic rules are produced when a utility receives a {@link dynamic} value.
+ * The `dynamicBindings` map CSS custom property names to runtime expressions,
+ * enabling values that can change without regenerating the class name.
+ *
+ * @internal
+ * @param declarations - A record of CSS property-value pairs, where values may
+ *   reference CSS custom properties (e.g., `{ color: 'var(--twc-d0)' }`).
+ * @param dynamicBindings - A record mapping CSS custom property names to their
+ *   runtime values (e.g., `{ '--twc-d0': '#ff0000' }`).
+ * @returns A new {@link StyleRule} with declarations, empty selectors/mediaQueries,
+ *   and the given `dynamicBindings`.
+ *
+ * @example
+ * ```ts
+ * const rule = createDynamicRule(
+ *   { 'color': 'var(--twc-d0)' },
+ *   { '--twc-d0': '#ff0000' },
+ * )
+ * // rule.dynamicBindings === { '--twc-d0': '#ff0000' }
+ * ```
+ */
+export function createDynamicRule(
+  declarations: Record<string, string>,
+  dynamicBindings: Record<string, string>,
+): StyleRule {
+  return {
+    _tag: 'StyleRule',
+    declarations,
+    selectors: [],
+    mediaQueries: [],
+    supportsQueries: [],
+    dynamicBindings,
+  }
+}
+
+/**
+ * Merges multiple {@link StyleRule} objects into a single combined rule.
+ *
+ * Declarations are merged left-to-right (later rules override earlier ones for
+ * the same property). Selectors and media queries are de-duplicated and
+ * concatenated. Dynamic bindings from all rules are merged together.
+ *
+ * @internal
+ * @param rules - An array of {@link StyleRule} objects to merge.
+ * @returns A single {@link StyleRule} containing the merged declarations,
+ *   selectors, media queries, and dynamic bindings from all input rules.
+ *
+ * @example
+ * ```ts
+ * const a = createRule({ padding: '1rem' })
+ * const b = createRule({ margin: '0' })
+ * const combined = combineRules([a, b])
+ * // combined.declarations === { padding: '1rem', margin: '0' }
+ * ```
+ */
+export function combineRules(rules: StyleRule[]): StyleRule {
+  const merged: Record<string, string> = {}
+  const selectors: string[] = []
+  const mediaQueries: string[] = []
+  const supportsQueries: string[] = []
+  let dynamicBindings: Record<string, string> | undefined
+  for (const rule of rules) {
+    Object.assign(merged, rule.declarations)
+    for (const s of rule.selectors) {
+      if (!selectors.includes(s)) selectors.push(s)
+    }
+    for (const mq of rule.mediaQueries) {
+      if (!mediaQueries.includes(mq)) mediaQueries.push(mq)
+    }
+    for (const sq of rule.supportsQueries) {
+      if (!supportsQueries.includes(sq)) supportsQueries.push(sq)
+    }
+    if (rule.dynamicBindings) {
+      if (!dynamicBindings) dynamicBindings = {}
+      Object.assign(dynamicBindings, rule.dynamicBindings)
+    }
+  }
+  const result: StyleRule = { _tag: 'StyleRule', declarations: merged, selectors, mediaQueries, supportsQueries }
+  if (dynamicBindings) result.dynamicBindings = dynamicBindings
+  return result
+}
+
+/**
+ * Returns a copy of the given rule with an additional CSS selector appended.
+ *
+ * The selector is appended directly to the generated class name when the CSS
+ * is rendered (e.g., `.abc:hover`). Multiple selectors can be stacked by
+ * calling this function repeatedly.
+ *
+ * @internal
+ * @param rule - The source {@link StyleRule} to wrap.
+ * @param selector - The CSS selector suffix to append (e.g., `':hover'`, `':first-child'`).
+ * @returns A new {@link StyleRule} with the selector added to its `selectors` array.
+ *
+ * @example
+ * ```ts
+ * const base = createRule({ opacity: '1' })
+ * const hovered = wrapWithSelector(base, ':hover')
+ * // Rendered CSS: .abc:hover { opacity: 1; }
+ * ```
+ */
+export function wrapWithSelector(rule: StyleRule, selector: string): StyleRule {
+  return {
+    ...rule,
+    selectors: [...rule.selectors, selector],
+  }
+}
+
+/**
+ * Returns a copy of the given rule wrapped in an additional CSS media query.
+ *
+ * When rendered, the rule's CSS block is nested inside a `@media` at-rule.
+ * Multiple media queries can be stacked by calling this function repeatedly.
+ *
+ * @internal
+ * @param rule - The source {@link StyleRule} to wrap.
+ * @param query - The media query condition (e.g., `'(min-width: 768px)'`,
+ *   `'(prefers-color-scheme: dark)'`).
+ * @returns A new {@link StyleRule} with the query added to its `mediaQueries` array.
+ *
+ * @example
+ * ```ts
+ * const base = createRule({ padding: '2rem' })
+ * const responsive = wrapWithMediaQuery(base, '(min-width: 768px)')
+ * // Rendered CSS: @media (min-width: 768px) { .abc { padding: 2rem; } }
+ * ```
+ */
+export function wrapWithMediaQuery(rule: StyleRule, query: string): StyleRule {
+  return {
+    ...rule,
+    mediaQueries: [...rule.mediaQueries, query],
+  }
+}
+
+/**
+ * Returns a copy of the given rule with a selector template applied.
+ *
+ * The template uses `&` as a placeholder for the generated class name.
+ * At render time, `&` is replaced with `.className`.
+ *
+ * @internal
+ * @param rule - The source {@link StyleRule} to wrap.
+ * @param template - The selector template (e.g., `'.group:hover &'`).
+ * @returns A new {@link StyleRule} with the `selectorTemplate` set.
+ */
+export function wrapWithSelectorTemplate(rule: StyleRule, template: string): StyleRule {
+  return {
+    ...rule,
+    selectorTemplate: template,
+  }
+}
+
+/**
+ * Returns a copy of the given rule wrapped in an additional CSS `@supports` query.
+ *
+ * When rendered, the rule's CSS block is nested inside a `@supports` at-rule.
+ * Multiple supports queries can be stacked by calling this function repeatedly.
+ *
+ * @internal
+ * @param rule - The source {@link StyleRule} to wrap.
+ * @param query - The supports query condition (e.g., `'(display: grid)'`).
+ * @returns A new {@link StyleRule} with the query added to its `supportsQueries` array.
+ */
+export function wrapWithSupportsQuery(rule: StyleRule, query: string): StyleRule {
+  return {
+    ...rule,
+    supportsQueries: [...rule.supportsQueries, query],
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,36 @@
+import type { DynamicResult } from './types.ts'
+
+/**
+ * Runtime helper injected by the compiler when `dynamic()` values are used.
+ *
+ * Combines a pre-computed static class name with a set of CSS custom property
+ * bindings that carry runtime values. The returned {@link DynamicResult} can
+ * be spread onto a DOM element (or passed to {@link useStyle} in React) to
+ * apply both the `className` and the inline `style` containing the custom
+ * property overrides.
+ *
+ * This function is **not intended to be called manually** -- the typewritingclass
+ * compiler generates calls to it when it encounters `dynamic()` in style
+ * expressions.
+ *
+ * @internal
+ * @param className - The hashed class name generated at compile time
+ *   (e.g., `'_a1b2c'`).
+ * @param bindings - A record mapping CSS custom property names to their
+ *   runtime string values (e.g., `{ '--twc-d0': '#ff0000' }`).
+ * @returns A {@link DynamicResult} with `className` and `style` properties
+ *   ready for spreading onto an element.
+ *
+ * @example
+ * ```ts
+ * // Compiler output (not written by hand):
+ * __twcDynamic('_a1b2c', { '--twc-d0': props.color })
+ * // => { className: '_a1b2c', style: { '--twc-d0': '#ff0000' } }
+ * ```
+ */
+export function __twcDynamic(
+  className: string,
+  bindings: Record<string, string>,
+): DynamicResult {
+  return { className, style: bindings }
+}

package/src/theme/animations.ts

@@ -0,0 +1,11 @@
+export const spin = 'spin 1s linear infinite'
+export const ping = 'ping 1s cubic-bezier(0, 0, 0.2, 1) infinite'
+export const pulse = 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite'
+export const bounce = 'bounce 1s infinite'
+
+export const keyframes = {
+  spin: `@keyframes spin { to { transform: rotate(360deg); } }`,
+  ping: `@keyframes ping { 75%, 100% { transform: scale(2); opacity: 0; } }`,
+  pulse: `@keyframes pulse { 50% { opacity: .5; } }`,
+  bounce: `@keyframes bounce { 0%, 100% { transform: translateY(-25%); animation-timing-function: cubic-bezier(0.8,0,1,1); } 50% { transform: none; animation-timing-function: cubic-bezier(0,0,0.2,1); } }`,
+}

package/src/theme/borders.ts

@@ -0,0 +1,9 @@
+export const none = '0px'
+export const sm = '0.125rem'
+export const DEFAULT = '0.25rem'
+export const md = '0.375rem'
+export const lg = '0.5rem'
+export const xl = '0.75rem'
+export const _2xl = '1rem'
+export const _3xl = '1.5rem'
+export const full = '9999px'