@k3-tech/react-kit 0.0.61 → 0.0.62

package/src/kit/components/data-table-headers/FilterFieldRenderer.tsx

@@ -0,0 +1,194 @@
+import type { ReactNode } from 'react';
+import type { Control, FieldValues } from 'react-hook-form';
+import { cn } from '@/shadcn/lib/utils';
+import { Label } from '@/shadcn/ui/label';
+import {
+  AutocompleteField,
+  CheckboxField,
+  DateField,
+  DatePickerField,
+  DateRangePickerField,
+  DateTimePickerField,
+  DateTimeRangePickerField,
+  FileField,
+  MonthPickerField,
+  MonthRangePickerField,
+  RadioField,
+  SelectField,
+  SwitchField,
+  TimePickerField,
+  TimeRangePickerField,
+} from '@/kit/builder/form/components/fields';
+import type { FieldRenderProps } from '@/kit/builder/form/components/fields/types';
+import { DebouncedFilterField } from './DebouncedFilterField';
+import type { FilterFieldConfig } from './types';
+
+/** Free-typing types that get an internal debounce. */
+const DEBOUNCED_TYPES = new Set([
+  'text',
+  'email',
+  'password',
+  'number',
+  'textarea',
+]);
+
+/** Types not supported inside a filter header (require RHF or are non-inputs). */
+const UNSUPPORTED_TYPES = new Set([
+  'object',
+  'array',
+  'custom_field',
+  'hidden',
+]);
+
+const warned = new Set<string>();
+const warnUnsupported = (type: string) => {
+  if (process.env.NODE_ENV !== 'production' && !warned.has(type)) {
+    warned.add(type);
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[DataTableHeader] field type '${type}' is not supported in filter headers and was skipped.`,
+    );
+  }
+};
+
+export interface FilterFieldRendererProps {
+  field: FilterFieldConfig;
+  /** Current value for this field (from the external values map). */
+  value: unknown;
+  /** Push a new value for this field upstream. */
+  onChange: (value: unknown) => void;
+  debounceMs: number;
+  /** Throwaway control shim so date fields' `useWatch` does not throw. */
+  control: Control<FieldValues>;
+}
+
+/**
+ * Renders a single filter field by mirroring FormBuilderField's type → component
+ * mapping, but WITHOUT react-hook-form's `useController`. Values flow in via
+ * props and out via `onChange`; the header owns no field state.
+ */
+export function FilterFieldRenderer({
+  field,
+  value,
+  onChange,
+  debounceMs,
+  control,
+}: FilterFieldRendererProps) {
+  if (UNSUPPORTED_TYPES.has(field.type)) {
+    warnUnsupported(field.type);
+    return null;
+  }
+
+  const inputClassName = cn('bg-background', field.className);
+
+  let input: ReactNode;
+
+  if (DEBOUNCED_TYPES.has(field.type)) {
+    input = (
+      <DebouncedFilterField
+        field={field}
+        value={value}
+        onChange={onChange}
+        debounceMs={debounceMs}
+        control={control}
+        className={inputClassName}
+      />
+    );
+  } else {
+    const common: FieldRenderProps = {
+      field,
+      control,
+      fieldPath: field.name,
+      value,
+      onChange,
+      className: inputClassName,
+    };
+
+    switch (field.type) {
+      case 'select':
+        input = <SelectField {...common} />;
+        break;
+      case 'autocomplete':
+        input = <AutocompleteField {...common} />;
+        break;
+      case 'checkbox':
+        input = <CheckboxField {...common} />;
+        break;
+      case 'switch':
+        input = <SwitchField {...common} />;
+        break;
+      case 'radio':
+        input = <RadioField {...common} />;
+        break;
+      case 'date':
+        input = <DateField {...common} />;
+        break;
+      case 'date_picker':
+        input = <DatePickerField {...common} />;
+        break;
+      case 'date_range':
+        input = <DateRangePickerField {...common} />;
+        break;
+      case 'date_time':
+        input = <DateTimePickerField {...common} />;
+        break;
+      case 'date_time_range':
+        input = <DateTimeRangePickerField {...common} />;
+        break;
+      case 'month':
+        input = <MonthPickerField {...common} />;
+        break;
+      case 'month_range':
+        input = <MonthRangePickerField {...common} />;
+        break;
+      case 'time':
+        input = <TimePickerField {...common} />;
+        break;
+      case 'time_range':
+        input = <TimeRangePickerField {...common} />;
+        break;
+      case 'file':
+        input = <FileField {...common} />;
+        break;
+      default:
+        // Unknown but not explicitly unsupported: fall back to plain text.
+        input = (
+          <DebouncedFilterField
+            field={field}
+            value={value}
+            onChange={onChange}
+            debounceMs={debounceMs}
+            control={control}
+            className={inputClassName}
+          />
+        );
+    }
+  }
+
+  // Show a label only when an explicit, non-blank label is provided and not
+  // hidden — filters commonly rely on placeholders alone.
+  const labelText =
+    typeof field.label === 'string' ? field.label.trim() : field.label;
+  const showLabel =
+    field.labelPlacement !== 'hidden' &&
+    labelText != null &&
+    labelText !== '' &&
+    field.type !== 'checkbox' &&
+    field.type !== 'switch';
+
+  return (
+    <div
+      className={cn(
+        'w-full space-y-1 sm:w-auto sm:min-w-[180px]',
+        field.wrapperClassName,
+      )}
+    >
+      {showLabel && (
+        <Label htmlFor={field.name} className="text-xs text-muted-foreground">
+          {field.label}
+        </Label>
+      )}
+      {input}
+    </div>
+  );
+}

package/src/kit/components/data-table-headers/index.ts

@@ -0,0 +1,6 @@
+export * from './DataTableHeader';
+export * from './FilterFieldRenderer';
+export * from './DebouncedFilterField';
+export * from './useDataTableHeaderUrl';
+export * from './urlSerialization';
+export * from './types';

package/src/kit/components/data-table-headers/types.ts

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react';
+import type { DataTableAction } from '@/kit/builder/data-table/types';
+import type { FormBuilderFieldConfig } from '@/kit/builder/form/types';
+
+/**
+ * A single filter field definition. Reuses {@link FormBuilderFieldConfig} so
+ * field definitions for the header work exactly like FormBuilder fields, but
+ * the header renders them WITHOUT react-hook-form and holds no value state.
+ *
+ * Supported `type`s: text, email, password, number (plain), textarea, select,
+ * autocomplete, checkbox, switch, radio, month, month_range, time, time_range,
+ * and the date family (date, date_picker, date_range, date_time,
+ * date_time_range).
+ *
+ * Unsupported in a filter header: object, array, custom_field, hidden — these
+ * are skipped with a dev warning.
+ */
+export type FilterFieldConfig = FormBuilderFieldConfig;
+
+/**
+ * Action shown on the right side of the header. Reuses the DataTable action
+ * shape and rendering, mirroring DataTable's `renderActionButton`.
+ */
+export type DataTableHeaderAction = DataTableAction;
+
+/**
+ * Adapter that lets the URL sync work against an arbitrary URL source instead
+ * of the browser History API. Provide this in environments with their own
+ * router (e.g. TanStack Router) so the header does not fight the router for
+ * control of the URL.
+ */
+export interface UrlSyncAdapter {
+  /** Read the current query params as a flat map (repeated keys -> string[]). */
+  read: () => Record<string, string | string[]>;
+  /** Write the given query params back to the URL. */
+  write: (params: Record<string, string | string[]>) => void;
+}
+
+/**
+ * URL sync option.
+ * - `false` / `undefined`: disabled.
+ * - `true`: use the native History API (URLSearchParams + replaceState).
+ * - `UrlSyncAdapter`: use the provided adapter (recommended when a router owns
+ *   the URL).
+ */
+export type UrlSyncOption = boolean | UrlSyncAdapter;
+
+export interface DataTableHeaderProps {
+  /** Filter field definitions (reuses FormBuilder field config). */
+  fields: FilterFieldConfig[];
+
+  /**
+   * Externally-owned filter values, keyed by `field.name`. This is the single
+   * source of truth — the header never holds its own copy.
+   */
+  values: Record<string, unknown>;
+
+  /** Called whenever a single field changes (debounced for free-typing inputs). */
+  onChange: (name: string, value: unknown) => void;
+
+  /**
+   * Bulk setter used to hydrate values from the URL on mount. If omitted, the
+   * header falls back to issuing one `onChange` per hydrated field.
+   */
+  onChangeAll?: (next: Record<string, unknown>) => void;
+
+  /** Debounce (ms) applied to free-typing inputs. Default 400. */
+  debounceMs?: number;
+
+  /** Enable URL sync. See {@link UrlSyncOption}. Default disabled. */
+  url?: UrlSyncOption;
+
+  /** Right-side action buttons. */
+  actions?: DataTableHeaderAction[];
+
+  /**
+   * Refresh handler. When provided, a default refresh button (mirroring the
+   * DataTable's standard refresh button) is rendered before the actions. Omit
+   * to hide it.
+   */
+  onRefresh?: () => void | Promise<void>;
+
+  /** Optional content rendered between filters and actions. */
+  children?: ReactNode;
+
+  className?: string;
+  filtersClassName?: string;
+  actionsClassName?: string;
+}

package/src/kit/components/data-table-headers/urlSerialization.ts

@@ -0,0 +1,173 @@
+import type { FilterFieldConfig } from './types';
+
+/**
+ * Type-aware (de)serialization between filter values and URL query params.
+ *
+ * Design rules:
+ * - `null` / `''` / `undefined` values are OMITTED (a missing key means "no
+ *   filter"); we never serialize empty values.
+ * - Numbers round-trip via String/Number (NaN dropped).
+ * - Booleans (checkbox/switch) round-trip via "true"/"false".
+ * - Multiple values (multi-select / multi autocomplete / arrays) use repeated
+ *   keys, read back via `getAll`.
+ * - Date-family values serialize to ISO; ranges use two suffixed keys
+ *   `<name>_from` / `<name>_to`.
+ * - select/radio values are recovered against `field.options` so the original
+ *   typed value (string | number | boolean | null) is preserved.
+ * - Unsupported field types (object/array/custom_field/hidden) are skipped.
+ */
+
+const DATE_TYPES = new Set([
+  'date',
+  'date_picker',
+  'month',
+  'time',
+  'date_time',
+]);
+const RANGE_TYPES = new Set([
+  'date_range',
+  'date_time_range',
+  'month_range',
+  'time_range',
+]);
+const SKIP_TYPES = new Set(['object', 'array', 'custom_field', 'hidden']);
+
+const isEmpty = (v: unknown) => v === null || v === undefined || v === '';
+
+const toIso = (v: unknown): string | null => {
+  const d = v instanceof Date ? v : new Date(v as string);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+};
+
+const fromIso = (raw: string): Date | null => {
+  const d = new Date(raw);
+  return Number.isNaN(d.getTime()) ? null : d;
+};
+
+/** Recover a select/radio value's original type by matching against options. */
+const recoverOptionValue = (field: FilterFieldConfig, raw: string): unknown => {
+  const match = field.options?.find((o) => String(o.value) === raw);
+  return match ? match.value : raw;
+};
+
+/** Numeric-looking strings become numbers (autocomplete IDs); else stay strings. */
+const coerceScalar = (raw: string): string | number =>
+  raw !== '' && !Number.isNaN(Number(raw)) ? Number(raw) : raw;
+
+/**
+ * Serialize a full values object into a query-param map. Repeated keys are
+ * represented as string[]; everything else as string.
+ */
+export function serializeAll(
+  fields: FilterFieldConfig[],
+  values: Record<string, unknown>,
+): Record<string, string | string[]> {
+  const params: Record<string, string | string[]> = {};
+
+  for (const field of fields) {
+    if (SKIP_TYPES.has(field.type)) continue;
+    const name = field.name;
+    const value = values[name];
+
+    if (RANGE_TYPES.has(field.type)) {
+      const range = value as { from?: unknown; to?: unknown } | null | undefined;
+      const from = range && !isEmpty(range.from) ? toIso(range.from) : null;
+      const to = range && !isEmpty(range.to) ? toIso(range.to) : null;
+      if (from) params[`${name}_from`] = from;
+      if (to) params[`${name}_to`] = to;
+      continue;
+    }
+
+    if (isEmpty(value)) continue;
+
+    if (Array.isArray(value)) {
+      const arr = value
+        .filter((v) => !isEmpty(v))
+        .map((v) => String(v));
+      if (arr.length) params[name] = arr;
+      continue;
+    }
+
+    if (DATE_TYPES.has(field.type)) {
+      const iso = toIso(value);
+      if (iso) params[name] = iso;
+      continue;
+    }
+
+    params[name] = String(value);
+  }
+
+  return params;
+}
+
+/**
+ * Deserialize a query-param map back into typed filter values, guided by field
+ * definitions. Only keys present in the params are included in the result.
+ */
+export function deserializeAll(
+  fields: FilterFieldConfig[],
+  params: Record<string, string | string[]>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const first = (v: string | string[] | undefined) =>
+    Array.isArray(v) ? v[0] : v;
+
+  for (const field of fields) {
+    if (SKIP_TYPES.has(field.type)) continue;
+    const name = field.name;
+
+    if (RANGE_TYPES.has(field.type)) {
+      const from = first(params[`${name}_from`]);
+      const to = first(params[`${name}_to`]);
+      const range: { from?: Date; to?: Date } = {};
+      if (from) {
+        const d = fromIso(from);
+        if (d) range.from = d;
+      }
+      if (to) {
+        const d = fromIso(to);
+        if (d) range.to = d;
+      }
+      if (range.from || range.to) result[name] = range;
+      continue;
+    }
+
+    const raw = params[name];
+    if (raw === undefined) continue;
+
+    if (field.multiple || Array.isArray(raw)) {
+      const arr = (Array.isArray(raw) ? raw : [raw]).map(coerceScalar);
+      result[name] = arr;
+      continue;
+    }
+
+    const value = raw as string;
+
+    switch (field.type) {
+      case 'number':
+        if (value !== '' && !Number.isNaN(Number(value)))
+          result[name] = Number(value);
+        break;
+      case 'checkbox':
+      case 'switch':
+        result[name] = value === 'true';
+        break;
+      case 'select':
+      case 'radio':
+        result[name] = recoverOptionValue(field, value);
+        break;
+      case 'autocomplete':
+        result[name] = coerceScalar(value);
+        break;
+      default:
+        if (DATE_TYPES.has(field.type)) {
+          const d = fromIso(value);
+          if (d) result[name] = d;
+        } else {
+          result[name] = value;
+        }
+    }
+  }
+
+  return result;
+}

package/src/kit/components/data-table-headers/useDataTableHeaderUrl.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from 'react';
+import { useForm } from 'react-hook-form';
+import type { Control, FieldValues } from 'react-hook-form';
+import type { FilterFieldConfig, UrlSyncAdapter } from './types';
+import { deserializeAll, serializeAll } from './urlSerialization';
+
+/**
+ * Default URL adapter backed by the browser History API. Suitable for
+ * router-less contexts (plain apps, Storybook). In an app whose router owns the
+ * URL (e.g. TanStack Router), pass a custom {@link UrlSyncAdapter} instead so
+ * the header does not fight the router.
+ */
+export const nativeAdapter: UrlSyncAdapter = {
+  read: () => {
+    if (typeof window === 'undefined') return {};
+    const usp = new URLSearchParams(window.location.search);
+    const out: Record<string, string | string[]> = {};
+    for (const key of usp.keys()) {
+      if (key in out) continue;
+      const all = usp.getAll(key);
+      out[key] = all.length > 1 ? all : all[0];
+    }
+    return out;
+  },
+  write: (params) => {
+    if (typeof window === 'undefined') return;
+    const usp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (Array.isArray(value))
+        value.forEach((v) => {
+          usp.append(key, v);
+        });
+      else usp.append(key, value);
+    }
+    const query = usp.toString();
+    const url = query
+      ? `${window.location.pathname}?${query}`
+      : window.location.pathname;
+    window.history.replaceState(null, '', url);
+  },
+};
+
+export interface UseDataTableHeaderUrlOptions {
+  enabled: boolean;
+  fields: FilterFieldConfig[];
+  values: Record<string, unknown>;
+  adapter: UrlSyncAdapter;
+  /** Bulk hydrate used on mount. */
+  onHydrate: (next: Record<string, unknown>) => void;
+}
+
+/**
+ * Two-way URL sync for the filter header:
+ * - On mount, reads params from the adapter and hydrates the external values.
+ * - On every values change, writes the serialized params back to the adapter.
+ *
+ * Holds no filter state of its own; the external `values` remain the single
+ * source of truth.
+ */
+export function useDataTableHeaderUrl({
+  enabled,
+  fields,
+  values,
+  adapter,
+  onHydrate,
+}: UseDataTableHeaderUrlOptions): void {
+  const hydratedRef = useRef(false);
+  const lastWrittenRef = useRef<string | null>(null);
+
+  // Mount: read from URL -> hydrate external state (once).
+  // biome-ignore lint: _
+  useEffect(() => {
+    if (!enabled || hydratedRef.current) return;
+    hydratedRef.current = true;
+    const params = adapter.read();
+    const hydrated = deserializeAll(fields, params);
+    // Record what we're hydrating so the write-effect doesn't echo it back.
+    lastWrittenRef.current = JSON.stringify(serializeAll(fields, hydrated));
+    if (Object.keys(hydrated).length) onHydrate(hydrated);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled]);
+
+  // Changes: write serialized values back to the URL (deduped).
+  // biome-ignore lint: _
+  useEffect(() => {
+    if (!enabled) return;
+    const params = serializeAll(fields, values);
+    const serialized = JSON.stringify(params);
+    if (serialized === lastWrittenRef.current) return;
+    lastWrittenRef.current = serialized;
+    adapter.write(params);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, values]);
+}
+
+/**
+ * A throwaway react-hook-form control used solely to satisfy date field
+ * components that call `useWatch({ control })`. It holds NO filter data —
+ * nothing ever writes to it — so it does not violate the "no internal state"
+ * rule. Cross-field date constraints (`minDateFromField`/`maxDateFromField`)
+ * resolve against this empty form and therefore won't apply in filters; static
+ * `minDate`/`maxDate` still work.
+ */
+export function useFilterControl(): Control<FieldValues> {
+  const { control } = useForm<FieldValues>();
+  return control;
+}