@plitzi/sdk-shared 0.33.2 → 0.34.0

package/dist/types/StoreTypes.d.ts

@@ -1,3 +1,4 @@
+import { ActionField } from './ActionTypes';
 import { SubscriptionCollaborator, SubscriptionCollaboratorPointer } from './BuilderTypes';
 import { Environment, RenderMode } from './CommonTypes';
 import { Source } from './DataSourceTypes';
@@ -6,6 +7,7 @@ import { Schema, Element } from './SchemaTypes';
 import { Segment } from './SegmentTypes';
 import { SpaceConnector } from './SpaceTypes';
 import { DisplayMode, Style, StyleState } from './StyleTypes';
+import { ColorScheme, Theme } from './ThemeTypes';
 export type RuntimeSourceValues = {
     variables?: Record<string, unknown>;
     navigation?: {
@@ -14,9 +16,7 @@ export type RuntimeSourceValues = {
     };
     auth?: Record<string, unknown>;
     state?: Record<string, unknown>;
-    /** @deprecated Use the `state` source (mirrors `runtime.state`). Kept as an alias so existing `page.*` bindings keep
-     * working; it still carries the runtime state plus `currentPageId`. */
-    page?: Record<string, unknown>;
+    host?: Record<string, unknown>;
 };
 export type CommonState = {
     prevSchema?: Schema;
@@ -27,16 +27,45 @@ export type CommonState = {
     runtime?: {
         sources: RuntimeSourceValues & Record<string, unknown>;
         state?: Record<string, unknown>;
+        /**
+         * What the embedding application handed this space — its screens, who is signed in to IT, whatever a shell
+         * needs to render. Written by whoever mounts the SDK and mirrored to `runtime.sources.host`.
+         *
+         * The counterpart of the `hostAction` step: without it that step is a one-way shout, because a shell cannot
+         * list the host's screens unless the host can give it the list.
+         */
+        host?: Record<string, unknown>;
         elements?: Record<string, unknown>;
     };
     sources?: Record<string, Source>;
     rsc?: RscState;
+    actions?: ActionsState;
     render?: RenderSettings;
+    /**
+     * The theme, mirrored from `themeStore` so it reads like everything else: `{{ theme.resolved }}` in a binding, a
+     * `when` rule that switches on it, and one line in the devtools store viewer that answers "which theme is this".
+     *
+     * A MIRROR and never the source. The theme has to be readable by things that are not under any provider — the
+     * dev-tools panel in its shadow root, an editor in a portal — which no app store can serve, so `themeStore` owns
+     * it and `ThemeProvider` publishes it here. Write through `useTheme`/`setThemeMode`; writing this copy changes
+     * the value nobody reads. Same contract `navigation` has below, for the same reason.
+     *
+     * Ephemeral: excluded from history (a toggle is not an edit) and not persisted here — `ThemeProvider` keeps it
+     * in a cookie, which is the one place a server can read it back from.
+     */
+    theme?: {
+        mode: Theme;
+        resolved: ColorScheme;
+        areas: Record<string, Theme>;
+    };
     navigation: {
         urlSearchParams?: URLSearchParams;
         routeParams: RouteParams;
         queryParams: QueryParams;
         hostname: string;
+        /** Scheme, host AND port — what a link needs to name this page absolutely. `hostname` has no port, which is why
+         *  it answers `when` rules and cannot answer this. */
+        origin: string;
         currentPageId: string;
         navigate: (url: string, isExternal?: boolean) => void;
     };
@@ -50,12 +79,94 @@ export type RenderSettings = {
     renderMode?: RenderMode;
     environment?: Environment;
     isHydrating?: boolean;
+    /**
+     * Whether React has finished hydrating this render — false during the pass that has to match the server's markup,
+     * true from the commit after it. Only ever true on a render that was hydrating in the first place; a client-only
+     * render has no markup to match and never sets either flag.
+     *
+     * It exists because "this render came from SSR" and "the SSR markup has been reconciled" are different questions,
+     * and everything that must not run until the second one has happened had no way to ask it. Restoring persisted
+     * state is the case that forced it: what a browser kept from last time is, by definition, something the server
+     * could not know, so applying it during the hydrating pass is a guaranteed mismatch — and React answers a mismatch
+     * by throwing away the whole tree it happened in, not the one node.
+     */
+    hydrated?: boolean;
+    /**
+     * This space is over its plan's quota, as the SERVER decided when it metered the render.
+     *
+     * Not the visitor's business and not the page's either — it is a fact about the account behind the site, which is
+     * why it rides the render surface rather than the schema: nothing an author writes can set it, and nothing in the
+     * space's settings can turn it off. `branding` is forced on by the same state; this is what says WHY.
+     */
+    overQuota?: boolean;
+    /**
+     * Whether every element carries `data-plitzi-el="<its id>"`, which is what an end-to-end test addresses it by.
+     *
+     * On unless a deployment says otherwise, and that default is the point: a consumer's own suite has to work
+     * against their own build without configuring anything, and the ids are already in the page — the schema the
+     * browser hydrates from carries every one of them, so the attribute publishes nothing new.
+     *
+     * `authorSpace` returns the matching handles, so a spec names `handles.hero.cta` rather than a string somebody
+     * has to keep in step with the document by hand.
+     */
+    testAttributes?: boolean;
+};
+/** Absent `endpoint` is the whole feature switch: a render with no server tier leaves every `serverAction` step
+ *  inert instead of letting each click discover a 404. */
+export type ActionsState = {
+    endpoint?: string;
+    /**
+     * What this space can run, for the editor that offers it.
+     *
+     * Authoring data, seeded by the builder from the space's own actions and empty everywhere else — a published
+     * page names one action and has no business holding a directory of the others. It is here rather than in
+     * `BuilderState` because the step that reads it is registered by the SDK runtime, in the same place a
+     * `navigate` step reads the page list: one vocabulary, and the options come from whoever knows them.
+     *
+     * A deployment answers it through `listActions`, so a self-hoster's own actions show up in their editor for the
+     * same reason their own tasks do.
+     */
+    catalog?: ActionCatalogEntry[];
+    /**
+     * Whether the target this space publishes to can run actions AT ALL.
+     *
+     * Seeded by the builder from the space's deployments, and absent everywhere else — a rendered page does not need
+     * to be told, it has an `endpoint` or it does not. It exists so a step can say "this space deploys nowhere that
+     * runs server code" while it is being authored, rather than at the first click in production.
+     */
+    available?: boolean;
+};
+/** One action as a picker needs it: what to store, what to show, and what it takes. Never the flow itself. */
+export type ActionCatalogEntry = {
+    identifier: string;
+    name: string;
+    /** The fields the `call` trigger declares, so an editor can say what an action expects before it is called. */
+    input: Record<string, ActionField>;
 };
 export type RscState = {
     enabled?: boolean;
     endpoint?: string;
     loaded?: boolean;
     data?: Record<string, unknown>;
+    /**
+     * True when the last refresh could not reach the server, so what every server element is showing is from before
+     * that.
+     *
+     * A refresh failing is not an error — the payload is supplemental, and dropping it keeps the page working — but
+     * silently keeping the old data is a page that looks current and is not. Published so an author can bind it and
+     * say so; cleared by the first refresh that gets through.
+     */
+    stale?: boolean;
+    /**
+     * The location the payload in `data` was resolved for — `pathname + search`, as the request carried it.
+     *
+     * A route change in the browser renders the new page immediately, while the answer for it is still in flight.
+     * Without this the payload sitting in the store is indistinguishable from one belonging to the page being
+     * shown, and every element on it reads "no slice for me": a binding with no value leaves the element as it was
+     * authored, so a visibility binding paints *visible* and an empty section is drawn and then corrected. Elements
+     * compare this against where the visitor actually is, and a mismatch means "not mine yet" rather than "gone".
+     */
+    location?: string;
 };
 export type BuilderState = CommonState & {
     collaboration: {
@@ -64,6 +175,22 @@ export type BuilderState = CommonState & {
     };
     connectors: Record<string, SpaceConnector>;
     hasServerRendering: boolean;
+    /**
+     * A URL the author is trying the page ON, instead of the one the editor itself is open at.
+     *
+     * The builder's own address is `/spaces/12/builder`, so a page whose route takes a `:slug`, a variable that
+     * switches on `?plan=pro`, or a binding that reads the hostname has nothing real to resolve against — the author
+     * had to publish to find out what any of it does. What is set here is laid over what the browser gives, in the
+     * one place that publishes `navigation.*`, so everything downstream of it — variable `when` rules, bindings,
+     * server-driven elements, an action's input — sees the URL being tested and not the editor's own.
+     *
+     * Editor-only and never published: `navigation` still holds the resolved values, which is what the page reads.
+     */
+    urlTest?: {
+        routeParams: RouteParams;
+        queryParams: QueryParams;
+        hostname: string;
+    };
     displayMode: DisplayMode;
     selector?: string;
     styleSelector?: string;
@@ -83,7 +210,17 @@ export type PropChange = {
     ref?: boolean;
 };
 export type CommitElementRender = {
+    /**
+     * This INSTANCE, not this element.
+     *
+     * A controlled list renders the same element once per row, and the element's id is the same string every time. Keyed
+     * by that, a hundred rows collapsed into one node: the flamegraph drew a single row carrying the last instance's
+     * timing, and the ninety-nine renders that made the commit expensive were nowhere in it. This is the identity React
+     * itself uses — one key per mounted component — so the tree the panel draws is the tree that rendered.
+     */
     id: string;
+    /** Which element this instance is, for the label, the schema lookup and the outline on the page. */
+    elementId: string;
     parentId?: string;
     phase: RenderPhase;
     actualDuration: number;
@@ -105,8 +242,49 @@ export type CommitEntry = {
 export type TracingTreeNode = {
     parentId?: string;
     baseDuration: number;
+    /** Which element this instance is — see `CommitElementRender.id`. */
+    elementId: string;
 };
 export type TracingTree = Record<string, TracingTreeNode>;
+/**
+ * One server action this page started, as the dev-tools show it back.
+ *
+ * Recorded by the `runServerAction` step itself, so it covers what no network tab makes legible: which action was
+ * named, in which mode, what the server answered, and — when the deployment is a dev one, which is the only time
+ * the server sends it — the STEPS the flow ran on the other side. A `detached` run has no answer to await and a
+ * `stream` returns before its frames arrive, so both are invisible without a record of their own.
+ */
+export type ActionRunEntry = {
+    /** Local to this page: assigned when the run is SENT, which is before any server run id exists. */
+    id: string;
+    actionId: string;
+    mode: 'await' | 'detached' | 'stream';
+    /** The server's own id, once it answers. Absent for a run that never reached one. */
+    runId?: string;
+    status: 'running' | 'completed' | 'failed' | 'accepted' | 'streaming' | 'skipped' | 'aborted';
+    /** The server's vocabulary when it refused: `duplicate`, `over_capacity`, `recursion`, `forbidden`… */
+    reason?: string;
+    /** What went wrong, when anything says so. Never a credential — the server redacts before answering. */
+    error?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    /** Chunks a streaming run emitted, in order. */
+    progress: unknown[];
+    /** The server-side steps, when the deployment sent them: authoring requests and dev servers only. */
+    trace?: Record<string, unknown>[];
+    /**
+     * Whether this run can still be stopped from the panel.
+     *
+     * True while it is in flight and the step that started it is still holding the handle. It is what lets the
+     * dev-tools offer a Cancel on a run that is happening rather than on one that already ended.
+     */
+    cancellable?: boolean;
+    startedAt: number;
+    endedAt?: number;
+};
+export type ActionRunsState = {
+    runs: ActionRunEntry[];
+};
 export type TracingState = {
     enabled: boolean;
     hydrated: boolean;

package/dist/types/StyleTypes.d.ts

@@ -1,10 +1,10 @@
+import { ColorScheme, Theme } from './ThemeTypes';
 import { default as styleConstants } from '../style/styleConstants';
 export type TagType = 'class' | 'element' | 'id';
 export type DisplayMode = 'desktop' | 'tablet' | 'mobile';
 export type StyleMode = 'mobile-first' | 'desktop-first';
 export type StyleState = 'hover' | 'active' | 'focus' | 'disabled' | 'checked' | 'visited';
 export type StyleValue = number | string;
-export type StyleThemeMode = 'system' | 'light' | 'dark';
 export type StyleCategory = (typeof styleConstants)[keyof typeof styleConstants];
 export declare enum StyleVariableCategory {
     COLOR = "color",
@@ -12,7 +12,7 @@ export declare enum StyleVariableCategory {
     SHADOW = "shadow",
     CUSTOM = "custom"
 }
-export type StyleThemeValue = Partial<Record<Exclude<StyleThemeMode, 'system'> | 'default', string>>;
+export type StyleThemeValue = Partial<Record<ColorScheme | 'default', string>>;
 export type StyleVariableValue = string | number | StyleThemeValue;
 export type StyleVariableGroup = Record<string, StyleVariableValue>;
 export type StyleVariables = Record<StyleVariableCategory, StyleVariableGroup>;
@@ -33,14 +33,90 @@ export type StyleItem = {
     cache: string;
     componentType?: string;
 };
+export type FontSource = 'system' | 'google' | 'remote' | 'hosted';
+export type FontStyle = 'normal' | 'italic';
+export type FontDisplay = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+/** One face of a family: the file carrying a given weight and slant. */
+export type FontFace = {
+    weight: number;
+    style: FontStyle;
+    format: 'woff2' | 'woff';
+    /** Limits the face to the code points it covers, so the browser fetches it only when needed. */
+    unicodeRange?: string;
+};
+export type FontBase = {
+    /** What `font-family` names. Unique within a space. */
+    family: string;
+    /** Appended to the stack — `'Lato', sans-serif` — and what renders while the face loads. */
+    fallback: string;
+    /** The weights the family really provides: what the picker offers, and what it disables against. */
+    weights: number[];
+    styles: FontStyle[];
+    display?: FontDisplay;
+    /** Worth a `<link rel="preload">`. The body family, and at most one more: preloading everything
+     *  is the same as preloading nothing. */
+    preload?: boolean;
+};
+/** Installed nowhere: a stack the visitor's system already has. Costs no bytes. */
+export type SystemFont = FontBase & {
+    source: 'system';
+};
+/** Google Fonts, reached through the single aggregated `css2` request the resolver builds. */
+export type GoogleFont = FontBase & {
+    source: 'google';
+    subsets?: string[];
+};
+/** Someone else's origin — Adobe Fonts, Bunny, Fontshare, the customer's own CDN. Either a
+ *  stylesheet that declares the faces, or the files themselves. */
+export type RemoteFont = FontBase & {
+    source: 'remote';
+    stylesheet?: string;
+    files?: (FontFace & {
+        url: string;
+    })[];
+};
+/** Uploaded to this deployment's font store. `path` is store-relative and never absolute: a
+ *  manifest that carried `https://cdn.plitzi.com/...` would follow a space onto a server that is
+ *  not ours and keep asking Plitzi for its fonts. The URL is made at render time. */
+export type HostedFont = FontBase & {
+    source: 'hosted';
+    files: (FontFace & {
+        path: string;
+    })[];
+};
+export type SpaceFont = SystemFont | GoogleFont | RemoteFont | HostedFont;
+/** What a surface needs to put in its `<head>` for a manifest — see `fontsToHead`. */
+export type FontHead = {
+    /** `crossorigin` where the origin serves the FILES: a font is fetched in CORS mode, and a preconnect that
+     *  omits it warms a connection the font fetch then cannot use. A stylesheet origin takes it off. */
+    preconnect: {
+        href: string;
+        crossorigin?: boolean;
+    }[];
+    links: {
+        href: string;
+        rel: 'stylesheet' | 'preload';
+        as?: 'style' | 'font';
+        type?: string;
+        crossorigin?: boolean;
+    }[];
+    /** `@font-face` blocks, as CSS text. Empty when every family is system or linked. */
+    faces: string;
+    /** Every origin the manifest reaches for, for a CSP that has to name them. */
+    origins: string[];
+};
 export type Style = {
     platform: Record<DisplayMode, Record<string, StyleItem>>;
     mode?: StyleMode;
     theme: {
-        default: StyleThemeMode;
-        schemes: StyleThemeMode[];
+        default: Theme;
+        schemes: Theme[];
     };
     variables: Partial<StyleVariables>;
+    /** The families this space declares. A `font-family` naming anything absent from here renders in a fallback,
+     *  because nothing else in the system loads a face. Optional because a document written before the manifest
+     *  existed has none, and that is a real state every reader has to survive rather than a bug. */
+    fonts?: SpaceFont[];
     cache: string;
 };
 export type StyleContextValue = {
@@ -55,6 +131,9 @@ export type StyleContextValue = {
     styleAddVariable?: unknown;
     styleUpdateVariable?: unknown;
     styleRemoveVariable?: unknown;
+    styleAddFont?: unknown;
+    styleUpdateFont?: unknown;
+    styleRemoveFont?: unknown;
     styleAddTemplate?: unknown;
     styleUpdateSettings?: unknown;
 };

package/dist/types/TemplateTypes.d.ts

@@ -0,0 +1,20 @@
+import { Element, Schema } from './SchemaTypes';
+import { Style } from './StyleTypes';
+/**
+ * A published template: a subtree, the style that dresses it, and the element a builder instantiates.
+ *
+ * The artefact someone hosts when they are not building a space — fetched by URL, shown in the Resources panel,
+ * dragged onto a canvas — which is why it lives beside the schema and the style rather than with the builder's own
+ * types: it is a document, produced and consumed by processes that never open a builder.
+ */
+export type Template = {
+    id?: string;
+    definition: {
+        name: string;
+        description: string;
+        /** Root of what travels. Its subtree is the whole of `schema.flat`, and it answers to no parent. */
+        baseElementId: Element['id'];
+    };
+    schema: Schema;
+    style: Style;
+};

package/dist/types/ThemeTypes.d.ts

@@ -1,5 +1,32 @@
 export type Theme = 'dark' | 'light' | 'system';
-export type ThemeContextValue = {
+/**
+ * The answer, once `system` has been put to the machine: what is actually on screen.
+ *
+ * Every consumer that paints something wants this one — a code editor, a chart, the dev-tools panel. `theme` is
+ * the CHOICE and can be `system`, which is not a colour and cannot be compared against one.
+ */
+export type ColorScheme = Exclude<Theme, 'system'>;
+/**
+ * The whole of what anybody knows about the theme, in one store.
+ *
+ * `scheme` is the machine's own answer, kept live by {@link ThemeProvider} — the only place that talks to
+ * `matchMedia`, so no two components can disagree about it during the frame after the visitor changes their system
+ * setting.
+ *
+ * `areas` is for a surface that paints more than one thing: the builder's canvas and its preview pane each get to
+ * be dark while the editor around them is light. An area with no entry FOLLOWS `mode`, and choosing a surface theme
+ * empties the map — an area's choice is an override of the current one, never a permanent divorce from it.
+ */
+export type ThemeState = {
+    mode: Theme;
+    scheme: ColorScheme;
+    areas: Record<string, Theme>;
+};
+export type ThemeValue = {
     theme: Theme;
+    /** `theme` with `system` already resolved, and kept in step when the machine changes its mind. */
+    resolvedTheme: ColorScheme;
+    /** `system` gives the machine back the decision; the other two are the visitor overruling it. */
+    setTheme: (theme: Theme) => void;
     toggleTheme: () => void;
 };

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './SchemaTypes';
 export * from './StyleTypes';
+export * from './TemplateTypes';
 export * from './InteractionTypes';
 export * from './PluginTypes';
 export * from './ElementTypes';
@@ -10,6 +11,7 @@ export * from './BuilderTypes';
 export * from './NavigationTypes';
 export * from './CollectionTypes';
 export * from './ConnectorTypes';
+export * from './ActionTypes';
 export * from './ComponentTypes';
 export * from './StateTypes';
 export * from './CommonTypes';

package/eslint.config.mjs

@@ -64,6 +64,8 @@ export default tsEslint.config({
     'react-hooks/preserve-manual-memoization': 'off', // @todo: review later
     'prettier/prettier': ['warn', { trailingComma: 'none' }],
     '@typescript-eslint/restrict-template-expressions': ['error', { allowNumber: true }],
+    // Destructuring a key out so the rest carries everything else is how a field is dropped from an object here.
+    '@typescript-eslint/no-unused-vars': ['error', { ignoreRestSiblings: true }],
     'import/order': [
       'error',
       {