@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/list/filter-fields.tsx

@@ -0,0 +1,339 @@
+/**
+ * Field + operator model for the list filter chrome (desk parity).
+ *
+ * Maps DoctypeMeta DocFields to kind-aware filter descriptors
+ * (select/link/check/date/number/text) and defines desk's operator
+ * vocabulary (=, !=, like, not like, in, not in, comparisons, between,
+ * is set / is not set) with two-way tuple conversion. This model speaks
+ * frappe tuples natively — the table package's FilterValue vocabulary is
+ * bridged separately (filterConversion.ts) for the DataTable surface;
+ * desk's own operator list is the parity target here.
+ */
+import type { FrappeFilter, FrappeFilters } from "../shared/types";
+import type { DocFieldMeta, DoctypeMeta } from "../shared/useDoctypeMeta";
+
+// ── Field descriptors ─────────────────────────────────────────
+
+export type FilterFieldKind = "select" | "link" | "check" | "date" | "number" | "text";
+
+export interface FilterFieldDescriptor {
+  fieldname: string;
+  label: string;
+  fieldtype: string;
+  kind: FilterFieldKind;
+  /** Link target doctype, or the raw Select options string. */
+  options?: string;
+}
+
+/** Layout / non-data fieldtypes that cannot meaningfully filter. */
+const NON_FILTERABLE_FIELDTYPES = new Set([
+  "Section Break",
+  "Column Break",
+  "Tab Break",
+  "Fold",
+  "Heading",
+  "HTML",
+  "Button",
+  "Image",
+  "Attach",
+  "Attach Image",
+  "Signature",
+  "Geolocation",
+  "Password",
+]);
+
+const NUMBER_FIELDTYPES = new Set(["Int", "Float", "Currency", "Percent", "Duration", "Rating"]);
+const DATE_FIELDTYPES = new Set(["Date", "Datetime", "Time"]);
+
+/** Editor kind for a frappe fieldtype (Dynamic Link has no static target → text). */
+export function fieldKind(fieldtype: string): FilterFieldKind {
+  if (fieldtype === "Select") return "select";
+  if (fieldtype === "Link") return "link";
+  if (fieldtype === "Check") return "check";
+  if (DATE_FIELDTYPES.has(fieldtype)) return "date";
+  if (NUMBER_FIELDTYPES.has(fieldtype)) return "number";
+  return "text";
+}
+
+function toDescriptor(field: DocFieldMeta): FilterFieldDescriptor {
+  return {
+    fieldname: field.fieldname,
+    label: field.label || field.fieldname,
+    fieldtype: field.fieldtype,
+    kind: fieldKind(field.fieldtype),
+    options: field.options,
+  };
+}
+
+/** Standard doc fields present on every doctype but absent from meta.fields. */
+export function standardDocFilterFields(): FilterFieldDescriptor[] {
+  return [
+    { fieldname: "name", label: "ID", fieldtype: "Data", kind: "text" },
+    { fieldname: "owner", label: "Created By", fieldtype: "Link", kind: "link", options: "User" },
+    { fieldname: "creation", label: "Created On", fieldtype: "Datetime", kind: "date" },
+    { fieldname: "modified", label: "Last Updated On", fieldtype: "Datetime", kind: "date" },
+    {
+      fieldname: "modified_by",
+      label: "Last Updated By",
+      fieldtype: "Link",
+      kind: "link",
+      options: "User",
+    },
+    // Desk `_` facet columns — the sidebar facets and heart column write
+    // tuples on these, so chips and the editor must label them (desk offers
+    // them in its filter field picker too). Never surface the raw
+    // underscore fieldname (no-raw-fieldname rule candidate).
+    { fieldname: "_assign", label: "Assigned To", fieldtype: "Data", kind: "text" },
+    { fieldname: "_user_tags", label: "Tags", fieldtype: "Data", kind: "text" },
+    { fieldname: "_liked_by", label: "Liked By", fieldtype: "Data", kind: "text" },
+    { fieldname: "_comments", label: "Comments", fieldtype: "Data", kind: "text" },
+  ];
+}
+
+/**
+ * All fields offered by the filter editor's field picker — data fields from
+ * meta (hidden ones included, desk parity) plus the standard doc fields.
+ */
+export function filterableFieldsFromMeta(meta?: DoctypeMeta): FilterFieldDescriptor[] {
+  const out: FilterFieldDescriptor[] = [];
+  const seen = new Set<string>();
+  for (const field of meta?.fields ?? []) {
+    if (!field.fieldname || seen.has(field.fieldname)) continue;
+    const fieldtype = String(field.fieldtype);
+    if (NON_FILTERABLE_FIELDTYPES.has(fieldtype) || fieldtype.startsWith("Table")) continue;
+    seen.add(field.fieldname);
+    out.push(toDescriptor(field));
+  }
+  for (const standard of standardDocFilterFields()) {
+    if (!seen.has(standard.fieldname)) out.push(standard);
+  }
+  return out;
+}
+
+/** Fields flagged `in_standard_filter`, in meta order (the quick-filter row). */
+export function standardFiltersFromMeta(meta?: DoctypeMeta): FilterFieldDescriptor[] {
+  return (meta?.fields ?? [])
+    .filter((field) => field.in_standard_filter === 1 && field.hidden !== 1 && field.fieldname)
+    .map(toDescriptor);
+}
+
+/** Select fieldtype options string → dropdown options (blank lines dropped). */
+export function selectOptionsFromField(options?: string): Array<{ label: string; value: string }> {
+  return (options ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => ({ label: line, value: line }));
+}
+
+/**
+ * Human label for a fieldname — descriptor label when known, else a
+ * title-cased form. The raw identifier (underscores) never reaches chips or
+ * editor rows (no-raw-fieldname rule candidate, parity audit pair 04/16).
+ */
+export function fieldLabelFor(fields: FilterFieldDescriptor[], fieldname: string): string {
+  const known = fields.find((field) => field.fieldname === fieldname)?.label;
+  if (known) return known;
+  const pretty = fieldname
+    .replace(/^_+/, "")
+    .split("_")
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+  return pretty || fieldname;
+}
+
+// ── Desk operator vocabulary ──────────────────────────────────
+
+export type DeskOperator =
+  | "="
+  | "!="
+  | "like"
+  | "not like"
+  | "in"
+  | "not in"
+  | ">"
+  | "<"
+  | ">="
+  | "<="
+  | "between"
+  | "is set"
+  | "is not set";
+
+/** English operator labels — translate at render time via t(). */
+export const DESK_OPERATOR_LABELS: Record<DeskOperator, string> = {
+  "=": "Equals",
+  "!=": "Not Equals",
+  like: "Like",
+  "not like": "Not Like",
+  in: "In",
+  "not in": "Not In",
+  ">": "Greater Than",
+  "<": "Less Than",
+  ">=": "Greater Than or Equal",
+  "<=": "Less Than or Equal",
+  between: "Between",
+  "is set": "Is Set",
+  "is not set": "Is Not Set",
+};
+
+const BASE_OPERATORS: DeskOperator[] = [
+  "=",
+  "!=",
+  "like",
+  "not like",
+  "in",
+  "not in",
+  "is set",
+  "is not set",
+];
+
+/** Operators offered for an editor kind (desk's list, comparisons gated). */
+export function operatorsForKind(kind: FilterFieldKind): DeskOperator[] {
+  switch (kind) {
+    case "check":
+      return ["=", "!="];
+    case "number":
+    case "date":
+      return ["=", "!=", ">", "<", ">=", "<=", "between", "in", "not in", "is set", "is not set"];
+    default:
+      return BASE_OPERATORS;
+  }
+}
+
+/** Initial operator when a field is picked (desk: text searches, others match). */
+export function defaultOperatorForKind(kind: FilterFieldKind): DeskOperator {
+  return kind === "text" ? "like" : "=";
+}
+
+// ── Editor row model + tuple conversion ───────────────────────
+
+export interface FilterRowDraft {
+  fieldname: string;
+  operator: DeskOperator;
+  /** Scalar editor value (single input / select / link / comma list). */
+  value: string;
+  /** Multi values: in / not in multi-select, or [from, to] for between. */
+  values: string[];
+}
+
+/**
+ * Draft → frappe tuple; null while the draft is incomplete.
+ * `like` wraps `%value%` unless the user typed their own wildcard;
+ * `is set` / `is not set` become ["field", "is", "set" | "not set"].
+ */
+export function draftToTuple(draft: FilterRowDraft, kind: FilterFieldKind): FrappeFilter | null {
+  const { fieldname, operator } = draft;
+  if (!fieldname) return null;
+  switch (operator) {
+    case "is set":
+      return [fieldname, "is", "set"];
+    case "is not set":
+      return [fieldname, "is", "not set"];
+    case "in":
+    case "not in": {
+      const values =
+        kind === "select"
+          ? draft.values.map((value) => value.trim()).filter(Boolean)
+          : draft.value
+              .split(",")
+              .map((value) => value.trim())
+              .filter(Boolean);
+      return values.length ? [fieldname, operator, values] : null;
+    }
+    case "between": {
+      const from = (draft.values[0] ?? "").trim();
+      const to = (draft.values[1] ?? "").trim();
+      return from && to ? [fieldname, "between", [from, to]] : null;
+    }
+    case "like":
+    case "not like": {
+      const text = draft.value.trim();
+      if (!text) return null;
+      return [fieldname, operator, text.includes("%") ? text : `%${text}%`];
+    }
+    default: {
+      const text = draft.value.trim();
+      return text ? [fieldname, operator, text] : null;
+    }
+  }
+}
+
+const SCALAR_OPERATORS: readonly string[] = ["=", "!=", "like", "not like", ">", "<", ">=", "<="];
+
+/** Frappe tuple → editable draft (inverse of draftToTuple). */
+export function tupleToDraft(tuple: FrappeFilter): FilterRowDraft {
+  const [fieldname, operator, raw] = tuple;
+  if (operator === "is") {
+    return {
+      fieldname,
+      operator: raw === "set" ? "is set" : "is not set",
+      value: "",
+      values: [],
+    };
+  }
+  if (operator === "in" || operator === "not in") {
+    const values = Array.isArray(raw)
+      ? raw.map(String)
+      : String(raw ?? "")
+          .split(",")
+          .map((value) => value.trim())
+          .filter(Boolean);
+    return { fieldname, operator, value: values.join(", "), values };
+  }
+  if (operator === "between") {
+    const values = Array.isArray(raw) ? raw.map(String) : [];
+    return {
+      fieldname,
+      operator: "between",
+      value: "",
+      values: [values[0] ?? "", values[1] ?? ""],
+    };
+  }
+  const known = SCALAR_OPERATORS.includes(operator) ? (operator as DeskOperator) : "=";
+  return {
+    fieldname,
+    operator: known,
+    value: raw === null || raw === undefined ? "" : String(raw),
+    values: [],
+  };
+}
+
+// ── Filter list helpers ───────────────────────────────────────
+
+/**
+ * Quick-filter semantics: a standard filter control owns every tuple for its
+ * fieldname — replace them with `tuple`, or clear when `tuple` is undefined.
+ */
+export function setFieldFilter(
+  filters: FrappeFilters,
+  fieldname: string,
+  tuple?: FrappeFilter,
+): FrappeFilters {
+  const rest = filters.filter(([name]) => name !== fieldname);
+  return tuple ? [...rest, tuple] : rest;
+}
+
+/** The active quick-filter display value for a fieldname ("" when none). */
+export function quickFilterValue(filters: FrappeFilters, fieldname: string): string {
+  const tuple = filters.find(([name]) => name === fieldname);
+  if (!tuple) return "";
+  const [, operator, raw] = tuple;
+  if (operator === "like") {
+    const text = String(raw ?? "");
+    return text.startsWith("%") && text.endsWith("%") && text.length >= 2
+      ? text.slice(1, -1)
+      : text;
+  }
+  if (operator === "=") return raw === null || raw === undefined ? "" : String(raw);
+  return "";
+}
+
+/** Chip label: "Status = Open", "Due Date between a, b", "Owner is set". */
+export function filterTupleLabel(fields: FilterFieldDescriptor[], tuple: FrappeFilter): string {
+  const [fieldname, operator, raw] = tuple;
+  const label = fieldLabelFor(fields, fieldname);
+  if (operator === "is") return `${label} ${raw === "set" ? "is set" : "is not set"}`;
+  const value = Array.isArray(raw) ? raw.map(String).join(", ") : String(raw ?? "");
+  return `${label} ${operator} ${value}`;
+}

package/src/list/filter-saved.tsx

@@ -0,0 +1,181 @@
+import React from "react";
+/**
+ * Saved filters — desk parity via the `List Filter` doctype
+ * (frappe.client.get_list / insert / delete — the same records desk's
+ * sidebar "Saved Filters" reads), bridged into the table package's
+ * storage-agnostic primitives: useSavedFilters (state), SavedFilterDropdown
+ * (picker) and FilterManager (save dialog with name + global toggle).
+ * Fixture mode (stories / no bench) runs in-memory.
+ */
+import { XStack, YStack } from "@multiplatform.one/components";
+// Catalog Button: the inline save affordance disables while there is nothing
+// to save — the catalog `disabledReason` explains it (DG-ST-03) instead of a
+// bare dangle.
+import { Button, Input } from "@multiplatform.one/forms";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import {
+  FilterManager,
+  SavedFilterDropdown,
+  useSavedFilters,
+  type ParsedFilter,
+  type SavedFilter,
+  type SavedFiltersStorage,
+} from "@multiplatform.one/table";
+import { useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { FrappeFilters } from "../shared/types";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import { useSessionUserId as useSessionUser } from "../shared/useSessionUserId";
+
+export interface SavedFiltersControlProps {
+  doctype: string;
+  filters: FrappeFilters;
+  onFiltersChange: (filters: FrappeFilters) => void;
+  /**
+   * Sheet-safe presentation for the compact list-tools sheet: the save
+   * affordance renders as an inline name + button row instead of the
+   * FilterManager dialog (tamagui dialogs portal behind the RN-Modal sheet
+   * on native).
+   */
+  inline?: boolean;
+  /** Fired after a filter set was saved (host hook — analytics, toasts). */
+  onFilterSaved?: (saved: { name: string; isGlobal: boolean; filters: FrappeFilters }) => void;
+}
+
+/**
+ * SavedFiltersStorage adapter over the `List Filter` doctype. Undefined in
+ * fixture mode / before the app is ready — useSavedFilters then keeps
+ * filters in memory only.
+ */
+function useListFilterStorage(doctype: string): SavedFiltersStorage | undefined {
+  const config = useFrappeConfig();
+  const app = useFrappeApp();
+  const fixtureMode = Boolean(config?.fixtures);
+  return useMemo(() => {
+    if (!app || fixtureMode) return undefined;
+    const storage: SavedFiltersStorage = {
+      load: async () => {
+        const res = await app.call().get<{ message?: SavedFilter[] }>("frappe.client.get_list", {
+          doctype: "List Filter",
+          filters: JSON.stringify([["reference_doctype", "=", doctype]]),
+          fields: JSON.stringify(["name", "filter_name", "for_user", "filters"]),
+          limit_page_length: 0,
+        });
+        return res.payload?.message ?? [];
+      },
+      save: async (filter) => {
+        await app.call().post("frappe.client.insert", {
+          doc: {
+            doctype: "List Filter",
+            reference_doctype: doctype,
+            filter_name: filter.filter_name ?? "",
+            for_user: filter.for_user ?? "",
+            filters: filter.filters ?? "[]",
+          },
+        });
+      },
+      remove: async (name) => {
+        await app.call().post("frappe.client.delete", { doctype: "List Filter", name });
+      },
+    };
+    return storage;
+  }, [app, fixtureMode, doctype]);
+}
+
+export function SavedFiltersControl({
+  doctype,
+  filters,
+  onFiltersChange,
+  inline,
+  onFilterSaved,
+}: SavedFiltersControlProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const storage = useListFilterStorage(doctype);
+  const user = useSessionUser();
+  const {
+    filters: savedFilters,
+    saveFilter,
+    deleteFilter,
+  } = useSavedFilters({ storage, userId: user });
+  const [selected, setSelected] = useState<ParsedFilter | null>(null);
+  const [draftName, setDraftName] = useState("");
+
+  const dropdown = (
+    <SavedFilterDropdown
+      filters={savedFilters}
+      selectedFilter={selected}
+      onSelectFilter={(filter) => {
+        setSelected(filter);
+        if (filter) onFiltersChange(filter.filters as FrappeFilters);
+      }}
+      onDeleteFilter={(name) => void deleteFilter(name)}
+      placeholder={t("list.filters.savedFilters", "Saved Filters")}
+    />
+  );
+
+  if (inline) {
+    const handleInlineSave = () => {
+      const name = draftName.trim();
+      if (!name || filters.length === 0) return;
+      void Promise.resolve(saveFilter(name, filters, false)).then(() => {
+        setDraftName("");
+        onFilterSaved?.({ name, isGlobal: false, filters });
+      });
+    };
+    return (
+      <YStack gap="$2">
+        {/* Column wrappers stretch the fields to full width on native (a
+            row wrapper leaves them at intrinsic width — sliver bug). */}
+        {savedFilters.length > 0 ? <YStack width="100%">{dropdown}</YStack> : null}
+        <XStack gap="$2" alignItems="center">
+          <YStack flex={1} minWidth={0}>
+            <Input
+              value={draftName}
+              onChangeText={setDraftName}
+              placeholder={t("list.filters.filterName", "Filter name")}
+              size="$3"
+              compact
+              aria-label={t("list.filters.filterName", "Filter name")}
+            />
+          </YStack>
+          <Button
+            size="$3"
+            disabled={filters.length === 0 || !draftName.trim()}
+            disabledReason={
+              filters.length === 0
+                ? t("list.filters.saveNeedsFilters", "Apply filters to save them")
+                : !draftName.trim()
+                  ? t("list.filters.saveNeedsName", "Name the filter to save it")
+                  : undefined
+            }
+            onPress={handleInlineSave}
+          >
+            {t("list.filters.saveFilter", "Save Filter")}
+          </Button>
+        </XStack>
+      </YStack>
+    );
+  }
+
+  return (
+    <XStack gap="$2" alignItems="center">
+      <XStack maxWidth={220}>{dropdown}</XStack>
+      <FilterManager
+        currentFilters={filters}
+        canCreateGlobal
+        // Toolbar row: the reason rides the control line — stacked-below
+        // broke the filter row's shared 44px height into a cramped
+        // two-line cluster (Button contract, DG-ST-03).
+        disabledReasonPlacement="inline"
+        onSaveFilter={(filterName, isGlobal) => {
+          const result = saveFilter(filterName, filters, isGlobal);
+          void Promise.resolve(result).then(() => {
+            onFilterSaved?.({ name: filterName, isGlobal, filters });
+          });
+          return result;
+        }}
+      />
+    </XStack>
+  );
+}