Initial Commit

openspec/changes/enterprise-react-rule-builder/proposal.md

@@ -0,0 +1,88 @@
+# OpenSpec Change: enterprise-react-rule-builder
+
+- **Change ID**: enterprise-react-rule-builder
+- **Package**: `@suaveplan/react-rule-builder`
+- **Category**: react
+- **Target path**: `react/forms/react-rule-builder`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-rule-builder.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-rule-builder` on genesis from scratch at enterprise quality. A visual rule-builder UI that reads/writes a Rule AST: `RuleBuilder`, `LogicGroup` (AND/OR/NOT), `ConditionRow`, `useRuleBuilder` hook, drag-and-drop reordering via `@suaveplan/react-dnd`, and AST path utilities. Genesis deletes the `src/mocks/` directory entirely, adds Storybook stories, Playwright E2E for drag-drop reorder, Zod schema validation at the rule-build boundary, and 100% test coverage using real workspace deps.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `RuleBuilderError` |
+| `@suaveplan/react-dnd` (`workspace:^`) | Drag-drop reordering |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n |
+| `@suaveplan/react-ui` (`workspace:^`) | UI primitives |
+| `zod` (`catalog:forms`) | Rule AST validation |
+
+External: `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+RuleBuilder, LogicGroup, ConditionRow
+useRuleBuilder
+
+// Helpers
+createEmptyCondition, createEmptyGroup
+getApplicableOperators, getRuleAtPath, insertRuleAtPath, removeRuleAtPath, updateRuleAtPath
+DEFAULT_OPERATORS
+
+// Types
+ConditionRowProps, FieldDefinition, LogicGroupProps, OnRuleChange,
+OperatorOption, RuleBuilderProps, SelectOption
+```
+
+---
+
+## New additions for genesis
+
+1. **No mocks** — all tests use real `@suaveplan/react-dnd`, `@suaveplan/react-translate`, `@suaveplan/react-ui`.
+2. **`RuleBuilderError`** — codes: `RULE_BUILDER_INVALID_PATH`, `RULE_BUILDER_INVALID_RULE`.
+3. **Zod `RuleSchema`** — validates the built rule before firing `onRuleChange`; invalid rule throws `RuleBuilderError(RULE_BUILDER_INVALID_RULE)`.
+4. **Stories** — `RuleBuilder` default, nested-groups, drag-reorder, playground.
+5. **Playwright E2E** — add condition, drag to reorder, verify AST shape.
+
+---
+
+## File layout
+
+```text
+react/forms/react-rule-builder/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    components/
+      rule-builder/ (tsx + types + md + test + stories + index)
+      logic-group/ (tsx + types + md + test + stories + index)
+      condition-row/ (tsx + types + md + test + stories + index)
+    hooks/
+      use-rule-builder/ (ts + types + md + test + index)
+    types/
+      rule-builder.types.ts
+    utils/
+      rule-helpers/ (ts + md + test + index)
+  e2e/
+    rule-builder.spec.ts
+```