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.