@mosetta/react 0.0.11 → 0.0.12

package/AUTHORING.md

@@ -0,0 +1,183 @@
+# 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`).
+
+## 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,20 @@
 # @mosetta/react
 
+## 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.12",
   "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.12",
+    "@mosetta/di": "0.0.12",
+    "@mosetta/runtime": "0.0.12",
+    "@mosetta/server": "0.0.12",
+    "@mosetta/server-action": "0.0.12"
   },
   "devDependencies": {
     "@types/react": "*",