@mosetta/react 0.0.11 → 0.0.13

package/AUTHORING.md

@@ -0,0 +1,212 @@
+# Writing tiles
+
+What a block of a mosetta site is made of, and the rules it lives by. Written for whoever writes one
+— a developer, or an assistant writing a project's own blocks.
+
+## A tile palette
+
+A tile palette is a folder: `package.json` (its version), `mosetta.json` (its brand), `tsconfig.json`
+and `tiles/`. A tile is a folder under `tiles/`; its files are its **sides**:
+
+```
+tiles/greeting/greeting.component.tsx   what the visitor sees (required)
+tiles/greeting/greeting.settings.ts     what its settings are — a schema (strongly advised)
+tiles/greeting/greeting.editor.tsx      its settings form in the editor (optional)
+tiles/greeting/greeting.server.ts       its server actions (optional)
+tiles/greeting/greeting.icon.svg        its icon in the block picker (optional)
+tiles/greeting/greetingCommon.ts        what the sides share: types, tokens, constants (any name)
+tiles/greeting/greeting.styles.css      its own stylesheet, imported by the component (any name)
+```
+
+A tile's full id is `_ns_<brand>_t_<side>_n_<name>_v_<version>`. A page names blocks by full id, so a
+released version never changes: a change is a new version, and a page takes it when its author
+updates the block. The tile's name is its folder's name: letters and digits, starting with a letter
+(`greeting`, `bookingForm`).
+
+## The component side
+
+```tsx
+import { defineComponentSide, useChildren, useSettings, useStyler } from '@mosetta/react';
+import type { IGreetingSettings } from './greetingCommon';
+import './greeting.styles.css';
+
+export default defineComponentSide<IGreetingSettings>({
+  Component() {
+    const styler = useStyler();
+    const { text, tone } = useSettings<IGreetingSettings>();
+    return (
+      <section {...styler.part('root')} className={`greeting greeting--${tone}`}>
+        <h2 {...styler.part('title')}>{text}</h2>
+        {useChildren({ max: 'many' })}
+      </section>
+    );
+  },
+  defaultSettings() {
+    return { text: 'Hello', tone: 'warm' };
+  },
+});
+```
+
+- **Settings** are the node's data, filled in the editor. `defaultSettings()` is copied into a node
+  when it is placed — the runtime never merges defaults later, so give every field a default, and
+  read fields defensively (a node saved by an older version may lack a newer field).
+- **Children**: a block holds other blocks only where it calls `useChildren`. `max` says how many fit
+  (`1`, `3`, `'many'`); a named slot (`useChildren({ slot: 'footer', max: 'many' })`) is a second place.
+  A block that calls none holds nothing.
+- **Styling**: `useStyler().part('<name>')` lets the page's author restyle a part from the editor
+  (declare the parts and accept them in the settings schema with `styles(PARTS)`). Use the theme's
+  CSS variables for colours and fonts so the block follows the site's theme. Import your own CSS file;
+  the build ships it with the tile.
+- **Translatable text**: `bindable: { text: 'text' }` in the definition lets a setting hold a reference
+  to a translation (`{"$ref": "i18n/<key>"}`) instead of the words; `useSettings` gives the words in
+  the visitor's language.
+- **Other hooks** (all from `@mosetta/react`): `useRoute`, `useRouter`, `useHref`, `Link` (moves
+  without reloading), `useLanguages`, `useTheme`, `useAddToHead`, `useMediaUpload`,
+  `useIsPreviewMode`.
+- **Rendering on the server**: pages are rendered on the server first. Do not touch `window`,
+  `document` or `localStorage` while rendering or at the top of a module — only in effects and event
+  handlers.
+
+## The settings schema
+
+```ts
+// tiles/greeting/greeting.settings.ts
+import { bindable, settingsOf, styles, z } from '@mosetta/settings';
+import { GREETING_PARTS } from './greetingCommon';
+import type { IGreetingSettings } from './greetingCommon';
+
+export const settings = settingsOf<IGreetingSettings>()(z.object({
+  text: bindable(z.string().describe('the greeting, plain text')),
+  tone: z.enum(['warm', 'cool']).describe('the colour behind it'),
+  styles: styles(GREETING_PARTS).optional(),
+}).describe('A greeting: a heading on a coloured band, with blocks under it'));
+```
+
+The build checks the schema against the settings type and puts it into the tile's descriptor: the
+editor and assistants read what each setting does and which values it allows, and settings are
+checked where they are written. Describe every field and the block itself in plain words — that text
+is how others learn the block without reading its code.
+
+## The editor side (optional)
+
+Without one, a block's settings are edited by its schema. Write one when the form needs more than
+fields:
+
+```tsx
+import { defineEditorSide, useSettingsDraft } from '@mosetta/react';
+import type { IGreetingSettings } from './greetingCommon';
+
+export default defineEditorSide<IGreetingSettings>({
+  Component() {
+    const { draft, update } = useSettingsDraft<IGreetingSettings>();
+    return <input value={draft.text} data-field="text" onChange={(e) => update({ text: e.target.value })} />;
+  },
+});
+```
+
+`data-field` marks a bindable field: the editor offers a translation reference beside it. An editor
+side may also declare `preview` (a small tree that shows the block in the picker) and `variants`
+(states worth seeing side by side on the block's page).
+
+## Server actions
+
+Code that must not run in the browser — reading a database, sending mail, using a secret — is a
+server action. The token is shared by both sides; keep it in the common file:
+
+```ts
+// tiles/booking/bookingCommon.ts
+import { ServerActionToken } from '@mosetta/server-action/core';
+
+export interface IBookingInput { name: string; email: string; slot: string }
+export const bookToken = new ServerActionToken<IBookingInput, { ok: boolean }>({ actionName: 'book' });
+```
+
+```ts
+// tiles/booking/booking.server.ts
+import { DiInject, DiServerAction, defineServerSide, SECRETS_TOKEN, ServerAction } from '@mosetta/server-action/server';
+import type { ICreateSchema, ISecrets, IServerActionPayload } from '@mosetta/server-action/server';
+import { bookToken } from './bookingCommon';
+import type { IBookingInput } from './bookingCommon';
+
+@DiServerAction(bookToken)
+class BookAction extends ServerAction<IBookingInput, { ok: boolean }> {
+  constructor(@DiInject(SECRETS_TOKEN) private readonly secrets: ISecrets) {
+    super();
+  }
+
+  authorize() {
+    return true; // a visitor's form: anyone may send it
+  }
+
+  createSchema({ builder }: ICreateSchema) {
+    return builder.object({ name: builder.string().min(1), email: builder.string().email(), slot: builder.string() });
+  }
+
+  async action({ input }: IServerActionPayload<IBookingInput>) {
+    const token = await this.secrets.get('D1_TOKEN');
+    // … write the booking with it
+    return { ok: Boolean(token && input.slot) };
+  }
+}
+
+export default defineServerSide({ services: [BookAction] });
+```
+
+```tsx
+// in the component side
+import { EServerActionStart } from '@mosetta/server-action/core';
+import { useServerAction } from '@mosetta/react/server-action';
+
+const booking = useServerAction({ token: bookToken, start: EServerActionStart.START_MANUAL });
+// booking.start?.(input) sends it; booking.isLoading(), booking.isSuccess(), booking.serverData
+```
+
+- **`authorize` is required.** It says who may call: `true` for anyone, or a check of the `caller` it is
+  given (what the host vouches for — on the platform, `roles: ['editor']` for the site's editors).
+- **Input is validated** by `createSchema` before `authorize` and the action run.
+- **Reading data** for a page: `useServerAction({ token, input })` starts as the block renders and
+  caches by input; `start: EServerActionStart.START_FROM_SERVER` runs it during server rendering, so
+  the page arrives with the data in it.
+- **Secrets** are asked for by name (`UPPER_SNAKE_CASE`) and set in the site's settings; a value is
+  never in the code or the environment. The server side of a tile is named like its component
+  (`booking.server.ts` beside `booking.component.tsx`).
+
+### The block a call comes from
+
+The input is whatever the browser sent — anybody can send anything. What the site's author set on
+the block (the hours a booking form offers, the address a contact form writes to) is given to the
+action separately, read by the host from the page itself: `block` beside `input`, in `action` and in
+`authorize`.
+
+```ts
+async action({ input, block }: IServerActionPayload<IBookingInput>) {
+  const hours = (block?.settings.hours ?? []) as string[];
+  if (!hours.includes(input.slot)) return { ok: false }; // not a time this form offers
+  // … write the booking
+  return { ok: true };
+}
+```
+
+- `block` is `{ page, node, reference, settings, draft }`: the page's name, the block's id on it, the
+  block's tile, its settings as stored, and whether it was read from a draft. A translated text in
+  the settings stays a reference (`{ $ref: … }`), as the page stores it.
+- The component side does nothing for it: `useServerAction` says which block on which page calls.
+  The host finds that block on the page as published; in a draft's preview, in the draft — for the
+  site's editors only, everybody else gets the published page.
+- `block` is `null` when the call comes from no page, when the block is not on the page as published
+  (a stale tab, a new block not published yet), or when it is not a tile of this palette at the
+  action's own version. An action that needs the block's settings refuses then: never fall back to
+  something the input says.
+- Inside a prefab, the block's id is `<prefab's id on the page>/<id in the prefab>` and its settings
+  are as rendered, the instance's fields filled. A block inside a library's prefab is not read.
+
+## Rules of a project's palette on the platform
+
+- Its brand is the project's own; it holds the project's tiles (and the packages they import), every
+  tile with its integrity — the build writes it. No prefabs: a project's prefabs are its content.
+- It is built over the platform's tiles: the UI kit and the framework come from the platform, not
+  from the palette. Name them in `package.json` at the versions the template gives.
+- Types are checked before a release: a type error in the palette's own files stops it, and the
+  error comes back as the checker's line.
+- Every release is the next patch version. Pages keep the version they name; update a block on a
+  page to take the new one.

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @mosetta/react
 
+## 0.0.13
+
+### Patch Changes
+
+- A server action learns the block it is called from: `block` — the page, the node, the tile and its
+  settings as the page stores them — beside `input`, in `action` and in `authorize` (and as
+  `BLOCK_TOKEN`). The browser only says which block on which page calls; the runner reads that block
+  off the published page itself (a draft's, for the site's editors), so the settings are the site
+  author's and can be trusted. `useServerAction` sends where the call comes from without the
+  component doing anything.
+- Updated dependencies
+  - @mosetta/server-action@0.0.13
+  - @mosetta/server@0.0.13
+  - @mosetta/core@0.0.13
+  - @mosetta/di@0.0.13
+  - @mosetta/runtime@0.0.13
+
+## 0.0.12
+
+### Patch Changes
+
+- `@mosetta/react` ships AUTHORING.md: what a tile is made of and the rules it lives by — sides,
+  settings and their schema, children and slots, styling, the editor side, server actions with their
+  access, inputs and secrets, and what a project's tile palette on a platform may hold. A catalog entry
+  (`@mosetta/content`) may name the public base of its tile host, for a block of a host other than the
+  site's primary.
+  - @mosetta/server@0.0.12
+  - @mosetta/core@0.0.12
+  - @mosetta/di@0.0.12
+  - @mosetta/runtime@0.0.12
+  - @mosetta/server-action@0.0.12
+
 ## 0.0.11
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,8 @@
 # @mosetta/react
 
-The React binding of the mosetta protocol: what a tile's sides are written with.
+The React binding of the mosetta protocol: what a tile's sides are written with. The whole of it —
+sides, settings schemas, editor forms, server actions, the rules a palette lives by — is in
+[AUTHORING.md](./AUTHORING.md), shipped with the package.
 
 A tile is a folder under `tiles/` whose files are its sides — `tiles/<name>/<name>.<side>.tsx`. The
 component side is what the visitor sees; it reads the settings a content manager filled in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosetta/react",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "React binding of the mosetta protocol: side definers, hooks, blueprint renderer, DI adapter, server-action hook, startAndMount. Subpath exports only (no barrel) — each entry ships as its own package tile; ./context is the internal state-singleton entry the others re-export from.",
   "license": "MIT",
   "type": "commonjs",
@@ -13,11 +13,11 @@
   "dependencies": {
     "react": "*",
     "react-dom": "*",
-    "@mosetta/core": "0.0.11",
-    "@mosetta/di": "0.0.11",
-    "@mosetta/runtime": "0.0.11",
-    "@mosetta/server": "0.0.11",
-    "@mosetta/server-action": "0.0.11"
+    "@mosetta/core": "0.0.13",
+    "@mosetta/runtime": "0.0.13",
+    "@mosetta/server": "0.0.13",
+    "@mosetta/server-action": "0.0.13",
+    "@mosetta/di": "0.0.13"
   },
   "devDependencies": {
     "@types/react": "*",

package/src/hooks/NodeContext.tsx

@@ -91,6 +91,9 @@ export const ProvideNode = NodeContext.Provide;
 
 export const useNode = NodeContext.use;
 
+/** the node a component renders in, or null outside a page's tree (a hosted mount, a tool) */
+export const useNodeOptional = NodeContext.useOptional;
+
 function useNodeState(): INodeState {
   const { id } = useNode();
   const di = useDi(DI_CONTAINER_TOKEN);

package/src/serverAction.ts

@@ -19,8 +19,10 @@
 // conditional hooks (branches are value-level), no module-level shared state. Opt-in suspense throws
 // the waiter promise — the legacy protocol both runtimes (and preact's renderToStringAsync) support.
 import { useCallback, useState, useSyncExternalStore } from 'react';
-import { useComponent } from '@mosetta/react';
+import { useComponent, useDiOptional, useNodeOptional } from '@mosetta/react';
 import { useDi } from '@mosetta/react';
+import { PAGE_MANAGER_TOKEN } from '@mosetta/runtime/client';
+import { blockOrigin } from '@mosetta/server-action/core';
 import {
   EServerActionStart,
   EXECUTION_ENV_TOKEN,
@@ -82,6 +84,13 @@ export function useServerAction<TIn extends {}, TOut>(
   ensureServerActionClient(di);
   const manager = useDi(SERVER_DATA_MANAGER);
   const { reference } = useComponent();
+  // where the call comes from — this node on the page shown now — for the host to read the
+  // block's settings itself (core.ts BLOCK_ORIGIN_HEADER); none outside a page. Asked again at
+  // every mutation: a block a move onto another page keeps is that page's block from then on
+  const pages = useDiOptional(PAGE_MANAGER_TOKEN);
+  const nodeId = useNodeOptional()?.id;
+  const originNow = (): string | null => blockOrigin(pages ? (pages.getCurrentPage() as { origin?: string }).origin : null, nodeId);
+  const origin = originNow();
 
   const env = useDi(EXECUTION_ENV_TOKEN);
   const recorder = useDi(SSR_ACTION_RECORDER_TOKEN);
@@ -116,18 +125,21 @@ export function useServerAction<TIn extends {}, TOut>(
         actionName: token.actionName,
         invalidates: mergeTags(token.invalidates, options.invalidates),
         customSerializer: token.customSerializer,
+        originOf: originNow,
       });
     }
     return null;
   });
 
-  const key = localHandle ? null : `${fullId}/${token.actionName}#${stableStringify(options.input)}`;
+  // two blocks of one tile asking with one input are two questions: the host answers each by its
+  // own block's settings
+  const key = localHandle ? null : `${fullId}/${token.actionName}#${stableStringify(options.input)}${origin ? `@${origin}` : ''}`;
   if (key !== null) {
     // render-phase, but idempotent by key (start-on-first-read); a new input → a new key → a new query
     manager.ensureQuery({
       key,
       tags: mergeTags(token.tags, options.tags),
-      request: { fullId, actionName: token.actionName, input: options.input },
+      request: { fullId, actionName: token.actionName, input: options.input, ...(origin ? { origin } : {}) },
       customSerializer: token.customSerializer,
     });
     // the head channel's counter waits for this query from the SAME render that started it