@molecule/app-rule-builder-vue 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 +489 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,496 @@
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.880Z
7
+ -->
8
+
1
9
  # @molecule/app-rule-builder-vue
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 Vue.
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
+ ```ts
36
+ import { createApp, defineComponent, h, ref } from 'vue'
37
+
38
+ import { RuleBuilder, emptyGroup, type Rule, type RuleSchema } from '@molecule/app-rule-builder-vue'
39
+
40
+ const schema: RuleSchema = {
41
+ fields: [
42
+ {
43
+ name: 'country',
44
+ label: 'Country',
45
+ type: 'select',
46
+ options: [{ value: 'US', label: 'United States' }],
47
+ },
48
+ { name: 'plan', label: 'Plan', type: 'text' },
49
+ { name: 'spend', label: 'Spend', type: 'number' },
50
+ ],
51
+ }
52
+
53
+ const rules = ref<Rule>(emptyGroup('AND'))
54
+
55
+ const App = defineComponent({
56
+ setup() {
57
+ return () =>
58
+ h(RuleBuilder, {
59
+ schema,
60
+ rules: rules.value,
61
+ onChange: (next: Rule) => {
62
+ rules.value = next
63
+ },
64
+ })
65
+ },
66
+ })
67
+
68
+ createApp(App).mount('#app')
69
+ ```
70
+
71
+ ## Type
72
+
73
+ `feature`
74
+
75
+ ## Installation
76
+
77
+ ```bash
78
+ npm install @molecule/app-rule-builder-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
79
+ ```
80
+
81
+ ## API
82
+
83
+ ### Interfaces
84
+
85
+ #### `RuleOperator`
86
+
87
+ Operator descriptor — `id` is what's stored on the leaf, `label` is
88
+ what's shown in the operator dropdown.
89
+
90
+ `arity` controls how many value inputs are rendered:
91
+
92
+ - `'unary'` — no value input (e.g. `is empty`, `exists`)
93
+ - `'binary'` — one value input (default)
94
+ - `'between'` — two value inputs (rendered as `from`/`to`)
95
+
96
+ ```typescript
97
+ interface RuleOperator {
98
+ /** Operator id stored on the leaf. */
99
+ id: string
100
+ /** Translated, human-readable label. */
101
+ label: string
102
+ /** Number of value inputs to render. Default `'binary'`. */
103
+ arity?: 'unary' | 'binary' | 'between'
104
+ }
105
+ ```
106
+
107
+ #### `RuleField`
108
+
109
+ Field descriptor in the schema — the rule builder uses it to render
110
+ the field dropdown, infer the value editor, and (when no explicit
111
+ `operators` list is given) pick a default operator catalog by `type`.
112
+
113
+ ```typescript
114
+ interface RuleField {
115
+ /** Stable field identifier stored on the leaf. */
116
+ name: string
117
+ /** Translated, human-readable label shown in the field dropdown. */
118
+ label: string
119
+ /** Built-in type used to pick the value editor + default operators. */
120
+ type: RuleFieldType
121
+ /**
122
+ * Operators valid for this field. Optional — when omitted, the
123
+ * builder uses the default catalog for `type` from `defaultOperators`.
124
+ */
125
+ operators?: RuleOperator[]
126
+ /**
127
+ * For `type: 'select'` — the option list rendered as a `<Select>`.
128
+ * Ignored for other types.
129
+ */
130
+ options?: Array<{ value: string; label: string }>
131
+ /** Optional placeholder for text/number/date inputs. */
132
+ placeholder?: string
133
+ }
134
+ ```
135
+
136
+ #### `RuleSchema`
137
+
138
+ Schema given to `<RuleBuilder>`. Currently only `fields` — kept as an
139
+ object so future schema-level config (max depth, group limit, etc.)
140
+ can be added without breaking the API.
141
+
142
+ ```typescript
143
+ interface RuleSchema {
144
+ /** Available fields, in the order they appear in the field dropdown. */
145
+ fields: RuleField[]
146
+ }
147
+ ```
148
+
149
+ #### `RuleLeaf`
150
+
151
+ Leaf rule — a single `field op value` predicate.
152
+
153
+ `value` is opaque to the builder for `text` / `number` / `select` /
154
+ `boolean` (it stores whatever the input produced — string for text /
155
+ select / date, number for number, boolean for boolean). For `between`
156
+ arity operators it's stored as a `[from, to]` two-element tuple.
157
+
158
+ ```typescript
159
+ interface RuleLeaf {
160
+ /** Discriminator. */
161
+ kind: 'leaf'
162
+ /** Stable id (uuid-ish) — used for element identity + delete identity. */
163
+ id: string
164
+ /** Field name from the schema. Empty string when unset. */
165
+ field: string
166
+ /** Operator id from the field's operator catalog. Empty when unset. */
167
+ op: string
168
+ /**
169
+ * Current value. `undefined` when unset. Encoding depends on the
170
+ * operator's `arity`:
171
+ * - `'unary'` — value is ignored.
172
+ * - `'binary'` — string | number | boolean.
173
+ * - `'between'` — `[from, to]` tuple.
174
+ */
175
+ value?: RuleLeafValue
176
+ }
177
+ ```
178
+
179
+ #### `RuleGroup`
180
+
181
+ Group rule — a logical conjunction (AND) or disjunction (OR) of
182
+ children. Children may themselves be groups, allowing arbitrary
183
+ nesting like `(A AND (B OR C) AND D)`.
184
+
185
+ ```typescript
186
+ interface RuleGroup {
187
+ /** Discriminator. */
188
+ kind: 'group'
189
+ /** Stable id. */
190
+ id: string
191
+ /** Logical operator joining the children. */
192
+ op: RuleGroupOp
193
+ /** Child rules — groups or leaves, in display order. */
194
+ children: Rule[]
195
+ }
196
+ ```
197
+
198
+ #### `RuleBuilderProps`
199
+
200
+ Public component props.
201
+
202
+ ```typescript
203
+ interface RuleBuilderProps {
204
+ /** Field catalog the user picks from. */
205
+ schema: RuleSchema
206
+ /** Current rule tree (controlled). */
207
+ rules: Rule
208
+ /**
209
+ * Called whenever the user mutates the tree — receives the full new
210
+ * root rule. Output is a deterministic JSON-serializable structure.
211
+ */
212
+ onChange: (next: Rule) => void
213
+ /** Optional extra root-level class. */
214
+ className?: string
215
+ }
216
+ ```
217
+
218
+ ### Types
219
+
220
+ #### `RuleGroupOp`
221
+
222
+ Logical join operator at a group level.
223
+
224
+ ```typescript
225
+ type RuleGroupOp = 'AND' | 'OR'
226
+ ```
227
+
228
+ #### `RuleFieldType`
229
+
230
+ Built-in field types supported by the default operator catalog and
231
+ value editors. Consumers can supply custom operator lists per field
232
+ if these don't fit.
233
+
234
+ ```typescript
235
+ type RuleFieldType = 'text' | 'number' | 'date' | 'select' | 'boolean'
236
+ ```
237
+
238
+ #### `RuleLeafValue`
239
+
240
+ Possible leaf value encodings. See `RuleLeaf.value`.
241
+
242
+ ```typescript
243
+ type RuleLeafValue = string | number | boolean | [string, string] | [number, number]
244
+ ```
245
+
246
+ #### `Rule`
247
+
248
+ Either a group or a leaf.
249
+
250
+ ```typescript
251
+ type Rule = RuleGroup | RuleLeaf
252
+ ```
253
+
254
+ ### Functions
255
+
256
+ #### `operatorsFor(field)`
257
+
258
+ Resolve the operator catalog for `field`. Returns the field's own
259
+ `operators` override when provided, otherwise the built-in catalog
260
+ for the field's `type`.
261
+
262
+ ```typescript
263
+ function operatorsFor(field: RuleField): RuleOperator[]
264
+ ```
265
+
266
+ - `field` — Field descriptor from the schema.
267
+
268
+ **Returns:** Operator catalog applicable to this field.
269
+
270
+ #### `operatorById(field, opId)`
271
+
272
+ Look up a single operator descriptor by id within `field`'s catalog.
273
+
274
+ ```typescript
275
+ function operatorById(field: RuleField, opId: string): RuleOperator | undefined
276
+ ```
277
+
278
+ - `field` — Field descriptor.
279
+ - `opId` — Operator id to look up.
280
+
281
+ **Returns:** The operator descriptor, or `undefined` if `opId` isn't in the catalog.
282
+
283
+ #### `makeId()`
4
284
 
285
+ Generate a short non-cryptographic id. Sufficient for rendered element
286
+ identity and in-memory rule identity within a single editing session.
287
+
288
+ ```typescript
289
+ function makeId(): string
5
290
  ```
6
- npm install @molecule/app-rule-builder-vue
291
+
292
+ **Returns:** A short random id.
293
+
294
+ #### `emptyLeaf()`
295
+
296
+ Build a fresh empty leaf — used when the user clicks "Add condition".
297
+
298
+ ```typescript
299
+ function emptyLeaf(): RuleLeaf
7
300
  ```
8
301
 
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.
302
+ **Returns:** A new leaf with all fields blank and a fresh id.
303
+
304
+ #### `emptyGroup(op)`
305
+
306
+ Build a fresh empty group — used when the user clicks "Add group".
307
+
308
+ ```typescript
309
+ function emptyGroup(op?: RuleGroupOp): RuleGroup
310
+ ```
311
+
312
+ - `op` — Initial group operator, defaults to `'AND'`.
313
+
314
+ **Returns:** A new group with one empty leaf already inside.
315
+
316
+ #### `replaceById(tree, targetId, replacement)`
317
+
318
+ Replace `target` (matched by id) anywhere in the tree with `replacement`.
319
+
320
+ ```typescript
321
+ function replaceById(tree: Rule, targetId: string, replacement: Rule): Rule
322
+ ```
323
+
324
+ - `tree` — Root of the rule tree.
325
+ - `targetId` — Id of the rule to replace.
326
+ - `replacement` — Replacement rule (same id is not required).
327
+
328
+ **Returns:** New tree with the replacement applied.
329
+
330
+ #### `removeById(tree, targetId)`
331
+
332
+ Remove the rule with id `targetId` from the tree. The root itself
333
+ cannot be removed — when `targetId` matches the root, the tree is
334
+ returned unchanged.
335
+
336
+ ```typescript
337
+ function removeById(tree: Rule, targetId: string): Rule
338
+ ```
339
+
340
+ - `tree` — Root of the rule tree.
341
+ - `targetId` — Id of the rule to remove.
342
+
343
+ **Returns:** New tree with the rule removed (or the original tree if no match).
344
+
345
+ #### `appendToGroup(tree, groupId, child)`
346
+
347
+ Append `child` to the children of the group identified by `groupId`.
348
+ If the id doesn't match any group, returns the tree unchanged.
349
+
350
+ ```typescript
351
+ function appendToGroup(tree: Rule, groupId: string, child: Rule): Rule
352
+ ```
353
+
354
+ - `tree` — Root of the rule tree.
355
+ - `groupId` — Id of the group to append to.
356
+ - `child` — Rule to append.
357
+
358
+ **Returns:** New tree with the child appended.
359
+
360
+ #### `toggleGroupOp(tree, groupId)`
361
+
362
+ Toggle a group's `op` between `'AND'` and `'OR'`.
363
+
364
+ ```typescript
365
+ function toggleGroupOp(tree: Rule, groupId: string): Rule
366
+ ```
367
+
368
+ - `tree` — Root of the rule tree.
369
+ - `groupId` — Id of the group to toggle.
370
+
371
+ **Returns:** New tree with the group's op flipped (or the original tree if no match).
372
+
373
+ ### Constants
374
+
375
+ #### `RuleBuilder`
376
+
377
+ Visual rule / predicate builder. The rendered tree is a recursive
378
+ `RuleGroup` of `RuleLeaf` predicates joined by `AND` or `OR`. The
379
+ component is fully controlled — every interaction emits a new root
380
+ rule via `onChange`.
381
+
382
+ Vue counterpart of `@molecule/app-rule-builder-react`'s `RuleBuilder` —
383
+ the same props (React names) and the same DOM for the same input.
384
+
385
+ ```typescript
386
+ const RuleBuilder: DefineComponent<
387
+ ExtractPropTypes<{
388
+ schema: { type: PropType<RuleSchema>; required: true }
389
+ rules: { type: PropType<Rule>; required: true }
390
+ onChange: { type: PropType<(next: Rule) => void>; required: true }
391
+ className: StringConstructor
392
+ }>,
393
+ () => VNode,
394
+ {},
395
+ {},
396
+ {},
397
+ ComponentOptionsMixin,
398
+ ComponentOptionsMixin,
399
+ {},
400
+ string,
401
+ PublicProps,
402
+ Readonly<
403
+ ExtractPropTypes<{
404
+ schema: { type: PropType<RuleSchema>; required: true }
405
+ rules: { type: PropType<Rule>; required: true }
406
+ onChange: { type: PropType<(next: Rule) => void>; required: true }
407
+ className: StringConstructor
408
+ }>
409
+ > &
410
+ Readonly<{}>,
411
+ {},
412
+ {},
413
+ {},
414
+ {},
415
+ string,
416
+ ComponentProvideOptions,
417
+ true,
418
+ {},
419
+ any
420
+ >
421
+ ```
422
+
423
+ - `props` — Component props (see {@link RuleBuilderProps}).
424
+
425
+ **Returns:** The rendered rule builder.
426
+
427
+ #### `OP`
428
+
429
+ Operator id constants — exported so consumers can inspect leaves.
430
+
431
+ ```typescript
432
+ const OP: {
433
+ readonly Equals: 'eq'
434
+ readonly NotEquals: 'neq'
435
+ readonly Contains: 'contains'
436
+ readonly NotContains: 'notContains'
437
+ readonly StartsWith: 'startsWith'
438
+ readonly EndsWith: 'endsWith'
439
+ readonly GreaterThan: 'gt'
440
+ readonly GreaterThanOrEqual: 'gte'
441
+ readonly LessThan: 'lt'
442
+ readonly LessThanOrEqual: 'lte'
443
+ readonly Between: 'between'
444
+ readonly Before: 'before'
445
+ readonly After: 'after'
446
+ readonly IsTrue: 'isTrue'
447
+ readonly IsFalse: 'isFalse'
448
+ readonly IsEmpty: 'isEmpty'
449
+ readonly IsNotEmpty: 'isNotEmpty'
450
+ readonly In: 'in'
451
+ readonly NotIn: 'notIn'
452
+ }
453
+ ```
454
+
455
+ #### `defaultOperators`
456
+
457
+ Untranslated operator descriptors per field type.
458
+
459
+ `RuleBuilder` translates each `label` at render time; the strings
460
+ here are English fallbacks only, never shown directly.
461
+
462
+ ```typescript
463
+ const defaultOperators: Record<RuleFieldType, RuleOperator[]>
464
+ ```
465
+
466
+ ## Injection Notes
467
+
468
+ ### Requirements
469
+
470
+ Peer dependencies:
471
+
472
+ - `@molecule/app-ui` ^1.0.1
473
+ - `@molecule/app-ui-vue` ^1.1.0
474
+ - `@molecule/app-vue` ^3.5.0
475
+ - `vue` ^3.4.0
476
+
477
+ ### Runtime Dependencies
478
+
479
+ - `@molecule/app-ui`
480
+ - `@molecule/app-ui-vue`
481
+ - `@molecule/app-vue`
482
+ - `vue`
483
+
484
+ - `<RuleBuilder>` throws unless rendered inside a Vue app that provides an
485
+ i18n provider (bonded `@molecule/app-i18n`, as `moleculePlugin` wires) with
486
+ a bonded ClassMap (`setClassMap()`).
487
+ - Output is a plain JSON-serializable `Rule` tree — this package only
488
+ renders and edits it. Evaluation (matching rows/users against the tree)
489
+ is the app's job, typically server-side.
490
+ - Fully controlled: keep the tree in a `ref` and pass it back via `rules`;
491
+ start with `emptyGroup('AND')`.
492
+ - Translations: registered companion bond `@molecule/app-locales-rule-builder`.
493
+
494
+ ## Translations
10
495
 
11
- License: Apache-2.0
496
+ 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-vue",
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-vue",
6
6
  "type": "module",
@@ -56,9 +56,9 @@
56
56
  "@molecule/app-framework-conformance": "0.0.0",
57
57
  "@molecule/app-i18n": "1.2.2",
58
58
  "@molecule/app-icons": "1.0.4",
59
- "@molecule/app-ui": "1.4.0",
60
- "@molecule/app-ui-vue": "1.1.5",
61
- "@molecule/app-vue": "3.7.2",
59
+ "@molecule/app-ui": "1.5.0",
60
+ "@molecule/app-ui-vue": "1.2.1",
61
+ "@molecule/app-vue": "3.9.0",
62
62
  "@types/node": "26.6.5",
63
63
  "jsdom": "30.1.3",
64
64
  "typescript": "6.0.3",