@pyreon/unistyle 0.14.0 → 0.16.0

package/src/__tests__/optimizeBreakpointDeltas.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+import { optimizeBreakpointDeltas } from '../responsive'
+
+describe('optimizeBreakpointDeltas', () => {
+  describe('cascade pruning', () => {
+    it('returns input unchanged when there is one or fewer breakpoints', () => {
+      expect(optimizeBreakpointDeltas([])).toEqual([])
+      expect(optimizeBreakpointDeltas(['color: red;'])).toEqual(['color: red;'])
+    })
+
+    it('strips re-emitted unchanged declarations from later breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; padding: 0;',
+        'color: red; padding: 1rem;',
+      ])
+      expect(out[0]).toBe('color: red; padding: 0;')
+      // `color: red` was already in the cascade — only padding survives
+      expect(out[1]).toBe('padding: 1rem;')
+    })
+
+    it('keeps changed declarations across multiple breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; font-size: 12px;',
+        'color: blue; font-size: 12px;',
+        'color: blue; font-size: 16px;',
+      ])
+      expect(out[0]).toBe('color: red; font-size: 12px;')
+      expect(out[1]).toBe('color: blue;')
+      expect(out[2]).toBe('font-size: 16px;')
+    })
+
+    it('emits empty string when a later breakpoint adds no deltas', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; padding: 0;',
+        'color: red; padding: 0;',
+      ])
+      expect(out[0]).toBe('color: red; padding: 0;')
+      expect(out[1]).toBe('')
+    })
+
+    it('passes through empty / null breakpoints unchanged', () => {
+      const out = optimizeBreakpointDeltas(['color: red;', '', 'color: blue;'])
+      expect(out[0]).toBe('color: red;')
+      expect(out[1]).toBe('')
+      expect(out[2]).toBe('color: blue;')
+    })
+  })
+
+  describe('parser edge cases', () => {
+    it('skips colons inside parens (linear-gradient args)', () => {
+      const out = optimizeBreakpointDeltas([
+        'background: linear-gradient(red 0%, blue 100%);',
+        'background: linear-gradient(red 0%, blue 100%);',
+      ])
+      expect(out[0]).toBe('background: linear-gradient(red 0%, blue 100%);')
+      // Same value cascades — delta is empty
+      expect(out[1]).toBe('')
+    })
+
+    it('skips semicolons inside quoted strings (content: ";")', () => {
+      const out = optimizeBreakpointDeltas([
+        `content: ";"; color: red;`,
+        `content: ";"; color: blue;`,
+      ])
+      // Both declarations parsed correctly on bp1; bp2 only color delta
+      expect(out[0]).toContain(`content: ";";`)
+      expect(out[0]).toContain('color: red;')
+      expect(out[1]).toBe('color: blue;')
+    })
+
+    it('treats nested selector blocks as opaque, deduped by exact text', () => {
+      const out = optimizeBreakpointDeltas([
+        '&:hover { color: red; } padding: 0;',
+        '&:hover { color: red; } padding: 1rem;',
+      ])
+      // The hover block dedupes; padding delta survives
+      expect(out[1]).not.toContain('&:hover')
+      expect(out[1]).toContain('padding: 1rem;')
+    })
+
+    it('keeps differently-shaped nested blocks across breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        '&:hover { color: red; }',
+        '&:hover { color: blue; }',
+      ])
+      expect(out[0]).toContain('&:hover { color: red; }')
+      // Different inner text → not deduped
+      expect(out[1]).toContain('&:hover { color: blue; }')
+    })
+
+    it('handles trailing declarations with no terminating semicolon', () => {
+      const out = optimizeBreakpointDeltas(['color: red', 'color: blue'])
+      expect(out[0]).toBe('color: red;')
+      expect(out[1]).toBe('color: blue;')
+    })
+
+    it('preserves @supports / @media-style nested blocks as opaque blocks', () => {
+      const out = optimizeBreakpointDeltas([
+        '@supports (display: grid) { display: grid; }',
+        '@supports (display: grid) { display: grid; } color: red;',
+      ])
+      expect(out[0]).toBe('@supports (display: grid) { display: grid; }')
+      // @supports block dedupes; color is new
+      expect(out[1]).toBe('color: red;')
+    })
+
+    it('keeps shorthand and longhand decls separately (no shorthand modeling)', () => {
+      const out = optimizeBreakpointDeltas([
+        'padding: 1rem;',
+        'padding-top: 0;',
+      ])
+      // Different `prop` keys → both retained
+      expect(out[0]).toBe('padding: 1rem;')
+      expect(out[1]).toBe('padding-top: 0;')
+    })
+
+    it('keeps malformed declaration-shaped fragments without losing them', () => {
+      const out = optimizeBreakpointDeltas([':abc;', ':abc;'])
+      // No prop name (starts with `:`) → kept as opaque block; deduped on bp2
+      expect(out[0]).toBe(':abc;')
+      expect(out[1]).toBe('')
+    })
+  })
+})

package/src/__tests__/special-keys.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import styles from '../styles/styles/index'
+
+const mockCss = (strings: TemplateStringsArray, ...vals: any[]) => {
+  let r = ''
+  for (let i = 0; i < strings.length; i++) {
+    r += strings[i]
+    if (i < vals.length) r += String(vals[i])
+  }
+  return r
+}
+
+// Regression: kind: 'special' descriptors (`fullScreen`, `hideEmpty`,
+// `clearFix`, `extendCss`, `backgroundImage`, `animation`) only carry an
+// `id` field — no `key` / `keys`. The keyToIndices builder used to walk
+// only `d.key` / `d.keys`, so special descriptors were never indexed.
+//
+// In single-special-property themes the bug was masked by the fallback
+// path (`if (fragments.length === 0 && Object.keys(t).length > 0)` triggers
+// a full-scan that hits processSpecial). The moment ANY non-special key is
+// also present in the theme — the real-world shape, e.g. `<Overlay>` with
+// `{ fullScreen: true, background: 'rgba(0,0,0,0.5)' }` — the fast path
+// processes `background`, fragments.length === 1, fallback skipped, the
+// special is silently dropped.
+//
+// Fix: index `d.id` alongside `d.key` / `d.keys` so the fast path resolves
+// special descriptors directly.
+describe('kind: special descriptors paired with non-special properties', () => {
+  it('fullScreen + background → both render', () => {
+    const result = styles({
+      theme: { fullScreen: true, background: 'rgba(0,0,0,0.5)' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('position: fixed;')
+    expect(output).toContain('top: 0;')
+    expect(output).toContain('background: rgba(0,0,0,0.5);')
+  })
+
+  it('hideEmpty + color → both render', () => {
+    const result = styles({
+      theme: { hideEmpty: true, color: 'red' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain('&:empty { display: none; }')
+    expect(normalized).toContain('color: red;')
+  })
+
+  it('clearFix + padding → both render', () => {
+    const result = styles({
+      theme: { clearFix: true, padding: 8 },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain("&::after { clear: both; content: ''; display: table; }")
+    expect(normalized).toContain('padding:')
+    expect(normalized).toContain('0.5rem')
+  })
+
+  it('extendCss + color → both render', () => {
+    const result = styles({
+      theme: { extendCss: 'border: 1px solid red;', color: 'blue' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('border: 1px solid red;')
+    expect(output).toContain('color: blue;')
+  })
+
+  it('backgroundImage + color → both render', () => {
+    const result = styles({
+      theme: { backgroundImage: 'https://example.com/img.png', color: 'green' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('background-image: url(https://example.com/img.png);')
+    expect(output).toContain('color: green;')
+  })
+
+  it('animation + color → both render', () => {
+    const result = styles({
+      theme: { animation: 'fadeIn 1s ease-in', color: 'purple' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('animation:')
+    expect(output).toContain('fadeIn 1s ease-in')
+    expect(output).toContain('color: purple;')
+  })
+
+  it('multiple specials + non-specials → all render', () => {
+    const result = styles({
+      theme: {
+        fullScreen: true,
+        hideEmpty: true,
+        clearFix: true,
+        extendCss: 'outline: 2px dashed orange;',
+        color: 'red',
+        padding: 16,
+      },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain('position: fixed;')
+    expect(normalized).toContain('&:empty { display: none; }')
+    expect(normalized).toContain("&::after { clear: both; content: ''; display: table; }")
+    expect(normalized).toContain('outline: 2px dashed orange;')
+    expect(normalized).toContain('color: red;')
+    expect(normalized).toContain('padding:')
+    expect(normalized).toContain('1rem')
+  })
+})

package/src/__tests__/styles.test.ts

@@ -212,3 +212,62 @@ describe('Tier 1: performance characteristics', () => {
     // the indexed path should always find matches.
   })
 })
+
+  // Regression test for PR #283's `_fragments` reuse — the module-level array
+  // was captured by reference inside the returned CSSResult's values, so the
+  // next styles() call would clear the previous result's data before its
+  // consumer ever resolved it.
+  //
+  // Pre-fix: r1.values[0] (the fragments array) was the SAME reference as the
+  // module-level array; the second styles() call ran `_fragments.length = 0`
+  // and wiped r1's fragments to []. Post-fix: each call gets its own array.
+  //
+  // Real-app symptom this caused: rocketstyle dimension themes (state="primary"
+  // → blue background) produced empty CSS because element.ts calls
+  // makeItResponsive 5 times (base/hover/focus/active/disabled), each calling
+  // styles() under the hood. Only the LAST one kept its data; the rest
+  // resolved empty. See `packages/ui/components/src/bases/element.ts`.
+  describe('regression: CSSResult ownership of fragments array (PR #283 follow-up)', () => {
+    // Lazy-capturing mock: stores strings + values without resolving, mimicking
+    // the real CSSResult contract where consumers resolve later.
+    const lazyCss = (strings: TemplateStringsArray, ...values: unknown[]) => ({
+      strings,
+      values,
+    })
+
+    it('first result retains its fragments after a second styles() call', () => {
+      const r1 = styles({
+        theme: { color: 'red', fontSize: 14 },
+        css: lazyCss as never,
+        rootSize: 16,
+      })
+      const r1Fragments = (r1 as { values: unknown[] }).values[0]
+      const r1LenBefore = Array.isArray(r1Fragments) ? r1Fragments.length : -1
+      expect(r1LenBefore).toBeGreaterThan(0)
+
+      // Second call — pre-fix this cleared r1's array via shared module-level
+      // reference. Post-fix: each call owns its array.
+      styles({
+        theme: { backgroundColor: 'blue', padding: 8 },
+        css: lazyCss as never,
+        rootSize: 16,
+      })
+
+      const r1FragmentsAfter = (r1 as { values: unknown[] }).values[0]
+      const r1LenAfter = Array.isArray(r1FragmentsAfter) ? r1FragmentsAfter.length : -1
+      expect(r1LenAfter).toBe(r1LenBefore)
+    })
+
+    it('two results from sequential calls have INDEPENDENT fragments arrays', () => {
+      const r1 = styles({ theme: { color: 'red' }, css: lazyCss as never, rootSize: 16 })
+      const r2 = styles({ theme: { backgroundColor: 'blue' }, css: lazyCss as never, rootSize: 16 })
+
+      const r1Fragments = (r1 as { values: unknown[] }).values[0]
+      const r2Fragments = (r2 as { values: unknown[] }).values[0]
+      // Different array identities — r1 is not r2.
+      expect(r1Fragments).not.toBe(r2Fragments)
+      // Both populated.
+      expect(Array.isArray(r1Fragments) && r1Fragments.length).toBeGreaterThan(0)
+      expect(Array.isArray(r2Fragments) && r2Fragments.length).toBeGreaterThan(0)
+    })
+  })

package/src/context.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { provide } from '@pyreon/core'
+import { nativeCompat, provide } from '@pyreon/core'
 import { ThemeContext } from '@pyreon/styler'
 import { Provider as CoreProvider, context } from '@pyreon/ui-core'
 import type { PyreonTheme } from './enrichTheme'
@@ -35,6 +35,10 @@ function Provider(props: TProvider): VNode | null {
   return CoreProvider({ theme: enrichedTheme, children }) as VNode | null
 }
 
+// Mark as native — invoked by PyreonUI internally; needs Pyreon's setup
+// frame for provide(ThemeContext, ...) to reach descendants.
+nativeCompat(Provider)
+
 export { context }
 
 export default Provider

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal process type — just enough for `process.env.NODE_ENV` checks.
+ * Avoids requiring @types/node in consumers that import pyreon source
+ * via the `"bun"` export condition.
+ */
+declare var process: { env: { NODE_ENV?: string } }

package/src/responsive/index.ts

@@ -6,6 +6,7 @@ export type { MakeItResponsive, MakeItResponsiveStyles } from './makeItResponsiv
 export { default as makeItResponsive } from './makeItResponsive'
 export type { NormalizeTheme } from './normalizeTheme'
 export { default as normalizeTheme } from './normalizeTheme'
+export { default as optimizeBreakpointDeltas } from './optimizeBreakpointDeltas'
 export type { OptimizeTheme } from './optimizeTheme'
 export { default as optimizeTheme } from './optimizeTheme'
 export type { SortBreakpoints } from './sortBreakpoints'

package/src/responsive/makeItResponsive.ts

@@ -1,12 +1,40 @@
 import { isEmpty } from '@pyreon/ui-core'
 import type createMediaQueries from './createMediaQueries'
 import normalizeTheme from './normalizeTheme'
+import optimizeBreakpointDeltas from './optimizeBreakpointDeltas'
 import optimizeTheme from './optimizeTheme'
 import type sortBreakpoints from './sortBreakpoints'
 import transformTheme from './transformTheme'
 
 type Css = (strings: TemplateStringsArray, ...values: any[]) => any
 
+/**
+ * Coerce a styles-callback result to a CSS string for delta optimization.
+ * Returns null when the engine's result type can't be stringified cleanly
+ * (e.g. styled-components / Emotion objects whose default toString() yields
+ * "[object Object]") — caller falls back to the unoptimized path.
+ *
+ * Styler's CSSResult provides toString() that resolves with empty props,
+ * so any function interpolation that needs render-time props must come from
+ * the styles-callback closure (theme is destructured at call time, not
+ * resolved later). Verified across the project's styles callbacks.
+ */
+const stringifyResult = (result: unknown): string | null => {
+  if (result == null) return ''
+  if (typeof result === 'string') return result
+  // CSSResult duck-type fast path: has `strings` (TemplateStringsArray) and
+  // `values`. We know its toString() resolves to clean CSS, so we can skip
+  // the "[object Foo]" validation for the common path.
+  if (typeof result === 'object' && 'strings' in result && 'values' in result) {
+    return String(result)
+  }
+  // Foreign engine result — coerce and validate. Default
+  // Object.prototype.toString → "[object Foo]" → bail out so caller can fall
+  // back to the unoptimized path.
+  const text = String(result)
+  return text.includes('[object ') ? null : text
+}
+
 type CustomTheme = Record<string, unknown>
 
 type Theme = Partial<{
@@ -45,16 +73,45 @@ export type MakeItResponsive = ({
   normalize?: boolean
 }) => (props: { theme?: Theme; [prop: string]: any }) => any
 
-const themeCache = new WeakMap<
-  object,
-  { breakpoints: unknown; optimized: Record<string, Record<string, unknown>> }
->()
-
+/**
+ * Per-internal-theme cache:
+ *  - `optimized`: the per-breakpoint theme object (`{ xs: {...}, md: {...} }`)
+ *    after `normalize → transform → optimize`. Reused as long as the same
+ *    `sortedBreakpoints` reference is passed in.
+ *  - `rendered`: memoized FINAL output (array of media-wrapped CSSResults),
+ *    keyed by the outer `theme` reference. Hit when the same internal theme
+ *    AND the same outer theme render again — which is the common case when
+ *    the provider value is stable. Avoids re-running renderStyles +
+ *    optimizeBreakpointDeltas on every parent re-render.
+ */
+interface ThemeCacheEntry {
+  breakpoints: unknown
+  optimized: Record<string, Record<string, unknown>>
+  rendered?: WeakMap<object, unknown[]> | undefined
+}
+
+const themeCache = new WeakMap<object, ThemeCacheEntry>()
+
+/**
+ * Core responsive engine used by every styled component in the system.
+ *
+ * Returns a styled-components interpolation function that:
+ * 1. Reads the component's theme prop (via `key` or direct `theme`)
+ * 2. Without breakpoints → renders plain CSS
+ * 3. With breakpoints → normalizes, transforms (property-per-breakpoint →
+ *    breakpoint-per-property), optimizes (deduplicates identical breakpoints),
+ *    deltas the per-breakpoint output against the mobile-first cascade
+ *    (drops re-emitted unchanged declarations), and wraps each non-empty
+ *    breakpoint's deltas in the appropriate `@media` query. Falls back to
+ *    the unoptimized path if any breakpoint's render result can't be
+ *    cleanly stringified.
+ */
 const makeItResponsive: MakeItResponsive =
   ({ theme: customTheme, key = '', css, styles, normalize = true }) =>
   ({ theme = {}, ...props }) => {
     const internalTheme = customTheme || props[key]
 
+    // if no theme is defined, return empty object
     if (isEmpty(internalTheme)) return ''
 
     const { rootSize, breakpoints, __PYREON__, ...restTheme } = theme as Theme
@@ -62,6 +119,7 @@ const makeItResponsive: MakeItResponsive =
     const renderStyles = (styleTheme: Record<string, unknown>): ReturnType<typeof styles> =>
       styles({ theme: styleTheme, css, rootSize, globalTheme: restTheme })
 
+    // if there are no breakpoints, return just standard css
     if (isEmpty(breakpoints) || isEmpty(__PYREON__)) {
       return css`
         ${renderStyles(internalTheme)}
@@ -72,47 +130,94 @@ const makeItResponsive: MakeItResponsive =
     const { media, sortedBreakpoints } = __PYREON__ as NonNullable<typeof __PYREON__>
 
     let optimizedTheme: Record<string, Record<string, unknown>>
+    const entry = themeCache.get(internalTheme)
+    const breakpointsMatch = entry?.breakpoints === sortedBreakpoints
+
+    // Full-render cache: same internal theme + same outer theme → return
+    // the previous render's output verbatim. CSSResult instances are
+    // immutable so reusing them is safe.
+    if (entry && breakpointsMatch && entry.rendered) {
+      const memoized = entry.rendered.get(theme as object)
+      if (memoized) return memoized
+    }
 
-    const cached = themeCache.get(internalTheme)
-    if (cached && cached.breakpoints === sortedBreakpoints) {
-      optimizedTheme = cached.optimized
+    if (entry && breakpointsMatch) {
+      optimizedTheme = entry.optimized
     } else {
       let helperTheme = internalTheme
 
       if (normalize) {
         helperTheme = normalizeTheme({
           theme: internalTheme,
-          breakpoints: sortedBreakpoints,
+          breakpoints: sortedBreakpoints ?? [],
         })
       }
 
       const transformedTheme = transformTheme({
         theme: helperTheme,
-        breakpoints: sortedBreakpoints,
+        breakpoints: sortedBreakpoints ?? [],
       })
 
       optimizedTheme = optimizeTheme({
         theme: transformedTheme,
-        breakpoints: sortedBreakpoints,
+        breakpoints: sortedBreakpoints ?? [],
       })
 
       themeCache.set(internalTheme, {
         breakpoints: sortedBreakpoints,
         optimized: optimizedTheme,
+        // Preserve any pre-existing rendered cache when re-entering with a
+        // changed sortedBreakpoints reference — usually unreachable because
+        // breakpoints come from a stable provider value, but the explicit
+        // handling avoids a memory cliff in tests / HMR.
+        rendered: entry?.rendered,
       })
     }
 
-    return sortedBreakpoints.map((item: string) => {
-      const breakpointTheme = optimizedTheme[item]
+    const bps = sortedBreakpoints ?? []
 
+    // Resolve each per-breakpoint render to a string so the delta optimizer
+    // can diff at the property level. If any breakpoint's result can't be
+    // cleanly stringified (foreign engine result), fall back to the original
+    // unoptimized path that lets the engine resolve interpolations itself.
+    const renderedTexts: (string | null)[] = bps.map((item: string) => {
+      const breakpointTheme = optimizedTheme[item]
       if (!breakpointTheme || !media) return ''
+      return stringifyResult(renderStyles(breakpointTheme))
+    })
 
-      const result = renderStyles(breakpointTheme)
+    const canOptimize = renderedTexts.every((t) => t !== null)
+    let result: unknown[]
+    if (canOptimize) {
+      const deltas = optimizeBreakpointDeltas(renderedTexts as string[])
+      result = bps.map((item: string, i: number) => {
+        const cssText = deltas[i]
+        if (!cssText || !media) return ''
+        return (media as Record<string, any>)[item]`${cssText}`
+      })
+    } else {
+      result = bps.map((item: string) => {
+        const breakpointTheme = optimizedTheme[item]
+        if (!breakpointTheme || !media) return ''
+        const r = renderStyles(breakpointTheme)
+        return (media as Record<string, any>)[item]`
+          ${r};
+        `
+      })
+    }
 
-      return (media as Record<string, any>)[item]`
-        ${result};
-      `
-    })
+    // Memoize the final rendered output by outer theme reference. Stable
+    // theme + stable internal theme → future renders return immediately.
+    // Invariant: by this point themeCache always has an entry for
+    // internalTheme — earlier paths either hit the rendered-cache and
+    // returned, or wrote one via themeCache.set above.
+    const cacheEntry = themeCache.get(internalTheme)
+    if (cacheEntry) {
+      if (!cacheEntry.rendered) cacheEntry.rendered = new WeakMap()
+      cacheEntry.rendered.set(theme as object, result)
+    }
+
+    return result
   }
 
 export default makeItResponsive