@neo-ui-kit/react 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pro100dimka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# @neo-ui-kit/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Migration: replace `@ad-voice/ui` with `@neo-ui-kit/react` in dependencies and imports, including CSS and `/core`, `/forms`, `/editor`, `/router` subpaths. Install `@neo-ui-kit/react`; component APIs and CSS class names are unchanged. The old package name is not an alias.
+
+NEO UI — React + TypeScript UI kit: glass/ruby surfaces, animated neon borders, fields, tabs, dialogs, audio controls and a melody editor.
+
+## Install
+
+Live docs: https://pro100dimka.github.io/adui/
+
+Install the package in your application. React and ReactDOM are peer dependencies; the declared range is React 18.2 through 19.
+
+```bash
+npm install @neo-ui-kit/react
+```
+
+Package: [@neo-ui-kit/react on npm](https://www.npmjs.com/package/@neo-ui-kit/react).
+
+Import the stylesheet once in the app entry point:
+
+```ts
+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.0.1.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
+
+Two colours build the whole palette (a primary scale, a secondary scale and tinted neutrals):
+
+```tsx
+import { ThemeProvider } from "@neo-ui-kit/react";
+
+<ThemeProvider theme="violet">…</ThemeProvider>            // a ready pair
+<ThemeProvider primary="#2f7bff" secondary="#9cc4ff">…</ThemeProvider>
+<ThemeProvider tokens={{ "primary-900": "#0a1430" }}>…</ThemeProvider> // any token by hand
+```
+
+## Usage
+
+```tsx
+import { Button, Card, Switch, TextField } from "@neo-ui-kit/react";
+
+export function SettingsCard() {
+  return (
+    <Card title="Настройки" border>
+      <TextField label="Имя в онлайн-комнате" defaultValue="BBB" clearable />
+      <Switch label="Радио включено" defaultChecked />
+      <Button variant="primary" icon="save">
+        Сохранить
+      </Button>
+    </Card>
+  );
+}
+```
+
+Fields that declare `value` / `defaultValue` support controlled and uncontrolled values; checkboxes and switches use `checked` / `defaultChecked`. Dialog supports `open` / `defaultOpen` and `onOpenChange`; Popover requires controlled `open`. See each component's API for its supported state and event names; a change callback reports a user action, while the owner applies the new controlled value.
+
+The package ships ESM only. Import styles once and wrap the UI in `ThemeProvider`; no playground CSS or router is required. `@neo-ui-kit/react/core`, `/forms`, `/editor`, and `/router` share the same provider contexts with the root entry.
+
+The library code is licensed under [MIT](./LICENSE). Bundled third-party materials retain their respective licenses and notices: `dist/fonts/melodix/OFL-PlayfairDisplay.txt` for the font and `dist/components/artwork/QuantumField/UPSTREAM-LICENSE.txt` for Quantum Fields.
+
+## QuantumField
+
+`QuantumField` is an original, theme-native 3D audio visualization for backgrounds and panels. It renders immediately—there is no Enter gate—and its seven `mode` values are `orbit`, `vortex`, `lattice`, `wave`, `bloom`, `helix`, and `terrain`. Its bounded WebGL renderer uses static particle and filament buffers without post-processing; Canvas 2D is a fallback when WebGL is unavailable. `quality="auto"` limits pixels and particles, and drawing pauses outside the viewport, in hidden tabs, or when the kit's motion setting is off. `interactive` enables deep wheel zoom, local pointer influence, and drag-to-rotate; hovering alone never rotates the whole field. `density`, `speed`, `quality`, `interactive`, and `paused` are optional. Normally its colours follow the nearest `ThemeProvider`; `palette={[primary, secondary]}` overrides one instance.
+
+```tsx
+import { QuantumField, ThemeProvider } from "@neo-ui-kit/react";
+
+<ThemeProvider primary="#10c99a" secondary="#7cf3d0">
+  <QuantumField mode="vortex" quality="auto" aria-label="Audio field" />
+</ThemeProvider>
+```
+
+To react to a microphone, request access only from a user click and pass the resulting stream. The component owns and releases its audio analysis graph; your app still owns the stream and stops its tracks when no longer needed.
+
+```tsx
+import { useEffect, useState } from "react";
+import { Button, QuantumField } from "@neo-ui-kit/react";
+
+function MicrophoneField() {
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  useEffect(() => () => stream?.getTracks().forEach((track) => track.stop()), [stream]);
+  return <>
+    <Button onClick={async () => setStream(await navigator.mediaDevices.getUserMedia({ audio: true }))}>
+      Enable microphone
+    </Button>
+    <QuantumField mode="terrain" stream={stream ?? undefined} />
+  </>;
+}
+```
+
+For a file player, `createQuantumFieldAudio()` provides a small optional transport. Create it in response to a user action, call `loadFile(file)` (which does **not** autoplay), then pass `controller.analyser` as `audio`. Its `play`, `pause`, `seek`, `media`, and `dispose` members let you build the controls with the kit's `FilePicker`, `Button`, and `Slider`. `requestMicrophone()` is explicit and stops only the stream it requested; `connectStream(stream)` accepts an app-owned stream without taking ownership.
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { Button, FilePicker, QuantumField, createQuantumFieldAudio } from "@neo-ui-kit/react";
+
+function FileField() {
+  const controller = useRef<ReturnType<typeof createQuantumFieldAudio> | null>(null);
+  const [analyser, setAnalyser] = useState<AnalyserNode | null>(null);
+  useEffect(() => () => { void controller.current?.dispose(); }, []);
+
+  return <>
+    <FilePicker variant="button" accept="audio/*" label="Choose audio" onFiles={([file]) => {
+      if (!file) return;
+      const audio = controller.current ??= createQuantumFieldAudio();
+      audio.loadFile(file); // does not autoplay
+      setAnalyser(audio.analyser);
+    }} />
+    <Button disabled={!analyser} onClick={() => { void controller.current?.play(); }}>Play</Button>
+    <QuantumField mode="wave" audio={analyser ?? undefined} />
+  </>;
+}
+```
+
+An existing audio engine can also pass its own `AnalyserNode` as `audio`, or a callback returning `{ bands: [bass, …, air], energy, beat }` with seven normalized band levels. Playback and permission handling stay outside the visualizer, so mounting it never captures audio unexpectedly.
+
+## DataTable
+
+`DataTable` includes multi-column sorting, per-column filters with distinct-value autocomplete, grouping and aggregates, search, selection, column visibility/order/pinning, lazy row details, row actions, row numbers, density controls, CSV export, and responsive cards. Readers can resize columns by dragging the header edge or focusing it and pressing ←/→; double-clicking the edge restores its original width. `resizableColumns={false}` disables all handles, and `resizable: false` disables one column.
+
+Set `pageSize` to enable pagination. `pageSizeOptions` provides footer choices (the initial size is always included), and the footer shows the visible result range. The reset button clears sorting, filters, grouping, search, hidden columns, resized widths, and the chosen page size. See the live `DataTable` example in the documentation for complete column and row definitions.
+
+Click a header to cycle ascending/descending/unsorted; Shift-click adds another sort criterion. `sorting` / `defaultSorting` / `onSortingChange` manage the ordered array of criteria. The existing single-column `sort` API remains supported. `columnOrder` and `columnPinning` have the same controlled/default/change pattern; pinning is `{ left: ["name"], right: ["status"] }`. The Columns menu exposes keyboard-accessible reordering and pinning. `renderRowDetails(row, index)` is called only for expanded, mounted rows; `expandedRows` contains stable row keys. `renderRowActions` adds an isolated actions cell (`rowActionsWidth` defaults to 120px). Enable `rowNumbers` and `densityToggle` as needed.
+
+For a remote table, supply only the current page and control the state used by your data client:
+
+```tsx
+import { useState } from "react";
+import { DataTable, type DataTablePagination, type DataTableSort } from "@neo-ui-kit/react";
+
+type Person = { id: string; name: string };
+const columns = [{ key: "name", title: "Name" }];
+
+export function PeopleTable({ rows, total, loading }: { rows: Person[]; total: number; loading: boolean }) {
+  const [query, setQuery] = useState("");
+  const [sorting, setSorting] = useState<DataTableSort[]>([]);
+  const [pagination, setPagination] = useState<DataTablePagination>({ pageIndex: 0, pageSize: 25 });
+  // Your data client loads rows for query, sorting and pagination; cancel stale requests there.
+  return <DataTable columns={columns} rows={rows} rowCount={total} loading={loading}
+    searchable query={query} onQueryChange={setQuery}
+    sorting={sorting} onSortingChange={setSorting}
+    pagination={pagination} onPaginationChange={setPagination}
+    manualFiltering manualSorting manualPagination />;
+}
+```
+
+Manual flags are independent: the table does not fetch data and does not re-filter, re-sort or re-slice the corresponding server results. Provide `rowCount` for exact remote page counts. Without it, remote pagination keeps the current page and offers Next while the received page is full. Selection keys survive changing remote pages. Column filters search the complete distinct-value set before offering up to 100 suggestions; the actual row filter is not capped.
+
+For an unpaginated large dataset use `virtualize maxHeight={480}`. The table mounts a viewport-sized range plus `overscan`, measures variable row/detail heights, and keeps a scrollable table on narrow screens rather than converting virtual rows into cards. Pinned tables also keep their horizontal table layout on narrow screens. `estimatedRowHeight` is the initial estimate, not a fixed-height restriction. Small paginated tables do not need virtualization. Stable row keys are important for measured heights, details and selection.
+
+## Responsiveness
+
+The package pauses decorative work outside the viewport and in hidden tabs. Its shared motion clock stops when no visible work remains; consumers do not need a separate animation scheduler. Playback updates are isolated from transport and volume controls. Audio analysis and loader image processing yield between short CPU work slices, and unmounting cancels stale results. Processed loader images are capped at 2048px on the longest side; turning background removal off restores the original upload.
+
+Router updates are immediate by default. Opt into native snapshot transitions with `transition` only when their temporary interruption of pointer interaction suits your screen; normal CSS entrances do not require it.
+
+Animated border geometry is initialized and resized in small batches on the shared clock, only while visible. Light positions use the cached contour instead of querying SVG geometry on every frame. Offscreen borders keep their light position without measuring layout or advancing the effect.
+
+Keep `rows`, `columns`, `options`, and `initialValues` immutable: replace them when their contents change. Stable references allow expensive derived results to be reused across selection, navigation, and other local UI changes. Do not memoize every prop automatically.
+
+For large tables, use `pageSize` or opt into `virtualize` to bound mounted rows. Virtualization bounds rendering, not the cost of client-side sorting/filtering: use the manual server contracts for datasets that are too large to process locally. Open Select/Autocomplete lists are not virtualized: filter very large datasets before supplying options. `PeoplePicker.onSearch(query, signal)` receives an optional `AbortSignal`; forward it to your data client to cancel superseded requests. Expensive custom renderers, validators, and aggregates still need their own work budget.
+
+## Entry points
+
+```ts
+import { Button, Card, Dialog, AudioPlayer } from "@neo-ui-kit/react";
+import { PianoRoll } from "@neo-ui-kit/react/editor";
+import { Router } from "@neo-ui-kit/react/router";
+import { Form, FormFields, useForm } from "@neo-ui-kit/react/forms";
+import { ThemeProvider, useMotion } from "@neo-ui-kit/react/core";
+```
+
+## 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.0.1 release notes
+
+- Clarifies npm installation and documents GitHub Actions trusted publishing through OIDC.
+- Corrects the documented DataTable `rowActionsWidth` default to 120px.
+- Runtime code is unchanged from 1.0.0.
+
+## 1.0.0 hardening notes
+
+Version 1.0.0 is the new NEO UI starting point. Rebuild the local archive after changing source files.
+
+- React 18 element refs now reach their public DOM targets. Controlled fields and RotaryKnob keep the supplied value until their owner accepts a change.
+- Nested layers close in order with Escape. Dialog restores focus, discards obsolete async confirmations, and keeps actions available in narrow containers.
+- Fields preserve explicit accessible names and descriptions. Select applies `style` / `className` to its layout wrapper and `id` / `data-*` to its trigger; text fields target their native input. Compound pickers retain their existing outer `id` / `data-*` location.
+- Select and ColorPicker button names include their rendered value or placeholder after the field label, including explicit `aria-label` / `aria-labelledby`. Exact accessible-name queries should include that value; external label references retain priority over `aria-label`.
+- AnimatedBorder follows independent elliptical corner radii, resizes without repeated contour work, resumes after motion preference changes, and does not enlarge scroll geometry. Visible borders follow the shared animation cadence; this improves smoothness at a higher CPU cost than the previous 10fps idle path.
+- Border overlays and moving lights share the exact border box, including fractional sizes, asymmetric borders, scrolling and transforms.
+- DataTable fills its container with pinned columns, keeps sorting/filtering/select-all visible in its narrow card layout, and resets density and details with the rest of the view. The default row-actions width is now 120px (previously 96px); set `rowActionsWidth` explicitly to retain a custom layout.
+- Icon and Loader accept `xs`, `sm`, `md`, `lg` alongside their existing numeric/CSS-length sizes. RotaryKnob fits narrow containers throughout rotation; documentation uses named size presets and NumberField for numeric parameters.
+- Badge text follows the theme foreground for readable status labels in light and dark schemes. StatusIndicator's offline text rule is scoped to that component.
+- `AudioPlayer.onVolumeChange` is additive. Pair it with `volume` when an external audio engine owns playback.
+- Explicit empty Waveform/Sparkline arrays now render empty data. Omit the data prop if you want the demonstration shape.
+- PianoRoll cancellation reports zero offsets before `onNoteDragEnd`. Apply offsets relative to the gesture start to restore a cancelled edit.
+- SplitButton `items` now uses the Menu item contract. Invalid item shapes that slipped through the previous `any[]` type must be corrected.
+- The root entry exports `FormProps` and `FormFieldsProps`. Artwork declarations work without `resolveJsonModule` or `skipLibCheck` in the consuming app.
+
+Repository evidence, browser runners, before/after measurements and coverage limits are recorded in `evidence/`. Unit and renderer checks complement actual browser geometry and interaction checks; they do not certify untested physical devices or browser engines.
+
+## Quantum Field experience
+
+`QuantumFieldExperience` restores the full Quantum Fields visualizer inside an iframe. A compact, transparent field sits above the kit's `FilePicker`, externally controlled `AudioPlayer`, tooltip-labelled microphone/screenshot/fullscreen actions, field selector, and sensitivity control. The selected song name appears on the file button; playback and seeking use the visualizer's single audio source. Other controls live in a closed-by-default “Тонкая настройка” section below the field. It follows the nearest `ThemeProvider` palette. This experience includes MIT-licensed upstream code and CDN-loaded Three.js modules; the upstream notice is shipped as `UPSTREAM-LICENSE.txt`. It is not mounted in overview-card previews. For a smaller self-authored field without transport controls, use `QuantumField` directly.

package/dist/artwork/icons.json.d.ts

@@ -0,0 +1,2 @@
+declare const assets: Record<"back" | "close" | "plus" | "minus" | "check" | "chevron" | "play" | "pause" | "music" | "document" | "wave" | "grid" | "cursor" | "pencil" | "eraser" | "scissors" | "mouse" | "volume" | "search" | "more" | "sliders" | "settings" | "fit" | "save" | "undo" | "redo" | "bulb" | "window" | "folder" | "upload" | "download" | "reset" | "info" | "copy" | "clock" | "warning" | "processing" | "stop" | "up" | "down" | "trash" | "database" | "refresh" | "motion" | "cloud-gpu" | "antenna" | "rocket" | "login" | "braces" | "ok" | "stopwatch" | "levels" | "mic" | "headphones" | "gauge" | "gear" | "palette" | "audio" | "chip" | "key" | "wrench" | "photo" | "eye" | "migrate" | "radio" | "heart" | "history" | "cube" | "file" | "list" | "stethoscope" | "crown" | "person" | "signal" | "leave" | "prev" | "sparkle" | "studio" | "note" | "rhythm" | "timer" | "target" | "user" | "users", import("../core/base").VectorNode>;
+export default assets;

package/dist/artwork/illustrations.json.d.ts

@@ -0,0 +1,2 @@
+declare const assets: Record<"planet" | "mountains" | "city" | "silk" | "horizon" | "landscape" | "brand" | "database" | "host" | "server" | "microphone", import("../core/base").VectorNode>;
+export default assets;

package/dist/chunks/chunk-347P6ZE4.js

@@ -0,0 +1,104 @@
+import {
+  motionEnabled
+} from "./chunk-FCOU3ODR.js";
+
+// src/components/navigation/Router/Router.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import { flushSync } from "react-dom";
+import { Fragment, jsx } from "react/jsx-runtime";
+var Context = createContext(null);
+var clean = (v) => {
+  const x = `/${v.replace(/^#?\/?/, "").replace(/\/+$/g, "")}`;
+  return x === "/" ? x : x.replace(/\/$/, "");
+};
+var current = (m) => clean(m === "hash" ? location.hash.slice(1) || "/" : location.pathname);
+var morph = (update, transition) => transition && motionEnabled() && "startViewTransition" in document ? void document.startViewTransition(() => flushSync(update)) : update();
+function matchPath(pattern, pathname) {
+  const p = clean(pattern).split("/").filter(Boolean), v = clean(pathname).split("/").filter(Boolean), params = /* @__PURE__ */ Object.create(null);
+  for (let i = 0, j = 0; i < p.length; i++, j++) {
+    const token = p[i];
+    if (token === "*") {
+      try {
+        params["*"] = decodeURIComponent(v.slice(j).join("/"));
+      } catch {
+        return null;
+      }
+      return params;
+    }
+    if (j >= v.length) return null;
+    if (token.startsWith(":")) {
+      try {
+        params[token.slice(1)] = decodeURIComponent(v[j]);
+      } catch {
+        return null;
+      }
+    } else if (token !== v[j]) return null;
+  }
+  return p.at(-1) === "*" || p.length === v.length ? params : null;
+}
+function matchRoute(routes, pathname) {
+  for (const route of routes) {
+    const params = matchPath(route.path, pathname);
+    if (params) return { route, pathname: clean(pathname), params };
+  }
+  return null;
+}
+function Router({
+  routes,
+  fallback = null,
+  context,
+  mode = "hash",
+  transition = false
+}) {
+  const [pathname, setPathname] = useState(() => current(mode));
+  useEffect(() => {
+    setPathname(current(mode));
+  }, [mode]);
+  useEffect(() => {
+    const event = mode === "hash" ? "hashchange" : "popstate", sync = () => morph(() => setPathname(current(mode)), transition);
+    window.addEventListener(event, sync);
+    return () => window.removeEventListener(event, sync);
+  }, [mode, transition]);
+  const match = useMemo(() => matchRoute(routes, pathname), [routes, pathname]);
+  const navigate = (to, replace = false) => {
+    const path = clean(to);
+    if (mode === "hash") {
+      const hash = `#${path}`;
+      if (replace) {
+        history.replaceState(null, "", hash);
+        setPathname(path);
+      } else location.hash = path;
+    } else {
+      history[replace ? "replaceState" : "pushState"](null, "", path);
+      morph(() => setPathname(current(mode)), transition);
+    }
+  };
+  useEffect(() => {
+    if (match?.route.redirectTo) navigate(match.route.redirectTo, true);
+  }, [match?.route.redirectTo]);
+  if (!match) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  if (match.route.redirectTo) return null;
+  const value = { ...match, navigate }, allowed = match.route.access?.({
+    pathname: match.pathname,
+    params: match.params,
+    context
+  }) ?? true, content = allowed ? match.route.element : match.route.denied;
+  return /* @__PURE__ */ jsx(Context.Provider, { value, children: typeof content === "function" ? content(match) : content ?? fallback });
+}
+function useRouter() {
+  const value = useContext(Context);
+  if (!value) throw new Error("useRouter must be used inside <Router>");
+  return value;
+}
+
+export {
+  matchRoute,
+  Router,
+  useRouter
+};