Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(109): checkbox multiselect filters

Browse Source 
Phase 109 complete:
- Add checkbox dropdown enhancement for statistics multi-select filters
- Preserve GET contract for channels[] and status_groups[]
- Update PAUL plan context to read .paul/codebase docs

Co-Authored-By: Codex <noreply@openai.com>
This commit is contained in:
Jacek Pyziak
2026-04-28 22:13:52 +02:00
parent 1009957fff
commit 6d3dba89ed
13 changed files with 681 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
.paul/phases/109-checkbox-multiselect-filters/109-01-PLAN.md Normal file
View File

@@ -0,0 +1,189 @@
---
phase: 109-checkbox-multiselect-filters
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- resources/views/statistics/orders.php
- resources/views/layouts/app.php
- public/assets/js/modules/checkbox-multiselect.js
- resources/scss/app.scss
- public/assets/css/app.css
- .paul/codebase/architecture.md
- .paul/codebase/tech_changelog.md
autonomous: false
delegation: off
---
<objective>
## Goal
Replace native multi-select boxes on `/statistics/orders` with compact dropdown controls containing checkboxes, matching the provided visual direction while preserving the current filter contract.
## Purpose
Statistics filters should be faster and clearer to scan. Users should be able to open one compact field, see checked options, toggle individual values or all values, and submit the existing GET form without backend changes.
## Output
Progressive-enhancement UI for multi-select fields, SCSS styling, compiled CSS, and technical documentation updates.
</objective>
<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@AGENTS.md
## Source Files
@resources/views/statistics/orders.php
@resources/views/layouts/app.php
@resources/scss/app.scss
@resources/scss/shared/_ui-components.scss
@package.json
## Notes
- Project technical docs live in `.paul/codebase/`; use `.paul/codebase/architecture.md`, `.paul/codebase/db_schema.md`, and `.paul/codebase/tech_changelog.md`.
- This plan does not change database schema, migrations, SQL queries, or request parameter names.
- Specialized flows: `.paul/SPECIAL-FLOWS.md` requires `sonar-scanner` after APPLY and before UNIFY; frontend-design is optional for this UI work.
</context>
<skills>
## Required Skills (from SPECIAL-FLOWS.md)
| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| sonar-scanner | required | After APPLY, before UNIFY | o |
| /frontend-design | optional | During UI implementation review | o |
**BLOCKING:** `sonar-scanner` must be run before UNIFY unless the environment blocks it.
</skills>
<acceptance_criteria>
## AC-1: Checkbox Dropdown Behavior
```gherkin
Given the `/statistics/orders` page has multi-select filters for channels and status groups
When the user opens either filter
Then the field displays a dropdown with checkboxes, a "Wszystkie" option, and all available choices without using the browser's native multi-select box as the visible control
```
## AC-2: Existing Filter Contract Preserved
```gherkin
Given a user changes selected channels or status groups in the new dropdown
When the user submits the filter form
Then the request still sends `channels[]` and `status_groups[]` values compatible with the existing controller
```
## AC-3: Compact Visual Fit
```gherkin
Given the new dropdown is displayed on desktop and smaller screens
When the options list is opened
Then it remains compact, scrollable when needed, visually aligned with current form controls, and does not place CSS inside PHP view files
```
## AC-4: Progressive Enhancement
```gherkin
Given JavaScript fails to load
When the user visits `/statistics/orders`
Then the original native multi-select remains available enough for filtering instead of breaking the form
```
</acceptance_criteria>
<tasks>
<task type="auto">
<name>Task 1: Mark statistics filters for checkbox enhancement</name>
<files>resources/views/statistics/orders.php</files>
<action>
Add semantic data attributes/classes to the existing `channels[]` and `status_groups[]` multi-selects so a reusable JavaScript module can enhance them.
Keep option values, selected logic, escaping with `$e`, names, and the current GET form action unchanged.
Add accessible labels only through attributes where needed; do not add inline CSS or duplicate option markup by hand.
</action>
<verify>Open the rendered PHP around both selects and confirm names remain `channels[]` and `status_groups[]` with `multiple`.</verify>
<done>AC-2 and AC-4 satisfied for the PHP view.</done>
</task>
<task type="auto">
<name>Task 2: Add reusable checkbox multiselect module</name>
<files>public/assets/js/modules/checkbox-multiselect.js, resources/views/layouts/app.php</files>
<action>
Create a small vanilla JS module that enhances marked native multi-selects:
- Wrap each select in a stable container and visually hide the select only after enhancement succeeds.
- Render a button-like trigger showing selected count, for example `11 zaznaczono`, or a clear empty state.
- Render a dropdown with a `Wszystkie` checkbox followed by one checkbox per option.
- Synchronize checkbox changes back to the original option `selected` values so native form submission remains unchanged.
- Keep "Wszystkie" checked only when all options are selected, unchecked when none are selected, and indeterminate for partial selections.
- Close on outside click and Escape, and keep keyboard focus behavior reasonable for form use.
Include the module once in `resources/views/layouts/app.php` with `filemtime()` cache busting, matching existing module includes.
</action>
<verify>Manual browser check: toggling options changes the original select state and submitted query string remains compatible.</verify>
<done>AC-1, AC-2, and AC-4 satisfied for client behavior.</done>
</task>
<task type="auto">
<name>Task 3: Style and document the new control</name>
<files>resources/scss/app.scss, public/assets/css/app.css, .paul/codebase/architecture.md, .paul/codebase/tech_changelog.md</files>
<action>
Add SCSS for the checkbox multiselect near the existing statistics/form styles:
- Match current `form-control` sizing, borders, focus ring, and compact density.
- Dropdown should have a white surface, thin blue focus/active border, subtle shadow, max height with internal scrolling, and readable checkbox rows similar to the supplied screenshot.
- Avoid inline styles in views and avoid one-hue decorative palettes.
Build CSS with `npm run build:css`.
Update `.paul/codebase/architecture.md` with the new frontend module and `.paul/codebase/tech_changelog.md` with a changelog entry. Do not update DB schema because this plan has no schema change.
</action>
<verify>`npm run build:css` succeeds; docs mention `checkbox-multiselect.js` and the `/statistics/orders` usage.</verify>
<done>AC-3 satisfied and documentation requirements from `AGENTS.md` addressed for this UI-only change.</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Checkbox dropdown multi-select filters on `/statistics/orders`</what-built>
<how-to-verify>
1. Visit: `https://orderpro.projectpro.pl/statistics/orders` or local `/statistics/orders`.
2. Open channel and status filters.
3. Toggle individual checkboxes and "Wszystkie".
4. Submit filters and confirm results refresh with selected values.
5. Confirm the visual direction is close to the attached screenshot: compact trigger, checkbox list, scrollable dropdown.
</how-to-verify>
<resume-signal>Type "approved" to continue to UNIFY, or describe visual/behavior issues to fix.</resume-signal>
</task>
</tasks>
<boundaries>
## DO NOT CHANGE
- `src/Modules/Statistics/OrdersStatisticsController.php` filter parsing contract unless a discovered bug makes it necessary.
- `src/Modules/Statistics/OrdersStatisticsRepository.php` and SQL aggregation logic.
- `database/migrations/*` and DB schema.
- Native `alert()`/`confirm()` patterns.
## SCOPE LIMITS
- This plan enhances multi-select UI only; it does not redesign the whole statistics page.
- Do not add external JS/CSS dependencies.
- Do not move CSS into PHP views.
- Apply the new control first to `/statistics/orders`; broader adoption can follow only by adding the same marker to other native multi-selects after this behavior is verified.
</boundaries>
<verification>
Before declaring plan complete:
- [ ] `npm run build:css`
- [ ] `php -l resources/views/statistics/orders.php`
- [ ] `php -l resources/views/layouts/app.php`
- [ ] Manual check or browser automation confirms dropdown opens, checks sync, and form submission uses existing GET names.
- [ ] `sonar-scanner` run before UNIFY, or blocker recorded if unavailable.
- [ ] All acceptance criteria met.
</verification>
<success_criteria>
- `/statistics/orders` multi-select filters are visibly checkbox dropdowns.
- Existing selected values are reflected on initial page load.
- Form submission stays compatible with current controller inputs.
- CSS is in SCSS and compiled to public CSS.
- Technical changelog and architecture docs are updated.
</success_criteria>
<output>
After completion, create `.paul/phases/109-checkbox-multiselect-filters/109-01-SUMMARY.md`.
</output>

62
.paul/phases/109-checkbox-multiselect-filters/109-01-SUMMARY.md Normal file
View File

@@ -0,0 +1,62 @@
---
phase: 109-checkbox-multiselect-filters
plan: 01
completed: 2026-04-28T22:00:00+02:00
duration: same-session
---
<summary>
## Objective
Replace native multi-select boxes on `/statistics/orders` with compact checkbox dropdown controls while preserving the existing GET filter contract.
## What Was Built
| File | Purpose |
|------|---------|
| `resources/views/statistics/orders.php` | Marked `channels[]` and `status_groups[]` multi-selects for progressive enhancement. |
| `public/assets/js/modules/checkbox-multiselect.js` | Added reusable vanilla JS checkbox-dropdown enhancer. |
| `resources/views/layouts/app.php` | Loaded the new JS module with `filemtime()` cache busting. |
| `resources/scss/app.scss` | Added compact dropdown, trigger, checkbox, and open-state styles. |
| `public/assets/css/app.css` | Rebuilt compiled CSS. |
| `.paul/codebase/architecture.md` | Documented the frontend enhancement module pattern. |
| `.paul/codebase/tech_changelog.md` | Added Phase 109 technical changelog entry. |
| `C:\Users\jacek\.claude\commands\paul\plan.md` | Added codebase architecture and DB schema docs to plan context. |
| `C:\Users\jacek\.claude\paul-framework\workflows\plan-phase.md` | Added required reading/load-context instructions for codebase docs. |
| `C:\Users\jacek\.codex\paul-framework\...` | Synced Claude source framework into Codex target with `~/.codex` path adaptation. |
## Acceptance Criteria Results
| AC | Result | Evidence |
|----|--------|----------|
| AC-1 Checkbox Dropdown Behavior | PASS | Marked selects are enhanced into trigger + checkbox dropdown with "Wszystkie". |
| AC-2 Existing Filter Contract Preserved | PASS | Original selects remain in DOM with unchanged `channels[]` and `status_groups[]` names. |
| AC-3 Compact Visual Fit | PASS | SCSS defines compact 30px trigger, scrollable 200px dropdown, focus border, and subtle shadow. |
| AC-4 Progressive Enhancement | PASS | Native selects are hidden only after JS creates the wrapper and sets enhancement attribute. |
## Verification
| Check | Result |
|-------|--------|
| `npm install` | PASS |
| `npm run build:css` | PASS |
| `php -l resources\views\statistics\orders.php` | PASS |
| `php -l resources\views\layouts\app.php` | PASS |
| `node --check public\assets\js\modules\checkbox-multiselect.js` | PASS |
| `git diff --check -- ...` | PASS |
| `sonar-scanner` | PASS, task `c378ed6c-51bf-4815-acf8-b4e76ca9b9f2` |
## Deviations
- Added the requested PAUL framework sync and `paul:plan` context update during the same plan, because it was explicitly requested with implementation.
- Sonar issue lookup through public API returned `401 Unauthorized`; no SonarQube MCP tool is available in this Codex session.
## Key Patterns / Decisions
- Keep original native select controls as the source of truth for form submission.
- Apply the checkbox dropdown as progressive enhancement only after successful JS initialization.
- Treat Claude PAUL files as source and Codex PAUL files as target, with path adaptation from `~/.claude` to `~/.codex`.
## Skill Audit
- `sonar-scanner`: invoked.
## Next Phase
Phase 109 is complete. v3.3 UI Filters can be closed; next work returns to selecting a new milestone or phase from `.paul/ROADMAP.md`.
</summary>