@usethrottle/builder-schema 0.0.0 → 0.1.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.
- package/README.md +39 -0
- package/dist/index.cjs +3530 -218
- package/dist/index.d.cts +494 -2
- package/dist/index.d.ts +494 -2
- package/dist/index.js +3528 -216
- package/package.json +2 -1
package/dist/index.d.cts
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
|
-
|
|
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 };
|