@pyreon/ui-core 0.22.0 → 0.23.0

package/README.md

@@ -1,150 +1,186 @@
 # @pyreon/ui-core
 
-Shared foundation for the Pyreon UI System ecosystem.
+Foundation layer for Pyreon's UI system — `PyreonUI` provider, config singleton, utilities.
 
-Provides utility functions, a styling engine bridge, theme context, and HTML tag definitions used across all `@pyreon` packages. No external utility dependencies — all implementations are built-in with prototype pollution protection where applicable.
+`@pyreon/ui-core` is the cross-cutting layer that ties Pyreon's UI packages (`styler`, `unistyle`, `elements`, `rocketstyle`, `coolgrid`, …) together. It ships the unified `<PyreonUI>` provider (theme + light/dark/system mode in one component), the `config` styling-engine singleton (a thin facade over `@pyreon/styler`), helper utilities (`omit` / `pick` / `merge` / `compose` / `throttle` / `set` / `get` / `isEmpty` / `isEqual` / `hoistNonReactStatics`), and the canonical HTML tag arrays + types. No external utility deps — every helper is built-in with prototype-pollution protection where it matters.
 
-## Installation
+## Install
 
 ```bash
-bun add @pyreon/ui-core
+bun add @pyreon/ui-core @pyreon/core @pyreon/styler
 ```
 
-## API
+## Quick start
 
-### Provider & Context
+```tsx
+import { PyreonUI, useMode } from '@pyreon/ui-core'
+import { theme } from '@pyreon/ui-theme'
 
-```ts
-import { Provider, context, config, init } from '@pyreon/ui-core'
+<PyreonUI theme={theme} mode="system">
+  <App />
+</PyreonUI>
+
+// In any descendant:
+function ModeAware() {
+  const mode = useMode()              // "light" | "dark" — reactive
+  return <span>Current mode: {mode}</span>
+}
+```
+
+## `<PyreonUI>` — unified provider
+
+Single provider that replaces the previous trio of theme / mode / config providers.
+
+```tsx
+<PyreonUI
+  theme={theme}                       // Theme object (breakpoints, rootSize, custom keys)
+  mode="light"                        // "light" | "dark" | "system" — also accepts () => mode
+  inversed                            // Flip mode for a nested section (dark sidebar in light app)
+>
+  <App />
+</PyreonUI>
 ```
 
-**Provider** wraps your app with a theme context. It bridges `@pyreon/styler`'s theming with the internal context system.
+- `mode="system"` — auto-detects OS dark mode via `matchMedia('(prefers-color-scheme: dark)')` and updates reactively when the user changes their OS preference.
+- `inversed` — flips the resolved mode for the subtree (e.g. a dark hero on a light page).
+- `mode` accepts a signal accessor — `<PyreonUI mode={() => userPref()}>` re-renders the entire subtree's CSS on change WITHOUT remounting (the theme is wrapped in `computed()`).
+- `PyreonUI` calls `init()` internally — you don't normally need to call it yourself.
+
+`PyreonUI` is marked `nativeCompat` so it works correctly inside compat-mode apps (`@pyreon/{react,preact,vue,solid,svelte}-compat`) — its `provide()` calls land in Pyreon's setup frame, not inside the compat wrapper.
+
+## `useMode()`
+
+Reactive — returns `'light'` or `'dark'`, updates on `mode` prop changes AND OS preference changes (when `mode="system"`).
 
 ```ts
-import { Provider } from '@pyreon/ui-core'
-
-Provider({
-  theme: { rootSize: 16, breakpoints: { xs: 0, md: 768 } },
-  children: [
-    /* your app */
-  ],
-})
+const mode = useMode()
 ```
 
-**config** — the styling engine singleton. Pyreon uses `@pyreon/styler` directly — no connector abstraction needed.
+## `config` — styling engine singleton
 
 ```ts
 import { config } from '@pyreon/ui-core'
 
-// Access the engine from anywhere
 const { styled, css, keyframes } = config
 ```
 
-### Utilities
+Pyreon uses `@pyreon/styler` directly — `config` is a thin facade exposed for symmetry across the UI packages. `init()` is the (idempotent) bootstrap call `PyreonUI` invokes internally.
 
-#### compose
+## Utility helpers
 
-Right-to-left function composition.
+### `compose(...fns)` — right-to-left function composition
 
 ```ts
-import { compose } from '@pyreon/ui-core'
-
 const transform = compose(toUpperCase, trim, normalize)
-transform('  hello  ') // => 'HELLO'
+transform('  hello  ')  // 'HELLO'
 ```
 
-#### render
+### `render(value)` — flexible value/element renderer
 
-Flexible element renderer. Handles components, elements, primitives, and arrays.
+Handles components, primitives, arrays, null. Useful when authoring helper components that accept a polymorphic content prop.
 
 ```ts
-import { render } from '@pyreon/ui-core'
-
-render('hello') // => 'hello'
-render(MyComponent) // => MyComponent({})
-render(null) // => null
+render('hello')           // 'hello'
+render(MyComponent)       // MyComponent({})
+render(null)              // null
 ```
 
-#### isEmpty
+### `isEmpty(value)` / `isEqual(a, b)`
 
-Type-safe emptiness check. Returns `true` for `null`, `undefined`, `{}`, `[]`, and non-object primitives.
+Type-safe checks. `isEmpty` returns `true` for `null`, `undefined`, `{}`, `[]`, and non-object primitives. `isEqual` performs a deep structural compare.
 
 ```ts
-import { isEmpty } from '@pyreon/ui-core'
-
-isEmpty({}) // => true
-isEmpty([]) // => true
-isEmpty(null) // => true
-isEmpty({ a: 1 }) // => false
+isEmpty({})           // true
+isEmpty([])           // true
+isEmpty({ a: 1 })     // false
+isEqual({a:1}, {a:1}) // true
 ```
 
-#### omit / pick
+### `omit(obj, keys)` / `pick(obj, keys)`
 
-Create objects without or with only specified keys. Accept nullable inputs. `omit()` also accepts a pre-built `Set<string>` for hot paths where the same key list is reused across many calls (avoids per-call Set allocation).
+Object key filtering. Accept nullable inputs. **`omit()` also accepts a pre-built `Set<string>`** for hot paths where the same key list is reused across many calls (used by rocketstyle to avoid per-mount Set allocation):
 
 ```ts
-import { omit, pick } from '@pyreon/ui-core'
-
-omit({ a: 1, b: 2, c: 3 }, ['b']) // => { a: 1, c: 3 }
-pick({ a: 1, b: 2, c: 3 }, ['a', 'b']) // => { a: 1, b: 2 }
+omit({ a:1, b:2, c:3 }, ['b'])      // { a:1, c:3 }
+pick({ a:1, b:2, c:3 }, ['a','b'])  // { a:1, b:2 }
 
-// Hot-path usage with pre-built Set (used by rocketstyle):
-const omitSet = new Set(['b', 'c'])
-omit({ a: 1, b: 2, c: 3 }, omitSet) // => { a: 1 }
+const omitSet = new Set(['b','c'])
+omit({ a:1, b:2, c:3 }, omitSet)    // { a:1 }
 ```
 
-#### set / get
+### `set(obj, path, value)` / `get(obj, path, default?)`
 
-Nested property access and mutation by dot/bracket path. `set` has built-in prototype pollution protection — keys like `__proto__`, `constructor`, and `prototype` are blocked.
+Nested property access by dot/bracket path. **`set` blocks prototype pollution** — `__proto__`, `constructor`, `prototype` keys are silently ignored.
 
 ```ts
-import { set, get } from '@pyreon/ui-core'
-
-const obj = {}
-set(obj, 'a.b.c', 42) // => { a: { b: { c: 42 } } }
-get(obj, 'a.b.c') // => 42
-get(obj, 'a.x', 'default') // => 'default'
+const o = {}
+set(o, 'a.b.c', 42)               // { a: { b: { c: 42 } } }
+get(o, 'a.b.c')                   // 42
+get(o, 'a.x', 'default')          // 'default'
 ```
 
-#### merge
+### `merge(...objects)` — left-to-right deep merge
 
-Deep merge objects left-to-right. Only plain objects are recursed into; arrays are replaced wholesale. Prototype pollution keys are blocked.
+Only plain objects are recursed; arrays are replaced wholesale. Prototype-pollution keys are blocked.
 
 ```ts
-import { merge } from '@pyreon/ui-core'
+merge({ a: { x: 1 } }, { a: { y: 2 } })  // { a: { x: 1, y: 2 } }
+```
+
+### `throttle(fn, ms)`
+
+Limits execution to at most once per window. Returns a function with `.cancel()`.
 
-merge({ a: { x: 1 } }, { a: { y: 2 } }) // => { a: { x: 1, y: 2 } }
+```ts
+const onResize = throttle(handleResize, 200)
+window.addEventListener('resize', onResize)
+// onResize.cancel()
 ```
 
-#### throttle
+### `useStableValue(value)`
+
+Returns a stable accessor that emits only when the input changes by `isEqual`. Useful for deriving signal-shaped values from props that may re-construct identical objects every render.
+
+### `hoistNonReactStatics(target, source)`
 
-Limits function execution to at most once per wait period. Returns a throttled function with a `.cancel()` method.
+Standard "hoist non-React statics" copy — used by HOC factories so wrapped components retain their static methods + display names.
+
+## HTML tag constants
 
 ```ts
-import { throttle } from '@pyreon/ui-core'
+import { HTML_TAGS, HTML_TEXT_TAGS, HTMLTags, HTMLTextTags } from '@pyreon/ui-core'
 
-const throttled = throttle(handleResize, 200)
-window.addEventListener('resize', throttled)
-// cleanup: throttled.cancel()
+HTML_TAGS         // array of 100+ valid HTML tag names
+HTML_TEXT_TAGS    // text-content tags: h1-h6, p, span, strong, em, ...
+type Tag = HTMLTags        // narrowed union type
+type TextTag = HTMLTextTags
 ```
 
-### HTML Constants
+Used by `@pyreon/elements` to constrain the `tag` prop and by the styler's `as` polymorphism.
+
+## Types
 
 ```ts
-import { HTML_TAGS, HTML_TEXT_TAGS } from '@pyreon/ui-core'
+import type {
+  BreakpointKeys, Breakpoints,
+  CoreContextValue,
+  HTMLElementAttrs, HTMLTagAttrsByTag, HTMLTags, HTMLTextTags,
+  IsEmpty,
+  PyreonUIProps, ThemeMode, ThemeModeInput,
+  Render,
+} from '@pyreon/ui-core'
 ```
 
-- **HTML_TAGS** — array of 100+ valid HTML tag names
-- **HTML_TEXT_TAGS** — array of text-content tags (h1–h6, p, span, strong, em, etc.)
+## Gotchas
 
-Both have corresponding TypeScript union types: `HTMLTags` and `HTMLTextTags`.
+- **`<PyreonUI>` is the canonical app-root provider.** Internal sub-providers (`CoreProvider` / `UnistyleProvider` / `ThemeProvider` / `Provider` from rocketstyle / `OverlayContextProvider`) are marked `nativeCompat` even though they're internal — never mount a sub-provider manually if `<PyreonUI>` is already in the tree.
+- **`set` / `merge` silently drop prototype-pollution keys.** If a user-supplied key matches `__proto__` / `constructor` / `prototype` it is ignored. Don't rely on these utilities for arbitrary JSON merging that might intentionally need those keys.
+- **`omit` with a Set is faster than with an array** only at scale. For one-off calls the array form is fine.
+- **`useMode()` is reactive — call inside a tracking scope** (JSX expression, effect, computed). Reading at component setup top-level captures the initial value.
 
-## Peer Dependencies
+## Documentation
 
-| Package        | Version  |
-| -------------- | -------- |
-| @pyreon/core   | >= 0.0.1 |
-| @pyreon/styler | >= 0.0.1 |
+Full docs: [docs.pyreon.dev/docs/ui-core](https://docs.pyreon.dev/docs/ui-core) (or `docs/docs/ui-core.md` in this repo).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/ui-core",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Core utilities, config, and context for Pyreon UI System",
   "license": "MIT",
   "repository": {
@@ -38,16 +38,16 @@
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/typescript": "^0.22.0",
-    "@vitus-labs/tools-rolldown": "^2.3.0"
+    "@pyreon/typescript": "^0.23.0",
+    "@vitus-labs/tools-rolldown": "^2.4.0"
   },
   "engines": {
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.22.0",
-    "@pyreon/reactivity": "^0.22.0",
-    "@pyreon/styler": "^0.22.0",
-    "@pyreon/unistyle": "^0.22.0"
+    "@pyreon/core": "^0.23.0",
+    "@pyreon/reactivity": "^0.23.0",
+    "@pyreon/styler": "^0.23.0",
+    "@pyreon/unistyle": "^0.23.0"
   }
 }