@neo-ui-kit/react 1.2.3 → 1.3.2

package/README.md

@@ -25,13 +25,19 @@ import "@neo-ui-kit/react/styles.css";
 To test repository changes before publishing, run `npm run package` from the repository root and install the resulting archive in a separate application:
 
 ```bash
-npm install /path/to/adui/release/neo-ui-kit-react-1.2.3.tgz
+npm install /path/to/adui/release/neo-ui-kit-react-1.3.2.tgz
 ```
 
 Maintainers publish new versions from `Pro100Dimka/adui` using the `release.yml` GitHub Actions workflow, a matching `v<version>` tag, and the `npm-publication` environment. npm trusts its OIDC identity; no `NPM_TOKEN` is required. The workflow checks the project and packed consumer before publishing the tested archive. Published `1.0.0` cannot be overwritten: code and README changes in npm require a new package version. See the [repository release instructions](https://github.com/Pro100Dimka/adui#npm-пакет).
 
 ## Theme
 
+Decorations inside `data-ad-paused` or `data-ad-offscreen` boundaries retain their
+phase while paused. After changing either attribute yourself, call `refreshMotion()`
+(imported from `@neo-ui-kit/react`) after the DOM update.
+This refreshes both CSS and scripted decorations on the next shared frame.
+`usePauseOffscreen` handles its own notifications.
+
 Two colours build the whole palette (a primary scale, a secondary scale and tinted neutrals):
 
 ```tsx
@@ -178,10 +184,71 @@ import { Form, FormFields, useForm } from "@neo-ui-kit/react/forms";
 import { ThemeProvider, useMotion } from "@neo-ui-kit/react/core";
 ```
 
+## ThemePicker and declarative fields
+
+`ThemePicker` renders compact built-in swatches, or a gallery when `options` are supplied. Each option has `value`, `label`, optional `image` (foreground), `background` (full-card backdrop), `color` and `description`. Foreground pictures keep the same contained size when selected; captions and their accent lines sit below the picture. The selected card has a check mark and glow. Arrow keys, Home and End select a theme; `disabled` blocks selection.
+
+```tsx
+import { ThemePicker } from "@neo-ui-kit/react";
+
+<ThemePicker value={theme} onValueChange={setTheme} options={[
+  { value: "dark", label: "Dark", image: "/themes/dark-icon.webp",
+    background: "/themes/dark-background.webp", color: "#ff244c" },
+  { value: "light", label: "Light", image: "/themes/light-icon.webp",
+    background: "/themes/light-background.webp", color: "#f3d38f" },
+]} />
+```
+
+`FormFields` binds each `name` (including dotted paths) to the nearest `Form`. Supported kinds: `text`, `number`, `textarea`, `select`, `autocomplete`, `checkbox`, `switch`, `color`, `date`, `file`, `people`, `slider`, `rotary`, `tags`, `theme`, `toggle`, `segmented`, `tabs` and `custom`. `theme` uses `ThemePicker`; `toggle` uses `ToggleButton`; `segmented` uses `SegmentedControl`. Pass the control's options through `props`. Initial values and resets come from the form, so set them in `initialValues` rather than `props.defaultValue`.
+
+For `kind: "custom"`, `render(field, form)` is required and returns your component. `field` supplies `value`, `onValueChange`, `onBlur`, `error` and `touched`; `form` is the typed `FormApi`. The renderer updates when any form value changes. It owns its label, value conversion and validation display. `span` and `showWhen` also work for custom fields; no registry entry is needed.
+
+```tsx
+import { TextField, type FormFieldDefinition } from "@neo-ui-kit/react";
+import { Form, FormFields, useForm } from "@neo-ui-kit/react/forms";
+
+type Values = { theme: string; nickname: string };
+const fields: FormFieldDefinition<Values>[] = [
+  { name: "theme", kind: "theme", label: "Theme" },
+  { name: "nickname", kind: "custom", render: (field, form) => (
+    <TextField label={`Nickname (${form.values.theme})`}
+      value={String(field.value ?? "")} onValueChange={field.onValueChange}
+      onBlur={field.onBlur} error={field.touched ? field.error : undefined} />
+  ) },
+];
+
+function Preferences() {
+  const form = useForm<Values>({ initialValues: { theme: "ruby", nickname: "DJ" } });
+  return <Form form={form}><FormFields fields={fields} /></Form>;
+}
+```
+
 ## RotaryKnob
 
 Canvas-rendered volume knob. Drag near the edge to rotate, drag from the center to move linearly, click the outer scale to jump. Wheel and arrow keys change the value, Shift gives a fine step, PageUp/PageDown change by 10, Home/End set 0/100, Escape cancels a drag, double-click resets. `onValueChange` fires while adjusting, `onValueCommit` after the gesture. `readOnly` turns it into a gauge.
 
+## 1.3.2 release notes
+
+- Waveform updates only its moving layers and pauses invisible sparks and fully clipped sheen.
+- RotaryKnob completes all canvas layers after StrictMode restarts, avoids duplicate pending renders of the same size, and waits for square canvas dimensions before drawing its feedback ring.
+- Scripted decorations respect pause/offscreen boundaries. `refreshMotion()` batches boundary changes without checking ancestors on every frame.
+- FormFields helper selectors avoid invalidating unrelated descendants while keeping the same layout.
+- Playground code windows can expand to the full browser viewport. The editor and preview resize together without resetting the draft.
+
+Standalone profiling on an RTX 3060, Electron 42.11.8, at 1920×1050 with CPU ×4
+showed 36.9 → 58.9 FPS over 45 seconds for 20 cards combining a waveform, knob,
+and animated border. This is a measured scenario, not a guarantee of 60 FPS for
+every application. CPU ×16/×32 and software compositing still have substantial
+slowdowns; changing rasterization alone did not remove them.
+
+## 1.3.1 release notes
+
+- ThemePicker gallery cards accept separate backgrounds and keep selected/unselected pictures at the same size, with readable captions and theme-coloured accent lines.
+- FormFields adds `theme`, `toggle`, `segmented`, `tabs` and a typed `custom` renderer. Existing kinds and registries remain supported.
+- QuantumBackground adds `particleDepth`, `particleScale` and `particleSharpness` to control particle depth, size and crispness. Defaults preserve the previous appearance.
+- The documentation includes interactive gallery and custom-field examples.
+- Updated English/Ukrainian catalog descriptions and existing release checks for the expanded fields and particle controls. Version 1.3.0 was not published to npm.
+
 ## 1.2.3 release notes
 
 - `Avatar` imports only its host seal illustration, allowing bundlers to remove unused illustrations. Its appearance and public API are unchanged.
@@ -260,6 +327,8 @@ import "@neo-ui-kit/react/styles.css";
 
 Settings (`QuantumBackgroundSettings`): `field` (one of `quantumBackgroundFields`), `sensitivity`, `density`, `timeScale`, `paused`, `interactive`, nebula, connection, crawler, particle-trail, lens-flare, depth-of-field, camera-shake, bloom, trails, chromatic, anamorphic, god-ray, grain, vortex, pulse, bass-gate, onset, audio-camera, terrain-height and adaptive-quality values. Unset props use `quantumBackgroundDefaults`; only props that change are sent to the scene. `quantumBackgroundControls` lists each setting's group, label, range, step and the switch it depends on, for building your own settings panel next to the component. `particleCount` sets how many particles are drawn across both layers (0 to `quantumBackgroundMaxParticles`, 85 000); leave it unset to follow `density`. Adaptive quality may draw fewer, so turn `adaptiveQualityEnabled` off when the exact count matters. `particleBudget` is an upper cap on top of either. `fieldSize` is the share of the scene the field spans (0.78 by default, 1 reaches the edges). `fullscreen` makes the scene cover the whole viewport above the page, and the field then runs edge to edge (`quantumBackgroundFullscreenFieldSize`, 1.1) unless `fieldSize` is set (in the browser's top layer, so no ancestor's `overflow`, `transform` or `z-index` clips it, and the iframe keeps running); Escape calls `onFullscreenChange(false)`, so keep it controlled. `children` are laid over the scene, e.g. a close button while full screen. This differs from `ref.toggleFullscreen()`, which uses the browser's Fullscreen API and needs a click.
 
+`particleDepth` (0–1, default 0) separates particles into depth: rare foreground lights are larger and move faster, while the secondary layer stays farther away. `particleScale` (0.5–3, default 1) changes their size independently of the field footprint. `particleSharpness` (0–1, default 0) blends toward a crisp white core with a compact coloured halo. These controls share the existing particle buffers and preserve the original appearance at their defaults. For a clear foreground over an image, try `particleDepth={1} particleScale={1.5} particleSharpness={1}` with `dofEnabled={false} bloom={0} trails={0}`.
+
 `threeUrl` points the scene at your own copy of three.js 0.182 instead of unpkg (for example `threeUrl="./vendor/three/"` with `build/three.module.js` and `examples/jsm/` served there); with it the scene makes no network requests at all. Only the scene's import map changes, so a strict CSP pins the same script hashes everywhere.
 
 `spectrum` feeds sound the scene cannot hear itself — a native audio engine, a WebRTC call, a server stream: band levels 0–1 from low to high frequencies, log-spaced across `spectrumRange` (default `[40, 12000]` Hz), any band count. Pass a new array whenever the levels change (10–60 times a second); bands, beats, reaction lines and flashes follow it exactly as they follow a playing song. A file or microphone started from the ref takes over while it plays; `spectrum={undefined}` returns the scene to silence.

package/dist/chunks/{chunk-YKCUOZ7V.js → chunk-ICRXRGIW.js}

@@ -1,3 +1,7 @@
+import {
+  classes,
+  mark
+} from "./chunk-BJSFN52W.js";
 import {
   canObserveIntersection,
   createResizeObserver,
@@ -32,6 +36,7 @@ var pendingTargets = /* @__PURE__ */ new Set();
 var active = [];
 var lastScan = -Infinity;
 var needsScan = false;
+var boundariesChanged = false;
 var tickers = /* @__PURE__ */ new Set();
 U.subscribeTick = (listener) => {
   tickers.add(listener);
@@ -81,6 +86,16 @@ function scan(now, animations = pendingAnimations) {
 }
 function tick(now) {
   raf = null;
+  if (boundariesChanged) {
+    boundariesChanged = false;
+    for (const scope of preferenceScopes) {
+      const runnable = scope.enabled && !scope.root.closest?.("[data-ad-offscreen], [data-ad-paused]");
+      if (runnable === running.has(scope)) continue;
+      scope.previous = null;
+      if (runnable) running.add(scope);
+      else running.delete(scope);
+    }
+  }
   if (needsScan || now - lastScan > 400) scan(now);
   const deadline = performance.now() + 8;
   for (const item of measurements) {
@@ -128,6 +143,7 @@ function schedule() {
 }
 function refreshMotion() {
   needsScan = true;
+  boundariesChanged = true;
   schedule();
 }
 var wake = () => {
@@ -243,7 +259,7 @@ U.createMotion = (root = document) => {
       this.previous = null;
       const target = root.dataset ? root : root.host || document.documentElement;
       target.dataset.adMotion = enabled ? "on" : "off";
-      if (this.enabled) running.add(this);
+      if (this.enabled && !root.closest?.("[data-ad-offscreen], [data-ad-paused]")) running.add(this);
       else running.delete(this);
       schedule();
       return this.enabled;
@@ -763,6 +779,83 @@ function useSmoothWheel(ref) {
   }, [ref, enabled]);
 }
 
+// src/components/foundation/ThemeProvider/ThemeProvider.tsx
+import { createContext, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+var themes = {
+  ruby: ["#ff244c", "#ff7c97"],
+  light: ["#e0a43a", "#f3d38f"],
+  green: ["#10c99a", "#7cf3d0"],
+  violet: ["#9b5cff", "#d3a8ff"]
+};
+var ThemeColorSchemeContext = createContext("dark");
+var ThemePaletteContext = createContext({
+  theme: "ruby",
+  primary: themes.ruby[0],
+  secondary: themes.ruby[1]
+});
+var useThemePalette = () => useContext(ThemePaletteContext);
+var emptyTokens = {};
+function hue(hex) {
+  const [r, g, b] = [1, 3, 5].map(
+    (i) => parseInt(hex.slice(i, i + 2), 16) / 255
+  );
+  const max = Math.max(r, g, b);
+  const delta = max - Math.min(r, g, b);
+  if (!delta) return 0;
+  let h = (r - g) / delta + 4;
+  if (max === r) h = (g - b) / delta % 6;
+  else if (max === g) h = (b - r) / delta + 2;
+  return (h * 60 + 360) % 360;
+}
+var ThemeProvider = ({
+  theme,
+  colorScheme,
+  primary,
+  secondary,
+  accent,
+  tokens = emptyTokens,
+  style,
+  children,
+  id,
+  className,
+  ...attributes
+}) => {
+  const inheritedScheme = useContext(ThemeColorSchemeContext);
+  const inheritedPalette = useThemePalette();
+  const scheme = colorScheme ?? inheritedScheme;
+  const selected = theme ?? inheritedPalette.theme;
+  const main = primary ?? accent ?? (theme ? themes[theme][0] : inheritedPalette.primary);
+  const light = secondary ?? (theme ? themes[theme][1] : inheritedPalette.secondary);
+  const vars = useMemo(() => {
+    const next = { ...style };
+    if (theme !== void 0 || primary !== void 0 || accent !== void 0) next["--ad-primary"] = main;
+    if (theme !== void 0 || secondary !== void 0) next["--ad-secondary"] = light;
+    for (const [key, value] of Object.entries(tokens))
+      next[key.startsWith("--") ? key : `--ad-${key}`] = value;
+    const effectivePrimary2 = next["--ad-primary"];
+    if (typeof effectivePrimary2 === "string" && /^#[0-9a-f]{6}$/i.test(effectivePrimary2) && next["--ad-hue-shift"] === void 0)
+      next["--ad-hue-shift"] = `${Math.round(hue(effectivePrimary2) - hue(themes.ruby[0]))}deg`;
+    return next;
+  }, [style, main, light, primary, secondary, accent, theme, tokens]);
+  const effectivePrimary = String(vars["--ad-primary"] ?? main);
+  const effectiveSecondary = String(vars["--ad-secondary"] ?? light);
+  const palette = useMemo(() => ({ theme: selected, primary: effectivePrimary, secondary: effectiveSecondary }), [selected, effectivePrimary, effectiveSecondary]);
+  return /* @__PURE__ */ jsx(ThemeColorSchemeContext.Provider, { value: scheme, children: /* @__PURE__ */ jsx(ThemePaletteContext.Provider, { value: palette, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...mark("ThemeProvider", attributes),
+      id,
+      className: classes("ad-theme", className),
+      style: vars,
+      "data-ad-component": "ThemeProvider",
+      "data-ad-theme": selected,
+      "data-ad-color-scheme": scheme,
+      children
+    }
+  ) }) });
+};
+
 export {
   refreshMotion,
   setMotionFrameRate,
@@ -773,5 +866,8 @@ export {
   useTick,
   usePauseOffscreen,
   useTabShape,
-  useSmoothWheel
+  useSmoothWheel,
+  themes,
+  useThemePalette,
+  ThemeProvider
 };