npm package: @akinon/akifilter
Description: Akifilter is a filtering library for Akinon frontend applications.
Latest version: 1.3.5

# akifilter

## Legacy Functionality Snapshot (`@akinon/ui/akifilter-old`)
- **Schema-driven forms**: Builds the main filter UI from `filterSchema` using `FormBuilderWatch`, applying `labelRightAligned` props and reflecting initial values from `useAppliedFilters[0]` or persisted storage.
- **Context-managed state**: `FilterContextProvider` derives `mainPath` from the router (or `customMainPath`), stores `appliedFilters`, `applicableFilters`, and `shownFilters` via `useImmerReducer`, and exposes actions for updates.
- **Local storage persistence**: Reads/writes `appliedFilters-{mainPath}` and `shownFilters-{mainPath}` so filter selections survive reloads; defaults to the first eight filters when no history exists.
- **Parent synchronization**: Propagates every applied-filter change back through `useAppliedFilters[1]`, allowing host apps to react or override initial state.
- **Applied filter chips**: Renders active filters with labels sourced from placeholders, formats values (dates via akidate utilities, arrays, booleans) for display, and supports removing individual filters or clearing all.
- **Dynamic filter visibility**: `SelectShownFilters` opens a modal with searchable, paginated checkboxes for every applicable filter; selections update `shownFilters` and trigger form recreation to avoid stale state.
- **Conditional filters**: Optional `conditionalFiltersSchema` renders a secondary form whose values merge into `appliedFilters` without local storage persistence, rebuilding whenever the schema changes.
- **Utility helpers**: Provides path parsing (`getPathFragments`) to scope state per route and a tree search helper (`getTreeNodeByValue`) for nested option lookups.
- **Internationalization scaffolding**: Loads static i18n bundles (EN/TR) through `Akilocale` for component copy such as the panel title.

## Implementation Plan (User Experience Focus)
1. **Filter Workspace Shell**
   - Recreate the legacy layout with updated styling hooks, keeping the header title, filter-selection trigger, applied filter strip, and main filter grid so existing users feel familiar while allowing future visual tweaks.
   - Integrate `akilocale` for default copy (`title`, modal labels) and expose translation keys for host apps.

2. **Schema Intake & Form Rendering**
   - Accept an external `filterSchema` (and optional `conditionalFiltersSchema`) and translate each field into `akiform` widgets, honoring component-specific props, labels, and placeholders.
   - Default-render only “primary” filters on first load (configurable count), but respect any persisted selections on subsequent visits.

3. **User Input & Applied State**
   - Mirror user edits into an internal state model while emitting JSON payloads to the host via the provided `useAppliedFilters` tuple so parent apps receive canonical data.
   - Display currently applied filters as removable chips; value formatting should transparently handle primitives, arrays, booleans, and date-like objects.

4. **Filter Visibility Management**
   - Provide a modal (using `@akinon/ui-modal`, `@akinon/ui-input`, `@akinon/ui-pagination`) that lists all available filters with search, pagination, and checkbox toggles to control visibility.
   - Persist visibility selections and main-form order to local storage, ensuring a stable experience across sessions.

5. **Persistence Strategy**
   - Derive unique local-storage keys using a caller-supplied prefix plus a deterministic suffix (e.g., hash of schema or route) so multiple filter instances cannot collide.
   - Support optional overrides (custom key + custom main path) while always appending our uniqueness salt.

6. **Conditional Filter Surface**
   - Render an auxiliary `akiform` section beneath the main filters when `conditionalFiltersSchema` exists, reset its form state whenever the schema changes, and merge its values into the emitted applied-filter JSON without persisting to storage.

7. **Bulk Actions & Import Filters**
   - Retain the “clear all” action for quick resets, updating UI state, storage, and parent callbacks consistently.
   - Plan dedicated affordances for CSV/XLS import: display buttons in the options toolbar, accept uploads via `@akinon/ui-upload`, and parse/normalize records into applied filters (details to be implemented in later stages).

8. **Testing & Quality Targets**
   - Cover all interactive flows (form entry, chip removal, modal toggles, persistence, conditional schema changes, CSV/XLS hooks) with Vitest and Testing Library, targeting ≥90% coverage without regressing existing suites.
   - Document sample integration snippets so partner apps can verify behavior during development.