@cratis/event-models 0.111.1 → 0.113.0

package/README.md

@@ -38,6 +38,71 @@ export const Board = () => (
 - The board fills its parent, so give the parent a height.
 - `readOnly` draws the board without any editing gestures. Leave it off and pass `editor` to receive the board's edits as callbacks. The package never persists anything by itself.
 
+## Open the screen editor from the board
+
+The board reports when someone selects a slice's screen preview. `@cratis/event-models/screen-editor` is the editor that opens over it, so a host outside Cratis Studio can let people design a screen without any Studio code. It is a separate entry, and a host that only draws the board installs none of what it needs.
+
+Install what the editor draws with. These are optional peers, required only by this entry:
+
+```bash
+npm install @cratis/scene.model @cratis/scene.engine @cratis/scene.react @cratis/scene.components @cratis/scene.primereact @cratis/scene.tailwind @cratis/scene.blueprint.default @cratis/scene.blueprint.components @primereact/core @primereact/headless primereact lucide-react react-icons chart.js quill
+```
+
+The Scene packages must be 4.7.0 or newer: that release adds the chart, multi-state checkbox, file upload, data scroller, tree table and rich text editor controls and the JSON property type the editor draws a field for. `chart.js` (4.5.1 or newer) draws the chart control and `quill` (2.0.3 or newer) is the rich text control's engine. Both are optional peers of this entry, and a host that offers those controls in its palette installs them. Quill's stylesheet is part of `@cratis/event-models/screen-editor/styles`, so there is nothing more to import.
+
+Import the editor's stylesheet beside the board's, and Scene's:
+
+```tsx
+import '@cratis/components/tokens';
+import '@cratis/components/styles';
+import '@cratis/components/theme';
+import '@cratis/event-models/styles';
+import '@cratis/event-models/screen-editor/styles';
+import '@cratis/scene/styles';
+import 'primeicons/primeicons.css';
+```
+
+Wrap the page in the two providers the components inside a screen need:
+
+```tsx
+import { CratisComponentsProvider } from '@cratis/components';
+import { ScreenEditorPrimeReactProvider } from '@cratis/event-models/screen-editor';
+
+<CratisComponentsProvider value={{ locale: 'en-US' }}>
+    <ScreenEditorPrimeReactProvider license={yourPrimeUiLicenseKey} theme={yourPrimeReactTheme}>
+        {/* the board and the editor */}
+    </ScreenEditorPrimeReactProvider>
+</CratisComponentsProvider>
+```
+
+`ScreenEditorPrimeReactProvider` is PrimeReact's own `PrimeReactProvider` under a name this package exports, and it takes the same props (license, theme, locale, pass-through, defaults). It is not a second context: the published bundle imports `@primereact/core/config` from your install, so the provider and every PrimeReact component in the page share one context. Import `PrimeReactProvider` from `@primereact/core/config` yourself if you prefer; the result is identical. Either way, install a single `@primereact/core`.
+
+- The editor needs no Studio Core, Arc, router or Studio provider. It does need a PrimeReact provider (`ScreenEditorPrimeReactProvider`), because the default palette offers PrimeReact components and those throw without one. If a component does fail, the editor closes with a message and the page it was opened over carries on.
+- PrimeReact 11 checks a license key at runtime and shows an *Invalid PrimeUI License* badge without one. The key belongs to your application: pass it to the provider. The package never sees it.
+- `ScreenEditorOverlay` takes an environment built with `createScreenEditorEnvironment`. That is where the host lends the queries a screen may bind, the state changes it may submit and the screens it can lead to, in the shapes described on the exported types. The editor hands the edited document back from `onClose`; the host decides where it is kept.
+- Two controls need something from the host, and neither needs anything by default. The rich text control loads Quill through `richText`, which defaults to the loader from `@cratis/scene.primereact/quill`; pass your own loader to supply the engine yourself, or `false` to leave rich text out, and the control then says it is not available. The file upload control posts to the address its author configured, to your own origin, and only when someone presses upload; pass `fileUpload: { handler, allowedOrigins }` to own the upload yourself or to allow other origins. An author's address is never rewritten, nothing is requested while a screen is being edited, and an address on an origin you did not allow is refused before anything is sent.
+- The same services reach the controls wherever the editor is drawn: `ScreenEditorOverlay` floats it over a page and `ScreenEditorWorkspace` sets it into one, as a screen template is authored, and both wrap what they draw in the same providers. The rich text control is editable in either, and an upload goes through your `fileUpload.handler` in either.
+- A property that holds any JSON value (a chart's data, its options) is edited as text next to its other properties. The author's text is parsed, and `null`, `0`, `false`, arrays and objects are values of their own; text that does not parse is refused where it is typed and nothing is applied. Emptying the field, or choosing "Not set" on a choice, puts the property back to its default, and one undo brings it back. A value the stored document holds that is none of a choice's options (an older document) is listed under its own value, so it can be read and kept.
+- A host with no chart in its palette and `richText: false` installs neither `chart.js` nor `quill`: the entry type-checks without skipping library declarations and builds without either.
+
+```tsx
+<EventModelBoard document={model} editor={{ editing: { onPrototypeOpened: (sliceId, actorId, rect) => open(sliceId, actorId, rect) } }} />
+
+{opening && (
+    <ScreenEditorOverlay
+        subject={{ documentText: saved[opening.key] }}
+        environment={environment}
+        strings={defaultScreenEditorStrings}
+        layoutLabels={defaultLayoutLabels}
+        icons={defaultPaletteIcons}
+        paletteSources={defaultPaletteSources}
+        sourceRect={opening.rect}
+        onClose={result => keep(opening.key, result)} />
+)}
+```
+
+`@cratis/components` 4.25 or later is required by this entry, and is now the minimum for the package. Consumers that only draw the board need to move to it too.
+
 ## Logo, view options and your own tools
 
 The board can draw the Cratis logo and a toolbar over itself. Both are off unless you ask for them:

package/dist/Collections/suppliesBoardEditing.d.ts

@@ -0,0 +1,2 @@
+import type { BoardEditing } from '../Board/BoardEditing';
+export declare const suppliesBoardEditing: (editing: BoardEditing) => boolean;