---
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>
