@aotter/mantle-ui 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,163 @@
+# @aotter/mantle-ui
+
+Shared interaction UI for the Mantle Admin and MCP Apps (ADR-0029). The
+`/controller` subpath is framework-free; the root adds React components on top
+of it (React 19 is an optional peer, needed only for the root and `/kit`).
+
+## Admin
+
+`dist/admin/` is the built Admin console (a static SPA with base `/admin/`).
+Nothing imports it: `mantle generate`'s Cloudflare preset binds
+`node_modules/@aotter/mantle-ui/dist/admin` as the Worker's static assets (the
+Bun preset resolves `@aotter/mantle-ui/admin/index.html` and serves its
+directory with `bunAdminAssets`), and
+`createAdminSurface` (`@aotter/mantle/admin`) serves it at `/admin`. It is
+built for that path, so `createAdminSurface` refuses `assets` under any other
+`basePath`. Its source is `admin/`.
+
+## MCP App
+
+`/mcp-app` exports `mantleAppHtml`, one self-contained HTML document. Give it
+to `planApp` from `@aotter/mantle/mcp`, which embeds the plan's catalog of
+Views and row operations and renders every View tool of a surface:
+
+```ts
+apps: { resources: [planApp(runtime.plan, { surface: "staff", html: mantleAppHtml })] }
+```
+
+The App shows a View's rows with Admin's value renderers and opens one row
+operation at a time through the controller and `OperationPanel`. Every read
+and write is a tool call through the host; it holds no credentials.
+
+An App of your own reuses the same pieces from the root: `readCatalog`,
+`toolOf`, `outputOf`, `rowsOf`, `invokeTool` and `actionsFor` read the catalog
+and tool results as Mantle's App does (the `develop` skill's MCP App recipe).
+
+## Controller
+
+The `/controller` subpath takes one operation opened from one
+row, the version the person reviewed, and one submit. It imports nothing at
+all, not even Mantle types. The shapes it expects (`InteractionBinding`,
+`InteractionDiagnostic`, `EntrySnapshot`) are structural, so a runtime
+`ViewRowAction` and `Diagnostic` fit them as they are.
+
+```ts
+import { createInteractionController } from "@aotter/mantle-ui/controller";
+
+const controller = createInteractionController({
+  interaction: rowAction,               // from a View capability's rowActions
+  row,                                  // the row as the person saw it
+  read: (signal) => readEntry(row.id, signal),
+  invoke: (input, signal) => callTool(rowAction.capability, input, signal),
+  initialInput: currentValues,          // optional prefill
+});
+await controller.open();
+controller.edit("reviewerNote", "Within budget.");
+await controller.submit();
+```
+
+The host injects `read` and `invoke`. Admin uses the staff MCP client, an MCP
+App uses `App.callServerTool`, and an application can use its own HTTP
+client. `subscribe` and `getSnapshot` plug straight into React's
+`useSyncExternalStore`, or into any other store. A listener that throws is
+reported asynchronously; it cannot interrupt a transition.
+
+| Phase | Meaning |
+|---|---|
+| `unreadable` | The target could not be read, or a different entry came back. Nothing is confirmed, so submit waits for a successful `reread()` or `refresh()`. |
+| `changedSinceList` | A read found a newer version than the one reviewed. `latestChanges()` shows what moved and `review()` adopts it; nothing is swapped silently. |
+| `conflict` | The runtime answered `CONFLICT` to an operation that locks a version. The input is kept; `reread()`, then review again. Without a `read`, the components ask the person to reopen the action from a refreshed list instead. |
+| `uncertain` | The write may have landed, so it is never retried. This covers a submit that threw, timed out or was cancelled, and a runtime `OUTCOME_UNKNOWN`, `PARTIAL_FAILURE` or `failure.outcome` of `unknown` or `partial`. `reread()` first; a host without `read` calls `acknowledgeUncertain()` after checking elsewhere. |
+| `failed` | The runtime refused, and `diagnostics` holds its answer. A `CONFLICT` on an operation that locks no version (a unique key, a state rule) is a refusal too: the person fixes the input and submits again. A conflict whose reread finds the same version also lands here, because the refusal was not about the version. |
+
+Behaviour to rely on:
+
+- A background `refresh()` never replaces the draft or the reviewed version. Its failure is recorded in `error` without blocking submit, and `reading` is true while any read is in flight.
+- Prefilled fields the person has not touched follow the newer entry on `review()`, so a prefill never reverts someone else's change.
+- `contested` lists touched fields that someone else also changed.
+- Bound inputs and the version input are not editable. A binding to a field the row lacks is refused at construction, and so is a locking operation with neither a `read` nor a row carrying `id` and `version`.
+- `changes()` lists the draft fields that differ from the reviewed entry, and `dirty` is true while the person's edits are unsaved.
+- A success that arrives after `cancel()` is ignored: the phase stays `uncertain` until a reread shows it.
+
+## Components
+
+```tsx
+import { OperationPanel, createInteractionController } from "@aotter/mantle-ui";
+
+<OperationPanel controller={controller} title="Review requisition" labels={labels} fieldLabel={label}>
+  {/* the host's own inputs, wired to controller.edit */}
+</OperationPanel>
+```
+
+`OperationPanel` composes the parts for a page, a dialog or a chat surface:
+
+- `EntityPreview`: the reviewed entry.
+- `ChangeDiff`: the person's own changes, or what someone else changed.
+- `OperationStatus`: the next step for each phase, with its one action.
+- `OperationOutcome`: the result.
+
+Each part reads only the controller snapshot (`useInteraction`) and calls only
+controller actions. None of them reads a router, a query cache, a transport or
+host globals.
+
+The host supplies:
+
+- **Inputs:** the editable fields, rendered as `children` and wired to
+  `controller.edit`.
+- **Strings:** every string, as `labels` (English defaults in
+  `defaultInteractionLabels`).
+- **Field labels:** a `fieldLabel` function.
+
+Styling uses Tailwind token classes (`bg-muted`, `border`, `text-destructive`,
+`bg-primary`, …) resolved from the host's CSS variables. Add
+`@source "../node_modules/@aotter/mantle-ui/dist/**/*.js"` (adjusted to your
+stylesheet's location) so Tailwind generates the classes.
+
+## Fields and values
+
+Admin's own value and field code is shared, so an MCP App renders a field
+exactly as the console does:
+
+- `SchemaFields` (from `/kit`, since its controls are kit components): a form over a JSON Schema (option lists from `enum` or a
+  `oneOf` of titled `const`s, money and date previews, arrays, nested objects).
+  Strings come from `labels`; a control only one host has (Admin's media
+  library and rich text editors) comes through `renderField`, and without it
+  markdown and HTML are a textarea. `propertyLabel` overrides how a label reads.
+- `renderDataValue` (root, React only), `optionLabel`, `propertyLabel`, `resolveLocalizedText` and
+  the money and date formatters: how a value reads in a cell or a card.
+
+## Kit
+
+`@aotter/mantle-ui/kit` is Admin's domain-neutral React/shadcn visual
+language, for applications that do not embed the Admin product: the
+primitives, the email sign-in flow and the compiled theme. Its libraries are
+optional peers, so `/controller` and `/mcp-app` consumers install none of them.
+Install them with the kit:
+
+```sh
+pnpm add @aotter/mantle-ui react react-dom radix-ui lucide-react class-variance-authority clsx tailwind-merge sonner input-otp react-day-picker
+```
+
+Then:
+
+```tsx
+import { Button, Card, CardContent, Input } from "@aotter/mantle-ui/kit";
+import "@aotter/mantle-ui/kit.css";
+```
+
+`SignInFlow` exports Admin's own two-step email-OTP form (email screen, then
+six-digit code screen). The host injects transport (`onSendCode`,
+`onVerifyCode`), whatever navigation follows a successful verify, and all copy;
+the component owns only the step, busy, and error state. A verify that resolves
+without an error is terminal: the form stays busy and locked so the consumed
+code cannot be resubmitted, and the host must navigate or unmount it (Admin
+does `window.location.assign`). Admin renders the same component, so a host's
+sign-in cannot drift from it.
+
+Use `@aotter/mantle-ui/tokens.css` when an application only needs the
+Mantle color, radius, background, and sidebar variables. The kit intentionally
+does not export `AdminApp`, authenticated layouts, routes, queries, or feature
+views; use the static Admin SPA or sandbox preview for the complete product.
+
+Applications that compile Tailwind themselves import `tokens.css` and add
+`@source` for `node_modules/@aotter/mantle-ui/dist/kit` instead of `kit.css`.