@multiplatform.one/backoffice 6.7.0 → 7.1.0

package/src/report/queryReportFilterBar.spec.tsx

@@ -0,0 +1,139 @@
+/**
+ * Query-report filter bar: apply-on-change for discrete controls, Apply for
+ * text, LC-49 (per-filter × is not a tab stop), LC-50 (Apply activates),
+ * disabled/read_only filters open nothing.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen } from "@testing-library/react";
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  QueryReportFilterBar,
+  queryReportFilterAppliesOnChange,
+  queryReportSelectOptions,
+} from "./queryReportFilterBar";
+import type { QueryReportFilterMeta } from "./reportShapes";
+
+const selectFilter: QueryReportFilterMeta = {
+  fieldname: "status",
+  label: "Status",
+  fieldtype: "Select",
+  options: "Open\nClosed",
+};
+const ownerFilter: QueryReportFilterMeta = {
+  fieldname: "owner",
+  label: "Owner",
+  fieldtype: "Data",
+  mandatory: 1,
+};
+const checkFilter: QueryReportFilterMeta = {
+  fieldname: "show_permissions",
+  label: "Show Permissions",
+  fieldtype: "Check",
+};
+const lockedFilter: QueryReportFilterMeta = {
+  fieldname: "company",
+  label: "Company",
+  fieldtype: "Select",
+  options: "Acme\nGlobex",
+  read_only: 1,
+};
+
+describe("queryReportFilterAppliesOnChange", () => {
+  it("commits select/link/date/check immediately and leaves text for Apply", () => {
+    expect(queryReportFilterAppliesOnChange(selectFilter)).toBe(true);
+    expect(queryReportFilterAppliesOnChange(checkFilter)).toBe(true);
+    expect(
+      queryReportFilterAppliesOnChange({ fieldname: "user", fieldtype: "Link", options: "User" }),
+    ).toBe(true);
+    expect(queryReportFilterAppliesOnChange({ fieldname: "from_date", fieldtype: "Date" })).toBe(
+      true,
+    );
+    expect(queryReportFilterAppliesOnChange(ownerFilter)).toBe(false);
+    expect(queryReportFilterAppliesOnChange({ fieldname: "limit", fieldtype: "Int" })).toBe(false);
+  });
+});
+
+describe("QueryReportFilterBar", () => {
+  it("applies a Check immediately (Desk/Metabase auto-apply)", () => {
+    const onApply = vi.fn();
+    renderWithProviders(
+      <QueryReportFilterBar filterMeta={[checkFilter]} filters={{}} onApply={onApply} />,
+    );
+    fireEvent.click(screen.getByRole("checkbox", { name: /show permissions/i }));
+    expect(onApply).toHaveBeenCalledWith({ show_permissions: 1 });
+  });
+
+  it("keeps text drafts local until Apply", () => {
+    const onApply = vi.fn();
+    renderWithProviders(
+      <QueryReportFilterBar filterMeta={[ownerFilter]} filters={{}} onApply={onApply} />,
+    );
+    const owner = screen.getByRole("textbox", { name: /owner/i });
+    fireEvent.change(owner, { target: { value: "jane@example.com" } });
+    expect(onApply).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("button", { name: "Apply" }));
+    expect(onApply).toHaveBeenCalledWith({ owner: "jane@example.com" });
+  });
+
+  it("in-box text clear commits the empty value immediately", () => {
+    const onApply = vi.fn();
+    renderWithProviders(
+      <QueryReportFilterBar
+        filterMeta={[ownerFilter]}
+        filters={{ owner: "jane@example.com" }}
+        onApply={onApply}
+      />,
+    );
+    fireEvent.click(screen.getByTestId("query-report-clear-owner"));
+    expect(onApply).toHaveBeenCalledWith({});
+  });
+
+  it("text-filter clear sits inside the input box (LC-71), not a sibling tab stop", () => {
+    renderWithProviders(
+      <QueryReportFilterBar
+        filterMeta={[ownerFilter]}
+        filters={{ owner: "jane@example.com" }}
+        onApply={vi.fn()}
+      />,
+    );
+    const clear = screen.getByTestId("query-report-clear-owner");
+    expect(clear.getAttribute("tabindex")).toBe("-1");
+    const field = screen.getByRole("textbox", { name: /owner/i });
+    const box = field.closest(".mp-composite-ring");
+    expect(box).toBeTruthy();
+    expect(box?.contains(clear)).toBe(true);
+  });
+
+  it("optional Select prepends All so clearing does not need a sibling ×", () => {
+    expect(queryReportSelectOptions("Open\nClosed", "All")).toEqual([
+      { label: "All", value: "" },
+      { label: "Open", value: "Open" },
+      { label: "Closed", value: "Closed" },
+    ]);
+  });
+
+  it("disabled/read_only filter is an inert value and opens nothing", () => {
+    renderWithProviders(
+      <QueryReportFilterBar
+        filterMeta={[lockedFilter]}
+        filters={{ company: "Acme" }}
+        onApply={vi.fn()}
+      />,
+    );
+    const field = screen.getByLabelText(/company/i);
+    fireEvent.click(field);
+    fireEvent.keyDown(field, { key: "Enter" });
+    fireEvent.keyDown(field, { key: " " });
+    expect(screen.queryByRole("listbox")).toBeNull();
+    expect(screen.queryByRole("combobox")).toBeNull();
+    expect(screen.queryByTestId("select-dropdown")).toBeNull();
+  });
+
+  it("exposes the band as a toolbar named Filters", () => {
+    renderWithProviders(
+      <QueryReportFilterBar filterMeta={[ownerFilter]} filters={{}} onApply={vi.fn()} />,
+    );
+    expect(screen.getByRole("toolbar", { name: "Filters" })).toBeTruthy();
+  });
+});

package/src/report/queryReportFilterBar.tsx

@@ -0,0 +1,315 @@
+// Query-report filter bar — declared filters as a sticky compact widget
+// band (Metabase dashboard filters, Looker Studio controls, Frappe Desk
+// page-form, Linear insights chips), not a bolted-on admin-table row.
+//
+// Placement: sticky under the report header so the grid scrolls beneath
+// it. Every declared filter stays visible even when empty (empty-filter
+// honesty); required empties keep the run gated upstream.
+//
+// Commit: select / link / date / check apply on change (Desk
+// `trigger_refresh` + Metabase auto-apply). Text/number wait for Enter,
+// blur, or Apply so typing does not thrash `query_report.run`. Applied
+// values round-trip through `?filters=` (the screen owns the URL write).
+//
+// Keyboard (LC-49 / LC-50 / LC-71): each filter is one tab stop (the house
+// field). Text-filter × lives INSIDE the Input.Box so the ring wraps the
+// whole control (never a sibling that splits the boundary) and is mouse/
+// touch only (`tabIndex={-1}`). Select clears via an All option (Desk
+// empty-select). Apply and Clear-all are their own stops. Disabled /
+// read_only filters pass `disabled` through so pickers open nothing.
+import { View, XStack, YStack, isWeb } from "@multiplatform.one/components";
+import { Button, Checkbox, Input, Select, zIndex } from "@multiplatform.one/forms";
+import { Date as DateField, Link as LinkField } from "@multiplatform.one/frappe-ui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { XIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { fieldKind, fieldLabelFor, selectOptionsFromField } from "../list/filter-fields";
+import {
+  compactQueryReportFilters,
+  isEmptyFilterValue,
+  type QueryReportFilterMeta,
+  type QueryReportFilters,
+} from "./reportShapes";
+
+export function queryReportFilterLabel(filter: QueryReportFilterMeta): string {
+  return filter.label || fieldLabelFor([], filter.fieldname);
+}
+
+/** Discrete kinds commit the run as soon as the value lands (Desk/Metabase). */
+export function queryReportFilterAppliesOnChange(filter: QueryReportFilterMeta): boolean {
+  const kind = fieldKind(filter.fieldtype || "Data");
+  return kind === "select" || kind === "link" || kind === "date" || kind === "check";
+}
+
+/** Desk empty-select / FrappeReportView "All": optional Select clears without a sibling ×. */
+export function queryReportSelectOptions(
+  options: string | undefined,
+  allLabel: string,
+): Array<{ label: string; value: string }> {
+  const choices = selectOptionsFromField(options);
+  if (choices.some((choice) => choice.value === "")) return choices;
+  return [{ label: allLabel, value: "" }, ...choices];
+}
+
+function draftFromFilters(
+  filterMeta: readonly QueryReportFilterMeta[],
+  filters: QueryReportFilters,
+): QueryReportFilters {
+  const draft: QueryReportFilters = {};
+  for (const filter of filterMeta) {
+    // Applied state only — defaults are seeded into it by the hook, so a
+    // deliberately cleared control stays visibly empty (gate consistency).
+    const value = filters[filter.fieldname];
+    draft[filter.fieldname] = value === undefined || value === null ? "" : value;
+  }
+  return draft;
+}
+
+function ReportFilterControl({
+  filter,
+  value,
+  onValueChange,
+  onCommit,
+  disabled,
+}: {
+  filter: QueryReportFilterMeta;
+  value: unknown;
+  onValueChange: (value: unknown) => void;
+  onCommit: () => void;
+  disabled?: boolean;
+}) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const label = queryReportFilterLabel(filter);
+  const required = filter.mandatory === 1;
+  const fieldtype = filter.fieldtype || "Data";
+  const kind = fieldKind(fieldtype);
+  const text = value === undefined || value === null ? "" : String(value);
+
+  // Locked filters stay visible (honest value) but must not open a picker.
+  // House Select/Link/Date still mount an overlay node when `disabled`; a
+  // disabled Input is a value display with no popup (LC-21 family).
+  if (disabled && (kind === "select" || kind === "link" || kind === "date")) {
+    return (
+      <Input
+        label={label}
+        required={required}
+        disabled
+        value={text}
+        compact
+        inputProps={{ "aria-label": label }}
+      />
+    );
+  }
+
+  switch (kind) {
+    case "select":
+      return (
+        <Select
+          label={label}
+          required={required}
+          value={text}
+          disabled={disabled}
+          onChange={(next) => {
+            if (typeof next === "string") onValueChange(next);
+          }}
+          options={queryReportSelectOptions(filter.options, t("queryReport.allValues", "All"))}
+          placeholder={t("queryReport.selectValue", "Select...")}
+          compact
+        />
+      );
+    case "link":
+      return (
+        <LinkField
+          label={label}
+          required={required}
+          value={text}
+          disabled={disabled}
+          onChange={(next) => onValueChange(next)}
+          doctype={filter.options ?? ""}
+          placeholder={label}
+          compact
+        />
+      );
+    case "date":
+      return (
+        <DateField
+          label={label}
+          required={required}
+          value={text}
+          disabled={disabled}
+          onChange={(next: string) => onValueChange(next)}
+          type={fieldtype === "Datetime" ? "datetime" : fieldtype === "Time" ? "time" : "date"}
+          compact
+        />
+      );
+    case "check":
+      return (
+        <Checkbox
+          label={label}
+          disabled={disabled}
+          checked={value === 1 || value === "1" || value === true}
+          onCheckedChange={(checked) => onValueChange(checked === true ? 1 : "")}
+        />
+      );
+    default: {
+      const showClear = !disabled && !isEmptyFilterValue(value);
+      const clearName = t("queryReport.clearFilter", {
+        label,
+        defaultValue: `Clear ${label}`,
+      });
+      return (
+        <Input
+          label={label}
+          required={required}
+          disabled={disabled}
+          value={text}
+          onChangeText={(next) => onValueChange(next)}
+          compact
+          rightIconInteractive={showClear}
+          rightIcon={
+            showClear ? (
+              <View
+                role="button"
+                tabIndex={-1}
+                padding="$1"
+                cursor="pointer"
+                hoverStyle={{ backgroundColor: "$color4" }}
+                onPress={() => {
+                  onValueChange("");
+                  onCommit();
+                }}
+                aria-label={clearName}
+                data-testid={`query-report-clear-${filter.fieldname}`}
+              >
+                <XIcon size={14} />
+              </View>
+            ) : undefined
+          }
+          inputProps={{
+            onBlur: onCommit,
+            onKeyDown: (event: { key?: string; preventDefault?: () => void }) => {
+              if (event.key === "Enter") {
+                event.preventDefault?.();
+                onCommit();
+              }
+            },
+          }}
+          {...(kind === "number" ? { keyboardType: "numeric" as const } : {})}
+        />
+      );
+    }
+  }
+}
+
+export interface QueryReportFilterBarProps {
+  filterMeta: readonly QueryReportFilterMeta[];
+  filters: QueryReportFilters;
+  onApply: (next: QueryReportFilters) => void;
+}
+
+/**
+ * The declared-filter band: one compact widget per filter (hidden ones
+ * excluded, desk parity — their defaults still apply), a mouse-only
+ * per-filter clear, Apply (flushes text drafts), and Clear-all when any
+ * visible filter is set.
+ */
+export function QueryReportFilterBar({ filterMeta, filters, onApply }: QueryReportFilterBarProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const [draft, setDraft] = useState<QueryReportFilters>(() =>
+    draftFromFilters(filterMeta, filters),
+  );
+  const draftRef = useRef(draft);
+  draftRef.current = draft;
+
+  useEffect(() => {
+    const next = draftFromFilters(filterMeta, filters);
+    draftRef.current = next;
+    setDraft(next);
+  }, [filterMeta, filters]);
+
+  const applyValues = useCallback(
+    (values: QueryReportFilters) => {
+      onApply(compactQueryReportFilters(filterMeta, values));
+    },
+    [filterMeta, onApply],
+  );
+
+  const setFieldValue = useCallback(
+    (fieldname: string, value: unknown, commit: boolean) => {
+      const next = { ...draftRef.current, [fieldname]: value };
+      draftRef.current = next;
+      setDraft(next);
+      if (commit) applyValues(next);
+    },
+    [applyValues],
+  );
+
+  const apply = useCallback(() => {
+    applyValues(draftRef.current);
+  }, [applyValues]);
+
+  const visible = filterMeta.filter((filter) => filter.hidden !== 1);
+  const hasVisibleValue = visible.some((filter) => !isEmptyFilterValue(draft[filter.fieldname]));
+
+  const clearAll = useCallback(() => {
+    const next = { ...draftRef.current };
+    for (const filter of visible) next[filter.fieldname] = "";
+    draftRef.current = next;
+    setDraft(next);
+    applyValues(next);
+  }, [visible, applyValues]);
+
+  return (
+    <XStack
+      role="toolbar"
+      aria-label={t("queryReport.filters", "Filters")}
+      data-testid="query-report-filter-bar"
+      flexWrap="wrap"
+      alignItems="flex-end"
+      gap="$2"
+      overflow="visible"
+      {...knobProps.panelPadding}
+      paddingVertical="$2"
+      backgroundColor="$color2"
+      borderBottomWidth={1}
+      borderColor="$borderColor"
+      {...(isWeb ? { position: "sticky" as const, top: 0, zIndex: zIndex.stickyHeader } : {})}
+    >
+      {visible.map((filter) => {
+        const value = draft[filter.fieldname];
+        const readOnly = filter.read_only === 1;
+        return (
+          <YStack
+            key={filter.fieldname}
+            minWidth={180}
+            maxWidth={280}
+            flex={1}
+            overflow="visible"
+            data-query-report-filter={filter.fieldname}
+          >
+            <ReportFilterControl
+              filter={filter}
+              value={value}
+              disabled={readOnly}
+              onValueChange={(next) =>
+                setFieldValue(filter.fieldname, next, queryReportFilterAppliesOnChange(filter))
+              }
+              onCommit={apply}
+            />
+          </YStack>
+        );
+      })}
+      {hasVisibleValue ? (
+        <Button size="$3" chromeless onPress={clearAll}>
+          {t("queryReport.clearAllFilters", "Clear all")}
+        </Button>
+      ) : null}
+      <Button theme="accent" onPress={apply}>
+        {t("queryReport.apply", "Apply")}
+      </Button>
+    </XStack>
+  );
+}

package/src/report/queryReportUrlState.spec.ts

@@ -0,0 +1,61 @@
+// `?filters=` codec specs — the query-report deep-link contract
+// (queryReportUrlState.ts documents the schema; list `?f=` sibling).
+import { describe, expect, it } from "vitest";
+import {
+  parseQueryReportFiltersParam,
+  serializeQueryReportFiltersParam,
+} from "./queryReportUrlState";
+
+describe("parseQueryReportFiltersParam", () => {
+  it("parses a raw JSON object param", () => {
+    expect(parseQueryReportFiltersParam('{"status":"Open","limit":20}')).toEqual({
+      status: "Open",
+      limit: 20,
+    });
+  });
+
+  it("parses a percent-encoded param (router handed it through raw)", () => {
+    expect(parseQueryReportFiltersParam("%7B%22user%22%3A%22test%40example.com%22%7D")).toEqual({
+      user: "test@example.com",
+    });
+  });
+
+  it("takes the first value of a repeated param", () => {
+    expect(parseQueryReportFiltersParam(['{"a":"1"}', '{"a":"2"}'])).toEqual({ a: "1" });
+  });
+
+  it("keeps scalar values only and drops empty strings", () => {
+    expect(
+      parseQueryReportFiltersParam(
+        '{"s":"x","n":3,"b":true,"empty":"","arr":[1],"obj":{"x":1},"nil":null}',
+      ),
+    ).toEqual({ s: "x", n: 3, b: true });
+  });
+
+  it("degrades malformed input to no filters", () => {
+    expect(parseQueryReportFiltersParam(undefined)).toEqual({});
+    expect(parseQueryReportFiltersParam("")).toEqual({});
+    expect(parseQueryReportFiltersParam("not json")).toEqual({});
+    expect(parseQueryReportFiltersParam('["status","=","Open"]')).toEqual({});
+    expect(parseQueryReportFiltersParam("%E0%A4%A")).toEqual({});
+  });
+});
+
+describe("serializeQueryReportFiltersParam", () => {
+  it("serializes scalar values with sorted keys (stable echo comparison)", () => {
+    expect(serializeQueryReportFiltersParam({ b: "2", a: "1" })).toBe('{"a":"1","b":"2"}');
+  });
+
+  it("drops empty values and non-scalars; empty state drops the param", () => {
+    expect(
+      serializeQueryReportFiltersParam({ a: "", b: null, c: undefined, d: ["x"] }),
+    ).toBeUndefined();
+    expect(serializeQueryReportFiltersParam({})).toBeUndefined();
+  });
+
+  it("round-trips through the parser", () => {
+    const filters = { status: "Open", from_date: "2026-08-01", show_permissions: 1 };
+    const serialized = serializeQueryReportFiltersParam(filters);
+    expect(parseQueryReportFiltersParam(serialized)).toEqual(filters);
+  });
+});

package/src/report/queryReportUrlState.ts

@@ -0,0 +1,68 @@
+/**
+ * URL state codec for the query-report surface — the `?filters=` query param.
+ *
+ * Schema (list `?f=` sibling, one JSON param per surface):
+ *   filters = urlencoded JSON OBJECT of filter values keyed by fieldname
+ *             (`{"status":"Open","from_date":"2026-08-01","show_permissions":1}`)
+ *             — the exact dict shape frappe.desk.query_report.run accepts;
+ *             absent while every filter sits at its default/empty state.
+ *
+ * Bidirectional best-effort channel (desk update_url_with_filters parity):
+ * the screen writes applied values through the navigator's optional
+ * `setParams` (history REPLACE, no remount) and adopts inbound param changes
+ * (deep links, back/forward), so reload and shared links reproduce the run.
+ */
+import { isEmptyFilterValue, type QueryReportFilters } from "./reportShapes";
+
+/**
+ * Parse the `?filters=` deep-link value. The router usually decodes the
+ * param already, so the raw value is tried first (same contract as the
+ * list's `?f=` parser). Only scalar values survive (strings, numbers,
+ * booleans — the run dict vocabulary); malformed input degrades to {}.
+ */
+export function parseQueryReportFiltersParam(
+  raw: string | string[] | undefined,
+): QueryReportFilters {
+  const value = typeof raw === "string" ? raw : Array.isArray(raw) ? raw[0] : undefined;
+  if (!value) return {};
+  const candidates = [value];
+  try {
+    const decoded = decodeURIComponent(value);
+    if (decoded !== value) candidates.push(decoded);
+  } catch {
+    // raw is not percent-encoded — the direct candidate covers it
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const filters: QueryReportFilters = {};
+      for (const [fieldname, entry] of Object.entries(parsed)) {
+        if (typeof entry === "string" && entry !== "") filters[fieldname] = entry;
+        else if (typeof entry === "number" || typeof entry === "boolean")
+          filters[fieldname] = entry;
+      }
+      if (Object.keys(filters).length > 0) return filters;
+    } catch {
+      // not JSON — try the next candidate
+    }
+  }
+  return {};
+}
+
+/**
+ * Filter values → `?filters=` value (raw JSON — the router encodes);
+ * undefined drops the param. Keys are sorted so equal states serialize
+ * identically (the inbound-adoption echo guard compares these strings).
+ */
+export function serializeQueryReportFiltersParam(filters: QueryReportFilters): string | undefined {
+  const entries = Object.entries(filters)
+    .filter(
+      ([, value]) =>
+        !isEmptyFilterValue(value) &&
+        (typeof value === "string" || typeof value === "number" || typeof value === "boolean"),
+    )
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  if (entries.length === 0) return undefined;
+  return JSON.stringify(Object.fromEntries(entries));
+}