@plitzi/sdk-shared 0.33.2 → 0.34.0

package/dist/types/SchemaTypes.d.ts

@@ -1,7 +1,24 @@
-import { InteractionCallback, InteractionCallbackParamValues, InteractionCallbackType } from './InteractionTypes';
+import { InteractionCallbackParamValues, InteractionCallbackType } from './InteractionTypes';
 import { Style } from './StyleTypes';
 import { RuleGroup } from '@plitzi/plitzi-ui/QueryBuilder';
 export type ElementRuntime = 'server' | 'client' | 'shared';
+/**
+ * When an element's CONTENTS are mounted, relative to its own `visibility`.
+ *
+ * About the subtree, never about the element itself: whatever a hidden element registers — a modal's `openModal`
+ * callback, a form's source, an interaction trigger — is registered by the element, so an element that stops
+ * rendering is an element nothing can ever show again. The shell always renders; what these decide is its items.
+ *
+ * - `eager` (default): always mounted. Right for an element that is on screen almost always — deferring it would only
+ *   add a render cycle between the page loading and the page appearing — and for a hidden element whose contents
+ *   have to be in the server's HTML: a section a search engine should read, a panel a CSS-only accordion opens
+ *   without the SDK's help.
+ * - `lazy`: mounted the first time it is shown, and kept from then on. The one for elements that start hidden by
+ *   nature, and those declare it themselves — a modal or a dialog nobody opens costs nothing, and one that has been
+ *   opened keeps what the visitor typed into it.
+ * - `visible`: mounted only while shown. Pays the build cost on every reveal and drops the subtree's state on
+ *   every hide — worth it for contents that are expensive to KEEP (a live map, a video, a polling source).
+ */
 export type ElementLoadStrategy = 'eager' | 'lazy' | 'visible';
 export type SchemaRsc = {
     enabled?: boolean;
@@ -23,7 +40,7 @@ export type ElementBinding = {
     enabled?: boolean;
     to: string;
 };
-export type ElementInteraction<T extends Record<keyof InteractionCallback['params'], unknown> = Record<string, unknown>> = {
+export type ElementInteraction<T extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
     title: string;
     type: InteractionCallbackType;
@@ -57,12 +74,19 @@ export type ElementDefinition = {
     };
     /** Where this element is rendered. 'server' = SSR only, 'client' = browser only, 'shared' = both (default). */
     runtime?: ElementRuntime;
-    /** Controls when the element is loaded/rendered. */
+    /** When this element's items are mounted, relative to its `visibility`. See {@link ElementLoadStrategy}. */
     loadStrategy?: ElementLoadStrategy;
 };
+/**
+ * An element, keyed by the one name it answers to.
+ *
+ * `id` is that name: the `flat` key, what `parentId`/`items`/`rootId` point at, the `<type>_<id>` a binding's source
+ * is built from, and the target an interaction wires to. It is chosen — typed by a person in the builder's tree,
+ * written by an agent, or minted as `<type>-<n>` — never an opaque generated handle, so the key an author writes
+ * down is the key the runtime resolves. `definition.label` stays free display text and wires nothing.
+ */
 export type Element<TAttributes extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
-    idRef?: string;
     attributes: TAttributes & {
         subType?: string;
     };
@@ -144,6 +168,7 @@ export type SchemaContextValue = {
     schemaUpdate?: (newSchema: SchemaRaw, fromSubscriptions?: boolean) => void;
     schemaAddElement?: (to: string, data: Element, dropPosition?: DropPosition, initialItems?: Record<string, Element>, variables?: SchemaVariable[], fromSubscriptions?: boolean) => void;
     schemaUpdateElement?: (element: Element, fromSubscriptions?: boolean) => void;
+    schemaRenameElement?: (elementId: Element['id'], id: Element['id'], fromSubscriptions?: boolean) => void;
     schemaUpdateElements?: (elements: Element[], fromSubscriptions?: boolean) => void;
     schemaMoveElement?: (from: string, to: string, elementId: string, dropPosition?: DropPosition, fromSubscriptions?: boolean) => void;
     schemaCloneElement?: (elementId: string, targetId?: string, fromSubscriptions?: boolean) => void;