@elaraai/e3-ui 1.0.83 → 1.0.85

package/dist/src/studio/component.js

@@ -0,0 +1,189 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Studio components (#991) — a component is self-contained: an East UI
+ * function written exactly like a `ui()` body, which binds its own data, sets
+ * up its own slices and returns its UI. Different data is a different
+ * component.
+ *
+ * `Studio.component(key, meta, fn)` returns it as a `Studio.Types.Component`
+ * struct, the way `Slice.config` returns a slice config: what the palette
+ * shows, what the function reads, the fingerprint of its code, and the
+ * function itself. A surface lists the components it offers, and the Studio's
+ * renderers draw a placement by calling its component's function, so a
+ * surface's `ui()` task holds every listed component's function and its
+ * manifest is the union of theirs.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BooleanType, East, FunctionType, IRType, IntegerType, NullType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, sha256Hex, some, variant, } from "@elaraai/east";
+import { UIComponentType } from "@elaraai/east-ui/internal";
+import { DataManifestType } from "@elaraai/e3-types";
+import { deriveManifest } from "../utils/derive.js";
+// ============================================================================
+// Types
+// ============================================================================
+/**
+ * How a component's placements are drawn.
+ *
+ * @property card - In a tile frame (the default)
+ * @property none - Bare, on the canvas and published alike
+ */
+export const StudioFrameType = VariantType({
+    card: NullType,
+    none: NullType,
+});
+/**
+ * A Studio component — what the palette shows, what the component reads, the
+ * fingerprint of its code, and the East UI function that renders it.
+ *
+ * @property key - The component's identity; a cell stores it
+ * @property name - Its name, in the palette and the inspector
+ * @property category - The palette group it sits in
+ * @property icon - A Font Awesome solid icon name
+ * @property span - The span a new placement takes, in columns of 12
+ * @property description - What it shows — the inspector's "fixed by developer" block
+ * @property frame - Drawn in a tile frame, or bare
+ * @property tags - Its tags, which the palette's Filter menu offers
+ * @property collections - Its collections, which the palette's Filter menu offers
+ * @property deprecated - Hidden from the palette; placements keep rendering
+ * @property reads - The datasets, functions and records its function binds, derived from its code
+ * @property fingerprint - A hash of its code; a cell stores it when placed and when its page publishes, so a code change since shows
+ * @property render - The East UI function that renders it
+ */
+export const StudioComponentType = StructType({
+    key: StringType,
+    name: StringType,
+    category: StringType,
+    icon: StringType,
+    span: IntegerType,
+    description: OptionType(StringType),
+    frame: StudioFrameType,
+    tags: ArrayType(StringType),
+    collections: ArrayType(StringType),
+    deprecated: BooleanType,
+    reads: DataManifestType,
+    fingerprint: StringType,
+    render: FunctionType([], UIComponentType),
+});
+// ============================================================================
+// The fingerprint
+// ============================================================================
+const encodeIR = encodeBeast2For(IRType);
+/**
+ * The IR in a canonical form: every location id zeroed and every variable
+ * renamed by its first appearance, so the same code has the same IR wherever
+ * it is written and whatever was built before it.
+ *
+ * @remarks
+ * The East types a node carries are kept as they are, not copied: equal types
+ * are one shared object, which the encoder writes once, and a copy would make
+ * it write a UI type again at every node.
+ */
+function canonicalIR(ir) {
+    const names = new Map();
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node === null || typeof node !== "object")
+            return node;
+        const proto = Object.getPrototypeOf(node);
+        if (proto !== Object.prototype && proto !== null)
+            return node;
+        const out = {};
+        for (const [field, value] of Object.entries(node)) {
+            out[field] = field === "loc_id" ? 0n
+                : (field === "type" && typeof value === "object") || field === "type_parameters" ? value
+                    : walk(value);
+        }
+        const v = out;
+        if (v.type === "Variable" && v.value !== undefined && typeof v.value.name === "string") {
+            const name = v.value.name;
+            let canonical = names.get(name);
+            if (canonical === undefined) {
+                canonical = `v${names.size}`;
+                names.set(name, canonical);
+            }
+            v.value = { ...v.value, name: canonical };
+        }
+        return out;
+    };
+    return walk(ir);
+}
+/**
+ * A function's fingerprint: the SHA-256 of its IR in canonical form. The same
+ * code fingerprints the same; a change to it changes the fingerprint.
+ *
+ * @param fn - The function
+ * @returns The fingerprint, hex
+ */
+export function fingerprintOf(fn) {
+    return sha256Hex(encodeIR(canonicalIR(fn.toIR().ir)));
+}
+// ============================================================================
+// Authoring
+// ============================================================================
+/**
+ * Declares a Studio component — a self-contained East UI function, and what
+ * the palette shows of it.
+ *
+ * @remarks
+ * `fn` is exactly what `ui()` takes, so a component written for a `ui()` body
+ * moves into `Studio.component` unchanged. Its `reads` come from its code
+ * (`deriveManifest`), and its `fingerprint` from its IR — neither is written.
+ * Call it at module scope or inside an East function, as `Slice.config` is.
+ *
+ * @param key - The component's identity; a cell stores it
+ * @param meta - What the palette shows ({@link StudioComponentMeta})
+ * @param fn - The East UI function that renders it
+ * @returns The component, a {@link StudioComponentType} value
+ *
+ * @example
+ * ```tsx
+ * import { East, IntegerType, NullType } from "@elaraai/east";
+ * import { Button, HStack, Reactive, State, Text, UIComponentType } from "@elaraai/east-ui";
+ * import { Studio } from "@elaraai/e3-ui";
+ *
+ * // A counter: its own state, shared by every placement of it.
+ * export const counter = Studio.component("counter", {
+ *     name: "Counter", category: "Display", icon: "gauge-high", span: 4n,
+ *     description: "Clicks so far",
+ * }, East.function([], UIComponentType, _$ => (
+ *     <Reactive>{$ => {
+ *         const clicks = $.let(State.bind([IntegerType], "counter.clicks", 0n));
+ *         const add = $.const(East.function([], NullType, $2 => { $2(clicks.write(clicks.read().add(1n))); }));
+ *         return (
+ *             <HStack gap="3" align="center">
+ *                 <Text>{East.str`${East.print(clicks.read())} clicks`}</Text>
+ *                 <Button size="xs" onClick={add}>Add</Button>
+ *             </HStack>
+ *         );
+ *     }}</Reactive>
+ * )));
+ * ```
+ */
+function createComponent(key, meta, fn) {
+    const reads = deriveManifest(fn);
+    return East.value({
+        key,
+        name: meta.name,
+        category: meta.category,
+        icon: meta.icon,
+        span: meta.span ?? 12n,
+        description: meta.description === undefined ? none : some(meta.description),
+        frame: variant(meta.frame ?? "card", null),
+        tags: meta.tags ?? [],
+        collections: meta.collections ?? [],
+        deprecated: meta.deprecated ?? false,
+        reads,
+        fingerprint: fingerprintOf(fn),
+        render: fn,
+    }, StudioComponentType);
+}
+/** The component half of the `Studio` namespace. */
+export const StudioComponents = {
+    component: createComponent,
+};
+//# sourceMappingURL=component.js.map

package/dist/src/studio/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/studio/component.ts"],"names":[],"mappings":"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"}

package/dist/src/studio/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Studio (#787) — components developers publish as code, and the pages
+ * operators build from them on the 12-column snap grid.
+ *
+ * @packageDocumentation
+ */
+import { StudioComponentType, StudioComponents, StudioFrameType } from "./component.js";
+import { StudioCellChangeType, StudioCellType, StudioChangeType, StudioEntryType, StudioKeyType, StudioLiveType, StudioPageEntryType, StudioPageType, StudioPages, StudioPagesType, StudioStatusType } from "./pages.js";
+import { StudioPage, StudioVersionType } from "./page.js";
+import { StudioBuilder } from "./builder.js";
+import { StudioLibrary } from "./library.js";
+export { StudioComponentType, StudioFrameType, fingerprintOf, type StudioComponentMeta, type StudioFrameLiteral, } from "./component.js";
+export { StudioCellChangeType, StudioCellType, StudioChangeType, StudioEntryType, StudioKeyType, StudioLiveType, StudioPageEntryType, StudioPageType, StudioPagesHandleType, StudioPagesType, StudioStatusType, saveCells, type StudioPagesHandle, } from "./pages.js";
+export { StudioPage, StudioPageComponent, StudioPagePayloadType, StudioVersionType, type StudioPageOptions, type StudioVersionLiteral, } from "./page.js";
+export { StudioBuilder, StudioBuilderComponent, StudioBuilderPayloadType, type StudioBuilderOptions, } from "./builder.js";
+export { builderKeys, paletteCards, palettePages, PaletteCardType, PalettePageType, } from "./palette.js";
+export { canvasTiles, CanvasTileType, StudioSaveTemplatePayloadType, } from "./canvas.js";
+export { StudioLibrary, StudioLibraryComponent, StudioLibraryPayloadType, StudioLibraryPageType, StudioLibraryTemplateType, libraryProjects, libraryPages, libraryTemplates, layoutSummary, nameWriteRefusal, type StudioLibraryOptions, } from "./library.js";
+export { PublishChangeType, PublishStandingType, PublishSummaryType, StudioPublishPayloadType, publishSummary, publishRefusal, } from "./publish.js";
+export { inspectorSelection, InspectorLayoutType, InspectorSelectionType, StudioInspectorPayloadType, } from "./inspector.js";
+/** The Studio's East types — what a solution declares its pages record with, and seeds it from. */
+export interface StudioTypes {
+    /** A Studio component ({@link StudioComponentType}). */
+    Component: typeof StudioComponentType;
+    /** How a component's placements are drawn ({@link StudioFrameType}). */
+    Frame: typeof StudioFrameType;
+    /** The pages record's type — every page and template, by key ({@link StudioPagesType}). */
+    Pages: typeof StudioPagesType;
+    /** A page's key ({@link StudioKeyType}). */
+    Key: typeof StudioKeyType;
+    /** One entry of the pages record: a page or a template ({@link StudioEntryType}). */
+    Entry: typeof StudioEntryType;
+    /** A page: its draft and its live version ({@link StudioPageEntryType}). */
+    PageEntry: typeof StudioPageEntryType;
+    /** A published version of a page ({@link StudioLiveType}). */
+    Live: typeof StudioLiveType;
+    /** A page's layout: its title and its placements ({@link StudioPageType}). */
+    Page: typeof StudioPageType;
+    /** One placement on a page ({@link StudioCellType}). */
+    Cell: typeof StudioCellType;
+    /** Which layout of a page to draw ({@link StudioVersionType}). */
+    Version: typeof StudioVersionType;
+}
+/** The type of the {@link Studio} namespace — what a solution mounts and declares. */
+export interface StudioNamespace {
+    /** Declares a component: a self-contained East UI function, and what the palette shows of it. */
+    component: typeof StudioComponents.component;
+    /** `<Studio.Builder>` — the builder: the open page's canvas, the palette and the inspector beside it, and the publish preview. */
+    Builder: typeof StudioBuilder;
+    /** `<Studio.Library>` — a project's templates and pages, and where new pages start. */
+    Library: typeof StudioLibrary;
+    /** `<Studio.Page>` — one page with no chrome, its live or draft layout on the snap grid. */
+    Page: typeof StudioPage;
+    /** The Studio's East types. */
+    Types: StudioTypes;
+}
+/**
+ * The Studio — components developers publish as code (`Studio.component`),
+ * the pages record operators build (`Studio.Types.Pages`), and the components
+ * a solution mounts: the builder (`<Studio.Builder>`), the page library
+ * (`<Studio.Library>`) and one page (`<Studio.Page>`).
+ */
+export declare const Studio: StudioNamespace;
+/**
+ * The type of the internal Studio namespace — the public one, and the page
+ * functions behind the builder and the page library.
+ */
+export interface StudioInternalNamespace extends Omit<StudioNamespace, "Types"> {
+    /** Saves a page's placements — the builder canvas's Apply, one patch to the page's draft. */
+    save: typeof StudioPages.save;
+    /** Publishes a page: the patch that makes its draft its next live version, each placement stamped with the code it goes live with. */
+    publish: typeof StudioPages.publish;
+    /** Reverts a page: the patch that makes its live version's layout its draft. */
+    revert: typeof StudioPages.revert;
+    /** Starts a page, from a template or blank: the patch that inserts it. */
+    newPage: typeof StudioPages.newPage;
+    /** Saves a page's draft as a template: the patch that inserts it. */
+    saveTemplate: typeof StudioPages.saveTemplate;
+    /** The changes from one layout of a page to another. */
+    changes: typeof StudioPages.changes;
+    /** A page's status: live or draft. */
+    status: typeof StudioPages.status;
+    /** The Studio's East types, and those of the change list and a page's status. */
+    Types: StudioTypes & {
+        /** One change between two layouts of a page ({@link StudioChangeType}). */
+        Change: typeof StudioChangeType;
+        /** One change to a placement ({@link StudioCellChangeType}). */
+        CellChange: typeof StudioCellChangeType;
+        /** A page's status ({@link StudioStatusType}). */
+        Status: typeof StudioStatusType;
+    };
+}
+/**
+ * The internal Studio namespace — `@elaraai/e3-ui/internal`'s `Studio`: the
+ * public namespace, and the page functions the renderers and the tests call.
+ *
+ * @internal
+ */
+export declare const StudioInternal: StudioInternalNamespace;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/studio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/studio/index.ts"],"names":[],"mappings":"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"}

package/dist/src/studio/index.js

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Studio (#787) — components developers publish as code, and the pages
+ * operators build from them on the 12-column snap grid.
+ *
+ * @packageDocumentation
+ */
+import { StudioComponentType, StudioComponents, StudioFrameType, } from "./component.js";
+import { StudioCellChangeType, StudioCellType, StudioChangeType, StudioEntryType, StudioKeyType, StudioLiveType, StudioPageEntryType, StudioPageType, StudioPages, StudioPagesType, StudioStatusType, } from "./pages.js";
+import { StudioPage, StudioVersionType } from "./page.js";
+import { StudioBuilder } from "./builder.js";
+import { StudioLibrary } from "./library.js";
+export { StudioComponentType, StudioFrameType, fingerprintOf, } from "./component.js";
+export { StudioCellChangeType, StudioCellType, StudioChangeType, StudioEntryType, StudioKeyType, StudioLiveType, StudioPageEntryType, StudioPageType, StudioPagesHandleType, StudioPagesType, StudioStatusType, saveCells, } from "./pages.js";
+export { StudioPage, StudioPageComponent, StudioPagePayloadType, StudioVersionType, } from "./page.js";
+export { StudioBuilder, StudioBuilderComponent, StudioBuilderPayloadType, } from "./builder.js";
+export { builderKeys, paletteCards, palettePages, PaletteCardType, PalettePageType, } from "./palette.js";
+export { canvasTiles, CanvasTileType, StudioSaveTemplatePayloadType, } from "./canvas.js";
+export { StudioLibrary, StudioLibraryComponent, StudioLibraryPayloadType, StudioLibraryPageType, StudioLibraryTemplateType, libraryProjects, libraryPages, libraryTemplates, layoutSummary, nameWriteRefusal, } from "./library.js";
+export { PublishChangeType, PublishStandingType, PublishSummaryType, StudioPublishPayloadType, publishSummary, publishRefusal, } from "./publish.js";
+export { inspectorSelection, InspectorLayoutType, InspectorSelectionType, StudioInspectorPayloadType, } from "./inspector.js";
+const types = {
+    Component: StudioComponentType,
+    Frame: StudioFrameType,
+    Pages: StudioPagesType,
+    Key: StudioKeyType,
+    Entry: StudioEntryType,
+    PageEntry: StudioPageEntryType,
+    Live: StudioLiveType,
+    Page: StudioPageType,
+    Cell: StudioCellType,
+    Version: StudioVersionType,
+};
+/**
+ * The Studio — components developers publish as code (`Studio.component`),
+ * the pages record operators build (`Studio.Types.Pages`), and the components
+ * a solution mounts: the builder (`<Studio.Builder>`), the page library
+ * (`<Studio.Library>`) and one page (`<Studio.Page>`).
+ */
+export const Studio = {
+    component: StudioComponents.component,
+    Builder: StudioBuilder,
+    Library: StudioLibrary,
+    Page: StudioPage,
+    Types: types,
+};
+/**
+ * The internal Studio namespace — `@elaraai/e3-ui/internal`'s `Studio`: the
+ * public namespace, and the page functions the renderers and the tests call.
+ *
+ * @internal
+ */
+export const StudioInternal = {
+    component: StudioComponents.component,
+    Builder: StudioBuilder,
+    Library: StudioLibrary,
+    Page: StudioPage,
+    save: StudioPages.save,
+    publish: StudioPages.publish,
+    revert: StudioPages.revert,
+    newPage: StudioPages.newPage,
+    saveTemplate: StudioPages.saveTemplate,
+    changes: StudioPages.changes,
+    status: StudioPages.status,
+    Types: {
+        ...types,
+        Change: StudioChangeType,
+        CellChange: StudioCellChangeType,
+        Status: StudioStatusType,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/src/studio/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/studio/index.ts"],"names":[],"mappings":"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"}

package/dist/src/studio/inspector.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The builder's inspector (#996) — the selected placement's component, what
+ * it reads, its description and its layout, computed in East for the
+ * `StudioBuilder` renderer, which draws the inspector in its pane after the
+ * canvas. It writes no page: a layout edit is a request the canvas takes as
+ * one gesture of the page's editing session, undone, redone, discarded and
+ * applied with the rest.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BooleanType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType } from "@elaraai/east";
+/**
+ * The selected placement's layout, as the canvas draws it.
+ *
+ * @property span - Its span, in columns of 12
+ * @property most - The most span its row leaves it: 12 less the row's other spans
+ * @property row - Its row, counting from 1 in the order the rows first appear
+ * @property rows - How many rows the page has
+ * @property height - Its height in px; `none` is its content's
+ * @property align - Where it sits in a taller row
+ */
+export declare const InspectorLayoutType: StructType<{
+    readonly span: IntegerType;
+    readonly most: IntegerType;
+    readonly row: IntegerType;
+    readonly rows: IntegerType;
+    readonly height: OptionType<IntegerType>;
+    readonly align: import("@elaraai/east").VariantType<{
+        readonly top: NullType;
+        readonly center: NullType;
+        readonly stretch: NullType;
+    }>;
+}>;
+/** Type representing the selected placement's layout. */
+export type InspectorLayoutType = typeof InspectorLayoutType;
+/**
+ * The selected placement, as the inspector shows it.
+ *
+ * @property key - The placement's key — what a layout request names
+ * @property name - Its title, else its component's name, else its component's key
+ * @property component - Its component's key
+ * @property changed - Its component's code changed since the page went live:
+ *   its fingerprint differs from the one the live version's cell stored
+ * @property reads - The paths of the datasets its component's code reads, whole
+ *   or a window at a time — the renderer prints each as its keypath (`.inputs.sales_daily`)
+ * @property description - Its component's description, fixed by its developer
+ * @property layout - Its layout ({@link InspectorLayoutType})
+ */
+export declare const InspectorSelectionType: StructType<{
+    readonly key: StringType;
+    readonly name: StringType;
+    readonly component: StringType;
+    readonly changed: BooleanType;
+    readonly reads: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+        readonly field: StringType;
+    }>>>;
+    readonly description: OptionType<StringType>;
+    readonly layout: StructType<{
+        readonly span: IntegerType;
+        readonly most: IntegerType;
+        readonly row: IntegerType;
+        readonly rows: IntegerType;
+        readonly height: OptionType<IntegerType>;
+        readonly align: import("@elaraai/east").VariantType<{
+            readonly top: NullType;
+            readonly center: NullType;
+            readonly stretch: NullType;
+        }>;
+    }>;
+}>;
+/** Type representing the selected placement, as the inspector shows it. */
+export type InspectorSelectionType = typeof InspectorSelectionType;
+/**
+ * The inspector, as the `StudioBuilder` renderer draws it.
+ *
+ * @property selection - The selected placement; `none` when nothing is selected
+ * @property onRequest - Asks the canvas for a layout change, which it takes as one gesture
+ */
+export declare const StudioInspectorPayloadType: StructType<{
+    readonly selection: OptionType<StructType<{
+        readonly key: StringType;
+        readonly name: StringType;
+        readonly component: StringType;
+        readonly changed: BooleanType;
+        readonly reads: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>>;
+        readonly description: OptionType<StringType>;
+        readonly layout: StructType<{
+            readonly span: IntegerType;
+            readonly most: IntegerType;
+            readonly row: IntegerType;
+            readonly rows: IntegerType;
+            readonly height: OptionType<IntegerType>;
+            readonly align: import("@elaraai/east").VariantType<{
+                readonly top: NullType;
+                readonly center: NullType;
+                readonly stretch: NullType;
+            }>;
+        }>;
+    }>>;
+    readonly onRequest: FunctionType<[StructType<{
+        readonly key: StringType;
+        readonly change: import("@elaraai/east").VariantType<{
+            readonly span: IntegerType;
+            readonly row: IntegerType;
+            readonly height: OptionType<IntegerType>;
+            readonly align: import("@elaraai/east").VariantType<{
+                readonly top: NullType;
+                readonly center: NullType;
+                readonly stretch: NullType;
+            }>;
+        }>;
+    }>], NullType>;
+}>;
+/** Type representing the inspector, as the builder draws it. */
+export type StudioInspectorPayloadType = typeof StudioInspectorPayloadType;
+/**
+ * The selected placement, as the inspector shows it — `none` when nothing is
+ * selected, or the page has no placement under the selected key.
+ *
+ * @remarks
+ * `cells` are the page's placements as the canvas draws them, its unsaved
+ * drafts in place; `live` the live version's, whose fingerprints say whether a
+ * component's code changed since the page went live — a placement the live
+ * version does not hold has not gone live, and has not changed. A placement
+ * whose component the surface does not list is named by its component's key,
+ * reads nothing and has no description.
+ */
+export declare const inspectorSelection: import("@elaraai/east").CallableFunctionExpr<[ArrayType<StructType<{
+    readonly key: StringType;
+    readonly name: StringType;
+    readonly category: StringType;
+    readonly icon: StringType;
+    readonly span: IntegerType;
+    readonly description: OptionType<StringType>;
+    readonly frame: import("@elaraai/east").VariantType<{
+        readonly card: NullType;
+        readonly none: NullType;
+    }>;
+    readonly tags: ArrayType<StringType>;
+    readonly collections: ArrayType<StringType>;
+    readonly deprecated: BooleanType;
+    readonly reads: StructType<{
+        readonly paths: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>>;
+        readonly functions: ArrayType<StringType>;
+        readonly records: ArrayType<StringType>;
+        readonly pages: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+            readonly field: StringType;
+        }>>>;
+    }>;
+    readonly fingerprint: StringType;
+    readonly render: FunctionType<[], import("@elaraai/east").RecursiveType<import("@elaraai/east-ui").UIComponentNode>>;
+}>>, ArrayType<StructType<{
+    readonly key: StringType;
+    readonly row: StringType;
+    readonly span: IntegerType;
+    readonly height: OptionType<IntegerType>;
+    readonly align: import("@elaraai/east").VariantType<{
+        readonly top: NullType;
+        readonly center: NullType;
+        readonly stretch: NullType;
+    }>;
+    readonly title: OptionType<StringType>;
+    readonly component: StringType;
+    readonly fingerprint: StringType;
+}>>, OptionType<ArrayType<StructType<{
+    readonly key: StringType;
+    readonly row: StringType;
+    readonly span: IntegerType;
+    readonly height: OptionType<IntegerType>;
+    readonly align: import("@elaraai/east").VariantType<{
+        readonly top: NullType;
+        readonly center: NullType;
+        readonly stretch: NullType;
+    }>;
+    readonly title: OptionType<StringType>;
+    readonly component: StringType;
+    readonly fingerprint: StringType;
+}>>>, OptionType<StringType>], OptionType<StructType<{
+    readonly key: StringType;
+    readonly name: StringType;
+    readonly component: StringType;
+    readonly changed: BooleanType;
+    readonly reads: ArrayType<ArrayType<import("@elaraai/east").VariantType<{
+        readonly field: StringType;
+    }>>>;
+    readonly description: OptionType<StringType>;
+    readonly layout: StructType<{
+        readonly span: IntegerType;
+        readonly most: IntegerType;
+        readonly row: IntegerType;
+        readonly rows: IntegerType;
+        readonly height: OptionType<IntegerType>;
+        readonly align: import("@elaraai/east").VariantType<{
+            readonly top: NullType;
+            readonly center: NullType;
+            readonly stretch: NullType;
+        }>;
+    }>;
+}>>>;
+//# sourceMappingURL=inspector.d.ts.map

package/dist/src/studio/inspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspector.d.ts","sourceRoot":"","sources":["../../../src/studio/inspector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH,OAAO,EACH,SAAS,EACT,WAAW,EAEX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EAEV,UAAU,EACV,UAAU,EAGb,MAAM,eAAe,CAAC;AAUvB;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAO9B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;EAQjC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGrC,CAAC;AAEH,gEAAgE;AAChE,MAAM,MAAM,0BAA0B,GAAG,OAAO,0BAA0B,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkF9B,CAAC"}