typewritingclass 0.2.0

package/src/theme/sizes.ts

@@ -0,0 +1,37 @@
+export const full = '100%'
+export const screen = '100vw'
+export const screenH = '100vh'
+export const min = 'min-content'
+export const max = 'max-content'
+export const fit = 'fit-content'
+export const auto = 'auto'
+
+// ---------------------------------------------------------------------------
+// Max-width scale (Tailwind v3 defaults)
+// ---------------------------------------------------------------------------
+
+export const maxWidths = {
+  none: 'none',
+  0: '0rem',
+  xs: '20rem',
+  sm: '24rem',
+  md: '28rem',
+  lg: '32rem',
+  xl: '36rem',
+  '2xl': '42rem',
+  '3xl': '48rem',
+  '4xl': '56rem',
+  '5xl': '64rem',
+  '6xl': '72rem',
+  '7xl': '80rem',
+  full: '100%',
+  min: 'min-content',
+  max: 'max-content',
+  fit: 'fit-content',
+  prose: '65ch',
+  screenSm: '640px',
+  screenMd: '768px',
+  screenLg: '1024px',
+  screenXl: '1280px',
+  screen2xl: '1536px',
+} as const

package/src/theme/spacing.ts

@@ -0,0 +1,44 @@
+const spacingScale: Record<number, string> = {
+  0: '0px',
+  0.5: '0.125rem',
+  1: '0.25rem',
+  1.5: '0.375rem',
+  2: '0.5rem',
+  2.5: '0.625rem',
+  3: '0.75rem',
+  3.5: '0.875rem',
+  4: '1rem',
+  5: '1.25rem',
+  6: '1.5rem',
+  7: '1.75rem',
+  8: '2rem',
+  9: '2.25rem',
+  10: '2.5rem',
+  11: '2.75rem',
+  12: '3rem',
+  14: '3.5rem',
+  16: '4rem',
+  20: '5rem',
+  24: '6rem',
+  28: '7rem',
+  32: '8rem',
+  36: '9rem',
+  40: '10rem',
+  44: '11rem',
+  48: '12rem',
+  52: '13rem',
+  56: '14rem',
+  60: '15rem',
+  64: '16rem',
+  72: '18rem',
+  80: '20rem',
+  96: '24rem',
+}
+
+export function resolveSpacing(value: number | string): string {
+  if (typeof value === 'string') return value
+  if (value in spacingScale) return spacingScale[value]
+  return `${value * 0.25}rem`
+}
+
+export { spacingScale }

package/src/theme/typography.ts

@@ -0,0 +1,72 @@
+export interface TextSize {
+  fontSize: string
+  lineHeight: string
+}
+
+export const xs: TextSize = { fontSize: '0.75rem', lineHeight: '1rem' }
+export const sm: TextSize = { fontSize: '0.875rem', lineHeight: '1.25rem' }
+export const base: TextSize = { fontSize: '1rem', lineHeight: '1.5rem' }
+export const lg: TextSize = { fontSize: '1.125rem', lineHeight: '1.75rem' }
+export const xl: TextSize = { fontSize: '1.25rem', lineHeight: '1.75rem' }
+export const _2xl: TextSize = { fontSize: '1.5rem', lineHeight: '2rem' }
+export const _3xl: TextSize = { fontSize: '1.875rem', lineHeight: '2.25rem' }
+export const _4xl: TextSize = { fontSize: '2.25rem', lineHeight: '2.5rem' }
+export const _5xl: TextSize = { fontSize: '3rem', lineHeight: '1' }
+export const _6xl: TextSize = { fontSize: '3.75rem', lineHeight: '1' }
+export const _7xl: TextSize = { fontSize: '4.5rem', lineHeight: '1' }
+export const _8xl: TextSize = { fontSize: '6rem', lineHeight: '1' }
+export const _9xl: TextSize = { fontSize: '8rem', lineHeight: '1' }
+
+export const thin = '100'
+export const extralight = '200'
+export const light = '300'
+export const normal = '400'
+export const medium = '500'
+export const semibold = '600'
+export const bold = '700'
+export const extrabold = '800'
+export const black_ = '900'
+
+// ---------------------------------------------------------------------------
+// Font families (Tailwind v3 defaults)
+// ---------------------------------------------------------------------------
+
+export const fontFamilies = {
+  sans: 'ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+  serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+  mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+} as const
+
+// ---------------------------------------------------------------------------
+// Letter spacing / tracking (Tailwind v3 defaults)
+// ---------------------------------------------------------------------------
+
+export const letterSpacings = {
+  tighter: '-0.05em',
+  tight: '-0.025em',
+  normal: '0em',
+  wide: '0.025em',
+  wider: '0.05em',
+  widest: '0.1em',
+} as const
+
+// ---------------------------------------------------------------------------
+// Line height / leading (Tailwind v3 defaults)
+// ---------------------------------------------------------------------------
+
+export const lineHeights = {
+  none: '1',
+  tight: '1.25',
+  snug: '1.375',
+  normal: '1.5',
+  relaxed: '1.625',
+  loose: '2',
+  '3': '.75rem',
+  '4': '1rem',
+  '5': '1.25rem',
+  '6': '1.5rem',
+  '7': '1.75rem',
+  '8': '2rem',
+  '9': '2.25rem',
+  '10': '2.5rem',
+} as const

package/src/types.ts

@@ -0,0 +1,273 @@
+// ---------------------------------------------------------------------------
+// Brand infrastructure
+// ---------------------------------------------------------------------------
+
+declare const __brand: unique symbol
+
+/**
+ * Creates a nominal/branded type from a base type.
+ *
+ * Branded types look like their base type at runtime but are distinct at the
+ * type level, preventing accidental misuse (e.g. passing a color where a
+ * spacing value is expected).
+ *
+ * @example
+ * ```ts
+ * type Meters = Brand<number, 'meters'>
+ * type Seconds = Brand<number, 'seconds'>
+ *
+ * const d: Meters = 5 as Meters
+ * const t: Seconds = d // Type error — distinct brands!
+ * ```
+ */
+export type Brand<T, B extends string> = T & { readonly [__brand]: B }
+
+// ---------------------------------------------------------------------------
+// CSS value brands
+// ---------------------------------------------------------------------------
+
+/**
+ * A branded CSS color value — hex, `rgb()`, `hsl()`, CSS variable, etc.
+ *
+ * Theme color tokens (e.g. `blue[500]`) carry this brand. Raw color strings
+ * are also accepted alongside `CSSColor` since utility functions accept both.
+ */
+export type CSSColor = Brand<string, 'css-color'>
+
+/**
+ * A branded CSS length value — `rem`, `px`, `em`, `%`, `vh`, `vw`, etc.
+ *
+ * Theme spacing, size, and border-radius tokens carry this brand.
+ */
+export type CSSLength = Brand<string, 'css-length'>
+
+/**
+ * A branded CSS shadow value — `box-shadow` definition string.
+ *
+ * Theme shadow tokens (e.g. `lg` from `theme/shadows`) carry this brand.
+ */
+export type CSSShadow = Brand<string, 'css-shadow'>
+
+/**
+ * A branded CSS font-weight value — numeric string like `'400'` or `'700'`.
+ *
+ * Theme font weight tokens (e.g. `bold`, `semibold`) carry this brand.
+ */
+export type CSSFontWeight = Brand<string, 'css-font-weight'>
+
+// ---------------------------------------------------------------------------
+// Utility input types
+// ---------------------------------------------------------------------------
+
+/** Shorthand for any DynamicValue — used in utility input types. */
+type DynamicValueAny = import('./dynamic.ts').DynamicValue
+
+/**
+ * Input type for color utilities ({@link bg}, {@link textColor}, {@link borderColor}).
+ *
+ * Accepts theme color tokens (`CSSColor`), raw CSS color strings, or dynamic values.
+ */
+export type ColorInput = CSSColor | string | DynamicValueAny
+
+/**
+ * Input type for spacing utilities ({@link p}, {@link m}, {@link gap}).
+ *
+ * Accepts a theme scale number (`4` → `1rem`), a raw CSS length string
+ * (`'1.5rem'`), a theme length token, or a dynamic value.
+ */
+export type SpacingInput = number | CSSLength | string | DynamicValueAny
+
+/**
+ * Input type for size utilities ({@link w}, {@link h}, {@link minW}).
+ *
+ * Accepts a theme scale number, a raw CSS string (`'100%'`), a theme size
+ * token (`full`, `screen`), or a dynamic value.
+ */
+export type SizeInput = number | CSSLength | string | DynamicValueAny
+
+/**
+ * Input type for border-radius utilities ({@link rounded}).
+ *
+ * Accepts a theme radius token (`lg`), a raw CSS string, or a dynamic value.
+ */
+export type RadiusInput = CSSLength | string | DynamicValueAny
+
+/**
+ * Input type for shadow utilities ({@link shadow}).
+ *
+ * Accepts a theme shadow token (`lg`), a raw CSS string, or a dynamic value.
+ */
+export type ShadowInput = CSSShadow | string | DynamicValueAny
+
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+/**
+ * A self-contained CSS rule produced by utility functions, the {@link css}
+ * helper, or modifier composition.
+ *
+ * `StyleRule` is the fundamental unit of the typewritingclass system. Every
+ * utility (`p`, `bg`, `rounded`, ...) returns a `StyleRule`, and composing
+ * functions like `cx` and `dcx` consume them to generate class names and
+ * register CSS in the global stylesheet.
+ *
+ * You rarely need to construct a `StyleRule` by hand -- use the provided
+ * utilities or the `css` tagged-template helper instead.
+ *
+ * @example Inspecting a rule returned by a utility
+ * ```ts
+ * import { p } from 'typewritingclass'
+ *
+ * const rule = p(4)
+ * // rule.declarations  => { padding: '1rem' }
+ * // rule.selectors      => []
+ * // rule.mediaQueries   => []
+ * ```
+ *
+ * @example A rule wrapped with a modifier
+ * ```ts
+ * import { p, hover } from 'typewritingclass'
+ *
+ * const rule = hover(p(4))
+ * // rule.selectors => [':hover']
+ * // CSS: .className:hover { padding: 1rem; }
+ * ```
+ */
+export interface StyleRule {
+  /** Discriminant tag used for runtime type narrowing. Always `'StyleRule'`. */
+  _tag: 'StyleRule'
+  /**
+   * A map of CSS property-value pairs that this rule will emit.
+   *
+   * Keys are CSS property names (e.g. `'padding'`, `'background-color'`),
+   * and values are their corresponding CSS values (e.g. `'1rem'`, `'#3b82f6'`).
+   */
+  declarations: Record<string, string>
+  /**
+   * Pseudo-class or pseudo-element selectors appended to the generated
+   * class name (e.g. `[':hover']`, `[':focus', ':active']`).
+   *
+   * An empty array means the rule applies unconditionally.
+   */
+  selectors: string[]
+  /**
+   * Media query strings that wrap the generated rule
+   * (e.g. `['(min-width: 768px)']`).
+   *
+   * An empty array means no `@media` wrapper is emitted.
+   */
+  mediaQueries: string[]
+  /**
+   * CSS custom property bindings for dynamic (runtime-changeable) values.
+   *
+   * When present, the generated CSS references `var(--twc-dN)` and these
+   * bindings must be applied as inline `style` on the element (via `dcx`).
+   * Keys are CSS custom property names (e.g. `'--twc-d0'`), values are
+   * the current runtime values (e.g. `'#ff0000'`).
+   */
+  dynamicBindings?: Record<string, string>
+  /**
+   * `@supports` query strings that wrap the generated rule
+   * (e.g. `['(display: grid)']`).
+   *
+   * An empty array means no `@supports` wrapper is emitted.
+   */
+  supportsQueries: string[]
+  /**
+   * Optional selector template that wraps the generated class name in a
+   * more complex selector pattern. The `&` character is replaced with the
+   * generated `.className` at render time.
+   *
+   * Used for utilities like `spaceX`/`spaceY` (child combinator selectors),
+   * `group-*` / `peer-*` modifiers, and `rtl`/`ltr` direction modifiers.
+   *
+   * @example
+   * ```ts
+   * // spaceX uses: '& > :not([hidden]) ~ :not([hidden])'
+   * // group-hover uses: '.group:hover &'
+   * ```
+   */
+  selectorTemplate?: string
+}
+
+/**
+ * A function that accepts a design-token value and returns a {@link StyleRule}.
+ *
+ * Every spacing, color, typography, and layout helper (`p`, `bg`, `text`, ...)
+ * satisfies this signature. The `value` parameter is intentionally `any` so
+ * that individual utilities can narrow it to their own accepted types
+ * (e.g. `number | string | DynamicValue`).
+ *
+ * @param value - The design-token or raw CSS value to apply.
+ * @returns A {@link StyleRule} containing the appropriate CSS declarations.
+ *
+ * @example
+ * ```ts
+ * import type { Utility } from 'typewritingclass'
+ * import { p } from 'typewritingclass'
+ *
+ * // `p` satisfies the Utility signature:
+ * const myUtility: Utility = p
+ * const rule = myUtility(4)
+ * // CSS: padding: 1rem;
+ * ```
+ */
+export type Utility = (value: any) => StyleRule
+
+/**
+ * A function that transforms a {@link StyleRule} by wrapping it with a
+ * pseudo-class selector or a media query.
+ *
+ * Modifiers are composable -- you can chain them via {@link when} to build
+ * multi-condition rules (e.g. "on hover, at medium breakpoint").
+ *
+ * @param rule - The source {@link StyleRule} to transform.
+ * @returns A new {@link StyleRule} with additional selectors or media queries.
+ *
+ * @example
+ * ```ts
+ * import type { Modifier } from 'typewritingclass'
+ * import { hover, md } from 'typewritingclass'
+ *
+ * // `hover` and `md` are both Modifiers:
+ * const hoverMod: Modifier = hover
+ * const mdMod: Modifier = md
+ * ```
+ */
+export type Modifier = (rule: StyleRule) => StyleRule
+
+/**
+ * The return value of {@link dcx}, containing both a class string and an
+ * inline `style` object for dynamic CSS custom-property bindings.
+ *
+ * Use this when your styles include runtime-changeable values created with
+ * {@link dynamic}. The `className` goes on the element's class attribute, and
+ * `style` must be spread onto the element's inline style so the CSS custom
+ * properties are set.
+ *
+ * @example
+ * ```ts
+ * import { dcx, bg, dynamic } from 'typewritingclass'
+ *
+ * const color = dynamic('#ff0000')
+ * const result = dcx(bg(color))
+ * // result.className => "_a1b2c"
+ * // result.style     => { '--twc-d0': '#ff0000' }
+ *
+ * // In JSX:
+ * // <div className={result.className} style={result.style} />
+ * // CSS: .\_a1b2c { background-color: var(--twc-d0); }
+ * ```
+ */
+export interface DynamicResult {
+  /** A space-separated string of generated CSS class names, ready for `className` or `class`. */
+  className: string
+  /**
+   * An object of CSS custom property assignments to apply as inline styles.
+   *
+   * Keys are custom property names (e.g. `'--twc-d0'`), values are the
+   * current runtime values (e.g. `'#ff0000'`, `'1.5rem'`).
+   */
+  style: Record<string, string>
+}

package/src/utilities/accessibility.ts

@@ -0,0 +1,33 @@
+import type { StyleRule } from '../types.ts'
+import { createRule } from '../rule.ts'
+
+export function srOnly(): StyleRule {
+  return createRule({
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: '0',
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    'white-space': 'nowrap',
+    'border-width': '0',
+  })
+}
+
+export function notSrOnly(): StyleRule {
+  return createRule({
+    position: 'static',
+    width: 'auto',
+    height: 'auto',
+    padding: '0',
+    margin: '0',
+    overflow: 'visible',
+    clip: 'auto',
+    'white-space': 'normal',
+  })
+}
+
+export function forcedColorAdjust(value: string): StyleRule {
+  return createRule({ 'forced-color-adjust': value })
+}

package/src/utilities/backgrounds.ts

@@ -0,0 +1,86 @@
+import type { StyleRule } from '../types.ts'
+import type { DynamicValue } from '../dynamic.ts'
+import { createRule, createDynamicRule } from '../rule.ts'
+import { isDynamic } from '../dynamic.ts'
+
+export function bgAttachment(value: string): StyleRule {
+  return createRule({ 'background-attachment': value })
+}
+
+export function bgClip(value: string): StyleRule {
+  return createRule({ 'background-clip': value })
+}
+
+export function bgOrigin(value: string): StyleRule {
+  return createRule({ 'background-origin': value })
+}
+
+export function bgPosition(value: string | DynamicValue): StyleRule {
+  if (isDynamic(value)) {
+    return createDynamicRule(
+      { 'background-position': `var(${value.__id})` },
+      { [value.__id]: String(value.__value) },
+    )
+  }
+  return createRule({ 'background-position': value })
+}
+
+export function bgRepeat(value: string): StyleRule {
+  return createRule({ 'background-repeat': value })
+}
+
+export function bgSize(value: string | DynamicValue): StyleRule {
+  if (isDynamic(value)) {
+    return createDynamicRule(
+      { 'background-size': `var(${value.__id})` },
+      { [value.__id]: String(value.__value) },
+    )
+  }
+  return createRule({ 'background-size': value })
+}
+
+export function bgImage(value: string | DynamicValue): StyleRule {
+  if (isDynamic(value)) {
+    return createDynamicRule(
+      { 'background-image': `var(${value.__id})` },
+      { [value.__id]: String(value.__value) },
+    )
+  }
+  return createRule({ 'background-image': value })
+}
+
+export function bgGradient(direction: string = 'to right'): StyleRule {
+  return createRule({
+    'background-image': `linear-gradient(${direction}, var(--twc-gradient-from, transparent), var(--twc-gradient-via, transparent), var(--twc-gradient-to, transparent))`,
+  })
+}
+
+export function gradientFrom(color: string | DynamicValue): StyleRule {
+  if (isDynamic(color)) {
+    return createDynamicRule(
+      { '--twc-gradient-from': `var(${color.__id})` },
+      { [color.__id]: String(color.__value) },
+    )
+  }
+  return createRule({ '--twc-gradient-from': color })
+}
+
+export function gradientVia(color: string | DynamicValue): StyleRule {
+  if (isDynamic(color)) {
+    return createDynamicRule(
+      { '--twc-gradient-via': `var(${color.__id})` },
+      { [color.__id]: String(color.__value) },
+    )
+  }
+  return createRule({ '--twc-gradient-via': color })
+}
+
+export function gradientTo(color: string | DynamicValue): StyleRule {
+  if (isDynamic(color)) {
+    return createDynamicRule(
+      { '--twc-gradient-to': `var(${color.__id})` },
+      { [color.__id]: String(color.__value) },
+    )
+  }
+  return createRule({ '--twc-gradient-to': color })
+}