@pyreon/unistyle 0.21.0 → 0.23.0

package/README.md

@@ -1,202 +1,198 @@
 # @pyreon/unistyle
 
-Responsive CSS engine for Pyreon.
+Responsive CSS engine — property-centric theme objects, automatic media queries, breakpoint dedup.
 
-Transforms property-centric theme objects into breakpoint-centric CSS with media queries. Automatic px-to-rem conversion, flex alignment helpers, and a data-driven style processor. Powers the responsive system behind `@pyreon/elements`, `@pyreon/coolgrid`, and `@pyreon/rocketstyle`.
+`@pyreon/unistyle` transforms theme objects (`{ padding: { xs: 8, md: 16 }, fontSize: 14 }`) into breakpoint-centric CSS with mobile-first media queries. Automatic px→rem conversion, 170+ CSS property mappings, three input shapes per property (scalar / mobile-first array / breakpoint object), and an optimizer that emits only the per-breakpoint DELTAS — so a property set at `xs` doesn't re-emit at every larger breakpoint. Powers the responsive system behind `@pyreon/elements`, `@pyreon/coolgrid`, and `@pyreon/rocketstyle`. Per-theme cached so re-renders against the same theme reference return the previous output verbatim.
 
-## Features
-
-- **Responsive pipeline** — write theme objects, get media queries automatically
-- **px-to-rem conversion** — configurable rootSize, zero-effort unit handling
-- **Breakpoint deduplication** — identical breakpoints are collapsed, no redundant CSS
-- **Three input formats** — scalar, mobile-first array, or breakpoint object per property
-- **Data-driven styles** — 100+ CSS properties processed from a theme object
-- **Alignment helpers** — flex alignment constants for X and Y axes
-
-## Installation
+## Install
 
 ```bash
-bun add @pyreon/unistyle
+bun add @pyreon/unistyle @pyreon/core @pyreon/reactivity @pyreon/ui-core
 ```
 
-## Quick Start
+## Quick start
 
-```ts
-import { Provider } from '@pyreon/unistyle'
-
-const theme = {
-  rootSize: 16,
-  breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
-}
-
-Provider({
-  theme,
-  children: [
-    /* your app */
-  ],
-})
+```tsx
+import { Provider, breakpoints } from '@pyreon/unistyle'
+
+<Provider theme={breakpoints}>
+  <App />
+</Provider>
 ```
 
-## API
+Or with a custom theme:
+
+```tsx
+<Provider
+  theme={{
+    rootSize: 16,
+    breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1440 },
+  }}
+>
+  <App />
+</Provider>
+```
+
+`Provider` is also re-exported from `@pyreon/coolgrid` and `@pyreon/elements` — set it once near the app root (typically `<PyreonUI>` wraps it automatically).
 
-### makeItResponsive
+## `makeItResponsive` — the core engine
 
-The core responsive engine. Takes a theme object and a styles processor, returns CSS with media query wrappers for each breakpoint.
+Reads a theme prop off styled-component props, runs the responsive pipeline, and returns CSS with media-query wrappers.
 
 ```ts
 import { makeItResponsive, styles } from '@pyreon/unistyle'
-import { config } from '@pyreon/ui-core'
-
-const { styled, css } = config
+import { css } from '@pyreon/styler'
+import { styled } from '@pyreon/styler'
 
 const Box = styled('div')`
-  ${makeItResponsive({
-    key: '$box',
-    css,
-    styles,
-  })}
+  ${makeItResponsive({ key: '$box', css, styles })}
 `
 
-// Single values
-Box({ $box: { padding: 16, fontSize: 14 } })
+// Scalar
+<Box $box={{ padding: 16, fontSize: 14 }} />
 
-// Responsive breakpoint object
-Box({ $box: { padding: { xs: 8, md: 16, lg: 24 }, fontSize: 14 } })
+// Breakpoint object
+<Box $box={{ padding: { xs: 8, md: 16, lg: 24 }, fontSize: 14 }} />
 
-// Responsive mobile-first array
-Box({ $box: { padding: [8, 16, 24], fontSize: 14 } })
+// Mobile-first array
+<Box $box={{ padding: [8, 16, 24], fontSize: 14 }} />
 ```
 
 **Pipeline:**
 
 ```text
-theme object → normalize (fill gaps) → transform (property → breakpoint pivot)
-  → optimize (deduplicate) → media queries
+theme object
+   ↓  normalize (fill gaps so every breakpoint has a complete set)
+   ↓  transform (property-centric → breakpoint-centric pivot)
+   ↓  optimize (drop declarations that don't change vs previous breakpoint)
+   ↓  emit @media rules
 ```
 
-**Parameters:**
-
-| Param     | Type       | Description                                                          |
-| --------- | ---------- | -------------------------------------------------------------------- |
-| key       | `string`   | Theme prop name to read from styled-component props                  |
-| css       | `function` | `css` tagged template function                                       |
-| styles    | `function` | Style processor (use the exported `styles`)                          |
-| normalize | `boolean`  | Fill missing breakpoints by inheriting from previous (default: true) |
+| Param | Type | Notes |
+|---|---|---|
+| `key` | `string` | Theme prop name to read from props |
+| `css` | `function` | `css` tagged template from `@pyreon/styler` |
+| `styles` | `function` | Style processor (use the exported `styles`) |
+| `normalize` | `boolean` | Fill missing breakpoints by inheriting from previous (default `true`) |
 
-### styles
+`makeItResponsive` carries a **render-output cache** keyed by theme reference — the same `(internalTheme, outerTheme)` pair returns the previous CSSResult array verbatim. Re-renders against a stable provider cost ~0.
 
-Data-driven CSS property processor. Reads a theme object and outputs CSS for all recognized properties — layout, spacing, typography, borders, backgrounds, transforms, and more.
+## `styles` — data-driven CSS processor
 
-Used internally by `makeItResponsive` but can be called directly:
+Reads a theme object and outputs CSS for 170+ recognized properties — layout, spacing, typography, borders, backgrounds, transforms, special keys (`fullScreen`, `clearFix`, `extendCss`, `backgroundImage`, `animation`). Used internally by `makeItResponsive`; callable directly when you have a non-responsive theme.
 
 ```ts
 import { styles } from '@pyreon/unistyle'
 
-// styles({ theme, css, rootSize }) => css``
+const cssResult = styles({ theme, css, rootSize: 16 })
 ```
 
-Supports shorthand properties (`margin`, `padding`, `borderRadius`) with automatic expansion, and converts numeric values to rem units.
+Supports shorthand expansion (`margin: 16` → `margin: 1rem`; `padding: '12 16'` → top/bottom/left/right), property-first naming (`borderWidthTop`, not CSS-spec `borderTopWidth`), and numeric→rem auto-conversion.
 
-### Unit Conversion
+## Responsive value formats
+
+Every property accepts three shapes:
 
 ```ts
-import { value, values, stripUnit } from '@pyreon/unistyle'
+// Scalar — applies at every breakpoint
+{ padding: 16 }
+
+// Mobile-first array — positional [xs, sm, md, lg, xl, xxl]
+{ padding: [8, 12, 16] }     // xs: 8, sm: 12, md: 16, fills above
 
-// value(input, rootSize?, outputUnit?) => string | number | null
-value(16) // => '1rem'     (16 / 16)
-value(24) // => '1.5rem'   (24 / 16)
-value(0) // => '0'        (always unitless)
-value('2em') // => '2em'      (string passthrough)
-value(16, 16, 'px') // => '16px'
-
-// stripUnit(input, unitReturn?)
-stripUnit('24px') // => 24
-stripUnit('24px', true) // => [24, 'px']
-stripUnit(24) // => 24
-
-// values(array, rootSize?, outputUnit?) => string
-// Picks first non-null and converts
-values([null, 16, 24], 16) // => '1rem'
+// Object — explicit breakpoint keys
+{ padding: { xs: 8, md: 16, xl: 24 } }
 ```
 
-### Alignment Helpers
+With `normalize: true` (default), missing breakpoints inherit from the previous one. The optimizer then DROPS declarations that don't actually change vs the previous breakpoint — so `{ color: { xs: 'red', sm: 'red' }, padding: { xs: 0, sm: '1rem' } }` emits only `padding: 1rem` at `@media (min-width: sm)`, not `color: red; padding: 1rem;`.
 
-```ts
-import { alignContent, ALIGN_CONTENT_MAP_X, ALIGN_CONTENT_MAP_Y } from '@pyreon/unistyle'
-```
+## Unit conversion
 
-Maps alignment keywords to CSS flex values:
+```ts
+import { value, values, stripUnit } from '@pyreon/unistyle'
 
-| Keyword            | X-axis CSS      | Y-axis CSS      |
-| ------------------ | --------------- | --------------- |
-| `left` / `top`     | `flex-start`    | `flex-start`    |
-| `center`           | `center`        | `center`        |
-| `right` / `bottom` | `flex-end`      | `flex-end`      |
-| `spaceBetween`     | `space-between` | `space-between` |
-| `spaceAround`      | `space-around`  | `space-around`  |
-| `block`            | `stretch`       | `stretch`       |
+value(16)              // '1rem'    (16 / 16)
+value(24)              // '1.5rem'
+value(0)               // '0'       (always unitless)
+value('2em')           // '2em'     (string passthrough)
+value(16, 16, 'px')    // '16px'    (output-unit override)
 
-### Default Breakpoints
+stripUnit('24px')           // 24
+stripUnit('24px', true)     // [24, 'px']
+stripUnit(24)               // 24
 
-```ts
-import { breakpoints } from '@pyreon/unistyle'
+values([null, 16, 24], 16)  // '1rem' (picks first non-null and converts)
 ```
 
+## Alignment helpers
+
 ```ts
-{
-  rootSize: 16,
-  breakpoints: {
-    xs: 0,      // mobile
-    sm: 576,    // small
-    md: 768,    // tablet
-    lg: 992,    // desktop
-    xl: 1200,   // large desktop
-    xxl: 1440,  // extra large
-  },
-}
+import { alignContent, ALIGN_CONTENT_MAP_X, ALIGN_CONTENT_MAP_Y, ALIGN_CONTENT_DIRECTION } from '@pyreon/unistyle'
 ```
 
-Breakpoint values are converted to `em` units in media queries for correct cross-browser behavior.
+Maps alignment keywords → CSS flex values:
 
-### Other Exports
+| Keyword            | X-axis            | Y-axis            |
+| ------------------ | ----------------- | ----------------- |
+| `left` / `top`     | `flex-start`      | `flex-start`      |
+| `center`           | `center`          | `center`          |
+| `right` / `bottom` | `flex-end`        | `flex-end`        |
+| `spaceBetween`     | `space-between`   | `space-between`   |
+| `spaceAround`      | `space-around`    | `space-around`    |
+| `block`            | `stretch`         | `stretch`         |
 
-| Export                 | Description                                                        |
-| ---------------------- | ------------------------------------------------------------------ |
-| `createMediaQueries`   | Builds breakpoint-name → tagged-template-function map              |
-| `transformTheme`       | Pivots property-centric theme to breakpoint-centric                |
-| `normalizeTheme`       | Fills gaps so every breakpoint has a complete set of values        |
-| `sortBreakpoints`      | Sorts breakpoint definitions by value (ascending)                  |
-| `extendCss`            | Helper for processing ExtendCss props (string, function, callback) |
-| `Provider` / `context` | Theme context provider and consumer                                |
+## Default breakpoints
 
-## Responsive Value Formats
+```ts
+import { breakpoints, enrichTheme } from '@pyreon/unistyle'
 
-Every property in the theme object supports three formats:
+breakpoints  // { rootSize: 16, breakpoints: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1440 } }
+```
 
-```ts
-// 1. Scalar — applied to all breakpoints
-{ padding: 16 }
+Values are converted to `em` units in media queries for correct cross-browser behaviour. `enrichTheme(userTheme)` merges your theme with the defaults — used by `<PyreonUI>` internally.
 
-// 2. Array — mobile-first, values map to breakpoints by position
-{ padding: [8, 12, 16] }  // xs: 8, sm: 12, md: 16
+## Other exports
 
-// 3. Object — explicit breakpoint keys
-{ padding: { xs: 8, md: 16, xl: 24 } }
+| Export | Notes |
+|---|---|
+| `createMediaQueries` | Builds breakpoint-name → tagged-template-function map |
+| `transformTheme` | Property-centric → breakpoint-centric pivot |
+| `normalizeTheme` | Fills gaps so every breakpoint has a complete set |
+| `sortBreakpoints` | Sorts breakpoint definitions by value (ascending) |
+| `extendCss` | Helper for processing `ExtendCss` props (string, fn, callback) |
+| `Provider` / `context` | Theme context provider + consumer |
+| `enrichTheme` | Merge user theme with default breakpoints/spacing |
+
+## Types
+
+```ts
+import type {
+  PyreonTheme, Breakpoints,
+  ITheme, Styles, StylesTheme, ExtendCss,
+  AlignContent, AlignContentAlignXKeys, AlignContentAlignYKeys, AlignContentDirectionKeys,
+  BrowserColors, Color, PropertyValue, UnitValue, Value, Values,
+  MakeItResponsive, MakeItResponsiveStyles, TransformTheme, NormalizeTheme, SortBreakpoints, CreateMediaQueries,
+  StripUnit, Defaults, TProvider,
+} from '@pyreon/unistyle'
 ```
 
-When using `normalize: true` (default), missing breakpoints inherit from the previous one.
+## Performance
 
-## Peer Dependencies
+- **Per-theme render cache** — `makeItResponsive` carries a `WeakMap<innerTheme, WeakMap<outerTheme, CSSResult[]>>`. Same theme reference → previous output returned verbatim.
+- **Key-to-index lookup** — `styles()` iterates ~10-20 descriptors per component (matched against the user's theme keys) instead of ~257 (full descriptor table). The index builder walks every branch's identifying field (`d.key` / `d.keys` / `d.id` for the `'special'` branch — `fullScreen`, `clearFix`, `extendCss`, `backgroundImage`, `animation`).
+- **Module-level reusable containers** — `styles()` reuses module-scoped `Set<number>` and `fragments[]` containers cleared on each synchronous call, eliminating ~160 allocations per 80-component page.
+- **Optimizer drops re-emitted declarations** — `optimizeBreakpointDeltas()` removes properties that don't change vs the previous breakpoint, cutting bytes in mobile-first responsive cascades.
 
-| Package            | Version  |
-| ------------------ | -------- |
-| @pyreon/core       | >= 0.0.1 |
-| @pyreon/reactivity | >= 0.0.1 |
-| @pyreon/ui-core    | >= 0.0.1 |
+## Gotchas
 
-## Performance
+- **Conditional CSS in responsive callbacks needs an explicit else.** When `t.block` is responsive (`[true, false, true]`), a callback like `${t.block && 'align-self: stretch'}` emits `stretch` at the truthy breakpoints AND emits NOTHING at the falsy ones — the optimizer is subtractive and can't synthesize a reset. The cascade leaves `stretch` in place. Fix: always emit a value with an explicit else: `align-self: ${t.block ? 'stretch' : 'auto'}`. The optimizer drops both halves when nothing changes, so the always-emit pattern is free in the steady state.
+- **CSS property naming follows unistyle convention** (`borderWidthTop` / `borderColorLeft`), NOT CSS-spec naming (`borderTopWidth`). Property-first.
+- **`extendCss`** accepts string, function, or callback. The function form receives the resolved theme so you can derive from it.
+- **`enrichTheme` merges; it does not replace.** Pass only the keys you want to override — defaults fill in the rest.
+
+## Documentation
 
-The `styles()` function reuses module-level `Set<number>` and `fragments[]` containers, cleared on each synchronous call instead of allocating per-call. Combined with the Tier 1 key-to-index lookup (iterates ~10-20 descriptors per component instead of ~257), this eliminates ~160 allocations per 80-component page.
+Full docs: [docs.pyreon.dev/docs/unistyle](https://docs.pyreon.dev/docs/unistyle) (or `docs/docs/unistyle.md` in this repo).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/unistyle",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Responsive theming and breakpoint utilities for Pyreon",
   "license": "MIT",
   "repository": {
@@ -43,18 +43,18 @@
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/test-utils": "^0.13.8",
-    "@pyreon/typescript": "^0.21.0",
+    "@pyreon/test-utils": "^0.13.10",
+    "@pyreon/typescript": "^0.23.0",
     "@vitest/browser-playwright": "^4.1.4",
-    "@vitus-labs/tools-rolldown": "^2.3.0"
+    "@vitus-labs/tools-rolldown": "^2.4.0"
   },
   "engines": {
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.21.0",
-    "@pyreon/reactivity": "^0.21.0",
-    "@pyreon/styler": "^0.21.0",
-    "@pyreon/ui-core": "^0.21.0"
+    "@pyreon/core": "^0.23.0",
+    "@pyreon/reactivity": "^0.23.0",
+    "@pyreon/styler": "^0.23.0",
+    "@pyreon/ui-core": "^0.23.0"
   }
 }