@pyreon/styler 0.11.0 → 0.11.2

package/src/forward.ts

@@ -0,0 +1,276 @@
+/**
+ * HTML prop filtering. Prevents unknown props from being forwarded to DOM
+ * elements (which causes warnings). Props starting with `$` are
+ * transient (styling-only) and are always filtered out.
+ */
+
+// Common HTML attributes, event handlers, and ARIA/data attributes
+const HTML_PROPS = new Set([
+  // Core props
+  "className",
+  "class",
+  "dangerouslySetInnerHTML",
+  "htmlFor",
+  "id",
+  "key",
+  "ref",
+  "style",
+  "tabIndex",
+  "role",
+  // Event handlers
+  "onAbort",
+  "onAnimationEnd",
+  "onAnimationIteration",
+  "onAnimationStart",
+  "onBlur",
+  "onChange",
+  "onClick",
+  "onCompositionEnd",
+  "onCompositionStart",
+  "onCompositionUpdate",
+  "onContextMenu",
+  "onCopy",
+  "onCut",
+  "onDoubleClick",
+  "onDrag",
+  "onDragEnd",
+  "onDragEnter",
+  "onDragLeave",
+  "onDragOver",
+  "onDragStart",
+  "onDrop",
+  "onError",
+  "onFocus",
+  "onInput",
+  "onKeyDown",
+  "onKeyPress",
+  "onKeyUp",
+  "onLoad",
+  "onMouseDown",
+  "onMouseEnter",
+  "onMouseLeave",
+  "onMouseMove",
+  "onMouseOut",
+  "onMouseOver",
+  "onMouseUp",
+  "onPaste",
+  "onPointerCancel",
+  "onPointerDown",
+  "onPointerEnter",
+  "onPointerLeave",
+  "onPointerMove",
+  "onPointerOut",
+  "onPointerOver",
+  "onPointerUp",
+  "onScroll",
+  "onSelect",
+  "onSubmit",
+  "onTouchCancel",
+  "onTouchEnd",
+  "onTouchMove",
+  "onTouchStart",
+  "onTransitionEnd",
+  "onWheel",
+  // HTML attributes
+  "accept",
+  "acceptCharset",
+  "accessKey",
+  "action",
+  "allow",
+  "allowFullScreen",
+  "alt",
+  "as",
+  "async",
+  "autoCapitalize",
+  "autoComplete",
+  "autoCorrect",
+  "autoFocus",
+  "autoPlay",
+  "capture",
+  "cellPadding",
+  "cellSpacing",
+  "charSet",
+  "checked",
+  "cite",
+  "cols",
+  "colSpan",
+  "content",
+  "contentEditable",
+  "controls",
+  "controlsList",
+  "coords",
+  "crossOrigin",
+  "dateTime",
+  "decoding",
+  "default",
+  "defaultChecked",
+  "defaultValue",
+  "defer",
+  "dir",
+  "disabled",
+  "disablePictureInPicture",
+  "disableRemotePlayback",
+  "download",
+  "draggable",
+  "encType",
+  "enterKeyHint",
+  "fetchPriority",
+  "form",
+  "formAction",
+  "formEncType",
+  "formMethod",
+  "formNoValidate",
+  "formTarget",
+  "frameBorder",
+  "headers",
+  "height",
+  "hidden",
+  "high",
+  "href",
+  "hrefLang",
+  "httpEquiv",
+  "inputMode",
+  "integrity",
+  "is",
+  "label",
+  "lang",
+  "list",
+  "loading",
+  "loop",
+  "low",
+  "max",
+  "maxLength",
+  "media",
+  "method",
+  "min",
+  "minLength",
+  "multiple",
+  "muted",
+  "name",
+  "noModule",
+  "noValidate",
+  "nonce",
+  "open",
+  "optimum",
+  "pattern",
+  "placeholder",
+  "playsInline",
+  "poster",
+  "preload",
+  "readOnly",
+  "referrerPolicy",
+  "rel",
+  "required",
+  "reversed",
+  "rows",
+  "rowSpan",
+  "sandbox",
+  "scope",
+  "scoped",
+  "scrolling",
+  "selected",
+  "shape",
+  "size",
+  "sizes",
+  "slot",
+  "span",
+  "spellCheck",
+  "src",
+  "srcDoc",
+  "srcLang",
+  "srcSet",
+  "start",
+  "step",
+  "summary",
+  "target",
+  "title",
+  "translate",
+  "type",
+  "useMap",
+  "value",
+  "width",
+  "wrap",
+])
+
+/**
+ * Filters props for HTML elements. Keeps valid HTML attrs, data-*, aria-*.
+ * Rejects unknown props and $-prefixed transient props.
+ */
+export const filterProps = (props: Record<string, unknown>): Record<string, unknown> => {
+  const filtered: Record<string, unknown> = {}
+
+  for (const key in props) {
+    // Skip transient props ($-prefixed) — used for styling-only props
+    if (key.charCodeAt(0) === 36) continue // '$'
+
+    // Skip `as` prop — handled separately by styled
+    if (key === "as") continue
+
+    // Keep data-* and aria-* attributes
+    if (key.startsWith("data-") || key.startsWith("aria-")) {
+      filtered[key] = props[key]
+      continue
+    }
+
+    // Keep known HTML props
+    if (HTML_PROPS.has(key)) {
+      filtered[key] = props[key]
+    }
+  }
+
+  return filtered
+}
+
+/**
+ * Build final props for a styled component in a single pass.
+ * Combines className merging, ref injection, and prop filtering into one
+ * allocation and one iteration.
+ */
+export const buildProps = (
+  rawProps: Record<string, any>,
+  generatedCls: string,
+  isDOM: boolean,
+  customFilter?: (prop: string) => boolean,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: complex logic is inherent to this function
+): Record<string, any> => {
+  const result: Record<string, any> = {}
+
+  // Merge generated + user className
+  const userCls = rawProps.class || rawProps.className
+  if (generatedCls) {
+    result.class = userCls ? `${generatedCls} ${userCls}` : generatedCls
+  } else if (userCls) {
+    result.class = userCls
+  }
+
+  // Component target — forward all props except as/className/class and $-prefixed
+  if (!isDOM) {
+    for (const key in rawProps) {
+      if (key === "as" || key === "className" || key === "class") continue
+      if (key.charCodeAt(0) === 36) continue // $-prefixed transient
+      result[key] = rawProps[key]
+    }
+    return result
+  }
+
+  // DOM element with custom shouldForwardProp
+  if (customFilter) {
+    for (const key in rawProps) {
+      if (key === "as" || key === "className" || key === "class") continue
+      if (customFilter(key)) result[key] = rawProps[key]
+    }
+    return result
+  }
+
+  // DOM element with default filtering
+  for (const key in rawProps) {
+    if (key === "as" || key === "className" || key === "class") continue
+    if (key.charCodeAt(0) === 36) continue // $-prefixed transient
+    if (key.startsWith("data-") || key.startsWith("aria-")) {
+      result[key] = rawProps[key]
+      continue
+    }
+    if (HTML_PROPS.has(key)) result[key] = rawProps[key]
+  }
+  return result
+}

package/src/globalStyle.ts

@@ -0,0 +1,48 @@
+/**
+ * createGlobalStyle() — tagged template function that injects global CSS
+ * rules (not scoped to a class name). Returns a component function that
+ * injects styles when called and supports dynamic interpolations via
+ * props/theme.
+ *
+ * Usage:
+ *   const GlobalStyle = createGlobalStyle`
+ *     body { margin: 0; font-family: ${({ theme }) => theme.font}; }
+ *     *, *::before, *::after { box-sizing: border-box; }
+ *   `
+ */
+import type { ComponentFn } from "@pyreon/core"
+import { type Interpolation, normalizeCSS, resolve } from "./resolve"
+import { isDynamic } from "./shared"
+import { sheet } from "./sheet"
+import { useTheme } from "./ThemeProvider"
+
+export const createGlobalStyle = (
+  strings: TemplateStringsArray,
+  ...values: Interpolation[]
+): ComponentFn => {
+  const hasDynamicValues = values.some(isDynamic)
+
+  // STATIC FAST PATH: compute once at creation time
+  if (!hasDynamicValues) {
+    const cssText = normalizeCSS(resolve(strings, values, {}))
+
+    // Inject into sheet immediately
+    if (cssText.trim()) sheet.insertGlobal(cssText)
+
+    const StaticGlobal: ComponentFn = () => null
+    return StaticGlobal
+  }
+
+  // DYNAMIC PATH: resolve on every render with theme/props
+  const DynamicGlobal: ComponentFn = (props: Record<string, any>) => {
+    const theme = useTheme()
+    const allProps = { ...props, theme }
+    const cssText = normalizeCSS(resolve(strings, values, allProps))
+
+    if (cssText.trim()) sheet.insertGlobal(cssText)
+
+    return null
+  }
+
+  return DynamicGlobal
+}

package/src/hash.ts

@@ -0,0 +1,30 @@
+/**
+ * Fast FNV-1a non-cryptographic hash. Returns base-36 string for compact class names.
+ *
+ * 32-bit hash space → ~4.3 billion unique values. Collision probability is
+ * negligible for typical applications (< 10,000 unique CSS rules).
+ */
+
+/** FNV-1a offset basis — starting state for streaming hash. */
+export const HASH_INIT = 2166136261
+
+const FNV_PRIME = 16777619
+
+/**
+ * Feed a string segment into the running hash state.
+ * Streaming: hashUpdate(hashUpdate(HASH_INIT, 'ab'), 'cd') === hash('abcd').
+ */
+export const hashUpdate = (init: number, str: string): number => {
+  let h = init
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, FNV_PRIME)
+  }
+  return h
+}
+
+/** Finalize a hash state into a base-36 class name suffix. */
+export const hashFinalize = (h: number): string => (h >>> 0).toString(36)
+
+/** Hash a complete string in one shot. Returns base-36 string. */
+export const hash = (str: string): string => hashFinalize(hashUpdate(HASH_INIT, str))

package/src/index.ts

@@ -0,0 +1,15 @@
+export { css } from "./css"
+export { buildProps, filterProps } from "./forward"
+export { createGlobalStyle } from "./globalStyle"
+export { HASH_INIT, hash, hashFinalize, hashUpdate } from "./hash"
+export { keyframes } from "./keyframes"
+export type { CSSResult, Interpolation } from "./resolve"
+export { clearNormCache, normalizeCSS, resolve, resolveValue } from "./resolve"
+export { isDynamic } from "./shared"
+export type { StyleSheetOptions } from "./sheet"
+export { createSheet, StyleSheet, sheet } from "./sheet"
+export type { StyledFunction, StyledOptions } from "./styled"
+export { styled } from "./styled"
+export type { DefaultTheme } from "./ThemeProvider"
+export { ThemeContext, ThemeProvider, useTheme } from "./ThemeProvider"
+export { useCSS } from "./useCSS"

package/src/keyframes.ts

@@ -0,0 +1,36 @@
+/**
+ * keyframes() tagged template function. Creates a CSS @keyframes rule,
+ * injects it into the stylesheet, and returns the generated animation name.
+ *
+ * Usage:
+ *   const fadeIn = keyframes`
+ *     from { opacity: 0; }
+ *     to { opacity: 1; }
+ *   `
+ *   // fadeIn === "pyr-kf-abc123" (deterministic, hash-based)
+ */
+import { hash } from "./hash"
+import { type Interpolation, normalizeCSS, resolve } from "./resolve"
+import { sheet } from "./sheet"
+
+class KeyframesResult {
+  readonly name: string
+
+  constructor(strings: TemplateStringsArray, values: Interpolation[]) {
+    const body = normalizeCSS(resolve(strings, values, {}))
+    const h = hash(body)
+    this.name = `pyr-kf-${h}`
+
+    sheet.insertKeyframes(this.name, body)
+  }
+
+  /** Returns the animation name when used in string context. */
+  toString(): string {
+    return this.name
+  }
+}
+
+export const keyframes = (
+  strings: TemplateStringsArray,
+  ...values: Interpolation[]
+): KeyframesResult => new KeyframesResult(strings, values)

package/src/resolve.ts

@@ -0,0 +1,172 @@
+/**
+ * Interpolation resolver: converts tagged template strings + values into a
+ * final CSS string. Handles nested CSSResults, arrays, functions, and
+ * primitive values.
+ */
+
+import type { DefaultTheme } from "./ThemeProvider"
+
+export type Interpolation =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | CSSResult
+  | Interpolation[]
+  | ((props: { theme?: DefaultTheme & Record<string, any>; [key: string]: any }) => Interpolation)
+
+/**
+ * Lazy representation of a `css` tagged template. Stores the raw template
+ * strings and interpolation values without resolving them. Resolution is
+ * deferred until a styled component renders (or until explicitly resolved).
+ */
+export class CSSResult {
+  constructor(
+    readonly strings: TemplateStringsArray,
+    readonly values: Interpolation[],
+  ) {}
+
+  /** Resolve with empty props — useful for static templates, testing, and debugging. */
+  toString(): string {
+    return resolve(this.strings, this.values, {})
+  }
+}
+
+/** Resolve a tagged template's strings + values into a final CSS string. */
+export const resolve = (
+  strings: TemplateStringsArray,
+  values: Interpolation[],
+  props: Record<string, any>,
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: complex logic is inherent to this function
+): string => {
+  // Tagged templates guarantee strings.length === values.length + 1,
+  // so strings[0] and strings[i+1] are always defined — no ?? needed.
+  let result = strings[0] as string
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i]
+    const s = strings[i + 1] as string
+    // Inline the most common value types to avoid function call overhead.
+    if (typeof v === "function") {
+      const r = v(props)
+      result +=
+        (typeof r === "string"
+          ? r
+          : r == null || r === false || r === true
+            ? ""
+            : resolveValue(r as Interpolation, props)) + s
+    } else if (v == null || v === false || v === true) {
+      result += s
+    } else if (typeof v === "string") {
+      result += v + s
+    } else if (typeof v === "number") {
+      result += v + s
+    } else {
+      result += resolveValue(v, props) + s
+    }
+  }
+  return result
+}
+
+/**
+ * Normalize resolved CSS text for strict `insertRule` compatibility.
+ *
+ * Single-pass scanner that handles all cleanup in one traversal:
+ * - Strips block comments and line comments (preserves :// in URLs)
+ * - Collapses whitespace to single spaces
+ * - Removes redundant semicolons
+ * - Trims leading/trailing whitespace
+ */
+const normCache = new Map<string, string>()
+/** Clear the normalizeCSS cache (called during HMR cleanup). */
+export const clearNormCache = () => normCache.clear()
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: complex logic is inherent to this function
+export const normalizeCSS = (css: string): string => {
+  const cached = normCache.get(css)
+  if (cached !== undefined) return cached
+
+  const len = css.length
+  let out = ""
+  let space = false // pending space to emit before next non-whitespace char
+  let last = 0 // charCode of last char written to output (0 = nothing yet)
+
+  for (let i = 0; i < len; i++) {
+    const c = css.charCodeAt(i)
+
+    // /* block comment */
+    if (c === 47 /* / */ && css.charCodeAt(i + 1) === 42 /* * */) {
+      const end = css.indexOf("*/", i + 2)
+      i = end === -1 ? len : end + 1
+      space = true
+      continue
+    }
+
+    // // line comment (but not :// in URLs)
+    if (c === 47 /* / */ && css.charCodeAt(i + 1) === 47 /* / */ && last !== 58 /* : */) {
+      const nl = css.indexOf("\n", i + 2)
+      i = nl === -1 ? len : nl
+      space = true
+      continue
+    }
+
+    // Whitespace → collapse
+    if (c === 32 || c === 9 || c === 10 || c === 13 || c === 12) {
+      space = true
+      continue
+    }
+
+    // Semicolon → skip if redundant (after start, {, }, or another ;)
+    if (c === 59 /* ; */) {
+      if (last === 0 || last === 123 /* { */ || last === 125 /* } */ || last === 59 /* ; */) {
+        continue
+      }
+      space = false
+      out += ";"
+      last = 59
+      continue
+    }
+
+    // Regular char — emit pending space (but not at start of output)
+    if (space && last !== 0) out += " "
+    space = false
+
+    out += css[i]
+    last = c
+  }
+
+  // Evict oldest ~10% to prevent memory leaks without cliff-edge drop
+  if (normCache.size > 2000) {
+    let count = 0
+    for (const key of normCache.keys()) {
+      if (count >= 200) break
+      normCache.delete(key)
+      count++
+    }
+  }
+  normCache.set(css, out)
+
+  return out
+}
+
+export const resolveValue = (value: Interpolation, props: Record<string, any>): string => {
+  // null, undefined, false, true → empty (enables conditional: ${cond && css`...`})
+  if (value == null || value === false || value === true) return ""
+
+  // function interpolation → call with props/theme context, resolve result
+  if (typeof value === "function") return resolveValue(value(props) as Interpolation, props)
+
+  // nested CSSResult → recursively resolve
+  if (value instanceof CSSResult) return resolve(value.strings, value.values, props)
+
+  // array of results (e.g. from makeItResponsive's breakpoints.map())
+  if (Array.isArray(value)) {
+    let arrayResult = ""
+    for (let i = 0; i < value.length; i++) {
+      arrayResult += resolveValue(value[i], props)
+    }
+    return arrayResult
+  }
+
+  return String(value)
+}

package/src/shared.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared utilities used across multiple modules.
+ */
+import { CSSResult, type Interpolation } from "./resolve"
+
+/** Check if an interpolation value is dynamic (contains functions or nested dynamic CSSResults). */
+export const isDynamic = (v: Interpolation): boolean => {
+  if (typeof v === "function") return true
+  if (Array.isArray(v)) return v.some(isDynamic)
+  if (v instanceof CSSResult) return v.values.some(isDynamic)
+  return false
+}