@dotcms/uve 1.2.1 → 1.2.2
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 +1143 -0
- package/index.cjs.js +621 -2
- package/index.esm.js +624 -2
- package/internal.cjs.js +0 -4
- package/internal.esm.js +1 -1
- package/package.json +4 -4
- package/public.cjs.js +10 -78
- package/public.esm.js +11 -75
- package/src/index.d.ts +2 -0
- package/src/internal/constants.d.ts +0 -2
- package/src/lib/core/core.utils.d.ts +0 -48
- package/src/lib/dom/dom.utils.d.ts +1 -10
- package/src/lib/style-editor/internal.d.ts +71 -0
- package/src/lib/style-editor/public.d.ts +372 -0
- package/src/lib/style-editor/types.d.ts +702 -0
- package/index.esm.d.ts +0 -1
- package/internal.esm.d.ts +0 -1
- /package/{index.cjs.d.ts → index.d.ts} +0 -0
- /package/{internal.cjs.d.ts → internal.d.ts} +0 -0
|
@@ -0,0 +1,702 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Available field types for the style editor.
|
|
3
|
+
*
|
|
4
|
+
* Each field type represents a different input control that can be used
|
|
5
|
+
* in the style editor form. Currently supported field types:
|
|
6
|
+
* - `input`: Text or number input fields
|
|
7
|
+
* - `dropdown`: Single-value selection from a dropdown list
|
|
8
|
+
* - `radio`: Single-value selection from radio button options
|
|
9
|
+
* - `checkboxGroup`: Multiple-value selection from checkbox options
|
|
10
|
+
* - `switch`: Boolean toggle switch (reserved for future implementation)
|
|
11
|
+
*/
|
|
12
|
+
export type StyleEditorFieldType = 'input' | 'dropdown' | 'radio' | 'checkboxGroup';
|
|
13
|
+
/**
|
|
14
|
+
* Available input types for input fields in the style editor.
|
|
15
|
+
*
|
|
16
|
+
* Determines the type of input control and the expected value type:
|
|
17
|
+
* - `'text'`: Standard text input for string values (e.g., font names, color codes)
|
|
18
|
+
* - `'number'`: Numeric input for number values (e.g., font sizes, dimensions)
|
|
19
|
+
*/
|
|
20
|
+
export type StyleEditorFieldInputType = 'text' | 'number';
|
|
21
|
+
/**
|
|
22
|
+
* Configuration type for creating input fields.
|
|
23
|
+
*
|
|
24
|
+
* This type is used by `styleEditorField.input()` to provide compile-time
|
|
25
|
+
* type checking for input field definitions.
|
|
26
|
+
*
|
|
27
|
+
* @typeParam T - The input type ('text' or 'number')
|
|
28
|
+
*/
|
|
29
|
+
export interface StyleEditorInputFieldConfig<T extends StyleEditorFieldInputType> {
|
|
30
|
+
/** The unique identifier for this field */
|
|
31
|
+
id: string;
|
|
32
|
+
/** The label text displayed to users for this field */
|
|
33
|
+
label: string;
|
|
34
|
+
/** The input type ('text' for strings, 'number' for numbers) */
|
|
35
|
+
inputType: T;
|
|
36
|
+
/** Optional placeholder text shown when the input is empty */
|
|
37
|
+
placeholder?: string;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Base option object with label and value properties.
|
|
41
|
+
*
|
|
42
|
+
* Used in dropdown, radio, and checkbox group fields to define
|
|
43
|
+
* selectable options with separate display labels and values.
|
|
44
|
+
*
|
|
45
|
+
* @property label - Display label shown to users
|
|
46
|
+
* @property value - Value returned when this option is selected
|
|
47
|
+
*/
|
|
48
|
+
export interface StyleEditorOptionObject {
|
|
49
|
+
/** Display label shown to users */
|
|
50
|
+
label: string;
|
|
51
|
+
/** Value returned when this option is selected */
|
|
52
|
+
value: string;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Extended option object for radio fields with visual properties.
|
|
56
|
+
*
|
|
57
|
+
* Extends the base option with optional image properties for
|
|
58
|
+
* creating visual radio button options (e.g., layout selectors with preview images).
|
|
59
|
+
*
|
|
60
|
+
* @property label - Display label shown to users
|
|
61
|
+
* @property value - Value returned when this option is selected
|
|
62
|
+
* @property imageURL - Optional URL to an image displayed for this option
|
|
63
|
+
*/
|
|
64
|
+
export interface StyleEditorRadioOptionObject extends StyleEditorOptionObject {
|
|
65
|
+
/** Optional URL to an image displayed for this option */
|
|
66
|
+
imageURL?: string;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Option type for dropdown and checkbox group fields.
|
|
70
|
+
*
|
|
71
|
+
* Can be a simple string (used as both label and value)
|
|
72
|
+
* or an object with separate label and value properties.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```typescript
|
|
76
|
+
* // String option - 'Arial' is used as both label and value
|
|
77
|
+
* const stringOption: StyleEditorOption = 'Arial';
|
|
78
|
+
*
|
|
79
|
+
* // Object option - separate label and value
|
|
80
|
+
* const objectOption: StyleEditorOption = {
|
|
81
|
+
* label: 'Times New Roman',
|
|
82
|
+
* value: 'times'
|
|
83
|
+
* };
|
|
84
|
+
* ```
|
|
85
|
+
*/
|
|
86
|
+
export type StyleEditorOption = StyleEditorOptionObject;
|
|
87
|
+
/**
|
|
88
|
+
* Helper type that extracts the union of all option values from an array of options.
|
|
89
|
+
*
|
|
90
|
+
* This type extracts the `value` property from each option object and creates
|
|
91
|
+
* a union type of all possible values.
|
|
92
|
+
*
|
|
93
|
+
* **Note:** For full type safety and autocomplete, use `as const` when defining options:
|
|
94
|
+
* ```typescript
|
|
95
|
+
* const options = [
|
|
96
|
+
* { label: 'The one', value: 'one' },
|
|
97
|
+
* { label: 'The two', value: 'two' }
|
|
98
|
+
* ] as const;
|
|
99
|
+
* ```
|
|
100
|
+
*
|
|
101
|
+
* @typeParam T - Array of option objects (should be `as const` for best results)
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* ```typescript
|
|
105
|
+
* const options = [
|
|
106
|
+
* { label: 'The one', value: 'one' },
|
|
107
|
+
* { label: 'The two', value: 'two' }
|
|
108
|
+
* ] as const;
|
|
109
|
+
*
|
|
110
|
+
* type OptionValues = StyleEditorOptionValues<typeof options>;
|
|
111
|
+
* // Result: 'one' | 'two'
|
|
112
|
+
* ```
|
|
113
|
+
*/
|
|
114
|
+
export type StyleEditorOptionValues<T extends readonly StyleEditorOption[]> = T[number] extends {
|
|
115
|
+
value: infer V;
|
|
116
|
+
} ? V : never;
|
|
117
|
+
/**
|
|
118
|
+
* Helper type that extracts the union of all radio option values from an array of radio options.
|
|
119
|
+
*
|
|
120
|
+
* Similar to `StyleEditorOptionValues`, but handles radio options which can be
|
|
121
|
+
* strings or objects. Extracts the `value` property from option objects, or uses
|
|
122
|
+
* the string itself if the option is a string.
|
|
123
|
+
*
|
|
124
|
+
* **Note:** For full type safety and autocomplete, use `as const` when defining options:
|
|
125
|
+
* ```typescript
|
|
126
|
+
* const options = [
|
|
127
|
+
* { label: 'The one', value: 'one' },
|
|
128
|
+
* { label: 'The two', value: 'two' }
|
|
129
|
+
* ] as const;
|
|
130
|
+
* ```
|
|
131
|
+
*
|
|
132
|
+
* @typeParam T - Array of radio option objects or strings (should be `as const` for best results)
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```typescript
|
|
136
|
+
* const options = [
|
|
137
|
+
* { label: 'The one', value: 'one' },
|
|
138
|
+
* { label: 'The two', value: 'two' }
|
|
139
|
+
* ] as const;
|
|
140
|
+
*
|
|
141
|
+
* type RadioOptionValues = StyleEditorRadioOptionValues<typeof options>;
|
|
142
|
+
* // Result: 'one' | 'two'
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
export type StyleEditorRadioOptionValues<T extends readonly StyleEditorRadioOption[]> = T[number] extends infer U ? U extends string ? U : U extends {
|
|
146
|
+
value: infer V;
|
|
147
|
+
} ? V : never : never;
|
|
148
|
+
/**
|
|
149
|
+
* Option type for radio fields with visual support.
|
|
150
|
+
*
|
|
151
|
+
* Can be a simple string (used as both label and value)
|
|
152
|
+
* or an object with label, value, and optional image properties.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```typescript
|
|
156
|
+
* // String option
|
|
157
|
+
* const stringOption: StyleEditorRadioOption = 'Left';
|
|
158
|
+
*
|
|
159
|
+
* // Object option with image
|
|
160
|
+
* const imageOption: StyleEditorRadioOption = {
|
|
161
|
+
* label: 'Left Layout',
|
|
162
|
+
* value: 'left',
|
|
163
|
+
* imageURL: 'https://example.com/left-layout.png'
|
|
164
|
+
* };
|
|
165
|
+
* ```
|
|
166
|
+
*/
|
|
167
|
+
export type StyleEditorRadioOption = StyleEditorRadioOptionObject;
|
|
168
|
+
/**
|
|
169
|
+
* Checkbox option object with label and key identifier.
|
|
170
|
+
*
|
|
171
|
+
* Unlike dropdown and radio options where `value` represents the actual value,
|
|
172
|
+
* checkbox options use `key` as the identifier. The checked state is managed
|
|
173
|
+
* by the form system and is not stored in the option definition.
|
|
174
|
+
*
|
|
175
|
+
* @property label - Display label shown to users
|
|
176
|
+
* @property key - Unique identifier/key used for this checkbox option
|
|
177
|
+
*
|
|
178
|
+
* @example
|
|
179
|
+
* ```typescript
|
|
180
|
+
* const checkboxOption: StyleEditorCheckboxOption = {
|
|
181
|
+
* label: 'Underline',
|
|
182
|
+
* key: 'underline'
|
|
183
|
+
* };
|
|
184
|
+
* ```
|
|
185
|
+
*/
|
|
186
|
+
export interface StyleEditorCheckboxOption {
|
|
187
|
+
/** Display label shown to users */
|
|
188
|
+
label: string;
|
|
189
|
+
/** Unique identifier/key used for this checkbox option */
|
|
190
|
+
key: string;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Checkbox group value type.
|
|
194
|
+
*
|
|
195
|
+
* A record mapping option keys to their boolean checked state.
|
|
196
|
+
* Keys match the `key` property from checkbox options, values indicate whether the option is checked.
|
|
197
|
+
*
|
|
198
|
+
* @example
|
|
199
|
+
* ```typescript
|
|
200
|
+
* const checkboxState: StyleEditorCheckboxDefaultValue = {
|
|
201
|
+
* 'underline': true,
|
|
202
|
+
* 'overline': false,
|
|
203
|
+
* 'line-through': false
|
|
204
|
+
* };
|
|
205
|
+
* ```
|
|
206
|
+
*/
|
|
207
|
+
export type StyleEditorCheckboxDefaultValue = Record<string, boolean>;
|
|
208
|
+
/**
|
|
209
|
+
* Base field definition that all field types extend.
|
|
210
|
+
*
|
|
211
|
+
* Provides the common properties shared by all field types in the style editor.
|
|
212
|
+
* All specific field types must include these base properties. The `type` property
|
|
213
|
+
* serves as a discriminator that allows TypeScript to narrow union types based on
|
|
214
|
+
* the field type.
|
|
215
|
+
*
|
|
216
|
+
* @property type - The type of field (discriminator for union types, enables type narrowing)
|
|
217
|
+
* @property label - The human-readable label displayed for this field in the UI
|
|
218
|
+
*/
|
|
219
|
+
export interface StyleEditorBaseField {
|
|
220
|
+
/** The unique identifier for this field */
|
|
221
|
+
id: string;
|
|
222
|
+
/** The type of field, used to discriminate between different field types in union types */
|
|
223
|
+
type: StyleEditorFieldType;
|
|
224
|
+
/** The label text displayed to users for this field */
|
|
225
|
+
label: string;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Input field definition.
|
|
229
|
+
*
|
|
230
|
+
* Supports both text and number input types for different value types.
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* ```typescript
|
|
234
|
+
* // Number input
|
|
235
|
+
* const numberField: StyleEditorInputField = {
|
|
236
|
+
* type: 'input',
|
|
237
|
+
* id: 'font-size',
|
|
238
|
+
* label: 'Font Size',
|
|
239
|
+
* inputType: 'number',
|
|
240
|
+
* placeholder: 'Enter font size'
|
|
241
|
+
* };
|
|
242
|
+
*
|
|
243
|
+
* // Text input
|
|
244
|
+
* const textField: StyleEditorInputField = {
|
|
245
|
+
* type: 'input',
|
|
246
|
+
* id: 'font-name',
|
|
247
|
+
* label: 'Font Name',
|
|
248
|
+
* inputType: 'text',
|
|
249
|
+
* placeholder: 'Enter font name'
|
|
250
|
+
* };
|
|
251
|
+
* ```
|
|
252
|
+
*/
|
|
253
|
+
export type StyleEditorInputField = (StyleEditorBaseField & {
|
|
254
|
+
/** Discriminator: must be 'input' */
|
|
255
|
+
type: 'input';
|
|
256
|
+
/** Input type for number values */
|
|
257
|
+
inputType: 'number';
|
|
258
|
+
/** Optional placeholder text shown when the input is empty */
|
|
259
|
+
placeholder?: string;
|
|
260
|
+
}) | (StyleEditorBaseField & {
|
|
261
|
+
/** Discriminator: must be 'input' */
|
|
262
|
+
type: 'input';
|
|
263
|
+
/** Input type for text/string values */
|
|
264
|
+
inputType: 'text';
|
|
265
|
+
/** Optional placeholder text shown when the input is empty */
|
|
266
|
+
placeholder?: string;
|
|
267
|
+
});
|
|
268
|
+
/**
|
|
269
|
+
* Dropdown field definition for single-value selection.
|
|
270
|
+
*
|
|
271
|
+
* Allows users to select a single option from a dropdown list.
|
|
272
|
+
* Options can be provided as simple strings or as objects with
|
|
273
|
+
* separate label and value properties for more flexibility.
|
|
274
|
+
*
|
|
275
|
+
* **Best Practice:** Use `as const` when defining options for better type safety:
|
|
276
|
+
* ```typescript
|
|
277
|
+
* const OPTIONS = [
|
|
278
|
+
* { label: '18', value: '18px' },
|
|
279
|
+
* { label: '24', value: '24px' }
|
|
280
|
+
* ] as const;
|
|
281
|
+
*
|
|
282
|
+
* styleEditorField.dropdown({
|
|
283
|
+
* id: 'size',
|
|
284
|
+
* label: 'Size',
|
|
285
|
+
* options: OPTIONS
|
|
286
|
+
* });
|
|
287
|
+
* ```
|
|
288
|
+
*
|
|
289
|
+
* @property type - Must be 'dropdown'
|
|
290
|
+
* @property options - Array of selectable options. Can be strings or objects with label/value. Use `as const` for best type safety.
|
|
291
|
+
*
|
|
292
|
+
* @example
|
|
293
|
+
* ```typescript
|
|
294
|
+
* const dropdownField: StyleEditorDropdownField = {
|
|
295
|
+
* type: 'dropdown',
|
|
296
|
+
* id: 'font-family',
|
|
297
|
+
* label: 'Font Family',
|
|
298
|
+
* options: ['Arial', 'Helvetica', { label: 'Times New Roman', value: 'times' }]
|
|
299
|
+
* };
|
|
300
|
+
* ```
|
|
301
|
+
*/
|
|
302
|
+
export interface StyleEditorDropdownField extends StyleEditorBaseField {
|
|
303
|
+
/** Discriminator: must be 'dropdown' */
|
|
304
|
+
type: 'dropdown';
|
|
305
|
+
/** Array of selectable options. Can be strings or objects with label and value properties. Accepts readonly arrays (use `as const` for best type safety). */
|
|
306
|
+
options: readonly StyleEditorOption[];
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Radio button field definition for single-value selection with visual options.
|
|
310
|
+
*
|
|
311
|
+
* Allows users to select a single option from a radio button group.
|
|
312
|
+
* Supports visual options with background images for enhanced UI/UX.
|
|
313
|
+
* Options can be provided as simple strings or as objects with label,
|
|
314
|
+
* value, and optional image properties.
|
|
315
|
+
*
|
|
316
|
+
* **Layout Options:**
|
|
317
|
+
* - `columns: 1` (default): Single column list layout
|
|
318
|
+
* - `columns: 2`: Two-column grid layout, ideal for visual options with images
|
|
319
|
+
*
|
|
320
|
+
* **Best Practice:** Use `as const` when defining options for better type safety:
|
|
321
|
+
* ```typescript
|
|
322
|
+
* const RADIO_OPTIONS = [
|
|
323
|
+
* { label: 'Left', value: 'left' },
|
|
324
|
+
* { label: 'Right', value: 'right' }
|
|
325
|
+
* ] as const;
|
|
326
|
+
*
|
|
327
|
+
* styleEditorField.radio({
|
|
328
|
+
* id: 'layout',
|
|
329
|
+
* label: 'Layout',
|
|
330
|
+
* options: RADIO_OPTIONS
|
|
331
|
+
* });
|
|
332
|
+
* ```
|
|
333
|
+
*
|
|
334
|
+
* @property type - Must be 'radio'
|
|
335
|
+
* @property options - Array of selectable options. Can be strings or objects with label, value, and optional image properties. Use `as const` for best type safety.
|
|
336
|
+
* @property columns - Optional number of columns for layout (1 or 2). Defaults to 1
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```typescript
|
|
340
|
+
* // Single column layout (default)
|
|
341
|
+
* const alignmentField: StyleEditorRadioField = {
|
|
342
|
+
* type: 'radio',
|
|
343
|
+
* id: 'alignment',
|
|
344
|
+
* label: 'Alignment',
|
|
345
|
+
* options: ['Left', 'Center', 'Right']
|
|
346
|
+
* };
|
|
347
|
+
*
|
|
348
|
+
* // Two-column grid layout with images
|
|
349
|
+
* const layoutField: StyleEditorRadioField = {
|
|
350
|
+
* type: 'radio',
|
|
351
|
+
* id: 'layout',
|
|
352
|
+
* label: 'Layout',
|
|
353
|
+
* columns: 2,
|
|
354
|
+
* options: [
|
|
355
|
+
* {
|
|
356
|
+
* label: 'Left',
|
|
357
|
+
* value: 'left',
|
|
358
|
+
* imageURL: 'https://example.com/layout-left.png'
|
|
359
|
+
* },
|
|
360
|
+
* {
|
|
361
|
+
* label: 'Right',
|
|
362
|
+
* value: 'right',
|
|
363
|
+
* imageURL: 'https://example.com/layout-right.png'
|
|
364
|
+
* },
|
|
365
|
+
* { label: 'Center', value: 'center' },
|
|
366
|
+
* { label: 'Overlap', value: 'overlap' }
|
|
367
|
+
* ]
|
|
368
|
+
* };
|
|
369
|
+
* ```
|
|
370
|
+
*/
|
|
371
|
+
export interface StyleEditorRadioField extends StyleEditorBaseField {
|
|
372
|
+
/** Discriminator: must be 'radio' */
|
|
373
|
+
type: 'radio';
|
|
374
|
+
/**
|
|
375
|
+
* Array of selectable options. Can be:
|
|
376
|
+
* - Simple strings (used as both label and value)
|
|
377
|
+
* - Objects with label, value, and optional imageURL for visual options
|
|
378
|
+
* Accepts readonly arrays (use `as const` for best type safety).
|
|
379
|
+
*/
|
|
380
|
+
options: readonly StyleEditorRadioOption[];
|
|
381
|
+
/**
|
|
382
|
+
* Number of columns to display options in.
|
|
383
|
+
* - `1`: Single column list layout (default)
|
|
384
|
+
* - `2`: Two-column grid layout
|
|
385
|
+
*/
|
|
386
|
+
columns?: 1 | 2;
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Checkbox group field definition for multiple-value selection.
|
|
390
|
+
*
|
|
391
|
+
* Allows users to select multiple options simultaneously. Each option
|
|
392
|
+
* can be independently checked or unchecked. The checked state is managed
|
|
393
|
+
* by the form system and is not stored in the option definition.
|
|
394
|
+
*
|
|
395
|
+
* **Key Differences from Other Field Types:**
|
|
396
|
+
* - Uses `key` instead of `value` for the identifier (to avoid confusion)
|
|
397
|
+
* - Checked state is managed by the form system, not stored in the option definition
|
|
398
|
+
*
|
|
399
|
+
* @property type - Must be 'checkboxGroup'
|
|
400
|
+
* @property options - Array of checkbox options with label and key
|
|
401
|
+
*
|
|
402
|
+
* @example
|
|
403
|
+
* ```typescript
|
|
404
|
+
* const checkboxField: StyleEditorCheckboxGroupField = {
|
|
405
|
+
* type: 'checkboxGroup',
|
|
406
|
+
* id: 'text-decoration',
|
|
407
|
+
* label: 'Text Decoration',
|
|
408
|
+
* options: [
|
|
409
|
+
* { label: 'Underline', key: 'underline' },
|
|
410
|
+
* { label: 'Overline', key: 'overline' },
|
|
411
|
+
* { label: 'Line Through', key: 'line-through' }
|
|
412
|
+
* ]
|
|
413
|
+
* };
|
|
414
|
+
* ```
|
|
415
|
+
*/
|
|
416
|
+
export interface StyleEditorCheckboxGroupField extends StyleEditorBaseField {
|
|
417
|
+
/** Discriminator: must be 'checkboxGroup' */
|
|
418
|
+
type: 'checkboxGroup';
|
|
419
|
+
/**
|
|
420
|
+
* Array of checkbox options. Each option contains:
|
|
421
|
+
* - `label`: Display text shown to users
|
|
422
|
+
* - `key`: Unique identifier for this checkbox option
|
|
423
|
+
*/
|
|
424
|
+
options: StyleEditorCheckboxOption[];
|
|
425
|
+
}
|
|
426
|
+
/**
|
|
427
|
+
* Union type of all possible field definitions.
|
|
428
|
+
*
|
|
429
|
+
* Represents any valid field type that can be used in a style editor form.
|
|
430
|
+
* This is a discriminated union type, meaning TypeScript can narrow the type
|
|
431
|
+
* based on the `type` property. Use this type when you need to work with
|
|
432
|
+
* fields of unknown or mixed types.
|
|
433
|
+
*
|
|
434
|
+
* **Supported Field Types:**
|
|
435
|
+
* - `StyleEditorInputField`: Text or number input fields
|
|
436
|
+
* - `StyleEditorDropdownField`: Single-value selection from dropdown
|
|
437
|
+
* - `StyleEditorRadioField`: Single-value selection from radio buttons
|
|
438
|
+
* - `StyleEditorCheckboxGroupField`: Multiple-value selection from checkboxes
|
|
439
|
+
*
|
|
440
|
+
* **Note:** The `switch` field type is reserved for future implementation
|
|
441
|
+
* and is not currently included in this union type.
|
|
442
|
+
*
|
|
443
|
+
* @example
|
|
444
|
+
* ```typescript
|
|
445
|
+
* const fields: StyleEditorField[] = [
|
|
446
|
+
* { type: 'input', id: 'font-size', label: 'Font Size', inputType: 'number' },
|
|
447
|
+
* { type: 'dropdown', id: 'font-family', label: 'Font Family', options: ['Arial', 'Helvetica'] },
|
|
448
|
+
* { type: 'radio', id: 'theme', label: 'Theme', options: ['Light', 'Dark'] },
|
|
449
|
+
* {
|
|
450
|
+
* type: 'checkboxGroup',
|
|
451
|
+
* id: 'styles',
|
|
452
|
+
* label: 'Styles',
|
|
453
|
+
* options: [
|
|
454
|
+
* { label: 'Bold', key: 'bold', value: true },
|
|
455
|
+
* { label: 'Italic', key: 'italic', value: false }
|
|
456
|
+
* ]
|
|
457
|
+
* }
|
|
458
|
+
* ];
|
|
459
|
+
*
|
|
460
|
+
* // TypeScript can narrow the type based on the discriminator
|
|
461
|
+
* function processField(field: StyleEditorField) {
|
|
462
|
+
* if (field.type === 'input') {
|
|
463
|
+
* // field is now narrowed to StyleEditorInputField
|
|
464
|
+
* console.log(field.inputType); // Type-safe access
|
|
465
|
+
* }
|
|
466
|
+
* }
|
|
467
|
+
* ```
|
|
468
|
+
*/
|
|
469
|
+
export type StyleEditorField = StyleEditorInputField | StyleEditorDropdownField | StyleEditorRadioField | StyleEditorCheckboxGroupField;
|
|
470
|
+
/**
|
|
471
|
+
* Section definition for organizing fields in a style editor form.
|
|
472
|
+
*
|
|
473
|
+
* Sections group related fields together with a title. All sections use a
|
|
474
|
+
* single-column layout with a flat array of fields. During normalization,
|
|
475
|
+
* these fields are automatically organized into the multi-dimensional array
|
|
476
|
+
* structure required by UVE.
|
|
477
|
+
*
|
|
478
|
+
* @property title - The section title displayed to users
|
|
479
|
+
* @property fields - Array of field definitions in this section
|
|
480
|
+
*
|
|
481
|
+
* @example
|
|
482
|
+
* ```typescript
|
|
483
|
+
* const section: StyleEditorSection = {
|
|
484
|
+
* title: 'Typography',
|
|
485
|
+
* fields: [
|
|
486
|
+
* { type: 'input', id: 'font-size', label: 'Font Size', inputType: 'number' },
|
|
487
|
+
* { type: 'dropdown', id: 'font-family', label: 'Font Family', options: ['Arial', 'Helvetica'] },
|
|
488
|
+
* { type: 'radio', id: 'alignment', label: 'Alignment', options: ['Left', 'Center', 'Right'] }
|
|
489
|
+
* ]
|
|
490
|
+
* };
|
|
491
|
+
* ```
|
|
492
|
+
*/
|
|
493
|
+
export interface StyleEditorSection {
|
|
494
|
+
/** The section title displayed to users */
|
|
495
|
+
title: string;
|
|
496
|
+
/** Array of field definitions in this section */
|
|
497
|
+
fields: StyleEditorField[];
|
|
498
|
+
}
|
|
499
|
+
/**
|
|
500
|
+
* Complete style editor form definition.
|
|
501
|
+
*
|
|
502
|
+
* Represents the full structure of a style editor form, including
|
|
503
|
+
* the content type identifier and all sections with their fields.
|
|
504
|
+
* This is the developer-friendly format used to define forms before
|
|
505
|
+
* they are normalized and sent to UVE.
|
|
506
|
+
*
|
|
507
|
+
* **Form Structure:**
|
|
508
|
+
* - Each form is associated with a specific content type via `contentType`
|
|
509
|
+
* - Forms contain one or more sections, each with a title and array of fields
|
|
510
|
+
* - All sections use a single-column layout (flat array of fields)
|
|
511
|
+
* - During normalization via `defineStyleEditorForm`, sections are automatically
|
|
512
|
+
* converted to the multi-dimensional array structure required by UVE
|
|
513
|
+
*
|
|
514
|
+
* @property contentType - The content type identifier this form is associated with
|
|
515
|
+
* @property sections - Array of sections, each containing a title and fields array
|
|
516
|
+
*
|
|
517
|
+
* @example
|
|
518
|
+
* ```typescript
|
|
519
|
+
* const form: StyleEditorForm = {
|
|
520
|
+
* contentType: 'my-content-type',
|
|
521
|
+
* sections: [
|
|
522
|
+
* {
|
|
523
|
+
* title: 'Typography',
|
|
524
|
+
* fields: [
|
|
525
|
+
* { type: 'input', id: 'font-size', label: 'Font Size', inputType: 'number' },
|
|
526
|
+
* { type: 'dropdown', id: 'font-family', label: 'Font Family', options: ['Arial', 'Helvetica'] },
|
|
527
|
+
* { type: 'radio', id: 'alignment', label: 'Alignment', options: ['Left', 'Center', 'Right'] }
|
|
528
|
+
* ]
|
|
529
|
+
* },
|
|
530
|
+
* {
|
|
531
|
+
* title: 'Colors',
|
|
532
|
+
* fields: [
|
|
533
|
+
* { type: 'input', id: 'primary-color', label: 'Primary Color', inputType: 'text' },
|
|
534
|
+
* { type: 'input', id: 'secondary-color', label: 'Secondary Color', inputType: 'text' }
|
|
535
|
+
* ]
|
|
536
|
+
* }
|
|
537
|
+
* ]
|
|
538
|
+
* };
|
|
539
|
+
* ```
|
|
540
|
+
*/
|
|
541
|
+
export interface StyleEditorForm {
|
|
542
|
+
/** The content type identifier this form is associated with */
|
|
543
|
+
contentType: string;
|
|
544
|
+
/** Array of sections, each containing a title and fields */
|
|
545
|
+
sections: StyleEditorSection[];
|
|
546
|
+
}
|
|
547
|
+
/**
|
|
548
|
+
* ============================================================================
|
|
549
|
+
* UVE Style Editor Schema Types
|
|
550
|
+
* ============================================================================
|
|
551
|
+
*
|
|
552
|
+
* The following types represent the normalized schema format sent to UVE
|
|
553
|
+
* (Universal Visual Editor). These are the output types after processing
|
|
554
|
+
* and normalizing the developer-friendly StyleEditorForm definitions.
|
|
555
|
+
* ============================================================================
|
|
556
|
+
*/
|
|
557
|
+
/**
|
|
558
|
+
* Configuration object for normalized field schemas.
|
|
559
|
+
*
|
|
560
|
+
* Contains all possible field-specific properties after normalization.
|
|
561
|
+
* This interface is used by `StyleEditorFieldSchema` to define the `config` property.
|
|
562
|
+
*
|
|
563
|
+
* **Note:** All properties are optional since different field types use different subsets:
|
|
564
|
+
* - Input fields use: `inputType`, `placeholder`
|
|
565
|
+
* - Dropdown fields use: `options`
|
|
566
|
+
* - Radio fields use: `options`, `columns`
|
|
567
|
+
* - Checkbox fields use: `options`
|
|
568
|
+
*/
|
|
569
|
+
export interface StyleEditorFieldSchemaConfig {
|
|
570
|
+
/** Optional input type for input fields ('text' or 'number') */
|
|
571
|
+
inputType?: StyleEditorFieldInputType;
|
|
572
|
+
/** Optional placeholder text shown when the field is empty */
|
|
573
|
+
placeholder?: string;
|
|
574
|
+
/**
|
|
575
|
+
* Optional array of normalized options for dropdown, radio, and checkbox fields.
|
|
576
|
+
* In the normalized schema, options are always in object form (strings are converted).
|
|
577
|
+
* Uses `StyleEditorRadioOptionObject` as the superset that supports all option properties.
|
|
578
|
+
*/
|
|
579
|
+
options?: StyleEditorRadioOptionObject[];
|
|
580
|
+
/**
|
|
581
|
+
* Number of columns to display options in (for radio fields).
|
|
582
|
+
* - `1`: Single column list layout (default)
|
|
583
|
+
* - `2`: Two-column grid layout
|
|
584
|
+
*/
|
|
585
|
+
columns?: 1 | 2;
|
|
586
|
+
}
|
|
587
|
+
/**
|
|
588
|
+
* Normalized field schema sent to UVE.
|
|
589
|
+
*
|
|
590
|
+
* This is the transformed format of field definitions after normalization.
|
|
591
|
+
* All field-specific properties are moved into a `config` object, ensuring
|
|
592
|
+
* a consistent structure that UVE can consume.
|
|
593
|
+
*
|
|
594
|
+
* **Normalization Process:**
|
|
595
|
+
* - Type-specific properties (like `inputType`, `options`, `placeholder`) are moved into `config`
|
|
596
|
+
* - String options are normalized to `{ label, value }` objects
|
|
597
|
+
* - Radio field image properties (`imageURL`) are preserved in option objects
|
|
598
|
+
* - The `type`, `id`, and `label` remain at the top level for easy access
|
|
599
|
+
*
|
|
600
|
+
* @property type - The field type identifier (discriminator for field types)
|
|
601
|
+
* @property label - The human-readable label displayed for this field
|
|
602
|
+
* @property config - Object containing all field-specific configuration properties
|
|
603
|
+
*/
|
|
604
|
+
export interface StyleEditorFieldSchema {
|
|
605
|
+
/** The unique identifier for this field */
|
|
606
|
+
id: string;
|
|
607
|
+
/** The field type identifier */
|
|
608
|
+
type: StyleEditorFieldType;
|
|
609
|
+
/** The field label */
|
|
610
|
+
label: string;
|
|
611
|
+
/** Object containing all field-specific configuration */
|
|
612
|
+
config: StyleEditorFieldSchemaConfig;
|
|
613
|
+
}
|
|
614
|
+
/**
|
|
615
|
+
* Normalized section schema sent to UVE.
|
|
616
|
+
*
|
|
617
|
+
* Represents a section in the normalized UVE format. All sections
|
|
618
|
+
* use a consistent multi-dimensional array structure (array of arrays),
|
|
619
|
+
* even for single-column layouts. This ensures a uniform schema format
|
|
620
|
+
* that UVE can consume.
|
|
621
|
+
*
|
|
622
|
+
* **Structure:**
|
|
623
|
+
* - The `fields` property is always a two-dimensional array
|
|
624
|
+
* - Each inner array represents a column (currently all sections use a single column)
|
|
625
|
+
* - Each field in the inner arrays is a normalized `StyleEditorFieldSchema` with
|
|
626
|
+
* all properties moved into the `config` object
|
|
627
|
+
*
|
|
628
|
+
* @property title - The section title displayed to users
|
|
629
|
+
* @property fields - Two-dimensional array where each inner array contains normalized field schemas for a column
|
|
630
|
+
*
|
|
631
|
+
* @example
|
|
632
|
+
* ```typescript
|
|
633
|
+
* // Single-column section (normalized format)
|
|
634
|
+
* const sectionSchema: StyleEditorSectionSchema = {
|
|
635
|
+
* title: 'Typography',
|
|
636
|
+
* fields: [
|
|
637
|
+
* // Single column containing all fields
|
|
638
|
+
* [
|
|
639
|
+
* { type: 'input', id: 'font-size', label: 'Font Size', config: { inputType: 'number' } },
|
|
640
|
+
* { type: 'dropdown', id: 'font-family', label: 'Font Family', config: { options: [...] } }
|
|
641
|
+
* ]
|
|
642
|
+
* ]
|
|
643
|
+
* };
|
|
644
|
+
* ```
|
|
645
|
+
*/
|
|
646
|
+
export interface StyleEditorSectionSchema {
|
|
647
|
+
/** The section title displayed to users */
|
|
648
|
+
title: string;
|
|
649
|
+
/** Two-dimensional array where each inner array contains normalized field schemas for a column */
|
|
650
|
+
fields: StyleEditorFieldSchema[];
|
|
651
|
+
}
|
|
652
|
+
/**
|
|
653
|
+
* Complete normalized form schema sent to UVE.
|
|
654
|
+
*
|
|
655
|
+
* This is the final output format after normalizing a `StyleEditorForm` using
|
|
656
|
+
* `defineStyleEditorForm`. The form structure is transformed into a consistent
|
|
657
|
+
* schema format that UVE (Universal Visual Editor) can consume.
|
|
658
|
+
*
|
|
659
|
+
* **Normalization Characteristics:**
|
|
660
|
+
* - All sections use the multi-dimensional array structure (`fields: StyleEditorFieldSchema[][]`)
|
|
661
|
+
* - All field-specific properties are moved into `config` objects
|
|
662
|
+
* - String options are normalized to `{ label, value }` objects
|
|
663
|
+
* - The `contentType` identifier is preserved for association with content types
|
|
664
|
+
*
|
|
665
|
+
* This schema format is ready to be sent to UVE via `registerStyleEditorSchemas`.
|
|
666
|
+
*
|
|
667
|
+
* @property contentType - The content type identifier this form is associated with
|
|
668
|
+
* @property sections - Array of normalized section schemas, each with fields organized as a multi-dimensional array
|
|
669
|
+
*
|
|
670
|
+
* @example
|
|
671
|
+
* ```typescript
|
|
672
|
+
* const formSchema: StyleEditorFormSchema = {
|
|
673
|
+
* contentType: 'my-content-type',
|
|
674
|
+
* sections: [
|
|
675
|
+
* {
|
|
676
|
+
* title: 'Typography',
|
|
677
|
+
* fields: [
|
|
678
|
+
* // Single column containing all fields
|
|
679
|
+
* [
|
|
680
|
+
* { type: 'input', id: 'font-size', label: 'Font Size', config: { inputType: 'number' } },
|
|
681
|
+
* { type: 'dropdown', id: 'font-family', label: 'Font Family', config: { options: [{ label: 'Arial', value: 'Arial' }] } }
|
|
682
|
+
* ]
|
|
683
|
+
* ]
|
|
684
|
+
* },
|
|
685
|
+
* {
|
|
686
|
+
* title: 'Colors',
|
|
687
|
+
* fields: [
|
|
688
|
+
* [
|
|
689
|
+
* { type: 'input', id: 'primary-color', label: 'Primary Color', config: { inputType: 'text' } }
|
|
690
|
+
* ]
|
|
691
|
+
* ]
|
|
692
|
+
* }
|
|
693
|
+
* ]
|
|
694
|
+
* };
|
|
695
|
+
* ```
|
|
696
|
+
*/
|
|
697
|
+
export interface StyleEditorFormSchema {
|
|
698
|
+
/** The content type identifier this form is associated with */
|
|
699
|
+
contentType: string;
|
|
700
|
+
/** Array of normalized section schemas */
|
|
701
|
+
sections: StyleEditorSectionSchema[];
|
|
702
|
+
}
|
package/index.esm.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export * from "./src/index";
|
package/internal.esm.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export * from "./src/internal";
|