@akinon/akifilter 1.8.0 → 1.9.0

package/README.md

@@ -42,3 +42,309 @@
 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.
+
+---
+
+## Section Fields
+
+Fields declared with `type: 'section'` render as collapsible panels below the
+main filter grid. Every field inside a section is part of the same form state as
+the top-level filters, so section values are emitted through `onValuesChange`
+and persisted to local storage exactly like regular filters.
+
+```tsx
+const filterSchema = [
+  { key: 'sku', type: 'text', label: 'SKU', config: { visible: true } },
+  {
+    key: 'excludeSection',
+    type: 'section',
+    label: 'Exclude Filters',
+    isExcludeSection: true,
+    fields: [{ key: 'excludeSku', type: 'text', label: 'Exclude SKU' }]
+  }
+];
+```
+
+### Section flags
+
+| Flag                | Effect                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| `defaultExpanded`   | `false` starts the panel collapsed.                                                       |
+| `isExcludeSection`  | Chips for the section's fields render with the exclude styling (red chip + exclude icon).  |
+| `selectableFields`  | Adds a funnel button that opens a per-section visibility modal.                            |
+| `enableImportCsv`   | Adds a CSV import button to the section header. Requires `onSectionImportCsv`.             |
+| `enableImportXls`   | Adds an XLS/XLSX import button to the section header. Requires `onSectionImportXls`.       |
+
+> Only Akifilter reads these flags. `isExcludeSection` and `selectableFields`
+> are declared on `SectionField` in `@akinon/akiform-builder` for historical
+> reasons and have builder setters of their own; `enableImportCsv` /
+> `enableImportXls` are Akifilter's own props and reach a builder-made section
+> through `field().extend({ enableImportCsv: true })`, which is where any new
+> Akifilter-only prop belongs. See the note on `SectionField` in that package's
+> `types.ts`.
+
+### Persistence
+
+Section values are stored under the same `…:values` local-storage entry as the
+top-level filters and rehydrated on the next mount, so a page refresh keeps
+exclude filters filled in. Per-section visibility selections (`selectableFields`)
+are stored separately under `…:section:<sectionKey>`.
+
+The storage key is hashed from the **top-level** field signature only, so editing
+a section's fields does not invalidate the entry (and existing entries survive an
+upgrade). Stale values from an older schema are instead rejected on read: a
+persisted value whose shape cannot fit its field's current `type`/`mode` is
+dropped rather than restored — e.g. an array left behind by a
+`select`/`multiple` field is not fed into a field that is now `text`. `file`
+fields are never restored at all, since a `File` cannot survive JSON
+serialisation.
+
+### Section-level CSV / XLS import
+
+A section can expose its own file-import buttons in the collapse header — the
+same affordance the top-level toolbar offers through `enableImportCsv` /
+`onImportCsv`, and rendered conditionally in the same way as the
+`selectableFields` funnel. This is typically used to exclude a large set of
+records by uploading a file instead of typing values one by one.
+
+A button renders only when **both** halves are present: the schema flag on the
+section and the matching handler on the component. The handler receives the
+section's `key` first, so a single handler can serve every section.
+
+```tsx
+<Akifilter
+  filterSchema={[
+    {
+      key: 'excludeSection',
+      type: 'section',
+      label: 'Exclude Filters',
+      isExcludeSection: true,
+      enableImportCsv: true,
+      enableImportXls: true,
+      fields: [{ key: 'excludeSku', type: 'text', label: 'Exclude SKU' }]
+    }
+  ]}
+  onSectionImportCsv={(sectionKey, file) => uploadExcludeFile(sectionKey, file)}
+  onSectionImportXls={(sectionKey, file) => uploadExcludeFile(sectionKey, file)}
+/>
+```
+
+Akifilter never reads or parses the file — it only surfaces the picker and hands
+the `File` to the host application. To show the upload as an active filter, feed
+it back through `externalAppliedFilters` (set `isExclude: true` on the chip to
+match the exclude styling) and clear it from `onRemoveExternalFilter`.
+
+Import buttons combine freely with `selectableFields`: the funnel is rendered
+after the file buttons inside the same header action group. Both mouse clicks and
+Enter presses are stopped from bubbling out of that group, so activating a header
+action never toggles the panel underneath it.
+
+With the builder API:
+
+```ts
+field()
+  .key('excludeSection')
+  .type('section')
+  .label('Exclude Filters')
+  .isExcludeSection(true)
+  // Akifilter's own flags travel through `extend()`; `isExcludeSection` and
+  // `selectableFields` predate it and keep their setters.
+  .extend({ enableImportCsv: true, enableImportXls: true })
+  .fields([field().key('excludeSku').type('text').label('Exclude SKU').build()])
+  .build();
+```
+
+### Localization
+
+Section header action copy lives under the `section.actions` namespace
+(`importCsv`, `importXls`, `importCsvTooltip`, `importXlsTooltip`). The tooltip
+keys interpolate `{{section}}` with the section's label.
+
+---
+
+## Field Labels
+
+A field's `label` drives its form input. Two optional props override it for one
+surface each, so the chip and the picker can say something different from the
+input:
+
+| Prop              | Overrides                                      | Falls back to |
+| ----------------- | ---------------------------------------------- | ------------- |
+| `appliedLabel`    | The applied-filter chip (and its remove button's accessible name). | `label` → `placeholder` → `key` |
+| `visibilityLabel` | The field's row in the "Select visible filters" modal. | `label` → `placeholder` → `key` |
+
+```tsx
+const filterSchema: AkifilterSchema = [
+  {
+    key: 'orderNo',
+    type: 'text',
+    label: 'Order No', // form input
+    appliedLabel: 'Order number', // chip: "Order number: 1001"
+    visibilityLabel: 'Order reference no' // modal row
+  },
+  {
+    key: 'excludeSection',
+    type: 'section',
+    label: 'Exclude Filters',
+    isExcludeSection: true,
+    fields: [
+      {
+        key: 'excludeStatus',
+        type: 'text',
+        label: 'Status',
+        // The chip is rendered outside the section, so it carries the context
+        // the section header would otherwise provide.
+        appliedLabel: 'Excluded status'
+      }
+    ]
+  }
+];
+```
+
+Notes:
+
+- Both props are optional. A field that sets neither behaves exactly as before,
+  so adding them to one field never affects the rest of the schema.
+- Section children support them too, including inside exclude sections.
+- The visibility modal's search box matches `visibilityLabel`, `label`,
+  `placeholder` and `key`, so an overridden field stays findable under either
+  name.
+- Neither prop affects the form input's own label or its accessible name — use
+  `label` for that.
+- Storage is keyed by field `key`, never by any label, so renaming or
+  overriding labels does not invalidate persisted values or visibility
+  selections.
+- They are Akifilter's own props, not part of the shared form schema. With the
+  fluent builder they travel through its generic `extend()` hatch:
+
+  ```tsx
+  import { field } from '@akinon/akiform-builder';
+
+  field()
+    .key('orderNo')
+    .type('text')
+    .label('Order No')
+    .extend({ appliedLabel: 'Order number' })
+    .build();
+  ```
+
+  The call is type-checked even though the builder knows nothing about filters:
+  Akifilter declares its props on the builder's `FieldExtensions` interface, and
+  `extend()` accepts *only* declared keys — a typo or a wrong type is a compile
+  error, and an application that wants to hang its own metadata on a field
+  declares it the same way:
+
+  ```ts
+  declare module '@akinon/akiform-builder' {
+    interface FieldExtensions {
+      requestKey?: string;
+    }
+  }
+  ```
+
+  `AkiformBuilder` ignores all of it — it renders the form label from `label`
+  alone.
+
+See the `With Distinct Labels` Storybook story for a live example.
+
+---
+
+## Multi-Value Filters and Switchable Filter Types
+
+### Tags input out of the box
+
+A `select` field with `mode: 'tags'` and no options is a free-form multi-value
+input: type a value, press Enter to turn it into a removable tag, repeat. The
+applied chip joins the entries with `, `.
+
+```tsx
+{
+  key: 'keywords',
+  type: 'select',
+  label: 'Keywords',
+  mode: 'tags',
+  options: []
+}
+```
+
+`mode` is part of the storage signature, so switching a field between single
+and multi-value modes invalidates its persisted entry instead of restoring an
+incompatible shape.
+
+### One field, several chips (`appliedChips`)
+
+By default a field contributes one applied-filter chip. A field that owns
+several filters at once — a bucket per filter type, a range that reads better as
+two chips — can produce its own instead:
+
+```tsx
+{
+  key: 'attributeName',
+  type: 'custom',
+  label: 'Attribute Name',
+  // Value shape is the field's own business, e.g.
+  // { mode: 'exact', buckets: { contains: ['a', 'b'], exact: ['c'] } }
+  appliedChips: ({ field, value, formValues }) => [
+    { id: 'contains', label: 'Attribute Name (Contains)', value: 'a, b' },
+    { id: 'exact', label: 'Attribute Name (Exact match)', value: 'c' }
+  ],
+  // Return the value the field should hold after the chip is removed,
+  // or `null` to clear the field.
+  onRemoveAppliedChip: ({ field, value, id }) => dropBucket(value, id),
+  render: ({ control }) => <MyInput control={control} />
+}
+```
+
+| Prop | Behaviour |
+| ---- | --------- |
+| `appliedChips` | Replaces the field's single chip with one chip per returned entry. Return `[]` for "no chips right now". Each entry is `{ id, value, label?, isExclude? }`; `label` defaults to the field's applied label, `isExclude` to whether the field sits in an exclude section. |
+| `onRemoveAppliedChip` | Maps one chip's × back onto a new field value, which Akifilter commits, persists and emits. Without it the chips render but cannot be removed. |
+
+`id` must be stable for the same logical entry and unique within the field. Chip
+keys are `<field key>::<chip id>` internally and are split at the first
+separator, so an id may contain `::` — a field key may not.
+
+`appliedChips` is only called while the field's own value is non-empty — the
+emptiness rules that suppress a plain chip (`null`/`undefined`, a blank string,
+an empty array) suppress these too. Use `formValues` to *format* the chips (a
+unit or a mode held by a sibling field), not to derive them from a sibling while
+this field holds nothing.
+
+With the fluent builder both props travel the same route as the label
+overrides: `field().…​.extend({ appliedChips, onRemoveAppliedChip })`.
+
+Because every chip is derived from the field's **form value**, persistence comes
+for free: Akifilter stores and rehydrates the composite value like any other
+one, and `Clear all` clears the field like any other. Nothing has to be mirrored
+into host state or written to storage by the application.
+
+Declaring `appliedChips` also tells the storage layer that the field owns its
+value shape, so a composite (object) value is rehydrated instead of being
+rejected as schema drift — the same exemption `type: 'custom'` gets. Without the
+prop, only `custom` fields may hold object values across a reload.
+
+### A filter whose type the user can switch
+
+Some filters carry a *type* next to their value — contains / exact match /
+starts with — where each type emits under its own request key and several types
+can be active at the same time. The `With Tag Type Selector` Storybook story
+implements the whole flow on top of the pieces above:
+
+| Concern | Mechanism |
+| ------- | --------- |
+| The input (tags + the type switcher on its right) | A `custom` field. Bind it with `useController({ control: renderProps.control, name })`. |
+| Where the state lives | One form value holding a bucket per type plus the active type — so Akifilter persists and rehydrates all of it, active type included. |
+| One chip per type, each with its own label | `appliedChips`. |
+| Removing a single type | `onRemoveAppliedChip`, returning the value without that bucket (`null` when the last one goes). |
+| Mapping buckets onto request keys | Host logic, since one logical filter can emit several keys at once. |
+
+The flow the story demonstrates:
+
+1. With `Contains` active, entering `filter a` and `filter b` produces
+   `Attribute Name (Contains): filter a, filter b`.
+2. Switching the type leaves that bucket with its own chip and shows the new
+   type's (empty) bucket in the input.
+3. Entering `filter c` adds `Attribute Name (Exact match): filter c`, and the
+   payload carries both request keys.
+4. Switching back shows the earlier bucket in the input again.
+5. A page refresh restores every bucket **and** the active type.

package/dist/cjs/akifilter.d.ts

@@ -71,6 +71,25 @@ export type AkifilterProps<TFieldValues extends AkifilterFieldValues = Akifilter
      * Notified whenever the set of active filter buttons changes.
      */
     onFilterButtonsChange?: (activeButtons: AkifilterButton[]) => void;
+    /**
+     * Triggered when a user picks a CSV file from a section header's import
+     * button. Receives the section's `key` and the selected file, so one handler
+     * can serve every section.
+     *
+     * The button only renders for sections that set `enableImportCsv: true` —
+     * mirroring how the top-level toolbar pairs `enableImportCsv` with
+     * `onImportCsv`. Akifilter never parses the file; the host application
+     * decides what to do with it (e.g. call an exclude-by-file endpoint and
+     * surface a chip through `externalAppliedFilters`).
+     */
+    onSectionImportCsv?: (sectionKey: string, file: File) => void;
+    /**
+     * Triggered when a user picks an XLS/XLSX file from a section header's import
+     * button. Receives the section's `key` and the selected file.
+     *
+     * The button only renders for sections that set `enableImportXls: true`.
+     */
+    onSectionImportXls?: (sectionKey: string, file: File) => void;
 };
 export declare const Akifilter: {
     <TFieldValues extends AkifilterFieldValues = FieldValues>(props: AkifilterProps<TFieldValues>): React.JSX.Element;

package/dist/cjs/akifilter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"akifilter.d.ts","sourceRoot":"","sources":["../../src/akifilter.tsx"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAC;AAGtB,OAAO,EAIL,WAAW,EACX,IAAI,EAIL,MAAM,iBAAiB,CAAC;AAYzB,OAAO,KAAK,MAAM,OAAO,CAAC;AAc1B,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,8BAA8B,CAAC;AAgBtC,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAEf,eAAe,EAChB,MAAM,SAAS,CAAC;AAWjB,KAAK,oBAAoB,GAAG,WAAW,CAAC;AA2KxC,MAAM,MAAM,cAAc,CACxB,YAAY,SAAS,oBAAoB,GAAG,oBAAoB,IAC9D;IACF;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC7C;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACzD;;OAEG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,CAAC;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IACnC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAClD;;;OAGG;IACH,sBAAsB,CAAC,EAAE,aAAa,EAAE,CAAC;IACzC;;OAEG;IACH,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC;;OAEG;IACH,qBAAqB,CAAC,EAAE,CAAC,aAAa,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;CACpE,CAAC;AA+3BF,eAAO,MAAM,SAAS;KACpB,YAAY,SAAS,oBAAoB,uBAElC,cAAc,CAAC,YAAY,CAAC;;CAoBpC,CAAC"}
+{"version":3,"file":"akifilter.d.ts","sourceRoot":"","sources":["../../src/akifilter.tsx"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAC;AAGtB,OAAO,EAIL,WAAW,EACX,IAAI,EAIL,MAAM,iBAAiB,CAAC;AAYzB,OAAO,KAAK,MAAM,OAAO,CAAC;AAc1B,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,8BAA8B,CAAC;AAgBtC,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAEf,eAAe,EAChB,MAAM,SAAS,CAAC;AAYjB,KAAK,oBAAoB,GAAG,WAAW,CAAC;AAiLxC,MAAM,MAAM,cAAc,CACxB,YAAY,SAAS,oBAAoB,GAAG,oBAAoB,IAC9D;IACF;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC7C;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACzD;;OAEG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,CAAC;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IACnC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAClD;;;OAGG;IACH,sBAAsB,CAAC,EAAE,aAAa,EAAE,CAAC;IACzC;;OAEG;IACH,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC;;OAEG;IACH,qBAAqB,CAAC,EAAE,CAAC,aAAa,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;IACnE;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC9D;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CAC/D,CAAC;AAk9BF,eAAO,MAAM,SAAS;KACpB,YAAY,SAAS,oBAAoB,uBAElC,cAAc,CAAC,YAAY,CAAC;;CAoBpC,CAAC"}

package/dist/cjs/akifilter.js

@@ -48,6 +48,12 @@ const values_1 = require("./utils/values");
  * routed back to the owning button.
  */
 const BUTTON_CHIP_PREFIX = 'akifilter-button:';
+// Chips a field produced through `appliedChips`. The key carries both halves —
+// `<field key>::<chip id>` — so a removal can be routed back to the field that
+// owns it. Split at the *first* separator, so a chip id may contain one; a
+// field key may not, which holds for form paths.
+const FIELD_CHIP_PREFIX = 'akifilter-field:';
+const FIELD_CHIP_SEPARATOR = '::';
 const FilterFormItem = (_a) => {
     var _b, _c;
     var { children, control, name, valuePropName } = _a, props = __rest(_a, ["children", "control", "name", "valuePropName"]);
@@ -128,7 +134,7 @@ const resolveClearedFieldValue = (field, defaultValue) => {
             return undefined;
     }
 };
-const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onValuesChange, onVisibleFieldsChange, onImportCsv, onImportXls, onClearAll, enableImportCsv, enableImportXls, filterActionsRef, externalAppliedFilters, onRemoveExternalFilter, filterButtons, onFilterButtonsChange }) => {
+const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onValuesChange, onVisibleFieldsChange, onImportCsv, onImportXls, onClearAll, enableImportCsv, enableImportXls, filterActionsRef, externalAppliedFilters, onRemoveExternalFilter, filterButtons, onFilterButtonsChange, onSectionImportCsv, onSectionImportXls }) => {
     // Separate regular fields from section fields
     const { regularFields, sectionFields } = react_1.default.useMemo(() => (0, schema_1.partitionSchema)(filterSchema), [filterSchema]);
     const excludeSectionKeys = react_1.default.useMemo(() => (0, schema_1.deriveExcludeSectionKeys)(sectionFields), [sectionFields]);
@@ -138,16 +144,19 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     const schemaDefaults = react_1.default.useMemo(() => (0, schema_1.normaliseValuesBySchema)(flattenedSchema, (0, schema_1.extractDefaultValues)(flattenedSchema)), [flattenedSchema]);
     const externalDefaults = react_1.default.useMemo(() => (0, schema_1.normaliseValuesBySchema)(flattenedSchema, defaultValues), [flattenedSchema, defaultValues]);
     const baseDefaultValues = react_1.default.useMemo(() => (Object.assign(Object.assign({}, schemaDefaults), externalDefaults)), [schemaDefaults, externalDefaults]);
-    // Use state for persistedDefaults to make it reactive to localStorage changes
+    // Use state for persistedDefaults to make it reactive to localStorage changes.
+    // Read against the *flattened* schema: `readStoredValues` drops keys that are
+    // not in the schema it is given, so passing only the top-level fields would
+    // silently discard every section field's persisted value on reload.
     const [persistedDefaults, setPersistedDefaults] = react_1.default.useState(() => {
         var _a;
-        return (0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(regularFields, storageKey)) !== null && _a !== void 0 ? _a : undefined);
+        return (0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined);
     });
     // Re-read from localStorage when storageKey changes
     react_1.default.useEffect(() => {
         var _a;
-        setPersistedDefaults((0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(regularFields, storageKey)) !== null && _a !== void 0 ? _a : undefined));
-    }, [flattenedSchema, regularFields, storageKey]);
+        setPersistedDefaults((0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined));
+    }, [flattenedSchema, storageKey]);
     const mergedDefaultValues = react_1.default.useMemo(() => (Object.assign(Object.assign({}, baseDefaultValues), persistedDefaults)), [baseDefaultValues, persistedDefaults]);
     const formMethods = (0, akiform_1.useForm)({
         defaultValues: mergedDefaultValues
@@ -200,7 +209,23 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
             if (field.type === constants_1.FIELD_TYPES.CHECKBOX && currentValue !== true) {
                 return acc;
             }
-            const label = field.label || field.placeholder || key;
+            const label = (0, schema_1.getAppliedLabel)(field);
+            // A field that owns several filters renders its own chips: only it knows
+            // how to split its value and how to format each part.
+            if (typeof field.appliedChips === 'function') {
+                field
+                    .appliedChips({ field, value: currentValue, formValues })
+                    .forEach(chip => {
+                    var _a, _b;
+                    acc.push({
+                        key: `${FIELD_CHIP_PREFIX}${key}${FIELD_CHIP_SEPARATOR}${chip.id}`,
+                        label: (_a = chip.label) !== null && _a !== void 0 ? _a : label,
+                        value: chip.value,
+                        isExclude: (_b = chip.isExclude) !== null && _b !== void 0 ? _b : excludeSectionKeys.has(key)
+                    });
+                });
+                return acc;
+            }
             const fieldOptions = 'options' in field && field.options ? field.options : undefined;
             const resolveLabel = (val) => {
                 var _a;
@@ -418,17 +443,14 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         emitValues,
         persistValues
     ]);
-    const handleRemoveFilter = react_1.default.useCallback((key) => {
-        const schemaField = flattenedSchema.find(field => String(field.key) === key);
-        if (!schemaField) {
-            return;
-        }
-        const defaultValue = schemaDefaults[String(schemaField.key)];
-        const nextValue = resolveClearedFieldValue(schemaField, defaultValue);
+    // Writes one field's value and pushes the result through the whole
+    // persist/emit path immediately, bypassing the debounce the way a removal
+    // has to. Shared by chip removals — whole-field and per-chip alike.
+    const commitFieldValue = react_1.default.useCallback((fieldKey, nextValue) => {
         // Manually construct the updated form values instead of relying on setValue + getValues
         // because setValue is batched and getValues() wouldn't reflect the change immediately
         const currentFormValues = formMethods.getValues();
-        const updatedFormValues = Object.assign(Object.assign({}, currentFormValues), { [String(schemaField.key)]: nextValue });
+        const updatedFormValues = Object.assign(Object.assign({}, currentFormValues), { [fieldKey]: nextValue });
         // Normalize the values (removes empty/undefined entries)
         const nextValues = (0, values_1.normaliseOutputValues)(flattenedSchema, updatedFormValues);
         // updatedFormValues holds an explicit cleared value (e.g. `null` for custom/file
@@ -450,7 +472,36 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         hasInitialValuesRef.current = Object.keys(nextValues).length > 0;
         // Emit the change to parent
         emitValues(nextValues);
-    }, [schemaDefaults, flattenedSchema, formMethods, emitValues, persistValues]);
+    }, [flattenedSchema, formMethods, emitValues, persistValues]);
+    const handleRemoveFilter = react_1.default.useCallback((key) => {
+        const schemaField = flattenedSchema.find(field => String(field.key) === key);
+        if (!schemaField) {
+            return;
+        }
+        const defaultValue = schemaDefaults[String(schemaField.key)];
+        commitFieldValue(String(schemaField.key), resolveClearedFieldValue(schemaField, defaultValue));
+    }, [schemaDefaults, flattenedSchema, commitFieldValue]);
+    // Removal of a single chip produced by a field's own `appliedChips`. The
+    // field decides what its value becomes; Akifilter just commits it.
+    const handleFieldChipRemove = react_1.default.useCallback((chipKey) => {
+        const separatorIndex = chipKey.indexOf(FIELD_CHIP_SEPARATOR);
+        if (separatorIndex === -1) {
+            return;
+        }
+        const fieldKey = chipKey.slice(0, separatorIndex);
+        const chipId = chipKey.slice(separatorIndex + FIELD_CHIP_SEPARATOR.length);
+        const schemaField = flattenedSchema.find(field => String(field.key) === fieldKey);
+        if (!schemaField ||
+            typeof schemaField.onRemoveAppliedChip !== 'function') {
+            return;
+        }
+        const currentValue = formMethods.getValues()[fieldKey];
+        commitFieldValue(fieldKey, schemaField.onRemoveAppliedChip({
+            field: schemaField,
+            value: currentValue,
+            id: chipId
+        }));
+    }, [flattenedSchema, formMethods, commitFieldValue]);
     // Toggle a filter button. Button state lives outside the form, so this syncs
     // the value ref, persists, and emits immediately (bypassing the form debounce).
     const handleButtonToggle = react_1.default.useCallback((button) => {
@@ -514,6 +565,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         if (key.startsWith(BUTTON_CHIP_PREFIX)) {
             handleButtonRemove(key.slice(BUTTON_CHIP_PREFIX.length));
         }
+        else if (key.startsWith(FIELD_CHIP_PREFIX)) {
+            handleFieldChipRemove(key.slice(FIELD_CHIP_PREFIX.length));
+        }
         else if (externalAppliedFilters === null || externalAppliedFilters === void 0 ? void 0 : externalAppliedFilters.some(f => f.key === key)) {
             onRemoveExternalFilter === null || onRemoveExternalFilter === void 0 ? void 0 : onRemoveExternalFilter(key);
         }
@@ -524,7 +578,8 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         externalAppliedFilters,
         onRemoveExternalFilter,
         handleRemoveFilter,
-        handleButtonRemove
+        handleButtonRemove,
+        handleFieldChipRemove
     ]);
     const handleClearAllApplied = react_1.default.useCallback(() => {
         // Reset filter buttons before clearing the form so the merged emission in
@@ -599,7 +654,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
                     react_1.default.createElement("div", { className: "akinon-filter__form-grid", "data-testid": "akifilter-form-grid" },
                         visibleFields.map(renderFormField),
                         visibleFields.length === 0 && regularFields.length > 0 ? (react_1.default.createElement("div", { className: "akinon-filter__empty" }, i18n_1.i18n.t('form.noVisibleFields'))) : null),
-                    sectionFields.length > 0 && (react_1.default.createElement("div", { className: "akinon-filter__section-fields" }, sectionFields.map(section => (react_1.default.createElement(section_fieldset_1.SectionFieldset, { key: String(section.key), section: section, storageKey: storageKey, renderFormField: renderFormField, onRemoveField: handleRemoveFilter, formValues: normalisedValues }))))))),
+                    sectionFields.length > 0 && (react_1.default.createElement("div", { className: "akinon-filter__section-fields" }, sectionFields.map(section => (react_1.default.createElement(section_fieldset_1.SectionFieldset, { key: String(section.key), section: section, storageKey: storageKey, renderFormField: renderFormField, onRemoveField: handleRemoveFilter, formValues: normalisedValues, onImportCsv: onSectionImportCsv &&
+                            (file => onSectionImportCsv(String(section.key), file)), onImportXls: onSectionImportXls &&
+                            (file => onSectionImportXls(String(section.key), file)) }))))))),
             react_1.default.createElement(visibility_modal_1.VisibilityModal, Object.assign({}, modalProps)))));
 };
 const AkifilterEmptyState = () => {

package/dist/cjs/common/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/common/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA4B/C,eAAO,MAAM,eAAe,GAAI,YAAY,SAAS,WAAW,EAC9D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,MAKF,CAAC;AAIF,eAAO,MAAM,eAAe,GAAI,YAAY,SAAS,WAAW,EAC9D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,MAAM,EAAE,GAAG,IAoBb,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,EAAE,MAAM,MAAM,EAAE,KAAG,IAQrE,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,YAAY,MAAM,EAClB,YAAY,MAAM,GAAG,MAAM,KAC1B,MAAuD,CAAC;AAE3D,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,KAAG,IAQrD,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAAI,YAAY,SAAS,WAAW,EAC/D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,OAAO,CAAC,YAAY,CAAC,GAAG,IA+B1B,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,YAAY,SAAS,WAAW,EAChE,YAAY,MAAM,EAClB,QAAQ,OAAO,CAAC,YAAY,CAAC,KAC5B,IAeF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,YAAY,MAAM,KAAG,IAQtD,CAAC;AAKF,eAAO,MAAM,sBAAsB,GACjC,YAAY,MAAM,KACjB,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,IAwB3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,YAAY,MAAM,EAClB,QAAQ,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAC7B,IAcF,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,YAAY,MAAM,KAAG,IAQ5D,CAAC"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/common/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA4B/C,eAAO,MAAM,eAAe,GAAI,YAAY,SAAS,WAAW,EAC9D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,MAKF,CAAC;AAIF,eAAO,MAAM,eAAe,GAAI,YAAY,SAAS,WAAW,EAC9D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,MAAM,EAAE,GAAG,IAoBb,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,EAAE,MAAM,MAAM,EAAE,KAAG,IAQrE,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,YAAY,MAAM,EAClB,YAAY,MAAM,GAAG,MAAM,KAC1B,MAAuD,CAAC;AAE3D,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,KAAG,IAQrD,CAAC;AA0DF,eAAO,MAAM,gBAAgB,GAAI,YAAY,SAAS,WAAW,EAC/D,QAAQ,cAAc,CAAC,YAAY,CAAC,EAAE,EACtC,YAAY,MAAM,KACjB,OAAO,CAAC,YAAY,CAAC,GAAG,IAqC1B,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,YAAY,SAAS,WAAW,EAChE,YAAY,MAAM,EAClB,QAAQ,OAAO,CAAC,YAAY,CAAC,KAC5B,IAeF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,YAAY,MAAM,KAAG,IAQtD,CAAC;AAKF,eAAO,MAAM,sBAAsB,GACjC,YAAY,MAAM,KACjB,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,IAwB3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,YAAY,MAAM,EAClB,QAAQ,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAC7B,IAcF,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,YAAY,MAAM,KAAG,IAQ5D,CAAC"}

package/dist/cjs/common/storage.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearStoredButtonValues = exports.writeStoredButtonValues = exports.readStoredButtonValues = exports.clearStoredValues = exports.writeStoredValues = exports.readStoredValues = exports.clearVisibleKeys = exports.buildSectionVisibilityKey = exports.writeVisibleKeys = exports.readVisibleKeys = exports.buildStorageKey = void 0;
+const constants_1 = require("../constants");
 const i18n_1 = require("../i18n");
 const STORAGE_PREFIX = 'akifilter:v1';
 const VALUES_SUFFIX = ':values';
@@ -76,6 +77,46 @@ const clearVisibleKeys = (storageKey) => {
 };
 exports.clearVisibleKeys = clearVisibleKeys;
 const buildValuesStorageKey = (storageKey) => `${storageKey}${VALUES_SUFFIX}`;
+/**
+ * Guards a persisted value against schema drift.
+ *
+ * The storage key is hashed from the top-level field signature only, so a
+ * section field whose `type`/`mode` changed between releases keeps the same key
+ * and its stale value would otherwise be restored into an incompatible widget
+ * (e.g. a multi-select's array landing in a text input, which then renders
+ * `a,b` and is re-emitted as an array to a host expecting a string).
+ *
+ * Deliberately conservative: it only rejects shapes that no widget of that type
+ * can hold, and never polices string-vs-number.
+ */
+const isStoredValueCompatible = (field, value) => {
+    // `File` objects stringify to `{}`, so a persisted file value is always junk.
+    if (field.type === constants_1.FIELD_TYPES.FILE) {
+        return false;
+    }
+    // Custom fields own their value shape; the package cannot judge it. So does
+    // any field that renders its own chips: `appliedChips` means the value is a
+    // composite only that field interprets, whatever the field's type is.
+    if (field.type === constants_1.FIELD_TYPES.CUSTOM ||
+        typeof field.appliedChips === 'function') {
+        return true;
+    }
+    const isMultiSelect = field.type === constants_1.FIELD_TYPES.SELECT &&
+        (field.mode === constants_1.FIELD_MODES.MULTIPLE || field.mode === constants_1.FIELD_MODES.TAGS);
+    if (Array.isArray(value)) {
+        // Only multi-selects hold arrays. A bare scalar is still fine for them —
+        // `normaliseValuesBySchema` wraps it.
+        return isMultiSelect;
+    }
+    // Nothing else round-trips through a filter widget as a plain object.
+    if (value !== null && typeof value === 'object') {
+        return false;
+    }
+    if (field.type === constants_1.FIELD_TYPES.CHECKBOX) {
+        return typeof value === 'boolean';
+    }
+    return true;
+};
 const readStoredValues = (schema, storageKey) => {
     if (!isBrowser)
         return null;
@@ -88,9 +129,13 @@ const readStoredValues = (schema, storageKey) => {
         if (!parsed || typeof parsed !== 'object') {
             return null;
         }
-        const schemaKeys = new Set(schema.map(field => String(field.key)));
+        const fieldsByKey = new Map(schema.map(field => [String(field.key), field]));
         return Object.entries(parsed).reduce((acc, [key, value]) => {
-            if (schemaKeys.has(String(key))) {
+            const field = fieldsByKey.get(String(key));
+            // Unknown keys belong to a different schema version; values whose shape no
+            // longer fits their field are stale leftovers of one (see
+            // `isStoredValueCompatible`).
+            if (field && isStoredValueCompatible(field, value)) {
                 acc[key] =
                     value;
             }

package/dist/cjs/components/file-import-button.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+export type FileImportButtonProps = {
+    /**
+     * Accepted file extensions, forwarded to the hidden file input
+     * (e.g. `'.csv'`, `'.xls,.xlsx'`).
+     */
+    accept: string;
+    /**
+     * Text rendered inside the button (e.g. `'CSV'`).
+     */
+    label: string;
+    /**
+     * Tooltip / accessible name. Falls back to `label` when omitted, which is
+     * what the top-level toolbar relies on.
+     */
+    title?: string;
+    /**
+     * Called with the picked file. The component never uploads anything itself;
+     * the host application decides what to do with the file.
+     */
+    onImport: (file: File) => void;
+    /**
+     * Extra class names appended to the button.
+     */
+    className?: string;
+};
+/**
+ * Button that opens the native file picker and hands the selected file to
+ * `onImport`. Shared by the top-level filter toolbar and the section headers so
+ * both surfaces behave identically.
+ */
+export declare const FileImportButton: ({ accept, label, title, onImport, className }: FileImportButtonProps) => React.JSX.Element;
+//# sourceMappingURL=file-import-button.d.ts.map

package/dist/cjs/components/file-import-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-import-button.d.ts","sourceRoot":"","sources":["../../../src/components/file-import-button.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC/B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,+CAM9B,qBAAqB,sBA6CvB,CAAC"}