@molecule/app-rule-builder-svelte 0.0.1-stage → 1.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 +435 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,442 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:47:11.554Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-rule-builder-svelte
|
|
2
10
|
|
|
3
|
-
Visual condition / rule builder
|
|
11
|
+
Visual condition / rule builder for Svelte.
|
|
12
|
+
|
|
13
|
+
Exports:
|
|
14
|
+
|
|
15
|
+
- `<RuleBuilder>` — controlled tree editor for AND / OR groups of
|
|
16
|
+
field-operator-value leaves.
|
|
17
|
+
- `RuleSchema`, `RuleField`, `RuleOperator`, `Rule`, `RuleGroup`,
|
|
18
|
+
`RuleLeaf`, `RuleLeafValue`, `RuleGroupOp`, `RuleFieldType` types.
|
|
19
|
+
- `defaultOperators`, `operatorsFor`, `operatorById`, `OP` operator
|
|
20
|
+
catalog helpers.
|
|
21
|
+
- `emptyGroup`, `emptyLeaf`, `replaceById`, `removeById`,
|
|
22
|
+
`appendToGroup`, `toggleGroupOp`, `makeId` pure tree utilities.
|
|
23
|
+
|
|
24
|
+
Used by feature-flag-manager (audience targeting),
|
|
25
|
+
ai-workflow-automator (trigger conditions), email-marketing
|
|
26
|
+
(segments), iot-device-manager + smart-home-dashboard (scenes /
|
|
27
|
+
automations).
|
|
28
|
+
|
|
29
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
30
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
31
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
32
|
+
|
|
33
|
+
## Quick Start
|
|
34
|
+
|
|
35
|
+
```svelte
|
|
36
|
+
<script lang="ts">
|
|
37
|
+
import {
|
|
38
|
+
RuleBuilder,
|
|
39
|
+
emptyGroup,
|
|
40
|
+
type Rule,
|
|
41
|
+
type RuleSchema,
|
|
42
|
+
} from '@molecule/app-rule-builder-svelte'
|
|
43
|
+
|
|
44
|
+
const schema: RuleSchema = {
|
|
45
|
+
fields: [
|
|
46
|
+
{
|
|
47
|
+
name: 'country',
|
|
48
|
+
label: 'Country',
|
|
49
|
+
type: 'select',
|
|
50
|
+
options: [{ value: 'US', label: 'United States' }],
|
|
51
|
+
},
|
|
52
|
+
{ name: 'plan', label: 'Plan', type: 'text' },
|
|
53
|
+
{ name: 'spend', label: 'Spend', type: 'number' },
|
|
54
|
+
],
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
let rules = $state<Rule>(emptyGroup('AND'))
|
|
58
|
+
</script>
|
|
59
|
+
|
|
60
|
+
<RuleBuilder {schema} {rules} onChange={(next) => (rules = next)} />
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Type
|
|
64
|
+
|
|
65
|
+
`feature`
|
|
66
|
+
|
|
67
|
+
## Installation
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install @molecule/app-rule-builder-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## API
|
|
74
|
+
|
|
75
|
+
### Interfaces
|
|
76
|
+
|
|
77
|
+
#### `RuleOperator`
|
|
78
|
+
|
|
79
|
+
Operator descriptor — `id` is what's stored on the leaf, `label` is
|
|
80
|
+
what's shown in the operator dropdown.
|
|
81
|
+
|
|
82
|
+
`arity` controls how many value inputs are rendered:
|
|
83
|
+
|
|
84
|
+
- `'unary'` — no value input (e.g. `is empty`, `exists`)
|
|
85
|
+
- `'binary'` — one value input (default)
|
|
86
|
+
- `'between'` — two value inputs (rendered as `from`/`to`)
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
interface RuleOperator {
|
|
90
|
+
/** Operator id stored on the leaf. */
|
|
91
|
+
id: string
|
|
92
|
+
/** Translated, human-readable label. */
|
|
93
|
+
label: string
|
|
94
|
+
/** Number of value inputs to render. Default `'binary'`. */
|
|
95
|
+
arity?: 'unary' | 'binary' | 'between'
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### `RuleField`
|
|
100
|
+
|
|
101
|
+
Field descriptor in the schema — the rule builder uses it to render
|
|
102
|
+
the field dropdown, infer the value editor, and (when no explicit
|
|
103
|
+
`operators` list is given) pick a default operator catalog by `type`.
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
interface RuleField {
|
|
107
|
+
/** Stable field identifier stored on the leaf. */
|
|
108
|
+
name: string
|
|
109
|
+
/** Translated, human-readable label shown in the field dropdown. */
|
|
110
|
+
label: string
|
|
111
|
+
/** Built-in type used to pick the value editor + default operators. */
|
|
112
|
+
type: RuleFieldType
|
|
113
|
+
/**
|
|
114
|
+
* Operators valid for this field. Optional — when omitted, the
|
|
115
|
+
* builder uses the default catalog for `type` from `defaultOperators`.
|
|
116
|
+
*/
|
|
117
|
+
operators?: RuleOperator[]
|
|
118
|
+
/**
|
|
119
|
+
* For `type: 'select'` — the option list rendered as a `<Select>`.
|
|
120
|
+
* Ignored for other types.
|
|
121
|
+
*/
|
|
122
|
+
options?: Array<{ value: string; label: string }>
|
|
123
|
+
/** Optional placeholder for text/number/date inputs. */
|
|
124
|
+
placeholder?: string
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
#### `RuleSchema`
|
|
129
|
+
|
|
130
|
+
Schema given to `<RuleBuilder>`. Currently only `fields` — kept as an
|
|
131
|
+
object so future schema-level config (max depth, group limit, etc.)
|
|
132
|
+
can be added without breaking the API.
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
interface RuleSchema {
|
|
136
|
+
/** Available fields, in the order they appear in the field dropdown. */
|
|
137
|
+
fields: RuleField[]
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
#### `RuleLeaf`
|
|
142
|
+
|
|
143
|
+
Leaf rule — a single `field op value` predicate.
|
|
144
|
+
|
|
145
|
+
`value` is opaque to the builder for `text` / `number` / `select` /
|
|
146
|
+
`boolean` (it stores whatever the input produced — string for text /
|
|
147
|
+
select / date, number for number, boolean for boolean). For `between`
|
|
148
|
+
arity operators it's stored as a `[from, to]` two-element tuple.
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
interface RuleLeaf {
|
|
152
|
+
/** Discriminator. */
|
|
153
|
+
kind: 'leaf'
|
|
154
|
+
/** Stable id (uuid-ish) — used for element identity + delete identity. */
|
|
155
|
+
id: string
|
|
156
|
+
/** Field name from the schema. Empty string when unset. */
|
|
157
|
+
field: string
|
|
158
|
+
/** Operator id from the field's operator catalog. Empty when unset. */
|
|
159
|
+
op: string
|
|
160
|
+
/**
|
|
161
|
+
* Current value. `undefined` when unset. Encoding depends on the
|
|
162
|
+
* operator's `arity`:
|
|
163
|
+
* - `'unary'` — value is ignored.
|
|
164
|
+
* - `'binary'` — string | number | boolean.
|
|
165
|
+
* - `'between'` — `[from, to]` tuple.
|
|
166
|
+
*/
|
|
167
|
+
value?: RuleLeafValue
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
#### `RuleGroup`
|
|
172
|
+
|
|
173
|
+
Group rule — a logical conjunction (AND) or disjunction (OR) of
|
|
174
|
+
children. Children may themselves be groups, allowing arbitrary
|
|
175
|
+
nesting like `(A AND (B OR C) AND D)`.
|
|
176
|
+
|
|
177
|
+
```typescript
|
|
178
|
+
interface RuleGroup {
|
|
179
|
+
/** Discriminator. */
|
|
180
|
+
kind: 'group'
|
|
181
|
+
/** Stable id. */
|
|
182
|
+
id: string
|
|
183
|
+
/** Logical operator joining the children. */
|
|
184
|
+
op: RuleGroupOp
|
|
185
|
+
/** Child rules — groups or leaves, in display order. */
|
|
186
|
+
children: Rule[]
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
#### `RuleBuilderProps`
|
|
191
|
+
|
|
192
|
+
Public component props.
|
|
193
|
+
|
|
194
|
+
```typescript
|
|
195
|
+
interface RuleBuilderProps {
|
|
196
|
+
/** Field catalog the user picks from. */
|
|
197
|
+
schema: RuleSchema
|
|
198
|
+
/** Current rule tree (controlled). */
|
|
199
|
+
rules: Rule
|
|
200
|
+
/**
|
|
201
|
+
* Called whenever the user mutates the tree — receives the full new
|
|
202
|
+
* root rule. Output is a deterministic JSON-serializable structure.
|
|
203
|
+
*/
|
|
204
|
+
onChange: (next: Rule) => void
|
|
205
|
+
/** Optional extra root-level class. */
|
|
206
|
+
className?: string
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Types
|
|
211
|
+
|
|
212
|
+
#### `RuleGroupOp`
|
|
213
|
+
|
|
214
|
+
Logical join operator at a group level.
|
|
215
|
+
|
|
216
|
+
```typescript
|
|
217
|
+
type RuleGroupOp = 'AND' | 'OR'
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
#### `RuleFieldType`
|
|
221
|
+
|
|
222
|
+
Built-in field types supported by the default operator catalog and
|
|
223
|
+
value editors. Consumers can supply custom operator lists per field
|
|
224
|
+
if these don't fit.
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
type RuleFieldType = 'text' | 'number' | 'date' | 'select' | 'boolean'
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
#### `RuleLeafValue`
|
|
231
|
+
|
|
232
|
+
Possible leaf value encodings. See `RuleLeaf.value`.
|
|
233
|
+
|
|
234
|
+
```typescript
|
|
235
|
+
type RuleLeafValue = string | number | boolean | [string, string] | [number, number]
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
#### `Rule`
|
|
239
|
+
|
|
240
|
+
Either a group or a leaf.
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
type Rule = RuleGroup | RuleLeaf
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Functions
|
|
247
|
+
|
|
248
|
+
#### `operatorsFor(field)`
|
|
249
|
+
|
|
250
|
+
Resolve the operator catalog for `field`. Returns the field's own
|
|
251
|
+
`operators` override when provided, otherwise the built-in catalog
|
|
252
|
+
for the field's `type`.
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
function operatorsFor(field: RuleField): RuleOperator[]
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
- `field` — Field descriptor from the schema.
|
|
259
|
+
|
|
260
|
+
**Returns:** Operator catalog applicable to this field.
|
|
261
|
+
|
|
262
|
+
#### `operatorById(field, opId)`
|
|
263
|
+
|
|
264
|
+
Look up a single operator descriptor by id within `field`'s catalog.
|
|
265
|
+
|
|
266
|
+
```typescript
|
|
267
|
+
function operatorById(field: RuleField, opId: string): RuleOperator | undefined
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- `field` — Field descriptor.
|
|
271
|
+
- `opId` — Operator id to look up.
|
|
272
|
+
|
|
273
|
+
**Returns:** The operator descriptor, or `undefined` if `opId` isn't in the catalog.
|
|
274
|
+
|
|
275
|
+
#### `makeId()`
|
|
276
|
+
|
|
277
|
+
Generate a short non-cryptographic id. Sufficient for rendered element
|
|
278
|
+
identity and in-memory rule identity within a single editing session.
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
function makeId(): string
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
**Returns:** A short random id.
|
|
285
|
+
|
|
286
|
+
#### `emptyLeaf()`
|
|
287
|
+
|
|
288
|
+
Build a fresh empty leaf — used when the user clicks "Add condition".
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
function emptyLeaf(): RuleLeaf
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
**Returns:** A new leaf with all fields blank and a fresh id.
|
|
295
|
+
|
|
296
|
+
#### `emptyGroup(op)`
|
|
297
|
+
|
|
298
|
+
Build a fresh empty group — used when the user clicks "Add group".
|
|
299
|
+
|
|
300
|
+
```typescript
|
|
301
|
+
function emptyGroup(op?: RuleGroupOp): RuleGroup
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- `op` — Initial group operator, defaults to `'AND'`.
|
|
305
|
+
|
|
306
|
+
**Returns:** A new group with one empty leaf already inside.
|
|
307
|
+
|
|
308
|
+
#### `replaceById(tree, targetId, replacement)`
|
|
309
|
+
|
|
310
|
+
Replace `target` (matched by id) anywhere in the tree with `replacement`.
|
|
311
|
+
|
|
312
|
+
```typescript
|
|
313
|
+
function replaceById(tree: Rule, targetId: string, replacement: Rule): Rule
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
- `tree` — Root of the rule tree.
|
|
317
|
+
- `targetId` — Id of the rule to replace.
|
|
318
|
+
- `replacement` — Replacement rule (same id is not required).
|
|
319
|
+
|
|
320
|
+
**Returns:** New tree with the replacement applied.
|
|
321
|
+
|
|
322
|
+
#### `removeById(tree, targetId)`
|
|
323
|
+
|
|
324
|
+
Remove the rule with id `targetId` from the tree. The root itself
|
|
325
|
+
cannot be removed — when `targetId` matches the root, the tree is
|
|
326
|
+
returned unchanged.
|
|
4
327
|
|
|
328
|
+
```typescript
|
|
329
|
+
function removeById(tree: Rule, targetId: string): Rule
|
|
5
330
|
```
|
|
6
|
-
|
|
331
|
+
|
|
332
|
+
- `tree` — Root of the rule tree.
|
|
333
|
+
- `targetId` — Id of the rule to remove.
|
|
334
|
+
|
|
335
|
+
**Returns:** New tree with the rule removed (or the original tree if no match).
|
|
336
|
+
|
|
337
|
+
#### `appendToGroup(tree, groupId, child)`
|
|
338
|
+
|
|
339
|
+
Append `child` to the children of the group identified by `groupId`.
|
|
340
|
+
If the id doesn't match any group, returns the tree unchanged.
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
function appendToGroup(tree: Rule, groupId: string, child: Rule): Rule
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
- `tree` — Root of the rule tree.
|
|
347
|
+
- `groupId` — Id of the group to append to.
|
|
348
|
+
- `child` — Rule to append.
|
|
349
|
+
|
|
350
|
+
**Returns:** New tree with the child appended.
|
|
351
|
+
|
|
352
|
+
#### `toggleGroupOp(tree, groupId)`
|
|
353
|
+
|
|
354
|
+
Toggle a group's `op` between `'AND'` and `'OR'`.
|
|
355
|
+
|
|
356
|
+
```typescript
|
|
357
|
+
function toggleGroupOp(tree: Rule, groupId: string): Rule
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
- `tree` — Root of the rule tree.
|
|
361
|
+
- `groupId` — Id of the group to toggle.
|
|
362
|
+
|
|
363
|
+
**Returns:** New tree with the group's op flipped (or the original tree if no match).
|
|
364
|
+
|
|
365
|
+
### Constants
|
|
366
|
+
|
|
367
|
+
#### `RuleBuilder`
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
const RuleBuilder: LegacyComponentType
|
|
7
371
|
```
|
|
8
372
|
|
|
9
|
-
|
|
373
|
+
#### `OP`
|
|
374
|
+
|
|
375
|
+
Operator id constants — exported so consumers can inspect leaves.
|
|
376
|
+
|
|
377
|
+
```typescript
|
|
378
|
+
const OP: {
|
|
379
|
+
readonly Equals: 'eq'
|
|
380
|
+
readonly NotEquals: 'neq'
|
|
381
|
+
readonly Contains: 'contains'
|
|
382
|
+
readonly NotContains: 'notContains'
|
|
383
|
+
readonly StartsWith: 'startsWith'
|
|
384
|
+
readonly EndsWith: 'endsWith'
|
|
385
|
+
readonly GreaterThan: 'gt'
|
|
386
|
+
readonly GreaterThanOrEqual: 'gte'
|
|
387
|
+
readonly LessThan: 'lt'
|
|
388
|
+
readonly LessThanOrEqual: 'lte'
|
|
389
|
+
readonly Between: 'between'
|
|
390
|
+
readonly Before: 'before'
|
|
391
|
+
readonly After: 'after'
|
|
392
|
+
readonly IsTrue: 'isTrue'
|
|
393
|
+
readonly IsFalse: 'isFalse'
|
|
394
|
+
readonly IsEmpty: 'isEmpty'
|
|
395
|
+
readonly IsNotEmpty: 'isNotEmpty'
|
|
396
|
+
readonly In: 'in'
|
|
397
|
+
readonly NotIn: 'notIn'
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
#### `defaultOperators`
|
|
402
|
+
|
|
403
|
+
Untranslated operator descriptors per field type.
|
|
404
|
+
|
|
405
|
+
`RuleBuilder` translates each `label` at render time; the strings
|
|
406
|
+
here are English fallbacks only, never shown directly.
|
|
407
|
+
|
|
408
|
+
```typescript
|
|
409
|
+
const defaultOperators: Record<RuleFieldType, RuleOperator[]>
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
## Injection Notes
|
|
413
|
+
|
|
414
|
+
### Requirements
|
|
415
|
+
|
|
416
|
+
Peer dependencies:
|
|
417
|
+
|
|
418
|
+
- `@molecule/app-svelte` ^3.5.0
|
|
419
|
+
- `@molecule/app-ui` ^1.0.1
|
|
420
|
+
- `@molecule/app-ui-svelte` ^1.1.0
|
|
421
|
+
- `svelte` ^5.0.0
|
|
422
|
+
|
|
423
|
+
### Runtime Dependencies
|
|
424
|
+
|
|
425
|
+
- `@molecule/app-svelte`
|
|
426
|
+
- `@molecule/app-ui`
|
|
427
|
+
- `@molecule/app-ui-svelte`
|
|
428
|
+
- `svelte`
|
|
429
|
+
|
|
430
|
+
- `<RuleBuilder>` throws unless the app provides an i18n provider (bonded
|
|
431
|
+
`@molecule/app-i18n`, or `setMoleculeContext({ i18n })`) with a bonded
|
|
432
|
+
ClassMap (`setClassMap()`).
|
|
433
|
+
- Output is a plain JSON-serializable `Rule` tree — this package only
|
|
434
|
+
renders and edits it. Evaluation (matching rows/users against the tree)
|
|
435
|
+
is the app's job, typically server-side.
|
|
436
|
+
- Fully controlled: keep the tree in `$state` and pass it back via `rules`;
|
|
437
|
+
start with `emptyGroup('AND')`.
|
|
438
|
+
- Translations: registered companion bond `@molecule/app-locales-rule-builder`.
|
|
439
|
+
|
|
440
|
+
## Translations
|
|
10
441
|
|
|
11
|
-
|
|
442
|
+
Translation strings are provided by `@molecule/app-locales-rule-builder`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-rule-builder-svelte",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Visual condition / rule builder — nested AND / OR groups of field-operator-value leaves, used for feature-flag targeting, automation triggers, segmentation, and IoT scenarios",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-rule-builder-svelte",
|
|
6
6
|
"type": "module",
|
|
@@ -62,9 +62,9 @@
|
|
|
62
62
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
63
63
|
"@molecule/app-i18n": "1.2.2",
|
|
64
64
|
"@molecule/app-icons": "1.0.4",
|
|
65
|
-
"@molecule/app-svelte": "3.
|
|
66
|
-
"@molecule/app-ui": "1.
|
|
67
|
-
"@molecule/app-ui-svelte": "1.1
|
|
65
|
+
"@molecule/app-svelte": "3.9.0",
|
|
66
|
+
"@molecule/app-ui": "1.5.0",
|
|
67
|
+
"@molecule/app-ui-svelte": "1.2.1",
|
|
68
68
|
"@sveltejs/package": "3.0.2",
|
|
69
69
|
"@sveltejs/vite-plugin-svelte": "7.1.2",
|
|
70
70
|
"@types/node": "26.6.5",
|