{"_id":"@bluefission/reactor","name":"@bluefission/reactor","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bluefission/reactor","version":"0.1.0","description":"Frontend primitives, bindings, and browser adapters for Blue Fission applications.","type":"module","main":"./src/index.js","module":"./src/index.js","exports":{".":"./src/index.js","./primitives":"./src/core/primitives.js","./response":"./src/core/response.js","./transport":"./src/core/transport.js","./module":"./src/core/module.js","./binding-contract":"./src/core/binding-contract.js","./surface-contract":"./src/ui/surface-contract.js","./signals":"./src/core/signals.js","./dom":"./src/dom/binder.js","./dashboard-shell":"./src/ui/dashboard-shell.js","./dialogs":"./src/ui/dialogs.js","./table-list":"./src/ui/table-list.js","./forms":"./src/ui/forms.js","./notifications":"./src/ui/notifications.js","./socket":"./src/browser/socket.js","./html":"./src/html/helpers.js","./html.css":"./src/html/theme.css","./jquery":"./src/adapters/jquery.js","./bluefission":"./src/adapters/bluefission.js","./resource-crud":"./src/adapters/resource-crud.js"},"scripts":{"check":"node --check src/index.js","test":"node --test","verify:release":"node tools/verify-release.js","prepublishOnly":"npm test && npm run check && npm run verify:release"},"keywords":["bluefission","develation","frontend","jquery","dashboard","bluecore"],"author":{"name":"Blue Fission Technology"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/BlueFissionTech/reactor.git"},"homepage":"https://github.com/BlueFissionTech/reactor#readme","bugs":{"url":"https://github.com/BlueFissionTech/reactor/issues"},"publishConfig":{"access":"public"},"gitHead":"ea28923b6157a40d5764b28c2950d917a02dd642","_id":"@bluefission/reactor@0.1.0","_nodeVersion":"24.19.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-bGrVVr0aPf8jsYpyH5B6PYSgHVz3tAfEPzHsn700pCnIdGlXk4TpNU1/OBQ5ebUwTcsDAMxd4rtueo5x/XUH8Q==","shasum":"9eb698116a61c45394b01cb660740f30eb66f4e7","tarball":"https://registry.npmjs.org/@bluefission/reactor/-/reactor-0.1.0.tgz","fileCount":54,"unpackedSize":254455,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bluefission%2freactor@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCTqWI+p9+4n4r1zZTw4rLU1eHxwzqvK1SxGo7Xp5g0PgIgbaJdgMpBxuznSTWL2uHZk14yQp1c2svJql8Rg1+ZZIg="}]},"_npmUser":{"name":"bluefissiontech","email":"programming@bluefission.com"},"directories":{},"maintainers":[{"name":"bluefissiontech","email":"programming@bluefission.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reactor_0.1.0_1787438778874_0.5266214573813801"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-22T22:46:18.700Z","0.1.0":"2026-08-22T22:46:19.005Z","modified":"2026-08-22T22:46:19.420Z"},"maintainers":[{"name":"bluefissiontech","email":"programming@bluefission.com"}],"description":"Frontend primitives, bindings, and browser adapters for Blue Fission applications.","homepage":"https://github.com/BlueFissionTech/reactor#readme","keywords":["bluefission","develation","frontend","jquery","dashboard","bluecore"],"repository":{"type":"git","url":"git+https://github.com/BlueFissionTech/reactor.git"},"author":{"name":"Blue Fission Technology"},"bugs":{"url":"https://github.com/BlueFissionTech/reactor/issues"},"license":"MIT","readme":"# Reactor\n\nReactor is the shared frontend foundation for Blue Fission applications and compatible browser projects.\n\nIt exists to replace copied, project-local JavaScript with a package that has a clear API, a stable mental model, and a practical migration path from current Blue Fission frontend code. Today that means supporting legacy jQuery-heavy screens while moving reusable behavior into framework-agnostic primitives.\n\n## What Reactor is\n\nReactor is a small frontend library for:\n\n- normalizing Blue Fission response payloads\n- calling backend APIs with a reusable transport and CRUD layer\n- expressing request and response flows with DevElation-style service objects\n- managing module lifecycle for admin and dashboard screens\n- modeling evented state and record collections without locking into one framework\n- binding lightweight reactive state to the DOM\n- rehoming legacy helpers such as templates, record sets, panels, and portlets\n- bridging current jQuery-first applications into a more structured architecture\n\n## What Reactor is not\n\nReactor is not trying to be:\n\n- a full UI framework\n- a complete replacement for every current dashboard widget\n- a forced rewrite away from jQuery\n- a compiled frontend runtime with heavy build requirements\n\nThe point is to centralize the stable patterns first, then modernize the rest from a safer base.\n\n## Why this repository exists\n\nRight now, Blue Fission frontend behavior is split across several places:\n\n- reusable utility code in existing internal frontend modules\n- app-level modules in `framework/resource/src/js/modules/app`\n- dashboard behavior in `framework/resource/src/js/modules/dashboard-ui`\n- project-specific copies and forks\n\nThose codebases share the same ideas:\n\n- CRUD API wrappers\n- response parsing\n- reactive record state\n- dashboard module bootstrapping\n- jQuery event wiring\n- screen swapping and notices\n\nThey just do it inconsistently. Reactor is the consolidation layer for those ideas.\n\n## Current documentation quality\n\nAt the moment, Reactor is reasonably documented for architecture and intent, but still early in operational guidance.\n\nIt already has:\n\n- a library-level overview in this file\n- scope and acceptance criteria in `SPEC.md`\n- a system view in `ARCHITECTURE.md`\n- a roadmap in `ROADMAP.md`\n- migration notes for legacy module composition\n\nIt was missing:\n\n- a better explanation of how the pieces fit together\n- a clear quick-start path\n- a public API reference\n- a stronger voice about what the library is trying to become\n\nThis README and the supporting docs are meant to close that gap.\n\n## The Reactor mental model\n\nReactor is organized around three layers:\n\n1. Core primitives\n   Primitive helpers, response normalization, transport, state, and module lifecycle.\n2. Browser binding\n   Small DOM helpers for simple reactive behavior without introducing a full renderer.\n3. Adapters\n   Compatibility layers for Blue Fission conventions, jQuery-heavy screens, and extracted legacy patterns.\n\nThat separation matters. It lets us keep legacy integration support without hard-coding legacy assumptions into the permanent center of the library.\n\n## Package surface\n\nThe current public surface is:\n\n- `src/core/response.js`\n  `normalizeResponse`, `BlueFissionResponse`\n- `src/core/primitives.js`\n  `Value`, `Arr`, `Obj`, `Str`, `Num`, `Primitive`, `toList`, `getPath`, `setPath`, `joinClassNames`, `toNumber`, and related value helpers\n- `src/core/transport.js`\n  `createTransport`, `createResource`, `createResourceFromDefinition`, `createResourceRegistry`\n- `src/core/signals.js`\n  `Signal`, `createSignal`, `computed`\n- `src/core/module.js`\n  `createModule`, `createModuleManager`\n- `src/core/binding-contract.js`\n  `createBindingContract`, `createBindingManifest`\n- `src/core/behavior.js`\n  `Events`, `States`, `BehavioralObject`, `createBehavioralObject`\n- `src/dom/binder.js`\n  `select`, `selectAll`, `bindText`, `bindValue`, `interpolate`, `on`\n- `src/dom/framework.js`\n  legacy-compatible `El`, `get`, `set`, `assign`, `create`\n- `src/dom/template.js`\n  lightweight selector-based template rendering\n- `src/net/http.js`\n  `HttpRequest`, `HttpResponse`, `createHttpClient`\n- `src/services/service.js`\n  `createGateway`, `createServiceClient`\n- `src/data/record-set.js`\n  `RecordSet`, `createRecordSet`\n- `src/ui/panels.js`\n  `createPanelRegistry`\n- `src/ui/dashboard-shell.js`\n  `createDashboardShell`, `normalizeRoute`\n- `src/ui/forms.js`\n  `FormStatus`, `createFormController`, `serializeFormInput`, `normalizeFormErrors`\n- `src/ui/surface-contract.js`\n  `SurfaceFamilies`, `SurfaceUpdateSources`, `createSurfaceContract`, `createSurfaceManifest`, `createSurfacePulse`\n- `src/ui/portlet.js`\n  `createPortletController`\n- `src/html/helpers.js`\n  `escapeHtml`, `renderHtml`, `renderHtmlPage`, `HtmlThemeClasses`, `renderElement`, `renderTable`, `renderForm`, `renderFormField`, `renderXml`, and small HTML utility helpers\n- `src/adapters/jquery.js`\n  `createJQueryBridge`, `createJQueryNotifier`\n- `src/adapters/bluefission.js`\n  `createBlueFissionApi`, `createBlueFissionApp`\n- `src/adapters/resource-crud.js`\n  `createRecordModel`, `createCrudPanelModule`\n- `src/browser/activity.js`\n  `createActivityTracker`\n- `src/browser/socket.js`\n  `SocketStates`, `createSocketClient`\n\n## Quick start\n\nThe package manifest is fixed at `0.1.0`. Once that version is available from the configured npm registry, consume it with an exact constraint:\n\n```bash\nnpm install --save-exact @bluefission/reactor@0.1.0\n```\n\nThen build an app with explicit resources and state:\n\n```js\nimport {\n  createBlueFissionApp,\n  createSignal,\n  bindText,\n  bindValue\n} from \"@bluefission/reactor\";\n\nconst app = createBlueFissionApp({\n  apiBaseUrl: \"/api\",\n  resources: {\n    user: \"users\",\n    report: \"reports\"\n  }\n});\n\nconst message = createSignal(\"Loading...\");\n\nbindText(\"[data-role='message']\", message);\nbindValue(\"[name='message']\", message);\n\napp.resources.user.read(1).then((response) => {\n  message.value = response.data.realname;\n});\n```\n\nFor direct browser usage inside internal repos, ESM imports also work:\n\n```html\n<script type=\"module\">\n  import { createBlueFissionApp } from \"./src/index.js\";\n\n  const app = createBlueFissionApp({\n    apiBaseUrl: \"/api\"\n  });\n\n  window.app = app;\n</script>\n```\n\n## Extracted CRUD Pattern\n\nOne concrete compatibility adapter in Reactor is a repeated CRUD admin panel flow.\n\nThat adapter captures the recurring shape used by many internal screens:\n\n- a reactive record model\n- listing and edit screens\n- read, save, and delete actions\n- jQuery event handling through a bridge\n- optional DataTables reload behavior\n- shared success and error notices\n\nRelevant files:\n\n- `src/adapters/resource-crud.js`\n- `examples/crud-panel-module.js`\n- `docs/legacy-crud-migration.md`\n\n## General Module Composition\n\nReactor supports a general module composition pattern through:\n\n- action-aware resource definitions on `createBlueFissionApi` and `createBlueFissionApp`\n- legacy-style `app.get`, `app.set`, `app.assign`, and `app.computed` helpers\n- `RecordSet` for list-oriented state\n- `createPanelRegistry` for panel bootstrapping\n- `createPortletController` for portlet collapse and removal behavior\n- `Template` for selector-addressed render-and-swap flows\n\nRelevant files:\n\n- `examples/primitives.js`\n- `examples/resource-workspace.js`\n- `docs/primitives.md`\n- `docs/module-composition.md`\n- `docs/develation-alignment.md`\n- `docs/develation-integration.md`\n\n## Primitive Helpers\n\nReactor exposes first-class primitive helpers for JavaScript-side value, list, object, string, and number normalization:\n\n```js\nimport { Obj, Arr, Num, Str } from \"@bluefission/reactor\";\n\nconst query = {\n  page: Num.toInteger(input.page, 1, { min: 1 }),\n  tags: Arr.toList(input.tags, { split: true }),\n  owner: Obj.getPath(input, \"record.owner.name\", \"Unknown\"),\n  className: Str.joinClassNames(\"resource-row\", input.active && \"is-active\")\n};\n```\n\nThese helpers are aligned with DevElation's upstream primitive vocabulary without becoming a browser-side clone of the PHP classes. The goal is consistent input normalization and mutation-free object access across Reactor modules.\n\n## HTML Helper Compatibility\n\nThe HTML helper group is intentionally small, but it now represents the reusable concepts from the upstream HTML utilities:\n\n- text formatting, href/base href normalization, images, files, pagination, result tables, lists, and bar graphs\n- form open/close, fields, dropdowns, date splitting/joining, and validation metadata\n- table rendering from row data\n- template/runtime output normalization through `renderHtml(...)`\n- XML-like node rebuilding through `renderXml(...)`\n\n`renderHtml(...)` accepts rendered strings as-is so output from parsing and runtime readers, including Vibrato `Reader::output()`, can be passed directly. Structured payloads can also use `html`, `output`, `rendered`, `renderedOutput`, `rendered_output`, `markdown`, `text`, `records`, `rows`, `fields`, `items`, `nodes`, `fragments`, `blocks`, or `children`.\n\nFor text safety, use `{ text: value }`, table rows, and form field values; those are escaped by default. Use `{ html: value }` only when the caller owns the trust boundary.\n\nFor a consistent optional baseline stylesheet, import `@bluefission/reactor/html.css` and wrap generated fragments with `renderHtmlPage(...)` or a root element using `class=\"bf-reactor-html\"`. The stylesheet is intentionally scoped to that root and `bf-rx-*` helper classes, so it can coexist with app, framework, or platform CSS without acting as a global reset.\n\n```js\nimport \"@bluefission/reactor/html.css\";\nimport { renderHtmlPage, renderResults } from \"@bluefission/reactor\";\n\nconst page = renderHtmlPage(renderResults(records), {\n  title: \"Resource index\",\n  density: \"compact\"\n});\n```\n\nRelevant files:\n\n- `examples/html-output-contracts.js`\n- `examples/develation-integration.js`\n- `src/html/theme.css`\n- `docs/api-reference.md`\n- `docs/develation-alignment.md`\n- `docs/develation-integration.md`\n\n## Legacy script coverage\n\nI also checked older shared script patterns and pulled reusable concepts into Reactor:\n\n- `framework.js`\n  now represented by `src/dom/framework.js`\n- `template.js`\n  now represented by `src/dom/template.js`\n- `activity.js`\n  now represented by `src/browser/activity.js`\n- `websocket.js`\n  now represented by `src/browser/socket.js`\n\nThese are compatibility-minded rehomes, not fragile line-for-line copies.\n\n## Design stance\n\nReactor is deliberately pragmatic:\n\n- jQuery support stays available because current products need it\n- jQuery is treated as an adapter, not the permanent core\n- npm installation is preferred, but direct inclusion remains possible\n- exact version constraints are preferred for production adoption\n- backend compatibility matters more than frontend fashion\n- migration is favored over rewrite theater\n\nThis is a platform library. Its value is not novelty. Its value is reducing drift across projects while giving us a cleaner path forward.\n\nReactor is a public MIT-licensed companion to DevElation for JavaScript and browser-facing concerns.\n\n## License\n\nReactor is available under the MIT License. See `LICENSE`.\n\n## Document map\n\n- `README.md`\n  project overview and usage entry point\n- `docs/getting-started.md`\n  first practical steps and composition patterns\n- `docs/socket-lifecycle.md`\n  authenticated bootstrap, reconnect, heartbeat, queue, ordering, and teardown contracts\n- `docs/releasing.md`\n  public npm publication, trusted publishing, provenance, and versioning workflow\n- `docs/api-reference.md`\n  current public API summary\n- `docs/module-composition.md`\n  general composition guidance for resources, records, panels, and optional compatibility adapters\n- `docs/primitives.md`\n  first-class value, list, object, string, and number helper contracts\n- `docs/binding-contracts.md`\n  reusable frontend binding contract shape and ownership boundaries\n- `docs/surface-contracts.md`\n  reusable rich-surface component, state, event, and pulse contract shape\n- `docs/dialog-flows.md`\n  modal and confirmation request/result contracts\n- `docs/table-list-adapters.md`\n  table/list query, row lookup, refresh, loading, and selection contracts\n- `docs/notification-adapters.md`\n  normalized notification payload and dispatch conventions\n- `docs/develation-alignment.md`\n  how Reactor aligns with DevElation service, net, html, and object patterns\n- `docs/develation-integration.md`\n  practical DevElation service, parser, HTML, XML, and object integration examples\n- `docs/legacy-script-coverage.md`\n  mapping from the original `scripts` utilities to Reactor equivalents\n- `docs/dashboard-ui-interop.md`\n  status of legacy `dashboard-ui` features and how they relate to jQuery\n- `docs/dashboard-utility-map.md`\n  method-level ownership map for legacy dashboard utility extraction\n- `docs/legacy-crud-migration.md`\n  compatibility notes for older CRUD-oriented module patterns\n- `docs/crud-validation.md`\n  validation notes for the extracted CRUD adapter and its remaining general gaps\n- `SPEC.md`\n  product scope, users, and acceptance criteria\n- `ARCHITECTURE.md`\n  structural and layering decisions\n- `ROADMAP.md`\n  near-term and long-term direction\n\n## Current status\n\nReactor is in its foundation phase.\n\nIt now has:\n\n- a coherent package structure\n- first-class primitive helper exports for consistent normalization\n- a documented architectural direction\n- a Blue Fission-oriented transport and app bootstrap layer\n- a DevElation-aligned request, response, and gateway layer\n- evented object and record-set primitives for legacy dashboard migrations\n- a lightweight signal and DOM binding model\n- an extracted CRUD panel adapter\n- dashboard shell, form helper, surface contract, and CRUD adapter coverage\n- baseline automated tests for response normalization, service gateways, evented objects, and Blue Fission API bootstrap\n\nIt still needs:\n\n- broader automated coverage for DOM helpers, templates, record sets, and UI adapters\n- reusable table, modal, and notification adapter slices\n- method-level dashboard interop mapping for the remaining legacy utility surface\n\nThose items are intentionally tracked as follow-up work rather than hidden as vague future intent.\n","readmeFilename":"README.md","_rev":"1-fdea3fb82a26259b78c7e51f6fb1001c"}