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