activeadmin-react 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92cba0113794ff8883e09e5bf1cfad4b498c705bf97fdabcf2c461c2d320e04c
+  data.tar.gz: 54dbdaed377bcd530612b4077ad9364b167b7a268438b09d8d038ff15d798052
+SHA512:
+  metadata.gz: 3aead5075fda511f7d0ce83ae644860eb2831432c93c99aeab3a68b5b8c07d513049237d1826db73b2bd79971d45845db449e4a113f09d874e8d709893ce95ee
+  data.tar.gz: dff36285667c02f65f3a52fe0f24ef0f52a5428e8be2640dd142f837b4cb42b4eeb799a3f7a18e119ea4a49c0c3c9ccda73bd16054b1ad6f5d18f157a1b2c87c

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+<!-- CHANGELOG.md -->
+
+# Changelog
+
+All notable changes to ActiveAdmin React are recorded here. During ordinary pre-1.0 development, PATCH releases contain fixes and small compatible improvements; MINOR releases may contain new capabilities, meaningful API evolution, and documented breaking changes.
+
+## 0.1.0.alpha1 — 2026-09-05
+
+First integrated prerelease for Rodeo dogfooding. Public Ruby and JavaScript contracts
+remain unstable during the 0.x line. This alpha includes the capabilities below and
+real Chromium coverage for engine rendering, Turbo cleanup/remount, server fallbacks,
+and live Action Cable reconnect/replay. Supported runtime dependencies are Ruby >= 3.2,
+Rails >= 8.0 and < 9, and ActiveAdmin >= 4.0.0.beta22 and < 5; React 18/19 is supplied
+by the host.
+
+### Added
+
+- Arbre-native `react_component` islands with deterministic markup, JSON-safe props, caller-owned HTML attributes, and server-rendered fallback content.
+- A build-tool-neutral React 18/19 runtime with explicit component registration, multiple islands per page, Turbo lifecycle cleanup, and duplicate-registration protection.
+- A validated Action Cable operation protocol with reconnect replay, duplicate and out-of-order suppression, terminal states, authenticated cancellation commands, and accessible status attributes.
+- Explicit Rails engine contribution contracts with ownership, namespaces, surfaces, deterministic diagnostics, collision errors, and RBS signatures.
+- An ActiveAdmin 4 dummy host, focused local validation commands, independent CI quality gates, packaged JavaScript and RBS files, and clean-install package verification.
+
+### Security
+
+- Props reject unsupported objects and non-finite floats instead of serializing arbitrary values.
+- Mount points reserve their runtime data attributes and render no inline JavaScript.
+- Action Cable examples keep user and tenant authorization on the server, and cancellation uses same-origin requests with Rails CSRF tokens.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Stan Carver II
+
+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.

data/README.md

@@ -0,0 +1,203 @@
+<!-- README.md -->
+
+# ActiveAdmin React
+
+React islands for ActiveAdmin, with an Arbre-native Ruby API and optional asynchronous integrations.
+
+ActiveAdmin React keeps administrative pages Rails-first and server-rendered while making React available for interactions that benefit from a client-side component. The project is on the ordinary pre-1.0 `0.x` line, so documented breaking changes may ship in a MINOR release while Rodeo dogfooding helps stabilize the public contracts.
+
+## Installation and compatibility
+
+Add the gem to a Rails application that uses ActiveAdmin:
+
+```ruby
+gem "activeadmin-react", "0.1.0.alpha1", require: "active_admin/react"
+```
+
+Then run `bundle install`. The gem requires Ruby 3.2 or newer, Rails 8.x, and ActiveAdmin `4.0.0.beta22` or newer within the 4.x line. The JavaScript runtime uses the React 18/19 `createRoot` API; the host supplies `react` and `react-dom` and remains responsible for compiling and serving browser assets.
+
+## Render an island from Arbre
+
+The `react_component` helper is available inside ActiveAdmin's Arbre DSL:
+
+```ruby
+ActiveAdmin.register Order do
+  show do
+    panel "Order activity" do
+      react_component(
+        "OrdersTable",
+        props: { order_id: resource.id },
+        fallback: -> { "Order activity is available without JavaScript." },
+        class: "orders-table"
+      )
+    end
+  end
+end
+```
+
+Props may contain `nil`, booleans, strings, integers, finite floats, symbols, dates, times, arrays, and hashes with string or symbol keys. Symbols become strings and date/time values become ISO 8601 strings. Unsupported values, non-finite floats, invalid component names, and malformed `data` attributes raise `ArgumentError` before markup is rendered.
+
+The mount owns the `data-react-component` and `data-react-props` attributes. Other HTML and data attributes remain caller-owned. A callable fallback receives polite `status` semantics by default and stays in the page until React mounts successfully.
+
+## Register and start components
+
+The packaged JavaScript entrypoint is `app/javascript/active_admin/react/index.js`. Configure the host's Vite, esbuild, or equivalent resolver so `active_admin/react` points to that file inside the installed gem. For example, Vite can derive the gem root with `bundle show activeadmin-react`:
+
+```js
+import { execFileSync } from "node:child_process"
+import { resolve } from "node:path"
+import { defineConfig } from "vite"
+
+const gemRoot = execFileSync("bundle", ["show", "activeadmin-react"], {
+  encoding: "utf8"
+}).trim()
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "active_admin/react": resolve(gemRoot, "app/javascript/active_admin/react/index.js")
+    }
+  }
+})
+```
+
+Register every component before starting the runtime:
+
+```js
+import { registerComponent, start } from "active_admin/react"
+import OrdersTable from "./components/OrdersTable"
+
+registerComponent("OrdersTable", OrdersTable)
+start()
+```
+
+`start()` mounts every `[data-react-component]` island, mounts newly rendered pages after `turbo:load`, and unmounts roots before Turbo caches the page. Repeated calls are safe. `stop()` removes the Turbo listeners and unmounts tracked roots. Duplicate component names, unknown components, and malformed JSON props fail loudly.
+
+The shipped modules use package-style relative imports intended for a JavaScript build tool. Copying the directory directly into an importmap or serving it to browsers without a resolver is not currently a supported integration path.
+
+## Engine contributions
+
+Requiring `active_admin/react` does not scan Rails engines, eager-load models, or require third-party adapters. An engine exposes a small adapter and the host installs it explicitly:
+
+```ruby
+module CommerceEngine
+  module ActiveAdminReact
+    module_function
+
+    def install!
+      ActiveAdmin::React::Contributions.register(
+        "OrdersTable",
+        namespace: "commerce.admin",
+        owner: "CommerceEngine",
+        source: "commerce_engine/active_admin_react",
+        surfaces: %i[component page],
+        description: "Interactive order review"
+      )
+    end
+  end
+end
+```
+
+`name`, `namespace`, `owner`, and `source` are required. `surfaces` defaults to `[:component]`; additional keywords become diagnostic metadata. Component names are globally unique. Conflicts identify both owners, namespaces, and sources.
+
+`ActiveAdmin::React::Contributions.diagnostics` returns entries sorted by namespace, component name, and owner. An installer can query `ActiveAdmin::React::Contributions.registry.registered?("OrdersTable")` before registering inside a reload hook. `ActiveAdmin::React::Contributions.reset!` creates a fresh registry for test isolation. Metadata hashes, arrays, sets, and strings are recursively copied and frozen during registration, so later changes to caller-owned values cannot alter registered state and diagnostics cannot mutate it. Other metadata values must be immutable objects supplied by the contributor.
+
+## Asynchronous Action Cable operations
+
+Action Cable transports operation state; application jobs and services own the expensive work. Each event uses a server-owned operation identifier, idempotency key, and monotonic sequence:
+
+```json
+{
+  "operation_id": "report-123",
+  "idempotency_key": "report-123:7",
+  "sequence": 7,
+  "state": "running",
+  "progress": 60,
+  "message": "Rendering pages",
+  "result": null,
+  "result_metadata": null,
+  "error": null,
+  "occurred_at": "2026-09-03T18:42:00Z"
+}
+```
+
+States are `pending`, `queued`, `running`, `retrying`, `completed`, `failed`, and `cancelled`; the last three are terminal. `OperationState` ignores duplicates, out-of-order events, events for another operation, and updates after a terminal event. `subscribeToOperation` validates envelopes and resumes after the last applied sequence:
+
+```js
+import { OperationState, subscribeToOperation } from "active_admin/react"
+
+const operationState = new OperationState({ operationId })
+const subscription = subscribeToOperation({
+  consumer,
+  channel: "OperationsChannel",
+  params: { operation_id: operationId },
+  operationState,
+  onEvent: (_event, current) => setOperation(current),
+  onProtocolError: (error) => reportProtocolError(error)
+})
+
+return () => subscription.unsubscribe()
+```
+
+Use `operationAccessibility(operationState)` on the visible status container. Active work returns a polite, busy `status`; successful and cancelled work returns a polite, non-busy status; failures return an assertive `alert`.
+
+Cancellation is an authenticated application command rather than a Cable event:
+
+```js
+import { requestOperationCancellation } from "active_admin/react"
+
+await requestOperationCancellation({
+  url: `/admin/operations/${operationId}/cancel`,
+  operationId,
+  csrfToken: document.querySelector('meta[name="csrf-token"]')?.content
+})
+```
+
+The helper sends only `operation_id` with same-origin credentials. The endpoint must load and authorize the operation in the current user and tenant context before asking the owning job or service to cancel it. Channels must apply the same server-side authorization before streaming or replaying events.
+
+## CSP, CSRF, and fallbacks
+
+The gem emits no inline scripts and does not create CSP nonces. Compile and serve React assets through the host's normal CSP-aware pipeline. Keep CSRF tokens in Rails-managed forms or meta tags rather than component props. Avoid placing credentials or sensitive tenant context in props because mount data is visible in HTML.
+
+Meaningful fallback content keeps the page usable when JavaScript is disabled or an asset fails. Keep progress text visible, associate progress bars with their labels, and never communicate state through color alone.
+
+## Development and testing
+
+Install pinned runtimes and dependencies, then run the complete local quality gate:
+
+```sh
+bin/setup
+bin/test
+```
+
+Focused checks remain directly runnable:
+
+```sh
+mise exec -- bundle exec rake spec
+mise exec -- bundle exec rake rubocop
+mise exec -- bundle exec rake rbs
+mise exec -- npm run test:js
+mise exec -- bundle exec rspec spec/integration
+```
+
+`bin/test` includes the dummy ActiveAdmin 4 integration host through the full RSpec suite. `bin/package` builds the gem, verifies its contents, installs it and its dependencies into an isolated gem home, and proves Rails loads the installed copy. These validation commands never publish.
+
+Ruby APIs live under `lib/`, browser modules under `app/javascript/`, RBS signatures under `sig/`, the dummy host under `spec/dummy/`, JavaScript tests under `test/javascript/`, and maintainer documentation under `docs/`.
+
+## Troubleshooting
+
+- `Unknown React component` means the exact, case-sensitive mount name was not registered before `start()` ran.
+- Prop errors mean the Arbre call received a value outside the documented grammar. Keep credentials, tenant identifiers, and CSRF tokens out of props.
+- Duplicate registration errors identify competing engine owners and sources. Rename the component or remove the duplicate adapter.
+- Repeated mounts usually mean both the host and `start()` own Turbo lifecycle listeners. Keep one lifecycle owner and call `stop()` before replacing it.
+- Rejected Cable subscriptions belong at the server authorization boundary. Never trust client-provided user or tenant parameters.
+- Browser resolution errors usually mean the host alias does not point to the packaged `app/javascript/active_admin/react/index.js` or the build tool is not resolving relative imports.
+
+## Documentation and license
+
+See the [documentation index](docs/README.md), [release process](docs/releasing.md), [release policy](RELEASES.md), and [changelog](CHANGELOG.md). ActiveAdmin React is available under the [MIT License](LICENSE.txt). Source, issues, and pull requests live in the [GitHub repository](https://github.com/scarver2/activeadmin-react).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/RELEASES.md

@@ -0,0 +1,53 @@
+<!-- RELEASES.md -->
+
+# Release Policy
+
+ActiveAdmin React uses capability-gated Semantic Versioning. There are no calendar
+commitments: quality gates, Rodeo dogfooding, community feedback, and ActiveAdmin 4
+maturity determine when a release is ready.
+
+## Pre-1.0 versions
+
+Development uses ordinary `0.MINOR.PATCH` versions, with explicit `0.MINOR.PATCH.alphaN`
+and `0.MINOR.PATCH.betaN` prereleases when authorized. The first integrated prerelease
+is `0.1.0.alpha1`. Prerelease numbers start at 1 and have no leading zeroes.
+
+- Increment PATCH for fixes and small backward-compatible improvements.
+- Increment MINOR for new capabilities, meaningful API evolution, and documented breaking
+  changes while the public API remains unstable under Semantic Versioning's `0.y.z` rules.
+- Keep Rodeo-specific business behavior outside the gem. Rodeo dogfooding supplies the
+  primary evidence for whether generally useful contracts are ready to stabilize.
+- Track ActiveAdmin 4 closely and consider generally useful ActiveAdmin or Arbre fixes for
+  upstream contribution instead of permanent private patches.
+
+## Path to 1.0
+
+Move to `1.0.0.rc1` only when Rodeo dogfooding indicates that the Ruby API, JavaScript
+adapter protocol, security guidance, packaging, and compatibility policy are ready to
+stabilize. Publish additional candidates as `1.0.0.rcN` when needed, then publish `1.0.0`
+after only release-blocking defects remain.
+
+The stable release guarantees an Arbre-native mounting API, deterministic React lifecycle,
+documented React and ActiveAdmin compatibility, Action Cable-friendly asynchronous
+integration, engine contribution contracts, CSP/CSRF guidance, and semantic versioning for
+public APIs.
+
+## Release mechanics
+
+1. Merge the entire reviewed stack into `master`.
+2. Ensure CI is green at the exact release commit.
+3. Update `ActiveAdmin::React::VERSION` and release notes.
+4. Tag that exact commit with the matching `v0.MINOR.PATCH`, optional `.alphaN` or
+   `.betaN` suffix, or future `v1.0.0.rcN` tag. Numeric components have no leading zeroes.
+5. Let GitHub Actions publish through RubyGems Trusted Publishing and the `release`
+   environment.
+6. Verify the gem is installable and its provenance is visible on RubyGems.org.
+7. Create or complete the corresponding GitHub Release.
+
+Never publish from an unreviewed working tree or store a long-lived RubyGems API key when
+Trusted Publishing is available.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/app/javascript/active_admin/react/cable.js

@@ -0,0 +1,84 @@
+// app/javascript/active_admin/react/cable.js
+
+import { normalizeEvent, validateOperationEvent } from "./protocol"
+
+export function subscribeToOperation({
+  consumer,
+  channel,
+  params = {},
+  operationState = null,
+  strict = true,
+  resume = true,
+  onEvent,
+  onIgnoredEvent,
+  onProtocolError,
+  onConnected,
+  onDisconnected,
+  onRejected
+}) {
+  if (!consumer?.subscriptions?.create) throw new Error("consumer is required")
+  if (typeof channel !== "string" || channel.trim().length === 0) throw new Error("channel is required")
+
+  const identifier = { channel, ...params }
+  let subscription
+
+  subscription = consumer.subscriptions.create(identifier, {
+    connected() {
+      const resumeFrom = operationState?.lastSequence ?? null
+      if (resume && resumeFrom !== null && typeof subscription?.perform === "function") {
+        subscription.perform("resume", { after_sequence: resumeFrom })
+      }
+      onConnected?.({ resumeFrom })
+    },
+    disconnected(details) {
+      onDisconnected?.(details)
+    },
+    rejected() {
+      onRejected?.()
+    },
+    received(event) {
+      try {
+        const normalized = strict ? validateOperationEvent(event) : normalizeEvent(event)
+        const outcome = operationState?.applyEvent(normalized)
+        if (outcome && !outcome.applied) {
+          onIgnoredEvent?.(normalized, outcome.reason)
+          return
+        }
+        onEvent?.(normalized, outcome?.value ?? normalized)
+      } catch (error) {
+        if (onProtocolError) onProtocolError(error, event)
+        else throw error
+      }
+    }
+  })
+
+  return subscription
+}
+
+export async function requestOperationCancellation({ url, operationId, csrfToken, fetchImpl = globalThis.fetch }) {
+  if (typeof url !== "string" || url.length === 0) throw new Error("url is required")
+  if (typeof operationId !== "string" || operationId.length === 0) throw new Error("operationId is required")
+  if (typeof fetchImpl !== "function") throw new Error("fetch is required")
+
+  const headers = { Accept: "application/json", "Content-Type": "application/json" }
+  if (csrfToken) headers["X-CSRF-Token"] = csrfToken
+
+  const response = await fetchImpl(url, {
+    method: "POST",
+    credentials: "same-origin",
+    headers,
+    body: JSON.stringify({ operation_id: operationId })
+  })
+  const payload = await response.json()
+  if (!response.ok) throw new OperationCancellationError(response.status, payload)
+  return payload
+}
+
+export class OperationCancellationError extends Error {
+  constructor(status, response) {
+    super(`Operation cancellation failed with HTTP ${status}`)
+    this.name = "OperationCancellationError"
+    this.status = status
+    this.response = response
+  }
+}

data/app/javascript/active_admin/react/index.js

@@ -0,0 +1,13 @@
+// app/javascript/active_admin/react/index.js
+
+export { clearComponents, registerComponent, resolveComponent } from "./registry"
+export { mountAll, mountElement, start, stop, unmountAll, unmountElement } from "./runtime"
+export { OperationCancellationError, requestOperationCancellation, subscribeToOperation } from "./cable"
+export { OperationState, operationAccessibility } from "./operation"
+export {
+  normalizeEvent,
+  OPERATION_STATES,
+  OperationProtocolError,
+  TERMINAL_OPERATION_STATES,
+  validateOperationEvent
+} from "./protocol"

data/app/javascript/active_admin/react/operation.js

@@ -0,0 +1,73 @@
+// app/javascript/active_admin/react/operation.js
+
+import { normalizeEvent, TERMINAL_OPERATION_STATES } from "./protocol"
+
+export class OperationState {
+  constructor(initial = {}) {
+    this.value = {
+      operationId: initial.operationId ?? initial.operation_id ?? null,
+      id: initial.id ?? null,
+      idempotencyKey: initial.idempotencyKey ?? initial.idempotency_key ?? initial.id ?? null,
+      sequence: initial.sequence ?? null,
+      state: initial.state ?? "pending",
+      progress: initial.progress ?? null,
+      message: initial.message ?? null,
+      result: initial.result ?? null,
+      resultMetadata: initial.resultMetadata ?? initial.result_metadata ?? null,
+      error: initial.error ?? null,
+      occurredAt: initial.occurredAt ?? null
+    }
+    this.seen = new Set()
+    if (this.value.idempotencyKey) this.seen.add(this.value.idempotencyKey)
+  }
+
+  apply(event) {
+    return this.applyEvent(event).value
+  }
+
+  applyEvent(event) {
+    const normalized = normalizeEvent(event)
+    const key = normalized.idempotencyKey
+
+    if (key && this.seen.has(key)) return this.ignored("duplicate")
+    if (this.operationMismatch(normalized)) return this.ignored("operation_mismatch")
+    if (this.outOfOrder(normalized)) return this.ignored("out_of_order")
+    if (this.terminal()) return this.ignored("terminal")
+
+    if (key) this.seen.add(key)
+    this.value = { ...this.value, ...normalized }
+    return { applied: true, reason: null, value: this.value }
+  }
+
+  get lastSequence() {
+    return this.value.sequence
+  }
+
+  ignored(reason) {
+    return { applied: false, reason, value: this.value }
+  }
+
+  operationMismatch(event) {
+    return Boolean(this.value.operationId && event.operationId && this.value.operationId !== event.operationId)
+  }
+
+  outOfOrder(event) {
+    return event.sequence !== null && this.lastSequence !== null && event.sequence <= this.lastSequence
+  }
+
+  terminal() {
+    return TERMINAL_OPERATION_STATES.includes(this.value.state)
+  }
+}
+
+export function operationAccessibility(operation) {
+  const value = operation instanceof OperationState ? operation.value : operation
+  const state = value?.state ?? "pending"
+
+  if (state === "failed") return { role: "alert", "aria-live": "assertive", "aria-busy": false }
+  return {
+    role: "status",
+    "aria-live": "polite",
+    "aria-busy": !TERMINAL_OPERATION_STATES.includes(state)
+  }
+}

data/app/javascript/active_admin/react/protocol.js

@@ -0,0 +1,102 @@
+// app/javascript/active_admin/react/protocol.js
+
+export const OPERATION_STATES = Object.freeze([
+  "pending",
+  "queued",
+  "running",
+  "retrying",
+  "completed",
+  "failed",
+  "cancelled"
+])
+
+export const TERMINAL_OPERATION_STATES = Object.freeze(["completed", "failed", "cancelled"])
+
+export class OperationProtocolError extends Error {
+  constructor(issues) {
+    super(`Invalid operation event: ${issues.join(", ")}`)
+    this.name = "OperationProtocolError"
+    this.issues = issues
+  }
+}
+
+export function normalizeEvent(event = {}) {
+  const source = event && typeof event === "object" && !Array.isArray(event) ? event : {}
+  const idempotencyKey = source.idempotency_key ?? source.idempotencyKey ?? source.id ?? null
+
+  return {
+    operationId: source.operation_id ?? source.operationId ?? null,
+    id: source.event_id ?? source.eventId ?? source.id ?? idempotencyKey,
+    idempotencyKey,
+    sequence: normalizeSequence(source.sequence),
+    state: normalizeState(source.state),
+    progress: clampProgress(source.progress),
+    message: source.message ?? null,
+    result: source.result ?? null,
+    resultMetadata: source.result_metadata ?? source.resultMetadata ?? null,
+    error: normalizeError(source.error),
+    occurredAt: source.occurred_at ?? source.occurredAt ?? null
+  }
+}
+
+export function validateOperationEvent(event) {
+  const issues = []
+
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    throw new OperationProtocolError(["event must be an object"])
+  }
+
+  const normalized = normalizeEvent(event)
+  if (!nonEmptyString(normalized.operationId)) issues.push("operation_id is required")
+  if (!nonEmptyString(normalized.idempotencyKey)) issues.push("idempotency_key is required")
+  if (!validSequence(event.sequence)) issues.push("sequence must be a non-negative integer")
+  if (!OPERATION_STATES.includes(normalized.state)) issues.push(`state must be one of ${OPERATION_STATES.join("/")}`)
+  if (!validProgress(event.progress)) issues.push("progress must be between 0 and 100")
+  if (normalized.state === "failed" && normalized.error === null) issues.push("failed events require an error")
+
+  if (issues.length > 0) throw new OperationProtocolError(issues)
+  return normalized
+}
+
+function clampProgress(value) {
+  if (value === null || value === undefined) return null
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) return null
+  return Math.min(100, Math.max(0, numeric))
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0
+}
+
+function normalizeError(error) {
+  if (error === null || error === undefined) return null
+  if (typeof error === "string") return { code: null, message: error, retryable: false, details: null }
+  if (typeof error !== "object" || Array.isArray(error)) return null
+
+  return {
+    code: error.code ?? null,
+    message: error.message ?? null,
+    retryable: error.retryable === true,
+    details: error.details ?? null
+  }
+}
+
+function normalizeSequence(value) {
+  const numeric = Number(value)
+  return Number.isInteger(numeric) && numeric >= 0 ? numeric : null
+}
+
+function normalizeState(value) {
+  return typeof value === "string" ? value.toLowerCase() : "unknown"
+}
+
+function validProgress(value) {
+  if (value === null || value === undefined) return true
+  const numeric = Number(value)
+  return Number.isFinite(numeric) && numeric >= 0 && numeric <= 100
+}
+
+function validSequence(value) {
+  return Number.isInteger(value) && value >= 0
+}

data/app/javascript/active_admin/react/registry.js

@@ -0,0 +1,18 @@
+const components = new Map()
+
+export function registerComponent(name, component) {
+  if (!name || !component) throw new Error("name and component are required")
+
+  const key = String(name)
+  if (components.has(key)) throw new Error(`component already registered: ${key}`)
+
+  components.set(key, component)
+}
+
+export function resolveComponent(name) {
+  return components.get(String(name))
+}
+
+export function clearComponents() {
+  components.clear()
+}

data/app/javascript/active_admin/react/runtime.js

@@ -0,0 +1,73 @@
+import React from "react"
+import { createRoot } from "react-dom/client"
+import { resolveComponent } from "./registry"
+
+const roots = new Map()
+const selector = "[data-react-component]"
+let started = false
+
+function elementsWithin(root) {
+  const elements = [...root.querySelectorAll(selector)]
+  if (typeof root.matches === "function" && root.matches(selector)) elements.unshift(root)
+  return elements
+}
+
+function mountOnTurboLoad() {
+  mountAll()
+}
+
+function unmountBeforeTurboCache() {
+  unmountAll()
+}
+
+function propsFor(element) {
+  const raw = element.dataset.reactProps || "{}"
+  return JSON.parse(raw)
+}
+
+export function mountElement(element) {
+  if (roots.has(element)) return roots.get(element)
+
+  const Component = resolveComponent(element.dataset.reactComponent)
+  if (!Component) throw new Error(`Unknown React component: ${element.dataset.reactComponent}`)
+
+  const root = createRoot(element)
+  root.render(React.createElement(Component, propsFor(element)))
+  roots.set(element, root)
+  return root
+}
+
+export function mountAll(root = document) {
+  elementsWithin(root).forEach(mountElement)
+}
+
+export function unmountElement(element) {
+  const root = roots.get(element)
+  if (!root) return
+  root.unmount()
+  roots.delete(element)
+}
+
+export function unmountAll(root = document) {
+  for (const element of roots.keys()) {
+    if (root === document || element === root || root.contains(element)) unmountElement(element)
+  }
+}
+
+export function start() {
+  if (started) return
+
+  mountAll()
+  document.addEventListener("turbo:load", mountOnTurboLoad)
+  document.addEventListener("turbo:before-cache", unmountBeforeTurboCache)
+  started = true
+}
+
+export function stop() {
+  if (!started) return
+
+  unmountAll()
+  document.removeEventListener("turbo:load", mountOnTurboLoad)
+  document.removeEventListener("turbo:before-cache", unmountBeforeTurboCache)
+  started = false
+}

data/docs/README.md

@@ -0,0 +1,16 @@
+<!-- docs/README.md -->
+
+# Documentation
+
+- [Project README](../README.md) — installation, compatibility, public APIs, supported asset integration, security, development, and troubleshooting.
+- [Release process](releasing.md) — maintainer validation, RubyGems Trusted Publishing, failure handling, and post-release verification.
+- [Release policy](../RELEASES.md) — ordinary pre-1.0 versioning and the path to `1.0.0.rcN` and `1.0.0`.
+- [Changelog](../CHANGELOG.md) — release notes for shipped and upcoming versions.
+- [MIT License](../LICENSE.txt) — terms for using and distributing ActiveAdmin React.
+
+Source, issues, and pull requests are available in the [GitHub repository](https://github.com/scarver2/activeadmin-react).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/releasing.md

@@ -0,0 +1,59 @@
+<!-- docs/releasing.md -->
+
+# Releasing ActiveAdmin React
+
+ActiveAdmin React uses reviewed tags and RubyGems Trusted Publishing. Local commands and continuous integration validate a release candidate; only the protected GitHub Actions release job publishes it. Never add a long-lived `RUBYGEMS_API_KEY`, `GEM_HOST_API_KEY`, or RubyGems credentials file to the repository or GitHub secrets.
+
+## One-time trusted publisher setup
+
+Configure the `activeadmin-react` trusted publisher on RubyGems.org with these exact claims:
+
+- GitHub owner: `scarver2`
+- Repository: `activeadmin-react`
+- Workflow filename: `release.yml`
+- Environment: `release`
+
+Create the matching GitHub `release` environment and restrict deployment to authorized maintainers and release refs. Require reviewer approval when more than one person can initiate a release. The publish job uses GitHub OIDC to exchange its identity for a short-lived credential scoped by these claims.
+
+## Validation does not publish
+
+Prepare a release only after the complete pull-request stack has merged into `master`. Update `ActiveAdmin::React::VERSION` and `CHANGELOG.md` together, then verify a clean local checkout of the exact `origin/master` commit:
+
+```sh
+bin/setup
+bin/test
+bin/package
+```
+
+`bin/test` runs the Ruby specs, RuboCop, RBS validation, JavaScript tests, and dummy-host integration coverage. `bin/package` builds the gem, inspects the packaged file list, installs it with dependencies in an isolated gem home, and proves Rails loads that installed copy. Neither command tags a commit, contacts RubyGems publishing APIs, or publishes a gem.
+
+Before tagging, confirm every required GitHub Actions quality and package job is green for the exact `master` commit. Inspect the generated gem contents and release notes; do not treat a successful local build as approval to publish.
+
+## Publishing
+
+Create a tag that exactly matches the gem version with a leading `v`: `v0.MINOR.PATCH`, or an authorized prerelease `v0.MINOR.PATCH.alphaN` or `v0.MINOR.PATCH.betaN`. The first integrated prerelease is `v0.1.0.alpha1`. When Rodeo dogfooding indicates readiness to converge on 1.0, use `v1.0.0.rcN`. All numeric components have no leading zeroes, and prerelease `N` starts at 1. Other suffixes, `0.x` release candidates, `1.0.0` alpha/beta versions, and build metadata are rejected by the guard.
+
+Push the tag only from the reviewed `master` commit. The tag-triggered `.github/workflows/release.yml` job checks out that commit and publishes through the protected `release` environment and RubyGems Trusted Publishing. Approving that environment deployment authorizes publication; local validation never does.
+
+## Release checklist
+
+1. Merge the complete reviewed stack into `master` from the bottom up.
+2. Update the version and changelog in a reviewed pull request.
+3. Confirm the exact resulting `master` commit passes every CI quality and package gate.
+4. Run `bin/test` and `bin/package` from a clean checkout of that commit.
+5. Create the matching allowed release tag at that exact commit and push it once.
+6. Review and approve the protected `release` environment deployment.
+7. Verify the version, dependencies, checksum, and provenance on RubyGems.org.
+8. Install the published gem in a clean host and require `active_admin/react`.
+9. Create or complete the matching GitHub Release from the reviewed changelog entry.
+
+## Failure and recovery
+
+Stop when validation, tag identity, environment approval, or OIDC claim verification fails. Do not bypass a failed gate, move a published tag, overwrite a released version, or fall back to a long-lived RubyGems token. Correct the source through another reviewed pull request, increment the version, and publish a new tag.
+
+RubyGems versions are immutable. Yank a version only when its artifact is unsafe or fundamentally unusable, then document the reason in both the changelog and GitHub Release. For ordinary defects, leave the prior release available and publish a corrected PATCH version.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/lib/active_admin/react/arbre.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module React
+    # Adds the Arbre DSL entry point for rendering a React island.
+    module Arbre
+      def react_component(component, props: {}, fallback: nil, **html)
+        mount = ActiveAdmin::React::Mount.new(component, props: props, fallback: fallback, html: html)
+        attributes = mount.attributes
+        if fallback.respond_to?(:call)
+          attributes['aria-live'] = 'polite' unless attributes.key?('aria-live') || attributes.key?(:'aria-live')
+          attributes['role'] = 'status' unless attributes.key?('role') || attributes.key?(:role)
+        end
+
+        div(**attributes) do
+          text_node fallback.call if fallback.respond_to?(:call)
+        end
+      end
+    end
+  end
+end

data/lib/active_admin/react/contributions.rb

@@ -0,0 +1,27 @@
+# lib/active_admin/react/contributions.rb
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module React
+    # Coordinates engine-owned React component contributions.
+    module Contributions
+      module_function
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def register(name, **attributes)
+        registry.register(name, **attributes)
+      end
+
+      def diagnostics
+        registry.diagnostics
+      end
+
+      def reset!
+        @registry = Registry.new
+      end
+    end
+  end
+end

data/lib/active_admin/react/mount.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'date'
+
+module ActiveAdmin
+  module React
+    # Builds immutable HTML attributes for a React island and retains its fallback.
+    class Mount
+      DATA_COMPONENT = 'react-component'
+      DATA_PROPS = 'react-props'
+      COMPONENT_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
+
+      def initialize(component, props: {}, fallback: nil, html: {})
+        @component = normalize_component(component)
+        @props = normalize_props(props)
+        @fallback = fallback
+        @html = html.dup
+      end
+
+      def attributes
+        data = html_data.merge(
+          DATA_COMPONENT => @component,
+          DATA_PROPS => props_json
+        )
+
+        @html.merge(data: data)
+      end
+
+      attr_reader :fallback
+
+      private
+
+      def normalize_component(component)
+        return component.to_s if component.is_a?(String) && component.match?(COMPONENT_PATTERN)
+        return component.to_s if component.is_a?(Symbol) && component.to_s.match?(COMPONENT_PATTERN)
+
+        raise ArgumentError, 'component must be a non-empty Ruby identifier'
+      end
+
+      def html_data
+        data = @html.fetch(:data, {})
+        raise ArgumentError, 'html data must be a Hash' unless data.is_a?(Hash)
+
+        data.dup
+      end
+
+      def props_json
+        @props_json ||= JSON.generate(@props)
+      end
+
+      # Keep the accepted prop grammar explicit so unsupported objects fail closed.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def normalize_props(value)
+        case value
+        when NilClass, TrueClass, FalseClass, String, Integer, Symbol
+          value.is_a?(Symbol) ? value.to_s : value
+        when Float
+          raise ArgumentError, 'props cannot contain a non-finite Float' unless value.finite?
+
+          value
+        when DateTime, Time
+          value.iso8601(6)
+        when Date
+          value.iso8601
+        when Array
+          value.map { |item| normalize_props(item) }
+        when Hash
+          value.to_h do |key, item|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise ArgumentError, 'props Hash keys must be Strings or Symbols'
+            end
+
+            [key.to_s, normalize_props(item)]
+          end
+        else
+          raise ArgumentError, "unsupported prop type: #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/active_admin/react/registry.rb

@@ -0,0 +1,134 @@
+# lib/active_admin/react/registry.rb
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module React
+    # Stores namespaced component contributions with copied, immutable metadata.
+    class Registry
+      include Enumerable
+
+      Entry = Data.define(:name, :namespace, :source, :owner, :surfaces, :metadata) do
+        def provenance
+          "#{owner.inspect} in namespace #{namespace.inspect} from #{source.inspect}"
+        end
+      end
+
+      def initialize
+        @entries = {}
+      end
+
+      def register(name, **attributes)
+        entry = build_entry(name, attributes)
+        raise_conflict(entry) if @entries.key?(entry.name)
+
+        @entries[entry.name] = entry
+      end
+
+      def fetch(name)
+        @entries.fetch(name.to_s)
+      end
+
+      def each(&)
+        ordered_entries.each(&)
+      end
+
+      def to_a
+        ordered_entries
+      end
+
+      def registered?(name)
+        @entries.key?(name.to_s.strip)
+      end
+
+      def diagnostics
+        ordered_entries.map do |entry|
+          {
+            name: entry.name,
+            namespace: entry.namespace,
+            owner: entry.owner,
+            source: entry.source,
+            surfaces: entry.surfaces,
+            metadata: entry.metadata
+          }.freeze
+        end.freeze
+      end
+
+      private
+
+      def build_entry(name, attributes)
+        surfaces = attributes.delete(:surfaces) { [:component] }
+        Entry.new(
+          name: normalize_required(name, :name),
+          namespace: normalize_attribute(attributes, :namespace),
+          source: normalize_attribute(attributes, :source),
+          owner: normalize_attribute(attributes, :owner),
+          surfaces: normalize_surfaces(surfaces),
+          metadata: immutable_metadata(attributes)
+        ).freeze
+      end
+
+      def immutable_metadata(value, ancestors = Set.new)
+        return value.dup.freeze if value.is_a?(String)
+        return value unless metadata_container?(value)
+
+        object_id = value.object_id
+        raise ActiveAdmin::React::Error, 'metadata must not contain cyclic containers' if ancestors.include?(object_id)
+
+        nested_ancestors = ancestors.dup.add(object_id)
+        return immutable_hash(value, nested_ancestors) if value.is_a?(Hash)
+        return immutable_array(value, nested_ancestors) if value.is_a?(Array)
+
+        immutable_set(value, nested_ancestors)
+      end
+
+      def immutable_hash(value, ancestors)
+        value.each_with_object({}) do |(key, nested_value), copy|
+          copy[immutable_metadata(key, ancestors)] = immutable_metadata(nested_value, ancestors)
+        end.freeze
+      end
+
+      def immutable_array(value, ancestors)
+        value.map { |nested_value| immutable_metadata(nested_value, ancestors) }.freeze
+      end
+
+      def immutable_set(value, ancestors)
+        value.each_with_object(Set.new) do |nested_value, copy|
+          copy << immutable_metadata(nested_value, ancestors)
+        end.freeze
+      end
+
+      def metadata_container?(value)
+        value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(Set)
+      end
+
+      def normalize_attribute(attributes, field)
+        normalize_required(attributes.delete(field), field)
+      end
+
+      def normalize_required(value, field)
+        normalized = value.to_s.strip
+        raise ActiveAdmin::React::Error, "#{field} must be present" if normalized.empty?
+
+        normalized
+      end
+
+      def normalize_surfaces(surfaces)
+        normalized = Array(surfaces).map { |surface| normalize_required(surface, :surface).to_sym }.uniq.sort.freeze
+        raise ActiveAdmin::React::Error, 'surfaces must not be empty' if normalized.empty?
+
+        normalized
+      end
+
+      def ordered_entries
+        @entries.values.sort_by { |entry| [entry.namespace, entry.name, entry.owner] }.freeze
+      end
+
+      def raise_conflict(incoming)
+        existing = @entries.fetch(incoming.name)
+        message = "component #{incoming.name.inspect} is owned by #{existing.provenance}; " \
+                  "attempted owner #{incoming.provenance}"
+        raise ActiveAdmin::React::Error, message
+      end
+    end
+  end
+end

data/lib/active_admin/react/version.rb

@@ -0,0 +1,8 @@
+# lib/active_admin/react/version.rb
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module React
+    VERSION = '0.1.0.alpha1'
+  end
+end

data/lib/active_admin/react.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'active_admin'
+require_relative 'react/arbre'
+require_relative 'react/contributions'
+require_relative 'react/mount'
+require_relative 'react/registry'
+require_relative 'react/version'
+
+module ActiveAdmin
+  module React
+    class Error < StandardError; end
+  end
+end
+
+Arbre::Element.include(ActiveAdmin::React::Arbre)

data/sig/active_admin/react.rbs

@@ -0,0 +1,32 @@
+# sig/active_admin/react.rbs
+
+module ActiveAdmin
+  module React
+    class Registry
+      class Entry
+        attr_reader name: String
+        attr_reader namespace: String
+        attr_reader source: String
+        attr_reader owner: String
+        attr_reader surfaces: Array[Symbol]
+        attr_reader metadata: Hash[Symbol, untyped]
+      end
+
+      def initialize: () -> void
+      def register: (String | Symbol name, namespace: String | Symbol, source: String | Symbol, owner: untyped, ?surfaces: Array[String | Symbol], **untyped metadata) -> Entry
+      def fetch: (String | Symbol name) -> Entry
+      def each: () { (Entry) -> void } -> Array[Entry]
+              | () -> Enumerator[Entry, Array[Entry]]
+      def to_a: () -> Array[Entry]
+      def registered?: (String | Symbol name) -> bool
+      def diagnostics: () -> Array[Hash[Symbol, untyped]]
+    end
+
+    module Contributions
+      def self.registry: () -> Registry
+      def self.register: (String | Symbol name, namespace: String | Symbol, source: String | Symbol, owner: untyped, ?surfaces: Array[String | Symbol], **untyped metadata) -> Registry::Entry
+      def self.diagnostics: () -> Array[Hash[Symbol, untyped]]
+      def self.reset!: () -> Registry
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: activeadmin-react
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha1
+platform: ruby
+authors:
+- Stan Carver II
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activeadmin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0.beta22
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0.beta22
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'An Arbre-native bridge for mounting optional React components inside
+  ActiveAdmin while keeping ActiveAdmin Rails-first and server-rendered.
+
+  '
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- RELEASES.md
+- app/javascript/active_admin/react/cable.js
+- app/javascript/active_admin/react/index.js
+- app/javascript/active_admin/react/operation.js
+- app/javascript/active_admin/react/protocol.js
+- app/javascript/active_admin/react/registry.js
+- app/javascript/active_admin/react/runtime.js
+- docs/README.md
+- docs/releasing.md
+- lib/active_admin/react.rb
+- lib/active_admin/react/arbre.rb
+- lib/active_admin/react/contributions.rb
+- lib/active_admin/react/mount.rb
+- lib/active_admin/react/registry.rb
+- lib/active_admin/react/version.rb
+- sig/active_admin/react.rbs
+homepage: https://github.com/scarver2/activeadmin-react
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/scarver2/activeadmin-react/issues
+  changelog_uri: https://github.com/scarver2/activeadmin-react/blob/v0.1.0.alpha1/CHANGELOG.md
+  documentation_uri: https://github.com/scarver2/activeadmin-react/blob/v0.1.0.alpha1/README.md
+  homepage_uri: https://github.com/scarver2/activeadmin-react
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/scarver2/activeadmin-react/tree/v0.1.0.alpha1
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: React islands for ActiveAdmin
+test_files: []