[DRAFT] Integrate spec-driven development workflow #2213
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Mendix Widget Development Rules | ||
|
|
||
| ## API Guards | ||
|
|
||
| - ALWAYS check `actionValue.canExecute` before calling `execute()` | ||
| - NEVER render widget content while value status is `"loading"` — show loading/placeholder state instead | ||
| - Use `editableValue.setValue()` for two-way binding, never mutate the value directly | ||
| - Handle all three `EditableValue` states: `"available"`, `"loading"`, `"unavailable"` | ||
|
|
||
| ## XML ↔ TypeScript | ||
|
|
||
| - XML property keys MUST be lowerCamelCase and MUST match TypeScript prop names exactly | ||
| - When adding an XML property: update `<Widget>.xml`, rebuild to regenerate `typings/<Widget>Props.d.ts`, update `editorConfig.ts`, and `editorPreview.tsx` | ||
| - Each widget MUST have a unique widget ID in `package.xml` — never duplicate across widgets | ||
|
|
||
| ## Versioning | ||
|
|
||
| - Any change to runtime behavior, XML schema, or public API REQUIRES: | ||
| - Semver bump in `package.json` | ||
| - CHANGELOG.md entry (Keep a Changelog format) | ||
| - Run `pnpm -w changelog` or update manually | ||
| - Refactor, test, or docs-only changes: no bump required | ||
|
|
||
| ## Styling | ||
|
|
||
| - SCSS only — no inline styles for static design | ||
| - Prefer Atlas UI classes (`btn`, `btn-primary`, `badge`, etc.) for common elements | ||
| - Custom classes MUST use the widget-name prefix: `.widget-<name>-<element>` | ||
| - NEVER override core Atlas UI classes — wrap in a widget-specific selector if custom styling is needed | ||
|
|
||
| ## Testing | ||
|
|
||
| - Run tests from the widget package dir: `cd packages/pluggableWidgets/<name>-web && pnpm test` | ||
| - Use `@mendix/widget-plugin-test-utils` builders for mocking Mendix API values: | ||
| ```ts | ||
| import { dynamicValue, EditableValueBuilder } from "@mendix/widget-plugin-test-utils"; | ||
| const mockAttr = new EditableValueBuilder<string>().withValue("test").build(); | ||
| ``` | ||
| - New features require unit tests; bug fixes require regression tests | ||
| - User-visible behavior changes require E2E updates in `e2e/*.spec.js` | ||
| - E2E tests MUST include `test.afterEach` session logout to avoid Mendix license limit issues | ||
|
|
||
| ## Constraints | ||
|
|
||
| - Never modify `dist/`, generated typings, or `pnpm-lock.yaml` | ||
| - No tree-shaking-hostile imports — use named imports for large dependencies | ||
| - No core Atlas class overrides | ||
| - `dangerouslySetInnerHTML` is forbidden unless the content is explicitly sanitized | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # React & MobX Patterns for Mendix Widgets | ||
|
|
||
| ## Hooks | ||
|
|
||
| - `useEffect` deps array MUST include all referenced variables — no stale closures | ||
| - Async effects MUST guard against state updates after unmount: | ||
| ```ts | ||
| useEffect(() => { | ||
| let active = true; | ||
| (async () => { | ||
| const data = await load(); | ||
| if (active) setData(data); | ||
| })(); | ||
| return () => { | ||
| active = false; | ||
| }; | ||
| }, [load]); | ||
| ``` | ||
| - No side effects in render — use `useEffect` for side effects | ||
| - Cleanup subscriptions, timers, and event listeners on unmount | ||
|
|
||
| ## State | ||
|
|
||
| - Use functional updates when reading previous state: `setCount(c => c + 1)` | ||
| - Do NOT store computed values in `useState` if they can be derived from props | ||
| - Source of truth priority: Mendix props → MobX store → React state | ||
| - Controlled vs. uncontrolled inputs: never mix `value` and `defaultValue` on the same element | ||
|
|
||
| ## Keys & Lists | ||
|
|
||
| - Stable, unique `key` props on all list items — NEVER use array index for dynamic lists | ||
| - For large lists, consider virtualization | ||
|
|
||
| ## MobX | ||
|
|
||
| - Stores: use `makeAutoObservable(this)` or explicit `makeObservable(this, { ... })` in the constructor | ||
| - State mutations: inside `action` or `runInAction` — never mutate observables outside an action | ||
| - Derived values: `computed` — no side effects allowed inside computed properties | ||
| - React integration: `observer()` HOC from `mobx-react-lite` + `useSubscribe()` from `@mendix/widget-plugin-mobx-kit` | ||
| - Use `reaction()` for side effects triggered by state changes, not `autorun()` in most cases | ||
|
|
||
| ## Performance | ||
|
|
||
| - `useMemo`/`useCallback` only where re-render cost is measurable — incorrect deps are worse than no memoization | ||
| - Avoid creating new objects/arrays/functions inline in JSX props passed to child components (new reference on every render forces child re-render) | ||
|
|
||
| ## Accessibility | ||
|
|
||
| - Semantic HTML first — ARIA only when native elements don't convey the right semantics | ||
| - WCAG 2.2 AA: 4.5:1 contrast for normal text, 3:1 for large text and UI elements | ||
| - Keyboard navigation: Arrow keys (menus/lists), Enter/Space (activation), Escape (dismiss), Tab (focus order) | ||
| - Use Floating UI accessibility hooks for floating elements: `useRole`, `useDismiss`, `useListNavigation`, `FloatingFocusManager` | ||
| - `dangerouslySetInnerHTML`: never — if unavoidable, sanitize with a trusted library | ||
|
|
||
| ## Props | ||
|
|
||
| - Do NOT spread unknown props onto DOM nodes — filter non-HTML attributes before spreading | ||
| - Prefer composition over prop drilling; use React Context for cross-tree state when prop chains exceed 2-3 levels |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # OpenSpec in This Repository | ||
|
|
||
| Spec-driven development for Mendix pluggable widgets. We use | ||
| [OpenSpec](https://github.com/Fission-AI/OpenSpec) to align on what to build | ||
| before any code is written. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ```bash | ||
| # Install the CLI (one-time) | ||
| npm install -g @fission-ai/openspec@latest | ||
|
|
||
| # Navigate to a widget you want to change | ||
| cd packages/pluggableWidgets/<widget-name>-web | ||
|
|
||
| # Propose a change | ||
| /opsx:propose "<what-you-want-to-build>" | ||
|
|
||
| # Implement the generated tasks | ||
| /opsx:apply | ||
|
|
||
| # Archive when done (merges delta specs into source of truth) | ||
| /opsx:archive | ||
| ``` | ||
|
|
||
| ## Structure | ||
|
Collaborator
There was a problem hiding this comment. Probably not final structure, so I would avoid this section for now. |
||
|
|
||
| ``` | ||
| openspec/ # Monorepo-level | ||
| ├── specs/ | ||
| │ └── conventions/spec.md # Shared widget dev conventions (source of truth) | ||
| ├── schemas/ | ||
| │ └── mendix-widget/ # Custom schema for widget development | ||
| │ ├── schema.yaml # Artifact definitions + instructions | ||
| │ └── templates/ # AI generation templates | ||
| │ ├── proposal.md | ||
| │ ├── spec.md | ||
| │ ├── design.md | ||
| │ └── tasks.md | ||
| └── config.yaml # Monorepo context + default schema | ||
|
|
||
| packages/pluggableWidgets/<name>-web/ # Per-widget (opt-in) | ||
| └── openspec/ | ||
| ├── specs/spec.md # Widget behavior source of truth | ||
| ├── changes/ # Active proposals (one folder per change) | ||
| │ └── <change-name>/ | ||
| │ ├── proposal.md | ||
| │ ├── specs/spec.md # Delta spec (ADDED/MODIFIED/REMOVED) | ||
| │ ├── design.md | ||
| │ └── tasks.md | ||
| └── config.yaml # Widget-specific context | ||
|
|
||
| .agents/rules/ # Tool-agnostic coding rules | ||
| ├── mendix-widget.md # Mendix API guards, versioning, styling | ||
| └── react-patterns.md # React hooks, MobX, accessibility | ||
| ``` | ||
|
|
||
| ## Pilot Widgets | ||
|
|
||
| These widgets have OpenSpec initialized and baseline specs: | ||
|
|
||
| | Widget | Spec | Status | | ||
| | -------------- | ------------------------------------------------------------------------------------------ | -------- | | ||
| | `datagrid-web` | [openspec/specs/spec.md](../packages/pluggableWidgets/datagrid-web/openspec/specs/spec.md) | baseline | | ||
| | `combobox-web` | [openspec/specs/spec.md](../packages/pluggableWidgets/combobox-web/openspec/specs/spec.md) | baseline | | ||
| | `gallery-web` | [openspec/specs/spec.md](../packages/pluggableWidgets/gallery-web/openspec/specs/spec.md) | baseline | | ||
|
|
||
| ## Initializing a New Widget | ||
|
|
||
| ```bash | ||
| cd packages/pluggableWidgets/<widget>-web | ||
| openspec init | ||
| ``` | ||
|
|
||
| Then edit `openspec/config.yaml` to add widget-specific context (architecture, | ||
| key XML properties, data dependencies). Use the pilot widgets as reference. | ||
|
|
||
| ## When to Use OpenSpec | ||
|
|
||
| | Situation | Use OpenSpec? | | ||
| | ----------------------------------- | --------------------------- | | ||
| | New feature or behavior change | Yes — `/opsx:propose` first | | ||
| | XML property added/modified/removed | Yes — `/opsx:propose` first | | ||
| | Bug fix | No | | ||
| | Refactor (no behavior change) | No | | ||
| | Test-only change | No | | ||
| | Docs update | No | | ||
|
|
||
| ## The `mendix-widget` Schema | ||
|
|
||
| The custom schema (`openspec/schemas/mendix-widget/`) generates four artifacts: | ||
|
|
||
| 1. **`proposal.md`** — Intent, Mendix XML impact, scope, release checklist | ||
| 2. **`specs/<domain>/spec.md`** — Delta specs (ADDED/MODIFIED/REMOVED) in Given/When/Then | ||
| 3. **`design.md`** — Mendix API usage, component hierarchy, file changes | ||
| 4. **`tasks.md`** — Grouped checklist: XML/Types → Implementation → Tests → Versioning | ||
|
|
||
| Dependency order: `proposal → specs + design → tasks → implement` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have a utility function that does this, maybe we could refer that too.