@usethrottle/builder-schema 0.0.0 → 0.1.1

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.
package/dist/index.d.ts CHANGED
@@ -12,7 +12,7 @@ declare function newNodeId(): string;
12
12
  * `INNER_IN_INNER` belongs to the document grammar (an inner section inside an
13
13
  * inner column), so Task 8's `PlacementCode` reuses it and must not add it again.
14
14
  */
15
- declare const ISSUE_CODES: readonly ["INVALID_SHAPE", "INVALID_VALUE", "REQUIRED", "UNKNOWN_KEY", "FORBIDDEN_KEY", "DUPLICATE_ID", "LIMIT_EXCEEDED", "UNSUPPORTED_SCHEMA_VERSION", "INVALID_WIDGET_TYPE", "INVALID_COLUMN_WIDTHS", "INNER_IN_INNER"];
15
+ declare const ISSUE_CODES: readonly ["INVALID_SHAPE", "INVALID_VALUE", "REQUIRED", "UNKNOWN_KEY", "FORBIDDEN_KEY", "DUPLICATE_ID", "LIMIT_EXCEEDED", "UNSUPPORTED_SCHEMA_VERSION", "INVALID_WIDGET_TYPE", "INVALID_COLUMN_WIDTHS", "INNER_IN_INNER", "SECTION_NOT_NESTABLE", "INNER_NOT_TOP_LEVEL", "COLUMN_LIMIT", "NOT_ALLOWED_IN_PART", "MOVE_INTO_SELF", "COLUMN_REMOVE_NEEDS_SETCOLUMNS", "COLUMN_NOT_EMPTY", "UNKNOWN_PROP", "SOURCE_NOT_ENABLED", "RESULT_TYPE_MISMATCH", "ID_NOT_FRESH", "NODE_NOT_FOUND", "TEMPLATE_SYNTAX", "TEMPLATE_FORBIDDEN", "ELEMENT_NOT_ALLOWED", "ATTRIBUTE_NOT_ALLOWED", "FIELD_NOT_ALLOWED", "UNKNOWN_REFERENCE", "CSS_SYNTAX", "CSS_FORBIDDEN", "CSS_PROPERTY_NOT_ALLOWED", "NO_RECURSION", "BINDING_TARGET_MISSING", "BINDING_TYPE_MISMATCH", "WIDGET_TOO_LARGE", "DUPLICATE_KEY", "VERSION_RULE"];
16
16
  type IssueCode = (typeof ISSUE_CODES)[number];
17
17
  type Issue = {
18
18
  path: string;
@@ -61,6 +61,13 @@ declare const spacingValueSchema: z.ZodUnion<readonly [z.ZodEnum<{
61
61
  xl: "xl";
62
62
  "2xl": "2xl";
63
63
  }>, z.ZodNumber]>;
64
+ /**
65
+ * The universal node props (spec §8.2): hide per device, an anchor and two margins.
66
+ * They are common props, not widget settings: every widget accepts them and they
67
+ * do not count against the 40-setting cap. `COMMON_WIDGET_SETTINGS` (basics.ts)
68
+ * holds their fields.
69
+ */
70
+ declare const COMMON_SETTING_KEYS: readonly ["hidden", "anchor", "spacingTop", "spacingBottom"];
64
71
  /** An id-safe anchor, on every node and on the `anchor` setting of widgets. */
65
72
  declare const ANCHOR_RE: RegExp;
66
73
  declare const sectionPropsSchema: z.ZodObject<{
@@ -3354,6 +3361,8 @@ declare const DATA_RESULT_TYPES: readonly ["product[]", "product", "collection",
3354
3361
  type DataResultType = (typeof DATA_RESULT_TYPES)[number];
3355
3362
  /** A name from the icon set; the set itself lives in `@usethrottle/ui`. */
3356
3363
  type IconName = string;
3364
+ /** The controls whose value is safe to put in CSS: each is validated to a token, number, colour or enum. */
3365
+ declare const CSS_CONTROLS: readonly ["color", "spacing", "font-size", "alignment", "number", "toggle", "select"];
3357
3366
  declare const settingFieldSchema: z.ZodObject<{
3358
3367
  key: z.ZodString;
3359
3368
  label: z.ZodString;
@@ -3557,6 +3566,7 @@ declare const widgetDefinitionSchema: z.ZodObject<{
3557
3566
  header: "header";
3558
3567
  slot: "slot";
3559
3568
  }>>>;
3569
+ topLevelOnly: z.ZodOptional<z.ZodBoolean>;
3560
3570
  }, z.core.$strict>>;
3561
3571
  }, z.core.$strict>;
3562
3572
  type DefinitionData = z.infer<typeof widgetDefinitionSchema>;
@@ -3564,8 +3574,16 @@ type DefinitionData = z.infer<typeof widgetDefinitionSchema>;
3564
3574
  type WidgetMigration = (props: Record<string, SettingValue>) => Record<string, SettingValue>;
3565
3575
  type WidgetDefinition = Omit<DefinitionData, 'type'> & {
3566
3576
  type: WidgetType;
3577
+ /** Set for custom widgets only. A composite cannot contain another composite. */
3578
+ kind?: 'composite' | 'template';
3567
3579
  /** `migrations[fromV](props)` lifts props from `fromV` to `fromV + 1`. */
3568
3580
  migrations?: Record<number, WidgetMigration>;
3581
+ /**
3582
+ * Custom widget versions only (§10.4): what this version renamed (`{ old: new }`)
3583
+ * and removed since the one before it. `upgradeNode` applies them.
3584
+ */
3585
+ renamed?: Record<string, string>;
3586
+ removed?: string[];
3569
3587
  };
3570
3588
  /**
3571
3589
  * Checks one value against its field. Returns a message, or `null` when valid.
@@ -3583,6 +3601,8 @@ interface WidgetRegistry {
3583
3601
  /** The highest version registered for the type. */
3584
3602
  latest(type: string): WidgetDefinition | undefined;
3585
3603
  source(id: string): DataSourceDescriptor | undefined;
3604
+ /** Every registered data source. Templates may read the fields of the sources an input accepts. */
3605
+ sources(): DataSourceDescriptor[];
3586
3606
  /** The latest definition of every type, ordered by type. */
3587
3607
  all(): WidgetDefinition[];
3588
3608
  }
@@ -3597,4 +3617,476 @@ declare function createRegistry(defs: readonly WidgetDefinition[], sources: read
3597
3617
  declare const COMMON_WIDGET_SETTINGS: readonly SettingField[];
3598
3618
  declare const BASIC_WIDGET_DEFINITIONS: WidgetDefinition[];
3599
3619
 
3600
- export { ANCHOR_RE, type AnyNode, BASIC_WIDGET_DEFINITIONS, BREAKPOINTS, CATALOG_STRING_KEYS, COLOR_VALUE_RE, COMMON_WIDGET_SETTINGS, CURRENT_SCHEMA_VERSION, type CatalogStringKey, type ColumnNode, type ColumnProps, type CustomWidgetSnapshot, DATA_RESULT_TYPES, type DataBinding, type DataResultType, type DataSourceDescriptor, type FieldSpec, type FrozenAsset, ISSUE_CODES, type IconName, type InnerColumnNode, type InnerSectionNode, type Issue, type IssueCode, LIMITS, LOCALE_TAG_RE, type LocalizedText, MAX_ISSUES, type MenuItem, type MenuTarget, NODE_ID_RE, type NodeId, type Overrides, PREVIEW_WIDTHS, type PageDocument, type PathSegment, type ResponsiveDevice, SAFE_HREF, SETTING_CONTROLS, SETTING_TABS, SITE_ASSET_PATHS, SITE_FONTS, SITE_FONT_FAMILIES, SITE_SETTINGS_SCHEMA_VERSION, SITE_STRING_DEFAULTS, SITE_STRING_KEYS, SITE_STRING_NAMESPACES, SPACING_TOKENS, type SectionNode, type SectionProps, type SettingField, type SettingValue, type SiteFont, type SiteFontCategory, type SiteFontFamily, type SitePalette, type SiteSettings, type SiteSettingsInput, type SiteStringKey, THROTTLE_PK_RE, type UpgradeResult, WIDGET_GROUPS, WIDGET_TYPE_RE, type WidgetDefinition, type WidgetMigration, type WidgetNode, type WidgetRegistry, type WidgetType, assetIdSchema, capIssues, checkLimits, colorValueSchema, columnPropsSchema, createRegistry, customWidgetSnapshotSchema, dataBindingSchema, dataSourceDescriptorSchema, defaultSiteSettings, emptyDocument, fieldSpecSchema, formatPath, frozenAssetSchema, isSettingValue, localeTagSchema, localizedTextSchema, makeIssue, menuItemSchema, menuTargetSchema, newNodeId, nodeIdSchema, pageDocumentSchema, resolveColumnProps, resolveColumnWidths, resolveResponsive, sectionPropsSchema, settingFieldSchema, settingValueSchema, siteSettingsSchema, spacingValueSchema, upgradeDocument, utf8Length, validateDocument, validateSettingValue, validateWidgetProps, walkNodes, widgetDefinitionSchema, wrapColumnRows, zodIssues };
3620
+ /** Where a document lives. A part or slot may refuse some widgets. */
3621
+ type DocumentKind = 'page' | 'part:header' | 'part:footer' | 'slot';
3622
+ type OpContext = {
3623
+ registry: WidgetRegistry;
3624
+ documentKind: DocumentKind;
3625
+ /** Data source ids the merchant has enabled (a source is also known to the registry). */
3626
+ enabledSources: ReadonlySet<string>;
3627
+ };
3628
+ type PlacementCode = Extract<IssueCode, 'SECTION_NOT_NESTABLE' | 'INNER_IN_INNER' | 'INNER_NOT_TOP_LEVEL' | 'COLUMN_LIMIT' | 'NOT_ALLOWED_IN_PART' | 'MOVE_INTO_SELF' | 'COLUMN_REMOVE_NEEDS_SETCOLUMNS' | 'COLUMN_NOT_EMPTY' | 'UNKNOWN_PROP' | 'SOURCE_NOT_ENABLED' | 'RESULT_TYPE_MISMATCH' | 'ID_NOT_FRESH'>;
3629
+ type Placement = {
3630
+ ok: true;
3631
+ } | {
3632
+ ok: false;
3633
+ code: PlacementCode;
3634
+ message: string;
3635
+ };
3636
+ /**
3637
+ * Whether a widget may live in this kind of document (`placement` of its
3638
+ * definition). Pass `v` to read the placement of that exact version.
3639
+ */
3640
+ declare function checkWidgetPart(type: string, ctx: OpContext, v?: number): Placement;
3641
+ /** A widget whose definition says `placement.topLevelOnly` cannot sit inside an inner section. */
3642
+ declare function checkTopLevel(type: string, ctx: OpContext, v?: number): Placement;
3643
+ /**
3644
+ * Can a node of this type go into this parent? `parentId` is `'root'` or the id
3645
+ * of a column. Pass the node's `v` for a widget, so its definition's `placement`
3646
+ * is read for that version, and its `id` when it already exists (a move), so that a
3647
+ * node cannot go into itself and a full column still takes its own child back.
3648
+ * The editor calls this before it shows a drop zone; `applyOps` calls it for
3649
+ * every insert and move.
3650
+ */
3651
+ declare function canPlace(doc: PageDocument, node: {
3652
+ type: string;
3653
+ id?: string;
3654
+ v?: number;
3655
+ }, parentId: string, ctx: OpContext): Placement;
3656
+
3657
+ /**
3658
+ * Document edit operations (spec §8.4). `applyOps` is pure and atomic, and
3659
+ * `invertOps` returns the batch that undoes it. Ids the ops create (a wrapper
3660
+ * section, new columns) are derived from the ids already in play, so the same
3661
+ * ops on the same document always give the same result.
3662
+ */
3663
+ type DocOpDevice = 'tablet' | 'phone';
3664
+ type ParentId = 'root' | string;
3665
+ type DocOp = {
3666
+ op: 'insert';
3667
+ parentId: ParentId;
3668
+ index: number;
3669
+ node: SectionNode | InnerSectionNode | WidgetNode;
3670
+ } | {
3671
+ op: 'remove';
3672
+ id: string;
3673
+ } | {
3674
+ op: 'move';
3675
+ id: string;
3676
+ parentId: ParentId;
3677
+ index: number;
3678
+ } | {
3679
+ op: 'setProps';
3680
+ id: string;
3681
+ props: Record<string, SettingValue | null>;
3682
+ } | {
3683
+ op: 'setResponsive';
3684
+ id: string;
3685
+ device: DocOpDevice;
3686
+ props: Record<string, SettingValue | null>;
3687
+ } | {
3688
+ op: 'setColumns';
3689
+ sectionId: string;
3690
+ widths: number[];
3691
+ /** Without a device the columns themselves change; with one only that device's width overrides are written. */
3692
+ device?: DocOpDevice;
3693
+ /** Needed to remove a column that has children: they join the column before it. */
3694
+ moveChildrenTo?: 'previous';
3695
+ /** Ids for the columns this op adds (fresh ones are derived when missing). */
3696
+ newIds?: string[];
3697
+ } | {
3698
+ op: 'setData';
3699
+ id: string;
3700
+ name: string;
3701
+ binding: DataBinding | null;
3702
+ } | {
3703
+ op: 'replaceDocument';
3704
+ document: PageDocument;
3705
+ } | {
3706
+ op: 'upgradeNode';
3707
+ id: string;
3708
+ toV: number;
3709
+ /** Set by the inverse of an upgrade: put these props and overrides back at `toV`. */
3710
+ restore?: {
3711
+ props: Record<string, SettingValue>;
3712
+ responsive?: WidgetNode['responsive'];
3713
+ };
3714
+ };
3715
+ type ApplyResult = {
3716
+ ok: true;
3717
+ doc: PageDocument;
3718
+ } | {
3719
+ ok: false;
3720
+ issues: Issue[];
3721
+ };
3722
+ /**
3723
+ * Brings every built-in and pack widget up to the latest definition's version
3724
+ * (§8.5), through `migrations`. Custom widgets are left alone: they move only
3725
+ * when the merchant clicks "Update" (`upgradeNode`). Pure; unchanged parts of
3726
+ * the document are shared with the input.
3727
+ */
3728
+ declare function upgradeNodes(doc: PageDocument, registry: WidgetRegistry): {
3729
+ doc: PageDocument;
3730
+ upgraded: string[];
3731
+ };
3732
+ /**
3733
+ * Applies the ops in order. Atomic: either every op applies and the result is a
3734
+ * valid document (schema and limits), or nothing changes and `issues` says why.
3735
+ * Pure; the input is never changed and untouched parts are shared with the result.
3736
+ */
3737
+ declare function applyOps(doc: PageDocument, ops: DocOp[], ctx: OpContext): ApplyResult;
3738
+ /**
3739
+ * The ops that undo `ops` when applied to the document `ops` produced. The undo
3740
+ * stack stores them with each batch. `ops` must apply cleanly to `before`;
3741
+ * otherwise this throws.
3742
+ *
3743
+ * The undo contract is deep equality (`toEqual`), not byte equality: key order
3744
+ * may differ, and props or overrides that were stored as an explicit `null`
3745
+ * come back absent (the same meaning: the definition's default), as do empty
3746
+ * `responsive` containers.
3747
+ *
3748
+ * Undoing a remove is checked again as an insert, so it can be refused, for
3749
+ * example when the node's widget is no longer available (spec 8.5). The editor
3750
+ * must handle `applyOps` refusing an inverse batch.
3751
+ */
3752
+ declare function invertOps(before: PageDocument, ops: DocOp[], ctx: OpContext): DocOp[];
3753
+
3754
+ /** Every op, for the editor's own autosave and undo (trusted callers). */
3755
+ declare const docOpSchema: z.ZodType<DocOp, unknown>;
3756
+ /** A batch from an agent is at most this many ops. */
3757
+ declare const AGENT_MAX_OPS = 500;
3758
+ /** The ops an agent may send (MCP `apply_ops`, Widget API): no `replaceDocument`, no `restore`. */
3759
+ declare const agentDocOpSchema: z.ZodType<Exclude<DocOp, {
3760
+ op: "replaceDocument";
3761
+ }>, unknown>;
3762
+ /** A batch from an agent: 1 to `AGENT_MAX_OPS` ops. */
3763
+ declare const agentDocOpsSchema: z.ZodArray<z.ZodType<{
3764
+ op: "insert";
3765
+ parentId: ParentId;
3766
+ index: number;
3767
+ node: SectionNode | InnerSectionNode | WidgetNode;
3768
+ } | {
3769
+ op: "remove";
3770
+ id: string;
3771
+ } | {
3772
+ op: "move";
3773
+ id: string;
3774
+ parentId: ParentId;
3775
+ index: number;
3776
+ } | {
3777
+ op: "setProps";
3778
+ id: string;
3779
+ props: Record<string, SettingValue | null>;
3780
+ } | {
3781
+ op: "setResponsive";
3782
+ id: string;
3783
+ device: DocOpDevice;
3784
+ props: Record<string, SettingValue | null>;
3785
+ } | {
3786
+ op: "setColumns";
3787
+ sectionId: string;
3788
+ widths: number[];
3789
+ device?: DocOpDevice;
3790
+ moveChildrenTo?: "previous";
3791
+ newIds?: string[];
3792
+ } | {
3793
+ op: "setData";
3794
+ id: string;
3795
+ name: string;
3796
+ binding: DataBinding | null;
3797
+ } | {
3798
+ op: "upgradeNode";
3799
+ id: string;
3800
+ toV: number;
3801
+ restore?: {
3802
+ props: Record<string, SettingValue>;
3803
+ responsive?: WidgetNode["responsive"];
3804
+ };
3805
+ }, unknown, z.core.$ZodTypeInternals<{
3806
+ op: "insert";
3807
+ parentId: ParentId;
3808
+ index: number;
3809
+ node: SectionNode | InnerSectionNode | WidgetNode;
3810
+ } | {
3811
+ op: "remove";
3812
+ id: string;
3813
+ } | {
3814
+ op: "move";
3815
+ id: string;
3816
+ parentId: ParentId;
3817
+ index: number;
3818
+ } | {
3819
+ op: "setProps";
3820
+ id: string;
3821
+ props: Record<string, SettingValue | null>;
3822
+ } | {
3823
+ op: "setResponsive";
3824
+ id: string;
3825
+ device: DocOpDevice;
3826
+ props: Record<string, SettingValue | null>;
3827
+ } | {
3828
+ op: "setColumns";
3829
+ sectionId: string;
3830
+ widths: number[];
3831
+ device?: DocOpDevice;
3832
+ moveChildrenTo?: "previous";
3833
+ newIds?: string[];
3834
+ } | {
3835
+ op: "setData";
3836
+ id: string;
3837
+ name: string;
3838
+ binding: DataBinding | null;
3839
+ } | {
3840
+ op: "upgradeNode";
3841
+ id: string;
3842
+ toV: number;
3843
+ restore?: {
3844
+ props: Record<string, SettingValue>;
3845
+ responsive?: WidgetNode["responsive"];
3846
+ };
3847
+ }, unknown>>>;
3848
+
3849
+ /**
3850
+ * The one place a URL becomes safe to put in `href` or `src` (spec §10.3).
3851
+ * It is an allow-list: anything it does not recognise, in any spelling, is `null`.
3852
+ * The renderer runs it again at render time, because data values are only known then.
3853
+ */
3854
+ type SafeUrlKind = 'href' | 'src';
3855
+ /**
3856
+ * Returns the URL when it is safe, otherwise `null`.
3857
+ *
3858
+ * - `href`: `https://host/...` or a root-relative path (`/shop`, never `//host`). `http:`,
3859
+ * `mailto:` and `tel:` are not in the spec's list and are refused.
3860
+ * - `src`: an `https` URL on exactly `ctx.mediaOrigin`.
3861
+ *
3862
+ * `javascript:`, `data:`, `vbscript:`, entity-encoded, escaped, mixed-case,
3863
+ * whitespace-split and non-ASCII spellings never match the allow-list.
3864
+ */
3865
+ declare function safeUrl(value: unknown, kind: SafeUrlKind, ctx: {
3866
+ mediaOrigin: string;
3867
+ }): string | null;
3868
+
3869
+ /**
3870
+ * The Throttle Template AST (spec §10.3). It is a closed union: the renderer
3871
+ * interprets exactly these node types and nothing else, and no string of markup
3872
+ * is ever built from it.
3873
+ */
3874
+ declare const TEMPLATE_FILTERS: readonly ["upper", "lower", "truncate", "default"];
3875
+ type TemplateFilterName = (typeof TEMPLATE_FILTERS)[number];
3876
+ declare const ALLOWED_ELEMENTS: readonly ["div", "span", "p", "h1", "h2", "h3", "h4", "h5", "h6", "a", "img", "ul", "ol", "li", "strong", "em", "small", "figure", "figcaption", "section", "article", "header", "footer", "br", "hr"];
3877
+ type AllowedElement = (typeof ALLOWED_ELEMENTS)[number];
3878
+ /** Elements with no children and no closing tag. */
3879
+ declare const VOID_ELEMENTS: readonly AllowedElement[];
3880
+ /** Attributes by element. `*` applies to every element. `data-*` is handled separately. */
3881
+ declare const ALLOWED_ATTRS: Readonly<Record<string, readonly string[]>>;
3882
+ /** Non-interactive roles only. */
3883
+ declare const ALLOWED_ROLES: readonly ["article", "banner", "complementary", "contentinfo", "figure", "group", "heading", "img", "list", "listitem", "none", "note", "presentation", "region", "separator"];
3884
+ /**
3885
+ * Author classes may not start with these: they belong to the platform's own
3886
+ * styles (`tb-` is the builder-react layer, `tsf-` and `throttle-` the storefront
3887
+ * kits, `b-` the builder). Reserving them keeps a widget from borrowing or
3888
+ * clashing with platform classes.
3889
+ */
3890
+ declare const RESERVED_CLASS_PREFIXES: readonly ["b-", "tb-", "tsf-", "throttle-"];
3891
+ declare const isReservedClass: (name: string) => boolean;
3892
+ /** Bidirectional override and isolate controls: they make text read differently from how it is stored. */
3893
+ declare const BIDI_CONTROL_RE: RegExp;
3894
+ declare const CLASS_TOKEN_RE: RegExp;
3895
+ declare const DATA_ATTR_RE: RegExp;
3896
+ /** `data-b-` is reserved for the renderer (`data-b-w` scopes widget CSS). */
3897
+ declare const RESERVED_DATA_PREFIX = "data-b-";
3898
+ type Filter = {
3899
+ name: 'upper';
3900
+ } | {
3901
+ name: 'lower';
3902
+ } | {
3903
+ name: 'truncate';
3904
+ n: number;
3905
+ } | {
3906
+ name: 'default';
3907
+ text: string;
3908
+ };
3909
+ type TextNode = {
3910
+ type: 'text';
3911
+ value: string;
3912
+ };
3913
+ /** `path` is the dotted path split into segments, such as `['settings', 'title']`. */
3914
+ type OutputNode = {
3915
+ type: 'output';
3916
+ path: string[];
3917
+ filters: Filter[];
3918
+ };
3919
+ type IfNode = {
3920
+ type: 'if';
3921
+ path: string[];
3922
+ then: TemplateNode[];
3923
+ else: TemplateNode[];
3924
+ };
3925
+ type UnlessNode = {
3926
+ type: 'unless';
3927
+ path: string[];
3928
+ body: TemplateNode[];
3929
+ };
3930
+ type EachNode = {
3931
+ type: 'each';
3932
+ path: string[];
3933
+ as: string;
3934
+ body: TemplateNode[];
3935
+ };
3936
+ type AttrPart = TextNode | OutputNode;
3937
+ type ElementAttr = {
3938
+ name: string;
3939
+ value: AttrPart[];
3940
+ };
3941
+ type ElementNode = {
3942
+ type: 'element';
3943
+ tag: AllowedElement;
3944
+ attrs: ElementAttr[];
3945
+ children: TemplateNode[];
3946
+ };
3947
+ type TemplateNode = TextNode | OutputNode | IfNode | UnlessNode | EachNode | ElementNode;
3948
+ type TemplateAst = TemplateNode[];
3949
+ /** The most rendered nodes a template may produce in total (see `templateWeight`). */
3950
+ declare const MAX_TEMPLATE_WEIGHT = 20000;
3951
+ /** The most iterations of one `{{#each}}` that are rendered (spec §10.3). */
3952
+ declare const EACH_ITERATION_CAP = 100;
3953
+ /**
3954
+ * The most nodes a template can render: each node counts once, times the
3955
+ * product of the loop caps (100 per enclosing `{{#each}}`). Both branches of an
3956
+ * `{{#if}}` are summed, which is an upper bound.
3957
+ * The renderer enforces the same number as a cap on rendered nodes.
3958
+ */
3959
+ declare function templateWeight(ast: readonly TemplateNode[], multiplier?: number): number;
3960
+
3961
+ type ParseTemplateResult = {
3962
+ ok: true;
3963
+ ast: TemplateAst;
3964
+ } | {
3965
+ ok: false;
3966
+ issues: Issue[];
3967
+ };
3968
+ /**
3969
+ * Parses Throttle Template source into the closed AST. Refuses everything the
3970
+ * language does not have (triple-stash, partials, helpers, lookups,
3971
+ * comparisons), every element and attribute outside the allow-lists, and
3972
+ * anything past the size, node, depth and `#each` limits. Issue paths read
3973
+ * `template:<line>:<column>`.
3974
+ */
3975
+ declare function parseTemplate(src: string): ParseTemplateResult;
3976
+
3977
+ /**
3978
+ * Checks a parsed template against the widget it belongs to (spec §10.3, §10.4):
3979
+ * every `settings.<key>` is declared, every `data.<input>.<field>` is in the
3980
+ * `fields` allow-list of the registered sources that input accepts, and a money
3981
+ * field can only be printed as `display` or `currency`, never as an amount.
3982
+ */
3983
+ type TemplateContext = {
3984
+ /** The widget's settings. Only `output: 'markup'` settings may be read. */
3985
+ settings: readonly SettingField[];
3986
+ /** The widget's data inputs. */
3987
+ data: Readonly<Record<string, {
3988
+ accepts: readonly DataResultType[];
3989
+ }>>;
3990
+ /** Registered data sources (the allow-lists). */
3991
+ sources: readonly DataSourceDescriptor[];
3992
+ };
3993
+ /** Issues for a template that parses but reads something it may not. */
3994
+ declare function validateTemplate(ast: TemplateAst, ctx: TemplateContext): Issue[];
3995
+
3996
+ type SanitizeCssResult = {
3997
+ ok: true;
3998
+ /** Re-serialised and scoped under `[data-b-w="<type>"]`. Safe to inject as it is. */
3999
+ css: string;
4000
+ /** The same rules re-serialised without the scope. Re-validating it gives the same output. */
4001
+ source: string;
4002
+ /** The setting keys read through `var(--w-<key>)`. */
4003
+ vars: string[];
4004
+ } | {
4005
+ ok: false;
4006
+ issues: Issue[];
4007
+ };
4008
+ /**
4009
+ * Validates widget CSS and returns it re-serialised and scoped to the widget.
4010
+ * Refuses `url(`, `image-set(`, `expression(`, `@import`, `@font-face`, every
4011
+ * other at-rule, backslash escapes, `!important`, properties outside the
4012
+ * allow-list, unbalanced braces and anything over 10 KB.
4013
+ */
4014
+ declare function sanitizeWidgetCss(css: string, type: `custom.${string}`): SanitizeCssResult;
4015
+
4016
+ /**
4017
+ * Custom widget definitions (spec §10): composite (inner nodes plus bindings)
4018
+ * and template (Throttle Template plus restricted CSS). `validateCustomWidget`
4019
+ * is the one gate the Widget API, the MCP tools and the editor go through
4020
+ * before a definition is stored or frozen into a document.
4021
+ */
4022
+ type DataInputDefinition = {
4023
+ accepts: DataResultType[];
4024
+ required: boolean;
4025
+ label: string;
4026
+ };
4027
+ type CustomCommon = {
4028
+ type: `custom.${string}`;
4029
+ v: number;
4030
+ title: string;
4031
+ description: string;
4032
+ icon: string;
4033
+ group: 'custom';
4034
+ settings: SettingField[];
4035
+ /** Old key to new key, applied by the editor's "Update". */
4036
+ renamed?: Record<string, string>;
4037
+ /** Keys dropped by this version. */
4038
+ removed?: string[];
4039
+ };
4040
+ type CompositeDefinition = CustomCommon & {
4041
+ kind: 'composite';
4042
+ /** Exactly one of the two. */
4043
+ body: {
4044
+ columns?: InnerColumnNode[];
4045
+ stack?: WidgetNode[];
4046
+ };
4047
+ bindings: {
4048
+ setting: string;
4049
+ targets: {
4050
+ node: string;
4051
+ prop: string;
4052
+ }[];
4053
+ }[];
4054
+ data?: Record<string, DataInputDefinition & {
4055
+ targets: {
4056
+ node: string;
4057
+ input: string;
4058
+ }[];
4059
+ }>;
4060
+ /** Set on normalisation: a composite with columns is an inner section. */
4061
+ placement?: {
4062
+ topLevelOnly: true;
4063
+ };
4064
+ };
4065
+ type TemplateDefinition = CustomCommon & {
4066
+ kind: 'template';
4067
+ data?: Record<string, DataInputDefinition>;
4068
+ /** Throttle Template source, at most 20 KB. */
4069
+ template: string;
4070
+ /** Restricted CSS, re-serialised and without the scope (see `sanitizeWidgetCss`). */
4071
+ css?: string;
4072
+ };
4073
+ type CustomWidgetDefinition = CompositeDefinition | TemplateDefinition;
4074
+ type ValidateCustomWidgetResult = {
4075
+ ok: true;
4076
+ normalized: CustomWidgetDefinition;
4077
+ ast?: TemplateAst;
4078
+ } | {
4079
+ ok: false;
4080
+ issues: Issue[];
4081
+ };
4082
+ /**
4083
+ * Validates a custom widget definition (composite or template) and returns it
4084
+ * normalised. A definition is refused when it is not plain JSON, holds a
4085
+ * prototype-poisoning key, is over 64 KB, breaks a limit, fails the template or
4086
+ * CSS rules, has a binding that points nowhere or at the wrong control, nests a
4087
+ * composite, or breaks the version rules against the previous version in
4088
+ * `registry`.
4089
+ */
4090
+ declare function validateCustomWidget(def: unknown, registry: WidgetRegistry): ValidateCustomWidgetResult;
4091
+
4092
+ export { AGENT_MAX_OPS, ALLOWED_ATTRS, ALLOWED_ELEMENTS, ALLOWED_ROLES, ANCHOR_RE, type AllowedElement, type AnyNode, type ApplyResult, type AttrPart, BASIC_WIDGET_DEFINITIONS, BIDI_CONTROL_RE, BREAKPOINTS, CATALOG_STRING_KEYS, CLASS_TOKEN_RE, COLOR_VALUE_RE, COMMON_SETTING_KEYS, COMMON_WIDGET_SETTINGS, CSS_CONTROLS, CURRENT_SCHEMA_VERSION, type CatalogStringKey, type ColumnNode, type ColumnProps, type CompositeDefinition, type CustomWidgetDefinition, type CustomWidgetSnapshot, DATA_ATTR_RE, DATA_RESULT_TYPES, type DataBinding, type DataInputDefinition, type DataResultType, type DataSourceDescriptor, type DocOp, type DocOpDevice, type DocumentKind, EACH_ITERATION_CAP, type EachNode, type ElementAttr, type ElementNode, type FieldSpec, type Filter, type FrozenAsset, ISSUE_CODES, type IconName, type IfNode, type InnerColumnNode, type InnerSectionNode, type Issue, type IssueCode, LIMITS, LOCALE_TAG_RE, type LocalizedText, MAX_ISSUES, MAX_TEMPLATE_WEIGHT, type MenuItem, type MenuTarget, NODE_ID_RE, type NodeId, type OpContext, type OutputNode, type Overrides, PREVIEW_WIDTHS, type PageDocument, type ParentId, type ParseTemplateResult, type PathSegment, type Placement, type PlacementCode, RESERVED_CLASS_PREFIXES, RESERVED_DATA_PREFIX, type ResponsiveDevice, SAFE_HREF, SETTING_CONTROLS, SETTING_TABS, SITE_ASSET_PATHS, SITE_FONTS, SITE_FONT_FAMILIES, SITE_SETTINGS_SCHEMA_VERSION, SITE_STRING_DEFAULTS, SITE_STRING_KEYS, SITE_STRING_NAMESPACES, SPACING_TOKENS, type SafeUrlKind, type SanitizeCssResult, type SectionNode, type SectionProps, type SettingField, type SettingValue, type SiteFont, type SiteFontCategory, type SiteFontFamily, type SitePalette, type SiteSettings, type SiteSettingsInput, type SiteStringKey, TEMPLATE_FILTERS, THROTTLE_PK_RE, type TemplateAst, type TemplateContext, type TemplateDefinition, type TemplateFilterName, type TemplateNode, type TextNode, type UnlessNode, type UpgradeResult, VOID_ELEMENTS, type ValidateCustomWidgetResult, WIDGET_GROUPS, WIDGET_TYPE_RE, type WidgetDefinition, type WidgetMigration, type WidgetNode, type WidgetRegistry, type WidgetType, agentDocOpSchema, agentDocOpsSchema, applyOps, assetIdSchema, canPlace, capIssues, checkLimits, checkTopLevel, checkWidgetPart, colorValueSchema, columnPropsSchema, createRegistry, customWidgetSnapshotSchema, dataBindingSchema, dataSourceDescriptorSchema, defaultSiteSettings, docOpSchema, emptyDocument, fieldSpecSchema, formatPath, frozenAssetSchema, innerSectionNodeSchema, invertOps, isReservedClass, isSettingValue, localeTagSchema, localizedTextSchema, makeIssue, menuItemSchema, menuTargetSchema, newNodeId, nodeIdSchema, pageDocumentSchema, parseTemplate, resolveColumnProps, resolveColumnWidths, resolveResponsive, safeUrl, sanitizeWidgetCss, sectionNodeSchema, sectionPropsSchema, settingFieldSchema, settingValueSchema, siteSettingsSchema, spacingValueSchema, templateWeight, upgradeDocument, upgradeNodes, utf8Length, validateCustomWidget, validateDocument, validateSettingValue, validateTemplate, validateWidgetProps, walkNodes, widgetDefinitionSchema, widgetNodeSchema, wrapColumnRows, zodIssues };