@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.
Files changed (2) hide show
  1. package/README.md +435 -4
  2. 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 — nested AND / OR groups of field-operator-value leaves, used for feature-flag targeting, automation triggers, segmentation, and IoT scenarios
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
- npm install @molecule/app-rule-builder-svelte
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
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
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
- License: Apache-2.0
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": "0.0.1-stage",
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.7.2",
66
- "@molecule/app-ui": "1.4.0",
67
- "@molecule/app-ui-svelte": "1.1.7",
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",