From 88e4917a048a3a15afb12d6ee74e3b164b130e76 Mon Sep 17 00:00:00 2001 From: Gift Nnko Date: Sun, 25 Oct 2026 22:59:36 +0300 Subject: [PATCH 1/2] docs: describe the current no-save flow in README and AGENTS.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LZTKXxVkBdpd1uHuJWerFT --- AGENTS.md | 37 +++++++++++++++++----------- README.md | 74 +++++++++++++++++++++++-------------------------------- 2 files changed, 54 insertions(+), 57 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 71585d8..d4f2b63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,17 +4,19 @@ Guidance for AI coding agents (Claude Code, Codex, and others) working in this r ## What this is -A DHIS2 custom app (built on the [DHIS2 Application Platform](https://github.com/dhis2/app-platform)) for viewing, testing and debugging DHIS2 program rules. A user picks a program, opens its registration/event forms, fills them in, and watches program rules evaluate live (hide/show fields and sections, assignments, mandatory, warnings/errors, feedback and indicator messages). Supports DHIS2 2.40 to 2.43 (see `d2.config.js`). +A DHIS2 custom app (built on the [DHIS2 Application Platform](https://github.com/dhis2/app-platform)) for viewing, testing and debugging DHIS2 program rules. A user picks a program, opens its enrollment and event forms, fills them in, and watches program rules evaluate live (hide/show fields and sections, assignments, mandatory, warnings/errors, feedback and indicator messages). Supports DHIS2 2.40 to 2.43 (see `d2.config.js`). + +**The app never saves data.** Its only write call is the tracker importer dry run (`importMode=VALIDATE`) in `hooks/useServerVerification.ts`, which runs the server's rule engine and validation and persists nothing. Keep it that way: do not add calls that post to `tracker` (or any other resource) without `importMode=VALIDATE`. It consumes five sibling libraries as regular npm dependencies, all published from the separate [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) monorepo and versioned in lockstep with this app. **File issues/PRs against the rule engine, hooks, widgets or devtools there, not here.** -- `@nnkogift/dhis2-form-utils-hooks`: `useEventProgramMetadataQuery`, `useTrackerMetadataQuery`, `useEventForm`, `FormStateProvider`, `useFieldControl`, `useFieldRuleEffect`, `useFormFeedback`, `useRuleEffectTrace` +- `@nnkogift/dhis2-form-utils-hooks`: `useEventProgramMetadataQuery`, `useTrackerMetadataQuery`, `useEventForm`, `useTrackerForm`, `FormStateProvider`, `useFieldControl`, `useFieldRuleEffect`, `useFieldState`, `useSectionRuleEffect`, `useSectionState`, `useFormFeedback`, `useRuleEffectTrace` - `@nnkogift/dhis2-form-utils-metadata`: program/program-stage metadata shaping (`selectProgramStage`, `resolveFormSectionLayout`, option group resolution, `ProgramRuleActionType`, metadata types) - `@nnkogift/dhis2-form-utils-rules`: rule engine runtime types and helpers (`RuleEventInput`, `RuleSupplementaryDataInput`, `feedbackItemKey`, `filterPayload`) - `@nnkogift/dhis2-form-utils-dhis2-ui`: `D2FieldWidget`, the `@dhis2/ui`-backed field renderer -- `@nnkogift/dhis2-form-utils-devtools`: rule inspection (`RulesPanel`, `RuleDevtoolsScope` from `/scope`, `createLabelLookup`, `getEffectVariant`, `getEffectVisual`, `EFFECT_ICONS`) +- `@nnkogift/dhis2-form-utils-devtools`: rule inspection (`RulesPanel`, `ServerEffectsSummary`, `RuleDevtoolsScope` from `/scope`, `createLabelLookup`, `getEffectVariant`/`getEffectVisual`/`EFFECT_ICONS` from `/effect-styles`, the server report types `ServerVerification`/`ServerReportEntry`, and since `0.1.0-alpha.14` the `EFFECT_LEGEND` and `PROVENANCE_TAGS` constants). The `EffectLegend` and `ProvenanceTag` components are bundled but not exported from the package entry in `alpha.14`; export them in `dhis2-form-utils` before using them here. -This app's own code is thin: routing, DHIS2 API queries (programs list, org units, current-user supplementary data, option groups), UI chrome around the library-produced forms, and tracker/event submission payloads. +This app's own code is thin: routing, DHIS2 API queries (programs list, accessible and program org units, current-user supplementary data, option groups), UI chrome around the library-produced forms, and the tracker/event payloads sent by the server dry run. ## Commands @@ -36,7 +38,7 @@ pnpm test -- src/modules/program-playground/hooks/usePublishFormValues.test.ts pnpm test -- -t "some test name" ``` -CI (`.github/workflows/ci.yml`) runs lint, typecheck, test and build as separate jobs on pushes and PRs to `main`, `alpha` and `beta`. `deploy.yml` and `release.yml` handle deployment and Changesets releases. +CI (`.github/workflows/ci.yml`) runs lint, test, build and a Fallow audit (fed with test coverage) as separate jobs on pushes and PRs to `main`, `alpha` and `beta`. It does not run `pnpm typecheck`, so run that locally before pushing. `deploy.yml` and `release.yml` handle deployment and Changesets releases. ## Source layout @@ -57,7 +59,7 @@ src/ ### Routing (`src/AppWrapper.tsx`) -`HashRouter` with three lazily loaded routes: `/` (program list), `/programs/:programId` (playground for one program), `/about`. `SyncUrlWithGlobalShell` keeps the DHIS2 global app shell's URL bar in sync with the hash router. +`HashRouter` with three lazily loaded routes: `/` (program list), `/programs/:programId` (playground for one program), `/about` (`About.tsx`: app version from `useConfig`, supported DHIS2 range and resource links). The program list page ends with a footer (`program-list/components/ProgramListHelpLinks`) linking to the docs and About. External URLs and the displayed DHIS2 range live in `src/shared/constants/links.ts`; `SUPPORTED_DHIS2_RANGE` there is a hard-coded string, so change it together with `minDHIS2Version`/`maxDHIS2Version` in `d2.config.js`. `SyncUrlWithGlobalShell` keeps the DHIS2 global app shell's URL bar in sync with the hash router. ### Program list flow (`modules/program-list/`) @@ -67,31 +69,38 @@ src/ ### Program playground flow (`modules/program-playground/`) -`pages/ProgramPage` loads program metadata via `useEventProgramMetadataQuery`, accessible org units via `useAccessibleOrgUnits`, current-user supplementary data (`userGroups`/`userRoles`, required by the rule engine) via `useCurrentUserSupplementaryData`, and option-group codes referenced by rules via `useOptionGroupsSupplementaryData`. `ProgramContextBar` sets org unit, the primary date (enrollment or event date) and a reset (`useProgramPlaygroundState` bumps a `resetKey` that remounts the forms). It then branches on `program.programType`: +`pages/ProgramPage` gets everything it needs from `hooks/useProgramPageData`: program metadata via `useEventProgramMetadataQuery`, the user's accessible org units via `useAccessibleOrgUnits`, the program's assigned org units via `useProgramOrgUnits`, current-user supplementary data (`userGroups`/`userRoles`, required by the rule engine) via `useCurrentUserSupplementaryData`, and option-group codes referenced by rules via `useOptionGroupsSupplementaryData`. `ProgramContextBar` sets the org unit (`components/orgUnit/OrgUnitSelectorField`, a searchable modal tree limited to the program's org units; `ProgramOrgUnitsContext` lets forms require it before validating or verifying), the primary date (enrollment or event date) and a reset (`useProgramPlaygroundState` bumps a `resetKey` that remounts the forms). It then branches on `program.programType`: - **`WITHOUT_REGISTRATION`** (event program): renders a single `ProgramStageFormScreen` for the first program stage. - **`WITH_REGISTRATION`** (tracker program): renders `components/forms/TrackerProgramShell`, the more complex piece: - Loads tracker-specific metadata (`useTrackerMetadataQuery`): TEAs, sections, tracked entity type. - - State lives in a per-shell zustand + immer store (`utils/trackerFormsStore.ts`, provided via `components/trackerFormsStoreContext.tsx`): selected slot, draft events per repeatable stage, registration values and per-slot event values. - - `components/EnrollmentRail` (left nav, with `RailRow` and `RepeatableStageGroup`) switches between the registration form and program-stage event forms. Repeatable stages can hold multiple draft events added via the store's `addEvent`; slots are identified by `TrackerSlot`/`slotKey` (`utils/trackerSlot.ts`). + - State lives in a per-shell zustand + immer store (`utils/trackerFormsStore.ts`, provided via `components/trackerFormsStoreContext.tsx`): selected slot, draft events per repeatable stage, registration (enrollment form) values and per-slot event values. + - `components/EnrollmentRail` (left nav, with `RailRow` and `RepeatableStageGroup`) switches between the enrollment form (rail row "Enrollment form", `TrackerSlot` kind `registration`) and program-stage event forms. Repeatable stages can hold multiple draft events added via the store's `addEvent`; slots are identified by `TrackerSlot`/`slotKey` (`utils/trackerSlot.ts`). - **All rendered forms stay mounted simultaneously** (visibility toggled with `hidden` CSS, not conditional rendering) so switching rail rows never discards in-progress input in another form. `TrackerStageFormSlot` fixes each event's date at first render for the same reason. - - Each form pushes its live values to the store via `usePublishFormValues` (debounced 150ms, uses RHF's `form.subscribe`, not `watch`) so sibling forms see them as `enrollment`/`events` rule-engine inputs. This is what lets a rule on an event form react to a value entered in the registration form, and vice versa. + - Each form pushes its live values to the store via `usePublishFormValues` (debounced 150ms, uses RHF's `form.subscribe`, not `watch`) so sibling forms see them as `enrollment`/`events` rule-engine inputs. This is what lets a rule on an event form react to a value entered in the enrollment form, and vice versa. - `selectEventsExcludingSlot` in `trackerFormsStore.ts` shapes per-slot values into `RuleEventInput[]`, excluding the form's own slot. A `WeakMap` cache keeps unchanged entries referentially stable, and each `TrackerStageFormSlot` subscribes with `useShallow`, so a keystroke in one form does not re-render the others. ### Rule-aware rendering (`modules/program-playground/components/rules/`) -- `RuleAwareField` wraps every metadata-driven field: pulls `useFieldControl`/`useFieldRuleEffect` from `-hooks`, renders the field's own label (blanking the widget's built-in label to avoid duplication, then wiring `aria-labelledby` back onto whatever DOM node the widget rendered; see the comment in that file for why), a `FieldEffectBadge` when a rule is affecting the field, and either the real `D2FieldWidget` or a `HiddenFieldPlaceholder`/nothing depending on `RuleDisplayContext`'s `ghostsEnabled` flag. -- `RuleDisplayContext` / `GhostToggleButton` control whether rule-hidden fields/sections render as dashed "ghost" placeholders (`HiddenFieldPlaceholder`, `HiddenSectionPlaceholder`) or are omitted entirely. +- `RuleAwareField` wraps every metadata-driven field: pulls `useFieldControl`/`useFieldRuleEffect` from `-hooks`, renders the field's own label (blanking the widget's built-in label to avoid duplication, then wiring `aria-labelledby` back onto whatever DOM node the widget rendered; see the comment in that file for why), a `FieldEffectBadge` when a rule is affecting the field, and either the real `D2FieldWidget` or a `HiddenFieldPlaceholder`/nothing depending on `RuleDisplayContext`'s `showHiddenFields` flag. +- `RuleDisplayContext` / `GhostToggleButton` (the "Show hidden fields" toggle, an `aria-pressed` button) control whether rule-hidden fields and sections render as dashed hidden-field placeholders (`HiddenFieldPlaceholder`, `HiddenSectionPlaceholder`) or are omitted entirely. Call them hidden-field placeholders in UI text and docs, not ghosts. - `RuleOutputColumn` is the sticky sidebar with separate Feedback and Indicators `RuleOutputCard`s, built from `useFormFeedback`. Each item resolves back to the rule that produced it via `useRuleEffectTrace(feedbackItemKey(item))` + `-devtools`' `createLabelLookup`. - `LazyRulesPanel` lazy-loads the devtools `RulesPanel` (rule list, trace and dependency graph) with `RulesPanelFallback` as the Suspense fallback. Forms wrap their content in `RuleDevtoolsScope` so the panel can read the form store. ### Forms (`modules/program-playground/components/forms/`) -`ProgramRegistrationForm`/`ProgramEventForm` are the RHF-backed forms wired to the rule engine through `-hooks` (`useEventForm`, `FormStateProvider`). `EventFormFields`/`RegistrationFormFields` lay out `RuleAwareField`s inside `FormSectionCard`s per `-metadata`'s section/data-element resolution (`resolveFormSectionLayout`, `getProgramStageSectionDataElementIds`). On save, values pass through `-rules`' `filterPayload` (drops rule-hidden values), are validated with the Zod schemas in `utils/trackerPayloads.ts`, and are turned into DHIS2 tracker payloads (`buildEventPayload`, `buildTrackerRegistrationPayload`) posted to the `tracker` resource. Payload building is app-local, not part of the shared libraries. DHIS2 errors are parsed/formatted by `utils/parseDhis2Error.ts` and `utils/formatDhis2Error.ts`. +`ProgramRegistrationForm` (the enrollment form, `useTrackerForm`) and `ProgramEventForm` (`useEventForm`) are the RHF-backed forms wired to the rule engine through `-hooks` (`FormStateProvider`). `EventFormFields`/`RegistrationFormFields` lay out `RuleAwareField`s inside `FormSectionCard`s per `-metadata`'s section/data-element resolution (`resolveFormSectionLayout`, `getProgramStageSectionDataElementIds`). `ProgramFormActions` renders the buttons below each form. None of them saves anything: + +- **Validate form** runs the form's own validation (`utils/validateForm.ts`, `hooks/useFormValidation.ts`) and `ValidationNotice` lists the fields with issues. No request is sent. +- **Verify with server** (`hooks/useFormServerCheck.ts` over `hooks/useServerVerification.ts`) posts the payload to `tracker` with `importMode=VALIDATE&async=false`. A run that finds problems answers 409 with the report, which `utils/parseRuleValidationReport.ts` parses. `utils/applyServerReport.ts` puts rule errors on the fields they target, and `ServerCheckStatus` shows the rest (including `OtherImportErrors`). +- **Preview server effects** (enrollment form submit, and the first of the two event form buttons) opens `SaveReviewDialog`, a read-only wrapper around the devtools `ServerEffectsSummary`. It shows the server-side effects (messages, scheduled events) the importer would run and compares them with the last Verify result. It has no post action. +- **Preview on-complete effects** (event forms only) first runs the completion pass (`hooks/useCompletionPass.ts`): it sets `status` to `COMPLETED`, waits for the rule engine, and collects on-complete warnings/errors and missing mandatory fields (`utils/completionIssues.ts`). If there are issues, `CompletionBanner` offers Back to editing or Complete anyway (when nothing blocks). It then opens the same summary for `COMPLETED`. `hooks/useEventReviewFlow.ts` tracks which status the summary was last opened for, and Verify dry-runs that status. + +The dry-run payload is built the way a real save would build it: values pass through `utils/parseFormValues.ts` (`-rules`' `filterPayload` drops rule-hidden values), are validated with the Zod schemas in `utils/trackerPayloads.ts`, and are turned into tracker payloads by `buildEventPayload` / `buildTrackerRegistrationPayload` there. Payload building is app-local, not part of the shared libraries. DHIS2 errors are parsed/formatted by `utils/parseDhis2Error.ts` and `utils/formatDhis2Error.ts`. ### Testing -Jest + Testing Library; tests sit next to the code as `*.test.ts(x)`. `usehooks-ts` ships ESM-only and is deliberately carved out of the default `transformIgnorePatterns` in `jest.config.js` (pnpm nests it under `.pnpm/`, hence the lookahead pattern). Don't "fix" that by reverting to the default ignore list. +Jest + Testing Library; tests sit next to the code as `*.test.ts(x)`. `usehooks-ts` and `lodash-es` ship ESM-only and are deliberately carved out of the default `transformIgnorePatterns` in `jest.config.js` (pnpm nests them under `.pnpm/`, hence the lookahead pattern). Don't "fix" that by reverting to the default ignore list. ### Releases diff --git a/README.md b/README.md index fb40aa1..c522cf7 100644 --- a/README.md +++ b/README.md @@ -2,62 +2,50 @@ [![fallow](.github/badges/fallow.svg)](https://github.com/fallow-rs/fallow) -This is a playground app for testing and debugging DHIS2 program rules. It exercises the [`@nnkogift/dhis2-form-utils-hooks`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-hooks), [`-rules`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-rules), and [`-metadata`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-metadata) packages against real form configurations, and uses [`@nnkogift/dhis2-form-utils-devtools`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-devtools) (rule trace and dependency graph panels) to inspect rule evaluation live. +A DHIS2 app for testing, validating and debugging program rules against your real form configurations. You pick a program, fill in its enrollment and event forms, and watch the rules evaluate live: hidden fields and sections, assigned values, mandatory fields, warnings and errors, and feedback and indicator messages. A live rule trace and a dependency graph show why each rule fired, or why it did not. -It consumes those packages as regular npm dependencies, published from the [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) monorepo — file issues or PRs against the underlying libraries there. + -This project was bootstrapped with [DHIS2 Application Platform](https://github.com/dhis2/app-platform). +## Who it's for -## Getting started +- **Program configurators and implementers** who write program rules and want to see them work before users do. +- **DHIS2 admins** who need to find out why a rule behaves differently on their instance. +- **Trainers** who explain program rules and want a safe place to show them in action. -```bash -pnpm install -pnpm dev # start the dev server, proxying against a DHIS2 instance -pnpm build # production build -pnpm test # run the test suite -pnpm lint # eslint + prettier check -``` - -## Available Scripts - -In the project directory, you can run: - -### `pnpm dev` - -Runs the app in development mode.
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser. +## Nothing is saved -The page will reload if you make edits.
-You will also see any lint errors in the console. +The playground never writes data to your instance. You can use it on a production server. -### `pnpm test` +- **Validate form** checks the form in your browser and sends nothing. +- **Verify with server** sends your form to the tracker importer as a dry run (`importMode=VALIDATE`). The server runs its rule engine and validation and reports the result, but stores nothing. +- **Preview server effects** and **Preview on-complete effects** open a read-only summary of the effects the server would run (messages, scheduled events). They do not post anything. -Launches the test runner and runs all available tests found in `/src`.
+## Supported DHIS2 versions -See the section about [running tests](https://platform.dhis2.nu/#/scripts/test) for more information. +DHIS2 2.40 to 2.43 (`minDHIS2Version` and `maxDHIS2Version` in [`d2.config.js`](d2.config.js)). The app's About page shows the same range and the installed version. -### `pnpm build` +## Documentation and install -Builds the app for production to the `build` folder.
-It correctly bundles React in production mode and optimizes the build for the best performance. +- User documentation: [prp-docs.nnkogift.dev](https://prp-docs.nnkogift.dev) +- DHIS2 App Hub (coming soon) +- Release bundles: the `.zip` attached to each [GitHub release](https://github.com/nnkogift/program-rules-playground/releases) -The build is minified and the filenames include the hashes.
-A deployable `.zip` file can be found in `build/bundle`! +## Built on dhis2-form-utils -See the section about [building](https://platform.dhis2.nu/#/scripts/build) for more information. +The rule engine, form hooks, field widgets and rule devtools come from the [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) libraries (`@nnkogift/dhis2-form-utils-*` on npm). File issues and pull requests for those parts there. This repository holds the app around them. -### `pnpm deploy` +## Development -Deploys the built app in the `build` folder to a running DHIS2 instance.
-This command will prompt you to enter a server URL as well as the username and password of a DHIS2 user with the App Management authority.
-You must run `pnpm build` before running `pnpm deploy`.
+You need Node.js 24 and pnpm. -See the section about [deploying](https://platform.dhis2.nu/#/scripts/deploy) for more information. - -## Learn More - -You can learn more about the platform in the [DHIS2 Application Platform Documentation](https://platform.dhis2.nu/). - -You can learn more about the runtime in the [DHIS2 Application Runtime Documentation](https://runtime.dhis2.nu/). +```bash +pnpm install +pnpm dev # start the dev server, proxied against a DHIS2 instance +pnpm test # run the Jest test suite +pnpm typecheck # tsc --noEmit +pnpm lint # eslint + prettier check +pnpm build # production build; the deployable .zip lands in build/bundle +pnpm changeset # describe your change for the next release +``` -To learn React, check out the [React documentation](https://reactjs.org/). +The app is built with the [DHIS2 Application Platform](https://platform.dhis2.nu/). Contributor and agent guidance lives in [`AGENTS.md`](AGENTS.md). From b31671cb3976eaeb5b532445f774d0f9fccb9bbd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Oct 2026 07:08:15 +0300 Subject: [PATCH 2/2] docs: note that file and image fields upload the picked file Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LZTKXxVkBdpd1uHuJWerFT --- AGENTS.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d4f2b63..27d6fc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Guidance for AI coding agents (Claude Code, Codex, and others) working in this r A DHIS2 custom app (built on the [DHIS2 Application Platform](https://github.com/dhis2/app-platform)) for viewing, testing and debugging DHIS2 program rules. A user picks a program, opens its enrollment and event forms, fills them in, and watches program rules evaluate live (hide/show fields and sections, assignments, mandatory, warnings/errors, feedback and indicator messages). Supports DHIS2 2.40 to 2.43 (see `d2.config.js`). -**The app never saves data.** Its only write call is the tracker importer dry run (`importMode=VALIDATE`) in `hooks/useServerVerification.ts`, which runs the server's rule engine and validation and persists nothing. Keep it that way: do not add calls that post to `tracker` (or any other resource) without `importMode=VALIDATE`. +**The app never saves data.** Its only data write call is the tracker importer dry run (`importMode=VALIDATE`) in `hooks/useServerVerification.ts`, which runs the server's rule engine and validation and persists nothing. One exception lives in the libraries: FILE_RESOURCE and IMAGE field widgets (`-dhis2-ui`, via `useFileResourceUpload` in `-hooks`) upload a picked file immediately with `POST fileResources`, leaving an unassigned file resource on the server. The user docs say so. Keep it that way: do not add calls that post to `tracker` (or any other resource) without `importMode=VALIDATE`. It consumes five sibling libraries as regular npm dependencies, all published from the separate [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) monorepo and versioned in lockstep with this app. **File issues/PRs against the rule engine, hooks, widgets or devtools there, not here.** diff --git a/README.md b/README.md index c522cf7..1d6f037 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ A DHIS2 app for testing, validating and debugging program rules against your rea ## Nothing is saved -The playground never writes data to your instance. You can use it on a production server. +The playground never saves tracker data, events, enrollments or metadata, and never sends notifications. You can use it on a production server. The one exception: choosing a file in a file or image field uploads that file to the server as an unused file resource, so use a test file on production. - **Validate form** checks the form in your browser and sends nothing. - **Verify with server** sends your form to the tracker importer as a dry run (`importMode=VALIDATE`). The server runs its rule engine and validation and reports the result, but stores nothing.