@dimaan/ui 0.0.24 → 0.0.26

package/dist/index.d.cts

@@ -1628,6 +1628,17 @@ interface ListPageSelectFilter extends ListPageFilterBase {
 interface ListPageTextFilter extends ListPageFilterBase {
     type: 'text';
     placeholder?: string;
+    /**
+     * Debounce window in milliseconds so a request fires only after the user
+     * pauses typing — instead of on every keystroke. The displayed value still
+     * updates instantly; only `onFilterChange` is delayed. **Live mode only**
+     * (ignored when `filterMode="manual"`, which already emits on Apply).
+     *
+     * Defaults to `400` — text filters are debounced out of the box, so you don't
+     * need to pass anything. Set a different number to tune it, or `0` to opt out
+     * and emit on every keystroke.
+     */
+    debounceMs?: number;
 }
 /** Date filter — rendered as a `DatePicker`. ISO `YYYY-MM-DD`; empty means "no filter". */
 interface ListPageDateFilter extends ListPageFilterBase {
@@ -1667,6 +1678,8 @@ interface ListPageEmptyState {
 interface ListPageLabels extends TableLabels {
     /** "Reset filters" button label. */
     reset?: string;
+    /** "Apply" button label — shown in `manual` filter mode (the default). */
+    apply?: string;
     /** "No results matching filters" title. */
     emptyTitle?: string;
     /** "No results matching filters" description. */
@@ -1703,8 +1716,19 @@ interface ListPageProps<T> {
     filters?: ListPageFilter[];
     /** Current filter selections, keyed by `filter.key` (date values are ISO `YYYY-MM-DD`). */
     filterValues?: Record<string, string>;
-    /** Fires when any filter control changes. */
+    /** Fires when a filter changes (`live`) or when Apply is pressed (`manual`). */
     onFilterChange?: (key: string, value: string) => void;
+    /**
+     * How filter edits reach `onFilterChange`. Defaults to `'manual'`.
+     * - `'manual'` (default) — edits are held locally; an **Apply** button (a real
+     *   form submit, so Enter also applies) flushes them in one go. Filtering only
+     *   fires on submit, so it never refetches on every keystroke/selection.
+     * - `'live'` — control changes fire `onFilterChange` as they happen. Text
+     *   filters are **debounced by default (400ms)** so they don't refetch on
+     *   every keystroke; tune it per filter with `debounceMs`, or set `0` to emit
+     *   immediately. Selects / dates emit instantly.
+     */
+    filterMode?: 'live' | 'manual';
     enableRowSelection?: boolean;
     bulkActions?: (selected: T[]) => ReactNode;
     /** Current page state from the consumer's data layer. */
@@ -1780,7 +1804,7 @@ interface ListPageProps<T> {
  * );
  * ```
  */
-declare function ListPage<T>({ title, description, bordered, actions, data, columns, getRowId, isLoading, loadingRowCount, filters, filterValues, onFilterChange, enableRowSelection, bulkActions, pagination, onPaginationChange, totalCount, pageSizeOptions, emptyState, noDataState, labels: labelsProp, className, }: ListPageProps<T>): react_jsx_runtime.JSX.Element;
+declare function ListPage<T>({ title, description, bordered, actions, data, columns, getRowId, isLoading, loadingRowCount, filters, filterValues, onFilterChange, filterMode, enableRowSelection, bulkActions, pagination, onPaginationChange, totalCount, pageSizeOptions, emptyState, noDataState, labels: labelsProp, className, }: ListPageProps<T>): react_jsx_runtime.JSX.Element;
 
 interface MultiSelectLabels {
     /** Search input placeholder. Direction-aware default: `"Search…"` / `"بحث…"`. */

package/dist/index.d.ts

@@ -1628,6 +1628,17 @@ interface ListPageSelectFilter extends ListPageFilterBase {
 interface ListPageTextFilter extends ListPageFilterBase {
     type: 'text';
     placeholder?: string;
+    /**
+     * Debounce window in milliseconds so a request fires only after the user
+     * pauses typing — instead of on every keystroke. The displayed value still
+     * updates instantly; only `onFilterChange` is delayed. **Live mode only**
+     * (ignored when `filterMode="manual"`, which already emits on Apply).
+     *
+     * Defaults to `400` — text filters are debounced out of the box, so you don't
+     * need to pass anything. Set a different number to tune it, or `0` to opt out
+     * and emit on every keystroke.
+     */
+    debounceMs?: number;
 }
 /** Date filter — rendered as a `DatePicker`. ISO `YYYY-MM-DD`; empty means "no filter". */
 interface ListPageDateFilter extends ListPageFilterBase {
@@ -1667,6 +1678,8 @@ interface ListPageEmptyState {
 interface ListPageLabels extends TableLabels {
     /** "Reset filters" button label. */
     reset?: string;
+    /** "Apply" button label — shown in `manual` filter mode (the default). */
+    apply?: string;
     /** "No results matching filters" title. */
     emptyTitle?: string;
     /** "No results matching filters" description. */
@@ -1703,8 +1716,19 @@ interface ListPageProps<T> {
     filters?: ListPageFilter[];
     /** Current filter selections, keyed by `filter.key` (date values are ISO `YYYY-MM-DD`). */
     filterValues?: Record<string, string>;
-    /** Fires when any filter control changes. */
+    /** Fires when a filter changes (`live`) or when Apply is pressed (`manual`). */
     onFilterChange?: (key: string, value: string) => void;
+    /**
+     * How filter edits reach `onFilterChange`. Defaults to `'manual'`.
+     * - `'manual'` (default) — edits are held locally; an **Apply** button (a real
+     *   form submit, so Enter also applies) flushes them in one go. Filtering only
+     *   fires on submit, so it never refetches on every keystroke/selection.
+     * - `'live'` — control changes fire `onFilterChange` as they happen. Text
+     *   filters are **debounced by default (400ms)** so they don't refetch on
+     *   every keystroke; tune it per filter with `debounceMs`, or set `0` to emit
+     *   immediately. Selects / dates emit instantly.
+     */
+    filterMode?: 'live' | 'manual';
     enableRowSelection?: boolean;
     bulkActions?: (selected: T[]) => ReactNode;
     /** Current page state from the consumer's data layer. */
@@ -1780,7 +1804,7 @@ interface ListPageProps<T> {
  * );
  * ```
  */
-declare function ListPage<T>({ title, description, bordered, actions, data, columns, getRowId, isLoading, loadingRowCount, filters, filterValues, onFilterChange, enableRowSelection, bulkActions, pagination, onPaginationChange, totalCount, pageSizeOptions, emptyState, noDataState, labels: labelsProp, className, }: ListPageProps<T>): react_jsx_runtime.JSX.Element;
+declare function ListPage<T>({ title, description, bordered, actions, data, columns, getRowId, isLoading, loadingRowCount, filters, filterValues, onFilterChange, filterMode, enableRowSelection, bulkActions, pagination, onPaginationChange, totalCount, pageSizeOptions, emptyState, noDataState, labels: labelsProp, className, }: ListPageProps<T>): react_jsx_runtime.JSX.Element;
 
 interface MultiSelectLabels {
     /** Search input placeholder. Direction-aware default: `"Search…"` / `"بحث…"`. */

package/dist/index.js

@@ -2920,37 +2920,130 @@ function hasActiveFilters(filters, values) {
   }
   return false;
 }
+function DebouncedFilterInput({
+  value,
+  onChange,
+  debounceMs,
+  ariaLabel,
+  placeholder,
+  wrapperClassName,
+  disabled
+}) {
+  const [local, setLocal] = useState(value);
+  const timerRef = useRef(null);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  useEffect(() => {
+    setLocal(value);
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, [value]);
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    []
+  );
+  const handleChange = (next) => {
+    setLocal(next);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    if (debounceMs <= 0) {
+      onChangeRef.current(next);
+      return;
+    }
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      onChangeRef.current(next);
+    }, debounceMs);
+  };
+  return /* @__PURE__ */ jsx(
+    Input,
+    {
+      type: "search",
+      "aria-label": ariaLabel,
+      placeholder,
+      value: local,
+      onChange: (e) => handleChange(e.target.value),
+      leadingIcon: /* @__PURE__ */ jsx(Search, { className: "size-4" }),
+      wrapperClassName,
+      disabled
+    }
+  );
+}
+var DEFAULT_TEXT_DEBOUNCE_MS = 400;
 function ListPageFilterBar({
   filters,
   values,
   onChange,
   disabled = false,
+  mode = "live",
   labels
 }) {
+  const manual = mode === "manual";
   const active = hasActiveFilters(filters, values);
+  const appliedKey = JSON.stringify(values ?? {});
+  const [draft, setDraft] = useState(values ?? {});
+  useEffect(() => {
+    if (manual) setDraft(values ?? {});
+  }, [appliedKey, manual]);
+  const effectiveValues = manual ? draft : values ?? {};
+  const handleChange = (key, value) => {
+    if (manual) {
+      setDraft((prev) => ({ ...prev, [key]: value }));
+    } else {
+      onChange?.(key, value);
+    }
+  };
+  const dirty = manual && (filters ?? []).some((filter) => {
+    const next = draft[filter.key] ?? filterDefaultValue(filter);
+    const current = values?.[filter.key] ?? filterDefaultValue(filter);
+    return next !== current;
+  });
+  const apply = (event) => {
+    event.preventDefault();
+    for (const filter of filters ?? []) {
+      const next = draft[filter.key] ?? filterDefaultValue(filter);
+      const current = values?.[filter.key] ?? filterDefaultValue(filter);
+      if (next !== current) onChange?.(filter.key, next);
+    }
+  };
   const reset = () => {
     for (const filter of filters ?? []) {
       onChange?.(filter.key, filterDefaultValue(filter));
     }
   };
+  const controls = /* @__PURE__ */ jsx("div", { className: "grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3", children: filters?.map((filter) => /* @__PURE__ */ jsx(
+    FilterControl,
+    {
+      filter,
+      value: effectiveValues[filter.key],
+      onChange: handleChange,
+      disabled,
+      mode
+    },
+    filter.key
+  )) });
+  const resetButton = active && !disabled ? /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "sm", onClick: reset, children: [
+    /* @__PURE__ */ jsx(RefreshCw, { className: "size-4" }),
+    labels.reset
+  ] }) : null;
+  if (manual) {
+    return /* @__PURE__ */ jsxs("form", { "data-slot": "list-page-filter-bar", className: "space-y-3", onSubmit: apply, children: [
+      controls,
+      /* @__PURE__ */ jsxs("div", { className: "flex justify-end gap-2", children: [
+        resetButton,
+        /* @__PURE__ */ jsx(Button, { type: "submit", size: "sm", disabled: disabled || !dirty, children: labels.apply ?? "Apply" })
+      ] })
+    ] });
+  }
   return /* @__PURE__ */ jsxs("div", { "data-slot": "list-page-filter-bar", className: "space-y-3", children: [
-    /* @__PURE__ */ jsx("div", { className: "grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3", children: filters?.map((filter) => /* @__PURE__ */ jsx(
-      FilterControl,
-      {
-        filter,
-        value: values?.[filter.key],
-        onChange,
-        disabled
-      },
-      filter.key
-    )) }),
-    active && !disabled ? /* @__PURE__ */ jsx("div", { className: "flex justify-end", children: /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "sm", onClick: reset, children: [
-      /* @__PURE__ */ jsx(RefreshCw, { className: "size-4" }),
-      labels.reset
-    ] }) }) : null
+    controls,
+    resetButton ? /* @__PURE__ */ jsx("div", { className: "flex justify-end", children: resetButton }) : null
   ] });
 }
-function FilterControl({ filter, value, onChange, disabled }) {
+function FilterControl({ filter, value, onChange, disabled, mode }) {
   const spanClass = FILTER_SPAN_CLASS[filter.width ?? "default"];
   const ariaLabel = typeof filter.label === "string" ? filter.label : filter.key;
   switch (filter.type) {
@@ -2968,14 +3061,13 @@ function FilterControl({ filter, value, onChange, disabled }) {
       );
     case "text":
       return /* @__PURE__ */ jsx(
-        Input,
+        DebouncedFilterInput,
         {
-          type: "search",
-          "aria-label": ariaLabel,
-          placeholder: filter.placeholder,
           value: value ?? "",
-          onChange: (e) => onChange?.(filter.key, e.target.value),
-          leadingIcon: /* @__PURE__ */ jsx(Search, { className: "size-4" }),
+          onChange: (v) => onChange?.(filter.key, v),
+          debounceMs: mode === "live" ? filter.debounceMs ?? DEFAULT_TEXT_DEBOUNCE_MS : 0,
+          ariaLabel,
+          placeholder: filter.placeholder,
           wrapperClassName: spanClass,
           disabled
         }
@@ -3007,13 +3099,22 @@ function FilterControl({ filter, value, onChange, disabled }) {
       );
   }
 }
-var DEFAULT_LABELS = {
+var EN_LABELS2 = {
   reset: "Reset filters",
+  apply: "Apply",
   emptyTitle: "No results",
   emptyDescription: "Try clearing the search or adjusting the filters.",
   noDataTitle: "No data yet",
   noDataDescription: "Nothing has been added here so far."
 };
+var AR_LABELS2 = {
+  reset: "\u0625\u0639\u0627\u062F\u0629 \u062A\u0639\u064A\u064A\u0646 \u0627\u0644\u0641\u0644\u0627\u062A\u0631",
+  apply: "\u062A\u0637\u0628\u064A\u0642",
+  emptyTitle: "\u0644\u0627 \u062A\u0648\u062C\u062F \u0646\u062A\u0627\u0626\u062C",
+  emptyDescription: "\u062C\u0631\u0651\u0628 \u0645\u0633\u062D \u0627\u0644\u0628\u062D\u062B \u0623\u0648 \u062A\u0639\u062F\u064A\u0644 \u0627\u0644\u0641\u0644\u0627\u062A\u0631.",
+  noDataTitle: "\u0644\u0627 \u062A\u0648\u062C\u062F \u0628\u064A\u0627\u0646\u0627\u062A \u0628\u0639\u062F",
+  noDataDescription: "\u0644\u0645 \u062A\u062A\u0645 \u0625\u0636\u0627\u0641\u0629 \u0623\u064A \u0634\u064A\u0621 \u0647\u0646\u0627 \u062D\u062A\u0649 \u0627\u0644\u0622\u0646."
+};
 function ListPage({
   title,
   description,
@@ -3027,6 +3128,7 @@ function ListPage({
   filters,
   filterValues,
   onFilterChange,
+  filterMode = "manual",
   enableRowSelection,
   bulkActions,
   pagination,
@@ -3038,7 +3140,8 @@ function ListPage({
   labels: labelsProp,
   className
 }) {
-  const labels = { ...DEFAULT_LABELS, ...labelsProp };
+  const dir = useDirection();
+  const labels = { ...dir === "rtl" ? AR_LABELS2 : EN_LABELS2, ...labelsProp };
   const showFilterBar = Boolean(filters?.length);
   const hasActiveQuery = useMemo(
     () => hasActiveFilters(filters, filterValues),
@@ -3058,8 +3161,8 @@ function ListPage({
         filters,
         values: filterValues,
         onChange: onFilterChange,
-        disabled: isLoading,
-        labels: { reset: labels.reset }
+        mode: filterMode,
+        labels: { reset: labels.reset, apply: labels.apply }
       }
     ) : null,
     tableMode === "loading" || tableMode === "rows" ? /* @__PURE__ */ jsx(