@quario/editor 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to @quario/editor are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-01
+
+### Added
+
+- **An embeddable `<quario-editor>`.** A banded document designer whose design
+  surface is the rendered preview itself: assign a starter schema, a quario
+  instance, the html target and sample data; the report renders on the sheet,
+  clicking output selects the definition behind it, and items, table columns
+  and groups rearrange structurally — every edit recompiles and re-renders
+  through the real engine. A properties panel edits the selected node's
+  literals, styles, templates and expressions; problems list with their exact
+  spans; undo and redo walk whole gestures. The edited document reaches the
+  host on every change, frozen, with its problem list. A failure reaches the
+  error panel and the `error` event once per distinct failure, however many
+  renders it survives, and a panel the author dismisses stays dismissed.
+- **The preview answers to the keystroke, undo to the gesture.** Typing in the
+  properties panel and dragging a colour picker move the report and its problem
+  list live, so a half-written expression shows what is wrong with it as it is
+  written. Neither takes an undo step or reaches the host until the gesture
+  ends — on blur, on Enter, on the picker's release, or after a half-second
+  pause — so one edit is one undo, not one per character. Interrupting an edit
+  never loses it: pressing another control or selecting something else leaves
+  the typing behind as its own undo step rather than folding it into what
+  came next.
+
+### Changed
+
+- **The adopted sheet's baseline face moved onto `.q-report`.** It was on
+  `.q-item` and `.q-table`, where a direct rule would have beaten a report's
+  own declared family. Same look; the fragment's new root is what carries it.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -0,0 +1,89 @@
+# @quario/editor
+
+**The embeddable banded document designer for [quario](https://www.npmjs.com/package/quario).**
+`<quario-editor>` shows a report rendered on your sample data and lets the author rearrange it
+structurally: drag items between bands with a gutter grip, reorder table columns on the table,
+restructure groups from a docked list, and edit the selected node's values, styles, templates and
+expressions in a properties panel. Every edit recompiles and re-renders through the real engine
+and the real HTML target, so what the author sees is the report — not an approximation of it.
+
+There is no infinite canvas and no free positioning, because the schema has no concept of either:
+bands stack, items stack, tables have columns. Every drag is structural and every drop snaps to a
+slot the schema actually has — and the editor refuses drops that would break at render time, such
+as moving an item that reads the current row (`@`) out of the detail band.
+
+## Install
+
+```bash
+npm install @quario/editor quario @quario/html
+```
+
+ESM-only, Node 22+ tooling, evergreen browsers. Runtime dependencies:
+[lit](https://lit.dev), `@lit/task`, and [tinykeys](https://github.com/jamiebuilds/tinykeys).
+The engine and the HTML target are **not** dependencies — your app passes its own configured
+instances in, so your bundle carries one copy of each.
+
+## Quick start
+
+```js
+import { quario } from "quario";
+import { html } from "@quario/html";
+import "@quario/editor/register";
+
+const editor = document.createElement("quario-editor");
+editor.instance = quario({ license: "quario_..." });
+editor.target = html({ paths: true }); // paths map rendered output back to the schema
+editor.schema = starterSchema; // the document the author begins with
+editor.data = sampleData; // what the preview renders on
+editor.addEventListener("change", ({ detail }) => {
+  save(detail.schema); // deep-frozen; assigning it back to `schema` is a no-op
+  saveButton.disabled = detail.problems.length > 0;
+});
+document.body.append(editor);
+```
+
+`html({ paths: true })` matters: it stamps `data-q-path` on the fragment, which is how clicking
+rendered output selects the schema node behind it. The editor tells you if you forget.
+
+## The element
+
+The editor is **uncontrolled**: `schema` seeds it, and the editor owns the document from there.
+Only assigning a **new** schema object resets the document, history and selection — assigning
+back the exact object the last `change` delivered does nothing, so a naive persist-and-restore
+loop cannot wipe the author's undo history. Assigning a new `instance`, `target`, `functions`,
+`data` or `page` recompiles and re-renders while leaving the author's work untouched — a license
+key arriving mid-session is one property write, not a catastrophe.
+
+| Property      | What it is                                                                       |
+| ------------- | -------------------------------------------------------------------------------- |
+| `schema`      | The starter report document. A new object identity loads and resets.             |
+| `instance`    | Your configured `quario()` instance; the license rides on it.                    |
+| `target`      | The HTML target, from `html({ paths: true })`.                                   |
+| `functions`   | Functions callable from the document's expressions.                              |
+| `data`        | The sample data the preview renders on.                                          |
+| `page`        | Sheet geometry (`{ size, margin }`), the same values you pass `pdf({ page })`.   |
+| `colorScheme` | `"light"` (default), `"dark"`, or `"auto"`. Chrome only — the sheet stays white. |
+
+**Events.** `change` fires on every committed change — edits, undo and redo alike — with
+`{ schema, problems }`: the document (deep-frozen) and its structured problem list, so you can
+disable Save without running the engine yourself. `error` reports host mistakes and render
+failures. `renderComplete` is a `Promise<boolean>` for the newest render settling.
+
+**Editing.** Hover an item for its gutter grip: drag to move (a caret shows exactly where it will
+land, and refuses to go anywhere illegal), click for Delete and Duplicate, and the `+` beside it
+inserts a text item. Drag table column headers to reorder — a column's total cell travels with
+it. The right rail holds the properties panel (real controls for styles, an `fx` toggle to make
+any style value an expression, errors underlined at the exact character when the engine knows
+it), the groups list, and every problem in the document. `Mod+Z` / `Shift+Mod+Z` undo and redo
+whole gestures; inside a text field they undo typing, not the document. While the document is
+mid-edit and invalid, the preview keeps showing the last version that compiled.
+
+**Reveal.** The render is an honest picture: an empty band or a hidden item draws nothing. The
+bar's Reveal toggle (off by default) shows placeholders for them — a hidden item's placeholder
+shows what you wrote in it — and during a drag, empty bands appear as drop targets on their own.
+
+## License
+
+quario is commercial software; evaluation is free and fully featured, with output marked as
+unlicensed. The key is stated once, on the `quario()` instance you pass in — the editor adds no
+license mechanics of its own. See [LICENSE](https://getquario.com/license).