# Responsive Filter System Design

## Objective

Create a consistent, responsive filter system for the dashboard and redesign the shared date picker across the entire application. The work must preserve existing filter parameters, API contracts, translations, and feature-specific behavior while replacing duplicated layout and styling with shared shadcn-based primitives.

## Scope

### Included

- Redesign the shared `DatePicker` used by filters, blog scheduling, LIFI forms, tickets, profile forms, and other existing consumers.
- Introduce shared filter layout primitives for surfaces, grids, fields, and actions.
- Migrate all dashboard filter panels to the shared layout.
- Keep desktop and tablet filters inline.
- Present filters in a shadcn `Sheet` on mobile.
- Use the existing theme tokens for every surface, border, text color, focus state, hover state, invalid state, and action.
- Preserve Arabic RTL and English LTR behavior.
- Validate date ranges before filters can be applied.

### Excluded

- Changing API payloads, query parameter names, or filter semantics.
- Replacing feature-specific filter state with a schema-generated filter engine.
- Redesigning unrelated confirmation, edit, preview, or destructive dialogs.
- Refactoring unrelated code in the existing dirty worktree.

## Architecture

### Shared Date Picker

`components/ui/inputs/date-picker.tsx` remains the single date-input implementation. Its public value contract stays as an ISO `yyyy-MM-dd` string so existing consumers and APIs do not change.

The redesigned picker will:

- Compose existing shadcn `Button`, `Popover`, and `Calendar` primitives.
- Use `bg-background`, `border-input`, `text-foreground`, `text-muted-foreground`, `ring-ring`, `bg-popover`, and related semantic tokens.
- Match the standard input height and radius used by the filter system.
- Display localized dates while retaining ISO values internally.
- Support RTL alignment and the Arabic `date-fns` locale.
- Expose empty, selected, hover, focus, disabled, and invalid states.
- Continue supporting optional placeholder and class overrides without requiring consumer rewrites.

### Shared Filter Primitives

Add focused primitives under `components/ui/filter/`:

- `FilterSurface`: renders the inline desktop/tablet surface and coordinates the mobile Sheet presentation.
- `FilterGrid`: applies the shared responsive field grid.
- `FilterField`: owns label, spacing, control width, help text, and error placement.
- `FilterActions`: renders consistent clear and apply actions, including the sticky mobile footer.

These components own presentation only. They do not know query parameter names, backend values, or feature-specific options.

### Feature Filter Panels

Each existing feature panel keeps responsibility for:

- Draft filter values.
- Option lists and translations.
- URL query parameter serialization.
- Apply and clear behavior.
- Feature-specific validation beyond shared date-range validation.

Panels compose the shared primitives instead of duplicating cards, grids, labels, and action layouts.

## Responsive Layout

### Large Screens

- Filters remain inline below the page toolbar.
- `FilterGrid` uses four compact columns per row.
- Standard controls use `h-10` and fill their grid cell.
- A date range remains one logical filter field containing two compact date controls.
- Fields use `gap-4`; date controls use a smaller internal gap.
- Action buttons align with the bottom of the filter surface and do not force uneven field heights.

### Medium Screens

- `FilterGrid` uses two columns.
- Date ranges may span both columns when their minimum usable width requires it.
- Actions remain below the fields and wrap without overlap.

### Mobile Screens

- The page filter button opens a shadcn `Sheet` rather than expanding an inline panel.
- Fields use one column.
- The Sheet has a clear title and independently scrollable body.
- Apply and clear actions stay visible in a sticky footer.
- Closing the Sheet without applying does not alter the active URL filters.

## Visual System

- Foundational surfaces use semantic tokens only; no new hex or palette-specific utility classes are introduced.
- Filter surface: `bg-card`, `border-border`, `text-card-foreground`.
- Inputs: `bg-background`, `border-input`, `text-foreground`, `placeholder:text-muted-foreground`.
- Focus: `ring-ring` and the existing focus-ring conventions.
- Primary action: existing default `Button` variant.
- Clear action: non-destructive outline or ghost treatment. Clearing filters is not represented as data destruction.
- Validation: `border-destructive`, `text-destructive`, and accessible invalid attributes.
- Radius and density follow the existing shadcn configuration rather than custom pixel radii.

## State And Data Flow

1. A panel initializes draft values from the current URL query.
2. The user edits controls without immediately changing the URL.
3. Shared range validation checks each from/to pair.
4. Apply remains disabled while any range is invalid.
5. Apply serializes the panel's existing query keys, resets `page` to `1`, updates the router without scrolling, and closes the mobile Sheet or inline panel as currently expected.
6. Clear resets only the query keys owned by that panel, resets `page` to `1`, and preserves unrelated URL state.
7. Existing active-filter badges continue deriving their display from applied URL values.

Back and forward navigation must continue synchronizing the panel with URL state where the current panel already supports it.

## Date Range Validation

- Empty start or end dates remain valid unless a feature already requires both.
- When both values exist, the start date must be earlier than or equal to the end date.
- An invalid range displays a localized inline error near the logical date-range field.
- The filter Apply action is disabled while invalid.
- Validation does not silently swap user-entered dates.

## Migration Strategy

1. Redesign the shared `DatePicker` without changing its ISO string contract.
2. Add and verify the shared filter primitives.
3. Migrate the generic LIFI/featured filter panel.
4. Migrate feature-specific panels for blogs, categories, tags, pages, users, roles, menus, widgets, and maintenance.
5. Update ticket date-range filtering to use the same date appearance and validation conventions.
6. Verify non-filter DatePicker consumers for visual and behavioral compatibility.
7. Remove duplicated layout classes only after each consumer uses the shared primitives.

Migration must preserve unrelated local modifications in every touched file.

## Error Handling And Accessibility

- Controls retain semantic labels and accessible names.
- Invalid fields use `aria-invalid` and connect errors through descriptions where supported by the existing form primitives.
- Calendar and Sheet interactions remain keyboard accessible through shadcn/Radix primitives.
- Focus returns to the filter trigger when the mobile Sheet closes.
- Mobile content remains reachable with the on-screen keyboard open.
- Apply and clear actions have explicit `type="button"` inside forms.

## Verification

### Automated

- Focused ESLint checks for every changed filter and shared component.
- TypeScript validation through the production Next.js build.
- Full production build.
- `git diff --check` for whitespace errors.

The repository's existing unrelated lint failures must be reported separately and must not be expanded into this scope.

### Interaction

- Select and clear single dates in every DatePicker context.
- Apply valid date ranges and reject reversed ranges.
- Apply and clear every migrated filter panel.
- Confirm URL query names and values remain unchanged.
- Confirm pagination resets to page one.
- Confirm browser back and forward navigation restores applied filters.
- Confirm closing the mobile Sheet without applying leaves URL state unchanged.

### Responsive And Locale Coverage

- Mobile: one-column Sheet with sticky actions.
- Tablet: two-column inline panel.
- Large desktop: four-column inline panel with compact controls.
- Arabic RTL and English LTR for DatePicker, Calendar, filter layout, and Sheet.
- Light and dark themes using the same semantic token contract.

## Success Criteria

- Every existing `DatePicker` uses the redesigned shared implementation.
- Every dashboard filter panel uses the shared surface, grid, field, and action primitives.
- Large screens show no more than four fields per row.
- Medium screens use two columns and mobile uses one column in a Sheet.
- No filter or date control introduces hard-coded foundational colors.
- Existing APIs, query parameters, translations, and applied-filter behavior remain compatible.
- Selected dates, invalid ranges, and filter actions are visually and accessibly clear in both themes and locales.