@akinon/akifilter 1.10.2-261002-0 → 1.11.0

package/README.md

@@ -45,6 +45,54 @@
 
 ---
 
+## Value Persistence (`persistValues`)
+
+By default, field values and active filter buttons are written to local storage
+and restored on the next mount. Set `persistValues={false}` when the filter has
+to start from values the host supplies (for example filters loaded from an API):
+
+```tsx
+<Akifilter
+  filterSchema={filterSchema}
+  storageNamespace="saved-filters"
+  persistValues={false}
+  defaultValues={savedFilters}
+  onValuesChange={setFilters}
+/>
+```
+
+- Values and button state are never read or written; the form starts from
+  schema defaults + `defaultValues`, and buttons start inactive.
+- Values stored before the prop was set are ignored, not deleted.
+- Visible-field (and per-section visibility) persistence is unaffected.
+- Leaving the prop out keeps today's behaviour (`true`).
+- `persistValues` and `defaultValues` are read on mount; changing them later
+  does not reset the form. When the values come from an API, render
+  `Akifilter` only after they have loaded. Turning `persistValues` off after
+  mount stops further writes but keeps what was already restored.
+
+---
+
+## Footer
+
+`footer` renders host content inside the filter card, below every field and
+section. Pass a node, or a function that receives `{ values }` (the
+`onValuesChange` shape, not debounced) to render conditionally. A falsy result
+(`null`, `undefined`, `false`, `''`, `0`) renders nothing:
+
+```tsx
+<Akifilter
+  filterSchema={filterSchema}
+  footer={({ values }) =>
+    Object.keys(values).length > 0 ? <Button>Save as rule</Button> : null
+  }
+/>
+```
+
+The footer sits outside the form, so a button there never submits it.
+
+---
+
 ## Section Fields
 
 Fields declared with `type: 'section'` render as collapsible panels below the

package/dist/cjs/akifilter.d.ts

@@ -4,6 +4,16 @@ import React from 'react';
 import { type AppliedFilter } from './components/applied-filters';
 import type { AkifilterActionsRef, AkifilterButton, AkifilterSchema } from './types';
 type AkifilterFieldValues = FieldValues;
+/**
+ * What a `footer` render function receives.
+ */
+export type AkifilterFooterContext<TFieldValues extends AkifilterFieldValues = AkifilterFieldValues> = {
+    /**
+     * Current filter values in the `onValuesChange` shape (normalised form values
+     * merged with active filter-button values), without the debounce.
+     */
+    values: Partial<TFieldValues>;
+};
 export type AkifilterProps<TFieldValues extends AkifilterFieldValues = AkifilterFieldValues> = {
     /**
      * Declarative description of the filter fields.
@@ -13,6 +23,18 @@ export type AkifilterProps<TFieldValues extends AkifilterFieldValues = Akifilter
      * Optional namespace for local storage persistence.
      */
     storageNamespace?: string;
+    /**
+     * When false, field values and filter-button state are never read from or
+     * written to localStorage; the form starts from schema defaults +
+     * `defaultValues`. Use it when the filter must start from values supplied by
+     * the host (e.g. filters loaded from an API). Values stored before the prop
+     * was set are ignored, not deleted. Visible-field persistence is unaffected.
+     * Read on mount, like `defaultValues`: render the filter once the values are
+     * ready instead of passing them in later, and changing this prop afterwards
+     * does not clear state that was already restored.
+     * @default true
+     */
+    persistValues?: boolean;
     /**
      * Default values supplied by the host application.
      */
@@ -101,6 +123,14 @@ export type AkifilterProps<TFieldValues extends AkifilterFieldValues = Akifilter
      * function on every render re-notifies with an unchanged list.
      */
     onSectionVisibleFieldsChange?: (sectionKey: string, keys: Array<Path<TFieldValues>>) => void;
+    /**
+     * Host content rendered inside the filter card, below every field and
+     * section (e.g. an action button). Pass a node, or a function that receives
+     * the current values to render conditionally. Rendered outside the form, so a
+     * button here never submits it. Nothing is rendered when it returns a
+     * falsy value (`null`, `undefined`, `false`, `''`, `0`).
+     */
+    footer?: React.ReactNode | ((context: AkifilterFooterContext<TFieldValues>) => React.ReactNode);
 };
 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;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;IAC9D;;;;;;;;;OASG;IACH,4BAA4B,CAAC,EAAE,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAC5B,IAAI,CAAC;CACX,CAAC;AAu9BF,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;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAChC,YAAY,SAAS,oBAAoB,GAAG,oBAAoB,IAC9D;IACF;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;CAC/B,CAAC;AAEF,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;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;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;IAC9D;;;;;;;;;OASG;IACH,4BAA4B,CAAC,EAAE,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAC5B,IAAI,CAAC;IACV;;;;;;OAMG;IACH,MAAM,CAAC,EACH,KAAK,CAAC,SAAS,GACf,CAAC,CAAC,OAAO,EAAE,sBAAsB,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;CAC1E,CAAC;AAsgCF,eAAO,MAAM,SAAS;KACpB,YAAY,SAAS,oBAAoB,uBAElC,cAAc,CAAC,YAAY,CAAC;;CAoBpC,CAAC"}

package/dist/cjs/akifilter.js

@@ -134,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, onSectionImportCsv, onSectionImportXls, onSectionVisibleFieldsChange }) => {
+const AkifilterContent = ({ filterSchema, storageNamespace, persistValues: shouldPersistValues = true, defaultValues, onValuesChange, onVisibleFieldsChange, onImportCsv, onImportXls, onClearAll, enableImportCsv, enableImportXls, filterActionsRef, externalAppliedFilters, onRemoveExternalFilter, filterButtons, onFilterButtonsChange, onSectionImportCsv, onSectionImportXls, onSectionVisibleFieldsChange, footer }) => {
     // 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]);
@@ -148,15 +148,22 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     // 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.
+    // With `persistValues={false}` storage is never read, so the form starts from
+    // `baseDefaultValues` alone.
     const [persistedDefaults, setPersistedDefaults] = react_1.default.useState(() => {
         var _a;
-        return (0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined);
+        return shouldPersistValues
+            ? (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;
+        if (!shouldPersistValues) {
+            return;
+        }
         setPersistedDefaults((0, schema_1.normaliseValuesBySchema)(flattenedSchema, (_a = (0, storage_1.readStoredValues)(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined));
-    }, [flattenedSchema, storageKey]);
+    }, [flattenedSchema, storageKey, shouldPersistValues]);
     const mergedDefaultValues = react_1.default.useMemo(() => (Object.assign(Object.assign({}, baseDefaultValues), persistedDefaults)), [baseDefaultValues, persistedDefaults]);
     const formMethods = (0, akiform_1.useForm)({
         defaultValues: mergedDefaultValues
@@ -165,12 +172,15 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     // --- Filter buttons (quick-filter toggles) ---------------------------------
     // A button is identified by its `value`, which must be unique across the
     // whole `filterButtons` array.
-    const [activeButtonValues, setActiveButtonValues] = react_1.default.useState(() => { var _a; return (_a = (0, storage_1.readStoredButtonValues)(storageKey)) !== null && _a !== void 0 ? _a : []; });
+    const [activeButtonValues, setActiveButtonValues] = react_1.default.useState(() => { var _a; return shouldPersistValues ? ((_a = (0, storage_1.readStoredButtonValues)(storageKey)) !== null && _a !== void 0 ? _a : []) : []; });
     // Re-read persisted button state when the storage key changes.
     react_1.default.useEffect(() => {
         var _a;
+        if (!shouldPersistValues) {
+            return;
+        }
         setActiveButtonValues((_a = (0, storage_1.readStoredButtonValues)(storageKey)) !== null && _a !== void 0 ? _a : []);
-    }, [storageKey]);
+    }, [storageKey, shouldPersistValues]);
     // Build the `{ key: value[] }` object contributed by the active buttons.
     // Buttons that share a key are merged into an array (legacy behaviour).
     const computeButtonValues = react_1.default.useCallback((values) => {
@@ -327,13 +337,16 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     const persistValues = react_1.default.useCallback((values, serialised) => {
         const nextSerialised = serialised !== null && serialised !== void 0 ? serialised : JSON.stringify(values);
         lastPersistedValuesRef.current = nextSerialised;
+        if (!shouldPersistValues) {
+            return nextSerialised;
+        }
         if (Object.keys(values).length === 0) {
             (0, storage_1.clearStoredValues)(storageKey);
             return nextSerialised;
         }
         (0, storage_1.writeStoredValues)(storageKey, values);
         return nextSerialised;
-    }, [storageKey]);
+    }, [storageKey, shouldPersistValues]);
     // Emit the normalised form values merged with the active filter-button
     // values. Buttons live outside the form state, so every emission point routes
     // through here to keep the two slices combined in the payload.
@@ -405,10 +418,12 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
             lastPersistedValuesRef.current = nextSerialised;
             currentSerialisedValuesRef.current = nextSerialised;
             // Update persistedDefaults to prevent stale mergedDefaultValues on re-render
-            setPersistedDefaults(currParsed);
+            if (shouldPersistValues) {
+                setPersistedDefaults(currParsed);
+            }
             emitValues(currParsed);
         }
-    }, [serialisedValues, emitValues, persistValues]);
+    }, [serialisedValues, emitValues, persistValues, shouldPersistValues]);
     const handleClearAll = react_1.default.useCallback(() => {
         const clearedDefaults = Object.assign({}, schemaDefaults);
         flattenedSchema.forEach(field => {
@@ -521,7 +536,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         // before the state-update effect runs.
         buttonValuesRef.current = computeButtonValues(nextValues);
         setActiveButtonValues(nextValues);
-        (0, storage_1.writeStoredButtonValues)(storageKey, nextValues);
+        if (shouldPersistValues) {
+            (0, storage_1.writeStoredButtonValues)(storageKey, nextValues);
+        }
         const formValuesNow = (0, values_1.normaliseOutputValues)(flattenedSchema, formMethods.getValues());
         hasEmittedValuesRef.current = true;
         emitValues(formValuesNow);
@@ -530,6 +547,7 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         activeButtonValues,
         computeButtonValues,
         storageKey,
+        shouldPersistValues,
         flattenedSchema,
         formMethods,
         emitValues,
@@ -589,7 +607,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         if (activeButtonValues.length > 0) {
             buttonValuesRef.current = {};
             setActiveButtonValues([]);
-            (0, storage_1.clearStoredButtonValues)(storageKey);
+            if (shouldPersistValues) {
+                (0, storage_1.clearStoredButtonValues)(storageKey);
+            }
             onFilterButtonsChange === null || onFilterButtonsChange === void 0 ? void 0 : onFilterButtonsChange([]);
         }
         handleClearAll();
@@ -600,6 +620,7 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         onRemoveExternalFilter,
         activeButtonValues,
         storageKey,
+        shouldPersistValues,
         onFilterButtonsChange
     ]);
     const renderFieldComponent = (field) => {
@@ -640,6 +661,11 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
                 return (react_1.default.createElement(ui_typography_1.Text, { type: "secondary", className: "akinon-filter__unsupported" }, i18n_1.i18n.t('form.unsupportedField', { field: String(field.type) })));
         }
     };
+    const footerContent = typeof footer === 'function'
+        ? footer({
+            values: Object.assign(Object.assign({}, normalisedValues), computeButtonValues(activeButtonValues))
+        })
+        : footer;
     const renderFormField = (field) => {
         return (react_1.default.createElement(FilterFormItem, { key: String(field.key), control: formMethods.control, name: field.key, tooltip: field.tooltip, help: field.help, labelDescription: field.labelDescription, required: Boolean(field.validation), className: "mb-0", valuePropName: field.type === constants_1.FIELD_TYPES.CHECKBOX ? 'checked' : undefined }, renderFieldComponent(field)));
     };
@@ -658,7 +684,8 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
                         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, onImportCsv: onSectionImportCsv &&
                             (file => onSectionImportCsv(String(section.key), file)), onImportXls: onSectionImportXls &&
-                            (file => onSectionImportXls(String(section.key), file)), onVisibleFieldsChange: onSectionVisibleFieldsChange }))))))),
+                            (file => onSectionImportXls(String(section.key), file)), onVisibleFieldsChange: onSectionVisibleFieldsChange })))))),
+                footerContent ? (react_1.default.createElement("div", { className: "akinon-filter__footer", "data-testid": "akifilter-footer" }, footerContent)) : null),
             react_1.default.createElement(visibility_modal_1.VisibilityModal, Object.assign({}, modalProps)))));
 };
 const AkifilterEmptyState = () => {

package/dist/cjs/styles.css

@@ -184,6 +184,10 @@
   color: var(--color-gray-500) !important;
 }
 
+.akinon-filter__footer {
+  margin-top: 1rem;
+}
+
 @media (max-width: 1024px) {
   .akinon-filter__form-grid {
     grid-template-columns: repeat(2, minmax(0, 1fr));

package/dist/esm/akifilter.d.ts

@@ -4,6 +4,16 @@ import React from 'react';
 import { type AppliedFilter } from './components/applied-filters';
 import type { AkifilterActionsRef, AkifilterButton, AkifilterSchema } from './types';
 type AkifilterFieldValues = FieldValues;
+/**
+ * What a `footer` render function receives.
+ */
+export type AkifilterFooterContext<TFieldValues extends AkifilterFieldValues = AkifilterFieldValues> = {
+    /**
+     * Current filter values in the `onValuesChange` shape (normalised form values
+     * merged with active filter-button values), without the debounce.
+     */
+    values: Partial<TFieldValues>;
+};
 export type AkifilterProps<TFieldValues extends AkifilterFieldValues = AkifilterFieldValues> = {
     /**
      * Declarative description of the filter fields.
@@ -13,6 +23,18 @@ export type AkifilterProps<TFieldValues extends AkifilterFieldValues = Akifilter
      * Optional namespace for local storage persistence.
      */
     storageNamespace?: string;
+    /**
+     * When false, field values and filter-button state are never read from or
+     * written to localStorage; the form starts from schema defaults +
+     * `defaultValues`. Use it when the filter must start from values supplied by
+     * the host (e.g. filters loaded from an API). Values stored before the prop
+     * was set are ignored, not deleted. Visible-field persistence is unaffected.
+     * Read on mount, like `defaultValues`: render the filter once the values are
+     * ready instead of passing them in later, and changing this prop afterwards
+     * does not clear state that was already restored.
+     * @default true
+     */
+    persistValues?: boolean;
     /**
      * Default values supplied by the host application.
      */
@@ -101,6 +123,14 @@ export type AkifilterProps<TFieldValues extends AkifilterFieldValues = Akifilter
      * function on every render re-notifies with an unchanged list.
      */
     onSectionVisibleFieldsChange?: (sectionKey: string, keys: Array<Path<TFieldValues>>) => void;
+    /**
+     * Host content rendered inside the filter card, below every field and
+     * section (e.g. an action button). Pass a node, or a function that receives
+     * the current values to render conditionally. Rendered outside the form, so a
+     * button here never submits it. Nothing is rendered when it returns a
+     * falsy value (`null`, `undefined`, `false`, `''`, `0`).
+     */
+    footer?: React.ReactNode | ((context: AkifilterFooterContext<TFieldValues>) => React.ReactNode);
 };
 export declare const Akifilter: {
     <TFieldValues extends AkifilterFieldValues = FieldValues>(props: AkifilterProps<TFieldValues>): React.JSX.Element;

package/dist/esm/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;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;IAC9D;;;;;;;;;OASG;IACH,4BAA4B,CAAC,EAAE,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAC5B,IAAI,CAAC;CACX,CAAC;AAu9BF,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;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAChC,YAAY,SAAS,oBAAoB,GAAG,oBAAoB,IAC9D;IACF;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;CAC/B,CAAC;AAEF,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;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;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;IAC9D;;;;;;;;;OASG;IACH,4BAA4B,CAAC,EAAE,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAC5B,IAAI,CAAC;IACV;;;;;;OAMG;IACH,MAAM,CAAC,EACH,KAAK,CAAC,SAAS,GACf,CAAC,CAAC,OAAO,EAAE,sBAAsB,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;CAC1E,CAAC;AAsgCF,eAAO,MAAM,SAAS;KACpB,YAAY,SAAS,oBAAoB,uBAElC,cAAc,CAAC,YAAY,CAAC;;CAoBpC,CAAC"}

package/dist/esm/akifilter.js

@@ -131,7 +131,7 @@ const resolveClearedFieldValue = (field, defaultValue) => {
             return undefined;
     }
 };
-const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onValuesChange, onVisibleFieldsChange, onImportCsv, onImportXls, onClearAll, enableImportCsv, enableImportXls, filterActionsRef, externalAppliedFilters, onRemoveExternalFilter, filterButtons, onFilterButtonsChange, onSectionImportCsv, onSectionImportXls, onSectionVisibleFieldsChange }) => {
+const AkifilterContent = ({ filterSchema, storageNamespace, persistValues: shouldPersistValues = true, defaultValues, onValuesChange, onVisibleFieldsChange, onImportCsv, onImportXls, onClearAll, enableImportCsv, enableImportXls, filterActionsRef, externalAppliedFilters, onRemoveExternalFilter, filterButtons, onFilterButtonsChange, onSectionImportCsv, onSectionImportXls, onSectionVisibleFieldsChange, footer }) => {
     // Separate regular fields from section fields
     const { regularFields, sectionFields } = React.useMemo(() => partitionSchema(filterSchema), [filterSchema]);
     const excludeSectionKeys = React.useMemo(() => deriveExcludeSectionKeys(sectionFields), [sectionFields]);
@@ -145,15 +145,22 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     // 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.
+    // With `persistValues={false}` storage is never read, so the form starts from
+    // `baseDefaultValues` alone.
     const [persistedDefaults, setPersistedDefaults] = React.useState(() => {
         var _a;
-        return normaliseValuesBySchema(flattenedSchema, (_a = readStoredValues(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined);
+        return shouldPersistValues
+            ? normaliseValuesBySchema(flattenedSchema, (_a = readStoredValues(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined)
+            : {};
     });
     // Re-read from localStorage when storageKey changes
     React.useEffect(() => {
         var _a;
+        if (!shouldPersistValues) {
+            return;
+        }
         setPersistedDefaults(normaliseValuesBySchema(flattenedSchema, (_a = readStoredValues(flattenedSchema, storageKey)) !== null && _a !== void 0 ? _a : undefined));
-    }, [flattenedSchema, storageKey]);
+    }, [flattenedSchema, storageKey, shouldPersistValues]);
     const mergedDefaultValues = React.useMemo(() => (Object.assign(Object.assign({}, baseDefaultValues), persistedDefaults)), [baseDefaultValues, persistedDefaults]);
     const formMethods = useForm({
         defaultValues: mergedDefaultValues
@@ -162,12 +169,15 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     // --- Filter buttons (quick-filter toggles) ---------------------------------
     // A button is identified by its `value`, which must be unique across the
     // whole `filterButtons` array.
-    const [activeButtonValues, setActiveButtonValues] = React.useState(() => { var _a; return (_a = readStoredButtonValues(storageKey)) !== null && _a !== void 0 ? _a : []; });
+    const [activeButtonValues, setActiveButtonValues] = React.useState(() => { var _a; return shouldPersistValues ? ((_a = readStoredButtonValues(storageKey)) !== null && _a !== void 0 ? _a : []) : []; });
     // Re-read persisted button state when the storage key changes.
     React.useEffect(() => {
         var _a;
+        if (!shouldPersistValues) {
+            return;
+        }
         setActiveButtonValues((_a = readStoredButtonValues(storageKey)) !== null && _a !== void 0 ? _a : []);
-    }, [storageKey]);
+    }, [storageKey, shouldPersistValues]);
     // Build the `{ key: value[] }` object contributed by the active buttons.
     // Buttons that share a key are merged into an array (legacy behaviour).
     const computeButtonValues = React.useCallback((values) => {
@@ -324,13 +334,16 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
     const persistValues = React.useCallback((values, serialised) => {
         const nextSerialised = serialised !== null && serialised !== void 0 ? serialised : JSON.stringify(values);
         lastPersistedValuesRef.current = nextSerialised;
+        if (!shouldPersistValues) {
+            return nextSerialised;
+        }
         if (Object.keys(values).length === 0) {
             clearStoredValues(storageKey);
             return nextSerialised;
         }
         writeStoredValues(storageKey, values);
         return nextSerialised;
-    }, [storageKey]);
+    }, [storageKey, shouldPersistValues]);
     // Emit the normalised form values merged with the active filter-button
     // values. Buttons live outside the form state, so every emission point routes
     // through here to keep the two slices combined in the payload.
@@ -402,10 +415,12 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
             lastPersistedValuesRef.current = nextSerialised;
             currentSerialisedValuesRef.current = nextSerialised;
             // Update persistedDefaults to prevent stale mergedDefaultValues on re-render
-            setPersistedDefaults(currParsed);
+            if (shouldPersistValues) {
+                setPersistedDefaults(currParsed);
+            }
             emitValues(currParsed);
         }
-    }, [serialisedValues, emitValues, persistValues]);
+    }, [serialisedValues, emitValues, persistValues, shouldPersistValues]);
     const handleClearAll = React.useCallback(() => {
         const clearedDefaults = Object.assign({}, schemaDefaults);
         flattenedSchema.forEach(field => {
@@ -518,7 +533,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         // before the state-update effect runs.
         buttonValuesRef.current = computeButtonValues(nextValues);
         setActiveButtonValues(nextValues);
-        writeStoredButtonValues(storageKey, nextValues);
+        if (shouldPersistValues) {
+            writeStoredButtonValues(storageKey, nextValues);
+        }
         const formValuesNow = normaliseOutputValues(flattenedSchema, formMethods.getValues());
         hasEmittedValuesRef.current = true;
         emitValues(formValuesNow);
@@ -527,6 +544,7 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         activeButtonValues,
         computeButtonValues,
         storageKey,
+        shouldPersistValues,
         flattenedSchema,
         formMethods,
         emitValues,
@@ -586,7 +604,9 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         if (activeButtonValues.length > 0) {
             buttonValuesRef.current = {};
             setActiveButtonValues([]);
-            clearStoredButtonValues(storageKey);
+            if (shouldPersistValues) {
+                clearStoredButtonValues(storageKey);
+            }
             onFilterButtonsChange === null || onFilterButtonsChange === void 0 ? void 0 : onFilterButtonsChange([]);
         }
         handleClearAll();
@@ -597,6 +617,7 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
         onRemoveExternalFilter,
         activeButtonValues,
         storageKey,
+        shouldPersistValues,
         onFilterButtonsChange
     ]);
     const renderFieldComponent = (field) => {
@@ -637,6 +658,11 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
                 return (React.createElement(Text, { type: "secondary", className: "akinon-filter__unsupported" }, i18n.t('form.unsupportedField', { field: String(field.type) })));
         }
     };
+    const footerContent = typeof footer === 'function'
+        ? footer({
+            values: Object.assign(Object.assign({}, normalisedValues), computeButtonValues(activeButtonValues))
+        })
+        : footer;
     const renderFormField = (field) => {
         return (React.createElement(FilterFormItem, { key: String(field.key), control: formMethods.control, name: field.key, tooltip: field.tooltip, help: field.help, labelDescription: field.labelDescription, required: Boolean(field.validation), className: "mb-0", valuePropName: field.type === FIELD_TYPES.CHECKBOX ? 'checked' : undefined }, renderFieldComponent(field)));
     };
@@ -655,7 +681,8 @@ const AkifilterContent = ({ filterSchema, storageNamespace, defaultValues, onVal
                         visibleFields.length === 0 && regularFields.length > 0 ? (React.createElement("div", { className: "akinon-filter__empty" }, i18n.t('form.noVisibleFields'))) : null),
                     sectionFields.length > 0 && (React.createElement("div", { className: "akinon-filter__section-fields" }, sectionFields.map(section => (React.createElement(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)), onVisibleFieldsChange: onSectionVisibleFieldsChange }))))))),
+                            (file => onSectionImportXls(String(section.key), file)), onVisibleFieldsChange: onSectionVisibleFieldsChange })))))),
+                footerContent ? (React.createElement("div", { className: "akinon-filter__footer", "data-testid": "akifilter-footer" }, footerContent)) : null),
             React.createElement(VisibilityModal, Object.assign({}, modalProps)))));
 };
 const AkifilterEmptyState = () => {

package/dist/esm/styles.css

@@ -184,6 +184,10 @@
   color: var(--color-gray-500) !important;
 }
 
+.akinon-filter__footer {
+  margin-top: 1rem;
+}
+
 @media (max-width: 1024px) {
   .akinon-filter__form-grid {
     grid-template-columns: repeat(2, minmax(0, 1fr));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/akifilter",
-  "version": "1.10.2-261002-0",
+  "version": "1.11.0",
   "private": false,
   "description": "Akifilter is a filtering library for Akinon frontend applications.",
   "type": "module",
@@ -16,20 +16,20 @@
     "@akinon/akiform": "1.1.9",
     "@akinon/akidate": "1.2.7",
     "@akinon/akilocale": "1.2.8",
-    "@akinon/icons": "1.6.0-261002-0",
-    "@akinon/ui-button": "1.5.8-261002-0",
+    "@akinon/icons": "1.6.0",
+    "@akinon/ui-button": "1.5.8",
     "@akinon/ui-card": "1.2.12",
     "@akinon/ui-checkbox": "1.4.12",
     "@akinon/ui-collapse": "1.4.8",
-    "@akinon/ui-date-picker": "1.5.8-261002-0",
+    "@akinon/ui-date-picker": "1.5.8",
     "@akinon/ui-input": "1.2.12",
     "@akinon/ui-input-number": "1.4.12",
     "@akinon/ui-modal": "1.2.13",
-    "@akinon/ui-pagination": "1.4.19-261002-0",
-    "@akinon/ui-select": "1.4.19-261002-0",
+    "@akinon/ui-pagination": "1.4.19",
+    "@akinon/ui-select": "1.4.19",
     "@akinon/ui-space": "1.4.12",
     "@akinon/ui-typography": "1.2.7",
-    "@akinon/ui-upload": "1.6.5-261002-0"
+    "@akinon/ui-upload": "1.6.5"
   },
   "devDependencies": {
     "@types/lodash-es": "^4.17.12",
@@ -37,7 +37,7 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.5",
     "typescript": "*",
-    "@akinon/akiform-builder": "1.8.4-261002-0",
+    "@akinon/akiform-builder": "1.8.4",
     "@akinon/typescript-config": "1.1.8",
     "@akinon/utils": "1.2.13",
     "@akinon/ui-theme": "1.3.3",