npm - @u-krupaveho-kraba/form-editor-schemas - Versions diffs - 0.1.0 → 0.2.0 - Mend

@u-krupaveho-kraba/form-editor-schemas 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/index.js +2 -0
package/package.json +2 -2
package/schemas/editorTheme.js +102 -0
package/schemas/notification.js +36 -0
package/schemas/options.js +33 -0
package/types/index.d.ts +2 -0
package/types/schemas/campaignItem.d.ts +969 -105
package/types/schemas/editorTheme.d.ts +72 -0
package/types/schemas/notification.d.ts +38 -0
package/types/schemas/options.d.ts +1370 -120

package/index.js CHANGED Viewed

@@ -1,4 +1,6 @@
 export * from "./schemas/campaignItem.js";
 export * from "./schemas/theme.js";
+export * from "./schemas/editorTheme.js";
 export * from "./schemas/fileManager.js";
+export * from "./schemas/notification.js";
 export * from "./schemas/options.js";

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@u-krupaveho-kraba/form-editor-schemas",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zod schemas for the Topol Form Editor's host-facing init/save contract",
   "author": "Topol.io",
   "license": "ISC",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@u-krupaveho-kraba/form-schemas": "^0.4.0",
+    "@u-krupaveho-kraba/form-schemas": "^0.5.0",
     "zod": "^4.1.11"
   }
 }

package/schemas/editorTheme.js ADDED Viewed

@@ -0,0 +1,102 @@
+import * as z from "zod/mini";
+/**
+ * The Host-settable look of the **editor's own UI chrome** -- the accent
+ * colour on buttons, active states and the canvas selection outline, the
+ * gray ramp every panel and toolbar is built from, the corner radii and the
+ * UI font.
+ *
+ * Not to be confused with `themes` (`./theme.ts`), which is the Brand Kit /
+ * Theme Panel library that styles *the form being built* (ADR 0022). The
+ * two are unrelated concerns that happen to share the word "theme": this
+ * one never reaches a published form, and `themes` never touches the
+ * editor's chrome.
+ *
+ * Deliberately the same shape as email-editor's and LPE's `theme` option
+ * (`apps/email-editor/src/schemas/theme/themeSchema.ts`), so a Host
+ * embedding more than one editor passes one object to all of them and they
+ * match. Applied as CSS custom properties on `<html>` by `setTheme()`
+ * (`@topol/utils`) -- no recompile, no store.
+ *
+ * The one key dropped from email-editor's shape is `canvasColor`, which
+ * sets `--c-email-canvas`: that is the paper colour behind an *email*
+ * template, a var no form-editor stylesheet reads. Everything else is kept
+ * even where form-editor happens not to read the var today, so that this
+ * and email-editor's option stay one shape rather than two that drift.
+ */
+export const EditorThemeSchema = z.object({
+    /**
+     * Which built-in gray ramp and accent to start from before any `colors`
+     * override. Defaults to `"dark"`, which is how the editor has always
+     * looked; `"light"` is the same ramp inverted.
+     *
+     * **`"light"` is accepted but not yet audited in the Form Editor**
+     * (ticket 196). The mechanism works -- the ramp inverts, the accent
+     * swaps -- but the Form Editor's own chrome was authored against the
+     * dark ramp only, so some utilities mean "a light surface" and get a
+     * dark one. Measured examples: the element-tile label drops to 3.28:1
+     * (below WCAG AA), and the band framing the canvas (`bg-gray-100`)
+     * inverts from light to dark. Kept in the contract rather than rejected
+     * so a Host can pass one theme object to every editor it embeds, per
+     * this schema's whole purpose.
+     */
+    preset: z.optional(z.enum(["light", "dark"])),
+    /**
+     * Corner radii for the editor's own controls, as CSS lengths ("4px",
+     * "0.5rem"). `small`/`large` also set `--b-radius-small`/`--b-radius-large`
+     * for `@topol/ui`'s older components.
+     */
+    borderRadius: z.optional(z.object({
+        extraSmall: z.optional(z.string()),
+        small: z.optional(z.string()),
+        large: z.optional(z.string()),
+        extraLarge: z.optional(z.string()),
+    })),
+    /**
+     * The editor UI's font. `url` is injected as a stylesheet link (a Google
+     * Fonts href, say) and `family` becomes `--font-family-primary`; a
+     * `family` with no comma gets a `, sans-serif` fallback appended.
+     */
+    font: z.optional(z.object({
+        family: z.optional(z.string()),
+        url: z.optional(z.string()),
+    })),
+    /**
+     * Individual overrides on top of `preset`. The numeric keys are the gray
+     * ramp, `"900"` being the darkest surface under `preset: "dark"`.
+     *
+     * The primary/accent knob most Hosts want is `active` -- it drives
+     * `--c-accent-1`, which is the editor's buttons, active states, focus
+     * outlines and the canvas selection outline.
+     */
+    colors: z.optional(z.object({
+        "900": z.optional(z.string()),
+        "800": z.optional(z.string()),
+        "700": z.optional(z.string()),
+        "600": z.optional(z.string()),
+        "500": z.optional(z.string()),
+        "400": z.optional(z.string()),
+        "300": z.optional(z.string()),
+        "200": z.optional(z.string()),
+        "100": z.optional(z.string()),
+        "50": z.optional(z.string()),
+        "10": z.optional(z.string()),
+        white: z.optional(z.string()),
+        primary: z.optional(z.string()),
+        "primary-light": z.optional(z.string()),
+        "primary-light-2": z.optional(z.string()),
+        "primary-dark": z.optional(z.string()),
+        secondary: z.optional(z.string()),
+        "secondary-light": z.optional(z.string()),
+        "secondary-light-2": z.optional(z.string()),
+        error: z.optional(z.string()),
+        "error-light": z.optional(z.string()),
+        success: z.optional(z.string()),
+        "success-light": z.optional(z.string()),
+        /** The editor's primary accent -- `--c-accent-1`. */
+        active: z.optional(z.string()),
+        "active-2": z.optional(z.string()),
+        "active-3": z.optional(z.string()),
+        "locked-structure": z.optional(z.string()),
+        "locked-content": z.optional(z.string()),
+    })),
+});

package/schemas/notification.js ADDED Viewed

@@ -0,0 +1,36 @@
+import * as z from "zod/mini";
+/**
+ * A transient, app-level message -- the Form Editor's notifications, declared
+ * here rather than app-locally because a Host can receive them: with
+ * `disableAlerts`, every notification is routed to the Host's `onAlert`
+ * instead of being rendered in the editor, so this shape crosses the wire.
+ *
+ * Deliberately identical to the Email Editor's and Landing Page Editor's
+ * `INotification`, minus two fields:
+ *
+ * - `expectSideEffect` is set at four call sites across those two apps and
+ *   read at none. Carrying a field nothing consumes into a *new* published
+ *   contract would mean hosts writing against something that does nothing.
+ * - `extarnalUse` (sic) means "render in-editor even when alerts are
+ *   disabled". It has real consumers there -- init/auth failures a Host may
+ *   not be listening for yet -- but none here, and it would arrive with its
+ *   typo preserved or with a silent rename. When the Form Editor grows a
+ *   notification that must survive `disableAlerts`, add it then, spelled
+ *   correctly.
+ */
+export const NotificationTypeSchema = z.enum(["info", "success", "error"]);
+export const EditorNotificationSchema = z.object({
+    /** Optional bold first line. Rendered above `text` when present. */
+    title: z.optional(z.string()),
+    /** The message itself, already translated -- callers own i18n. */
+    text: z.string(),
+    type: NotificationTypeSchema,
+    /** Suppresses the auto-dismiss timer; the notification stays until closed. */
+    persistent: z.optional(z.boolean()),
+    /**
+     * Assigned by the editor when the notification is created, not by the
+     * caller -- optional here because it only exists once a notification is
+     * live. A Host receiving one through `onAlert` always sees it set.
+     */
+    id: z.optional(z.string()),
+});

package/schemas/options.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import * as z from "zod/mini";
 import { FormThemeSchema, InputFieldSchema, PreferenceSchema, } from "@u-krupaveho-kraba/form-schemas";
 import { CampaignItemSchema, } from "./campaignItem.js";
+import { EditorThemeSchema } from "./editorTheme.js";
 import { FileManagerOptionsSchema } from "./fileManager.js";
 import { ThemeGroupSchema, } from "./theme.js";
 /**
@@ -61,6 +62,17 @@ export const EditorCallbacksSchema = z.object({
     onCreatePreference: z.optional(callback()),
     /** Fired when the editor fails to initialize, or when a payload the Host sent fails validation (ADR 0029 decision 3). */
     onError: z.optional(callback()),
+    /**
+     * Receives every notification the editor would otherwise have rendered
+     * itself, so a Host can surface them in its own UI -- same `{ notification }`
+     * argument shape LPE's `onAlert` uses, so a Host already embedding that
+     * editor can reuse its handler.
+     *
+     * Only called when `disableAlerts` is on. Unlike every other optional
+     * callback here, its *presence* is not the affordance: the editor keeps
+     * rendering its own notifications until a Host explicitly asks it to stop.
+     */
+    onAlert: z.optional(callback()),
     /** Fired when the user clicks the WindowBar's close button (requires `"close"` in `windowBar`). The Host is responsible for tearing down/hiding the editor -- the child does not attempt its own teardown. */
     onEditorClose: z.optional(callback()),
     /**
@@ -164,6 +176,17 @@ export const TopolFormEditorOptionsSchema = z
     language: z.optional(EditorLanguageSchema),
     /** Per-key overrides for editor UI strings, keyed by dot-path (e.g. "controls.autosaves.title"). Applied once at bootstrap, merged into whichever locale ends up active. */
     textOverride: z.optional(z.record(z.string(), z.string())),
+    /**
+     * The look of the editor's own UI chrome -- accent colour, gray ramp,
+     * corner radii, UI font. Same option name and shape as email-editor's
+     * and LPE's `theme`, so a Host embedding several editors passes one
+     * object to all of them. Omit it and the editor looks exactly as it
+     * always has (`preset: "dark"`).
+     *
+     * Note the neighbour below: `theme` is the *editor*, `themes` is the
+     * *form being built*. They are unrelated (see `./editorTheme.ts`).
+     */
+    theme: z.optional(EditorThemeSchema),
     /** Accepts the legacy flat shape for backward compatibility; a Host App is encouraged to move to `ThemeGroup[]` to supply locked/Brand Kit themes. */
     themes: z.optional(z.union([z.array(FormThemeSchema), z.array(ThemeGroupSchema)])),
     previewUrl: z.optional(z.string()),
@@ -214,5 +237,15 @@ export const TopolFormEditorOptionsSchema = z
     ])),
     comments: z.optional(CommentsConfigSchema),
     autosaves: z.optional(AutosaveConfigSchema),
+    /**
+     * Stops the editor rendering its own notifications and routes them to
+     * `callbacks.onAlert` instead, for a Host that wants them in its own UI
+     * (same option name and meaning as LPE's `disableAlerts`).
+     *
+     * Honoured only when `onAlert` is actually wired up -- a Host that sets
+     * this without it would otherwise silence the editor into a black hole,
+     * which is strictly worse than the notifications it asked to be rid of.
+     */
+    disableAlerts: z.optional(z.boolean()),
 })
     .check(z.refine(onlyOneOfItemAndItems, ITEM_AND_ITEMS_EXCLUSIVE_MESSAGE));

package/types/index.d.ts CHANGED Viewed

@@ -1,4 +1,6 @@
 export * from "./schemas/campaignItem.js";
 export * from "./schemas/theme.js";
+export * from "./schemas/editorTheme.js";
 export * from "./schemas/fileManager.js";
+export * from "./schemas/notification.js";
 export * from "./schemas/options.js";