@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/views/calendar-field-selector.tsx

@@ -0,0 +1,56 @@
+// Date-field selector for the calendar view. Desk picks the calendar axis
+// from a Calendar View settings doc; this selector exposes the same choice
+// interactively — candidates are the doctype's visible Date/Datetime
+// fields, and picking one round-trips through the `?field=` search param
+// (see CalendarView) so the choice is shareable.
+import { Button, DropdownMenu, type DropdownMenuEntry } from "@multiplatform.one/components";
+import type { DocFieldMeta, DoctypeMeta } from "../shared/useDoctypeMeta";
+import { CalendarBlankIcon, CaretDownIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+
+const CALENDAR_DATE_FIELD_TYPES = new Set(["Date", "Datetime"]);
+
+/** Visible Date/Datetime fields a calendar can be laid out on. */
+export function calendarDateFieldCandidates(meta: DoctypeMeta): DocFieldMeta[] {
+  return meta.fields.filter(
+    (field) => CALENDAR_DATE_FIELD_TYPES.has(field.fieldtype) && !field.hidden,
+  );
+}
+
+export interface CalendarFieldSelectorProps {
+  candidates: DocFieldMeta[];
+  /** Fieldname of the date field currently laying out the calendar. */
+  value: string;
+  onChange: (fieldname: string) => void;
+}
+
+/**
+ * Dropdown to switch which date field the calendar is laid out on
+ * (ViewHeader switcher pattern: the active field is disabled with a reason).
+ */
+export function CalendarFieldSelector({ candidates, value, onChange }: CalendarFieldSelectorProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const current = candidates.find((field) => field.fieldname === value);
+  const items: DropdownMenuEntry[] = candidates.map((field) => ({
+    key: field.fieldname,
+    label: field.label || field.fieldname,
+    disabled: field.fieldname === value,
+    disabledReason:
+      field.fieldname === value ? t("views.calendarFieldCurrent", "Current date field") : undefined,
+    onSelect: () => onChange(field.fieldname),
+  }));
+
+  return (
+    <DropdownMenu items={items} placement="bottom-end">
+      <Button
+        size="$3"
+        icon={CalendarBlankIcon}
+        iconAfter={CaretDownIcon}
+        aria-label={t("views.calendarFieldSelect", "Choose calendar date field")}
+      >
+        {current?.label || value}
+      </Button>
+    </DropdownMenu>
+  );
+}

package/src/views/connection.ts

@@ -0,0 +1,31 @@
+// Stable Frappe connection config derived from the FrappeProvider mounted by
+// the backoffice shell (shell/BackofficeLayout). All alt-view data fetching
+// (meta, kanban boards, aggregates) flows through this one shape.
+import type { FixtureProvider } from "@multiplatform.one/frappe";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useMemo } from "react";
+
+export interface ViewConnection {
+  baseURL: string;
+  socketPort?: number;
+  auth?: {
+    useToken?: boolean;
+    token?: string | (() => string | Promise<string>);
+    type?: string;
+  };
+  syncOptions?: unknown;
+  fixtures?: FixtureProvider;
+}
+
+export function useViewConnection(): ViewConnection | undefined {
+  const config = useFrappeConfig();
+  const baseURL = config?.baseURL;
+  const socketPort = config?.socketPort;
+  const auth = config?.auth;
+  const syncOptions = config?.syncOptions;
+  const fixtures = config?.fixtures;
+  return useMemo(() => {
+    if (!baseURL) return undefined;
+    return { baseURL, socketPort, auth, syncOptions, fixtures };
+  }, [baseURL, socketPort, auth, syncOptions, fixtures]);
+}

package/src/views/dashboard-data.tsx

@@ -0,0 +1,321 @@
+// Data layer for the per-doctype dashboard view: status-field detection,
+// list-view filter links, and the created-per-week series.
+//
+// Weekly series strategy (probed against the bench):
+//   - `useFrappeAggregate` cannot express date-truncation group-bys — its
+//     groupBy is a bare fieldname and `date(creation)` is rejected by the
+//     injection guard. The REST list endpoint DOES accept
+//     `fields=["date(creation) as _day","count(name) as _aggregate_value"]`
+//     + `group_by=date(creation)`, so the live path fetches per-DAY counts
+//     (≤ 7 × WEEKS_WINDOW rows) and buckets them into weeks client-side.
+//   - If the grouped query is rejected (older bench / restricted backend),
+//     fall back to fetching raw `creation` values in the window and
+//     bucketing those.
+//   - Fixture mode (stories/tests) always buckets raw fixture rows.
+// Realtime parity with FrappeKPICard/FrappeChartCard: doctype room events
+// schedule a debounced refetch (shared refcounted room via SyncModule).
+import React from "react";
+import {
+  AsyncDebouncer,
+  DbModule,
+  HttpClient,
+  useFrappeDoctypeEvents,
+  type AuthConfig,
+  type FixtureProvider,
+} from "@multiplatform.one/frappe";
+import { formatAbsoluteDate } from "@multiplatform.one/theme";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createBackofficePaths, type BackofficePaths } from "../navigation/paths";
+import type { FrappeFilters } from "../shared/types";
+import type { DocFieldMeta, DoctypeMeta } from "../shared/useDoctypeMeta";
+import type { ViewConnection } from "./connection";
+
+/** Row shape for the per-day aggregate query (closed type — implied index
+ * signature keeps it inside the FrappeDocData constraint). */
+type DayAggregateRow = {
+  name: string;
+  doctype: string;
+  _day?: string;
+  _aggregate_value?: number | string;
+};
+
+type CreationRow = { name: string; doctype: string; creation?: string };
+
+export const WEEKS_WINDOW = 12;
+
+/** Cap on per-status KPI cards — pathological Selects get the chart only. */
+export const MAX_STATUS_KPI_CARDS = 8;
+
+// ---------------------------------------------------------------------------
+// Status field detection + list links
+// ---------------------------------------------------------------------------
+
+function isSelectCandidate(field: DocFieldMeta): boolean {
+  return field.fieldtype === "Select" && !field.hidden && (field.options ?? "").trim().length > 0;
+}
+
+/**
+ * The doctype's status axis: a visible Select named `status` when one
+ * exists (desk convention), else the first visible Select with options
+ * (same fallback axis the kanban view uses).
+ */
+export function detectStatusField(meta: DoctypeMeta): DocFieldMeta | undefined {
+  const candidates = meta.fields.filter(isSelectCandidate);
+  return candidates.find((field) => field.fieldname === "status") ?? candidates[0];
+}
+
+const defaultPaths = createBackofficePaths();
+
+/**
+ * List-view URL pre-filtered to one field value (basePath-aware when the
+ * provider's `paths` are passed; defaults to the canonical "/backoffice").
+ * `?f=` carries the shared `FrappeFilters` tuple array (shared/types.ts)
+ * as URI-encoded JSON:
+ *   /backoffice/todo?f=%5B%5B%22status%22%2C%22%3D%22%2C%22Open%22%5D%5D
+ */
+export function filteredListHref(
+  doctype: string,
+  fieldname: string,
+  value: string,
+  paths: BackofficePaths = defaultPaths,
+): string {
+  const filters: FrappeFilters = [[fieldname, "=", value]];
+  return `${paths.list(doctype)}?f=${encodeURIComponent(JSON.stringify(filters))}`;
+}
+
+// ---------------------------------------------------------------------------
+// Date helpers
+// ---------------------------------------------------------------------------
+
+export function isoDate(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** Frappe date-string (YYYY-MM-DD) for `days` days before now. */
+export function daysAgoIso(days: number): string {
+  const date = new Date();
+  date.setDate(date.getDate() - days);
+  return isoDate(date);
+}
+
+/** Monday-start week bucket for a date. */
+export function weekStart(date: Date): Date {
+  const copy = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  const mondayOffset = (copy.getDay() + 6) % 7;
+  copy.setDate(copy.getDate() - mondayOffset);
+  return copy;
+}
+
+/** Parse "YYYY-MM-DD" as LOCAL midnight (new Date("YYYY-MM-DD") is UTC). */
+function parseIsoDateLocal(value: string): Date | undefined {
+  const [y, m, d] = value.slice(0, 10).split("-").map(Number);
+  if (!y || !m || !d) return undefined;
+  const date = new Date(y, m - 1, d);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+/** Parse a frappe datetime ("YYYY-MM-DD HH:mm:ss.SSSSSS") leniently. */
+function parseFrappeDatetime(value: unknown): Date | undefined {
+  if (typeof value !== "string" || !value) return undefined;
+  const date = new Date(value.replace(" ", "T"));
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+// ---------------------------------------------------------------------------
+// Created-per-week series
+// ---------------------------------------------------------------------------
+
+export interface WeeklyCreatedPoint {
+  label: string;
+  value: number;
+}
+
+export interface WeeklyCreatedState {
+  /** One point per week, oldest first, empty weeks included. */
+  data: WeeklyCreatedPoint[] | undefined;
+  isLoading: boolean;
+  /** A realtime event arrived / refetch in flight — series may lag. */
+  isStale: boolean;
+  error: Error | undefined;
+  /** Series is ready and no docs were created inside the window. */
+  isEmpty: boolean;
+  /** Immediate refetch (error retry). */
+  refresh: () => void;
+}
+
+function toAuthConfig(auth: ViewConnection["auth"]): AuthConfig | undefined {
+  if (!auth) return undefined;
+  return {
+    useToken: auth.useToken,
+    token: auth.token,
+    type: auth.type as AuthConfig["type"],
+  };
+}
+
+/** Day-ISO → count from raw rows carrying a `creation` value. */
+function bucketRowsByDay(rows: Array<{ creation?: unknown }>): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    const created = parseFrappeDatetime(row.creation);
+    if (!created) continue;
+    const day = isoDate(created);
+    counts.set(day, (counts.get(day) ?? 0) + 1);
+  }
+  return counts;
+}
+
+async function fetchLiveDayCounts(
+  connection: ViewConnection,
+  doctype: string,
+  cutoff: string,
+): Promise<Map<string, number>> {
+  const db = new DbModule(new HttpClient(connection.baseURL, toAuthConfig(connection.auth)));
+  try {
+    // Server-side per-day aggregate: bounded payload regardless of doc count.
+    const rows = await db.getDocList<DayAggregateRow>(doctype, {
+      fields: ["date(creation) as _day", "count(name) as _aggregate_value"],
+      filters: [["creation", ">=", cutoff]],
+      groupBy: "date(creation)",
+      limit: 0,
+    });
+    const counts = new Map<string, number>();
+    for (const row of rows) {
+      const day = typeof row._day === "string" ? row._day.slice(0, 10) : "";
+      if (!day) continue;
+      const value = Number(row._aggregate_value);
+      counts.set(day, (counts.get(day) ?? 0) + (Number.isFinite(value) ? value : 0));
+    }
+    return counts;
+  } catch {
+    // Grouped-by-function query rejected — fetch raw creation values instead.
+    const rows = await db.getDocList<CreationRow>(doctype, {
+      fields: ["creation"],
+      filters: [["creation", ">=", cutoff]],
+      limit: 0,
+    });
+    return bucketRowsByDay(rows);
+  }
+}
+
+async function fetchFixtureDayCounts(
+  fixtures: FixtureProvider,
+  doctype: string,
+): Promise<Map<string, number>> {
+  const rows = (await fixtures.getList(doctype, { fields: ["creation"] })) as Array<{
+    creation?: unknown;
+  }>;
+  return bucketRowsByDay(rows);
+}
+
+const REFETCH_DEBOUNCE_MS = 300;
+
+/**
+ * Docs created per week over the last {@link WEEKS_WINDOW} weeks (Monday
+ * buckets, empty weeks included so the series is continuous), refetched on
+ * doctype realtime events with a coalescing debounce — same recompute
+ * contract as `useFrappeAggregate`.
+ */
+export function useWeeklyCreated(
+  connection: ViewConnection | undefined,
+  doctype: string,
+  weeks: number = WEEKS_WINDOW,
+): WeeklyCreatedState {
+  const [data, setData] = useState<WeeklyCreatedPoint[] | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isStale, setIsStale] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  const fetchSeq = useRef(0);
+  const connectionRef = useRef(connection);
+  connectionRef.current = connection;
+  const specRef = useRef({ doctype, weeks });
+  specRef.current = { doctype, weeks };
+
+  const runFetch = useCallback(async () => {
+    const conn = connectionRef.current;
+    const { doctype: currentDoctype, weeks: currentWeeks } = specRef.current;
+    if (!conn || !currentDoctype) return;
+    const seq = ++fetchSeq.current;
+    try {
+      const firstWeek = weekStart(new Date());
+      firstWeek.setDate(firstWeek.getDate() - (currentWeeks - 1) * 7);
+      const dayCounts = conn.fixtures
+        ? await fetchFixtureDayCounts(conn.fixtures, currentDoctype)
+        : await fetchLiveDayCounts(conn, currentDoctype, isoDate(firstWeek));
+
+      const weekCounts = new Map<string, number>();
+      for (const [day, count] of dayCounts) {
+        const date = parseIsoDateLocal(day);
+        if (!date || date < firstWeek) continue;
+        const bucket = isoDate(weekStart(date));
+        weekCounts.set(bucket, (weekCounts.get(bucket) ?? 0) + count);
+      }
+
+      const series: WeeklyCreatedPoint[] = [];
+      for (let i = 0; i < currentWeeks; i += 1) {
+        const week = new Date(firstWeek);
+        week.setDate(week.getDate() + i * 7);
+        series.push({
+          // House date channel (LC-12), axis-tick register: these labels are
+          // the bar chart's x ticks, so the year is elided ("Aug 11") — the
+          // 12-week window's period context carries it. Never a raw
+          // toLocaleDateString beside channel-formatted dates elsewhere.
+          label: formatAbsoluteDate(week, { year: "never" }),
+          value: weekCounts.get(isoDate(week)) ?? 0,
+        });
+      }
+      if (seq !== fetchSeq.current) return; // stale response — a newer fetch won
+      setData(series);
+      setError(undefined);
+    } catch (err) {
+      if (seq !== fetchSeq.current) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (seq === fetchSeq.current) {
+        setIsLoading(false);
+        setIsStale(false);
+      }
+    }
+  }, []);
+
+  // Debouncer coalescing bursts of realtime events into one refetch.
+  const debouncerRef = useRef<AsyncDebouncer<() => Promise<void>> | undefined>(undefined);
+  if (!debouncerRef.current) {
+    debouncerRef.current = new AsyncDebouncer(() => runFetch(), { wait: REFETCH_DEBOUNCE_MS });
+  }
+  useEffect(() => {
+    return () => debouncerRef.current?.cancel();
+  }, []);
+
+  const baseURL = connection?.baseURL;
+  const hasFixtures = !!connection?.fixtures;
+  useEffect(() => {
+    if (!baseURL || !doctype) return;
+    setIsLoading(true);
+    setError(undefined);
+    void runFetch();
+    // Refetch on connection target / doctype change only — the connection
+    // object identity churns with provider re-renders.
+  }, [baseURL, hasFixtures, doctype, weeks, runFetch]);
+
+  useFrappeDoctypeEvents(
+    connection as Parameters<typeof useFrappeDoctypeEvents>[0],
+    doctype,
+    () => {
+      setIsStale(true);
+      void debouncerRef.current?.maybeExecute();
+    },
+    !!connection && !connection.fixtures,
+  );
+
+  const refresh = useCallback(() => {
+    debouncerRef.current?.cancel();
+    setIsStale(true);
+    void runFetch();
+  }, [runFetch]);
+
+  const isEmpty = !!data && data.every((point) => point.value === 0);
+
+  return { data, isLoading, isStale, error, isEmpty, refresh };
+}

package/src/views/deskViewConfigs.ts

@@ -0,0 +1,190 @@
+// Discovery of desk view-config documents that drive the alternate views:
+//   - "Kanban Board" docs (field_name + columns child table) for kanban
+//   - "Calendar View" docs (subject/start/end fields) for calendar
+// Probed payloads (bench @ localhost:8000):
+//   GET /api/resource/Kanban Board?filters=[["reference_doctype","=","ToDo"]]
+//     → { data: [{ name }] } (names only)
+//   GET /api/resource/Kanban Board/<name>
+//     → full doc incl. columns: [{ column_name, status: "Active"|"Archived",
+//       indicator: "Blue"|…|"Yellow", order }]
+//   GET /api/resource/Calendar View?filters=[["reference_doctype","=",dt]]
+//     → { data: [{ name }] }; full doc has subject_field, start_date_field,
+//       end_date_field, all_day
+// Fixture mode (stories/tests): reads ride connection.fixtures instead.
+import { HttpClient, type AuthConfig } from "@multiplatform.one/frappe";
+import { useCallback, useEffect, useState } from "react";
+import type { ViewConnection } from "./connection";
+
+/** HttpClient bound to the view connection (shared with kanbanBoardOps). */
+export function createViewHttp(connection: ViewConnection): HttpClient {
+  const auth: AuthConfig | undefined = connection.auth
+    ? {
+        useToken: connection.auth.useToken,
+        token: connection.auth.token,
+        type: connection.auth.type as AuthConfig["type"],
+      }
+    : undefined;
+  return new HttpClient(connection.baseURL, auth);
+}
+
+async function fetchConfigDoc<TDoc extends { name: string }>(
+  connection: ViewConnection,
+  configDoctype: string,
+  referenceDoctype: string,
+  preferredName?: string,
+): Promise<{ names: string[]; doc: TDoc | undefined }> {
+  const filters: Array<[string, string, unknown]> = [["reference_doctype", "=", referenceDoctype]];
+  let names: string[];
+  if (connection.fixtures) {
+    const rows = await connection.fixtures.getList<TDoc & { doctype: string }>(configDoctype, {
+      filters,
+    });
+    names = rows.map((row) => String(row.name));
+  } else {
+    const http = createViewHttp(connection);
+    const response = await http.get<{ data?: Array<{ name: string }> }>(
+      `/api/resource/${encodeURIComponent(configDoctype)}`,
+      { filters, limit_page_length: 0 },
+    );
+    names = (response.payload?.data ?? []).map((row) => row.name);
+  }
+  const selected = preferredName && names.includes(preferredName) ? preferredName : names[0];
+  if (!selected) return { names, doc: undefined };
+  let doc: TDoc | undefined;
+  if (connection.fixtures) {
+    doc =
+      ((await connection.fixtures.getDoc<TDoc & { doctype: string }>(
+        configDoctype,
+        selected,
+      )) as TDoc | null) ?? undefined;
+  } else {
+    const http = createViewHttp(connection);
+    const response = await http.get<{ data?: TDoc }>(
+      `/api/resource/${encodeURIComponent(configDoctype)}/${encodeURIComponent(selected)}`,
+    );
+    doc = response.payload?.data;
+  }
+  return { names, doc };
+}
+
+interface ConfigDocState<TDoc> {
+  names: string[];
+  doc: TDoc | undefined;
+  isLoading: boolean;
+  error: Error | undefined;
+}
+
+export interface ConfigDocResult<TDoc> extends ConfigDocState<TDoc> {
+  /** Refetch after a config-doc mutation (create board, add column, …). */
+  reload: () => void;
+}
+
+function useConfigDoc<TDoc extends { name: string }>(
+  connection: ViewConnection | undefined,
+  configDoctype: string,
+  referenceDoctype: string,
+  preferredName?: string,
+): ConfigDocResult<TDoc> {
+  const [state, setState] = useState<ConfigDocState<TDoc>>({
+    names: [],
+    doc: undefined,
+    isLoading: true,
+    error: undefined,
+  });
+  const [version, setVersion] = useState(0);
+  const reload = useCallback(() => setVersion((current) => current + 1), []);
+  const baseURL = connection?.baseURL;
+
+  useEffect(() => {
+    if (!connection) return;
+    let cancelled = false;
+    setState({ names: [], doc: undefined, isLoading: true, error: undefined });
+    void (async () => {
+      try {
+        const { names, doc } = await fetchConfigDoc<TDoc>(
+          connection,
+          configDoctype,
+          referenceDoctype,
+          preferredName,
+        );
+        if (!cancelled) setState({ names, doc, isLoading: false, error: undefined });
+      } catch (err) {
+        if (!cancelled) {
+          setState({
+            names: [],
+            doc: undefined,
+            isLoading: false,
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+    // Refetch on connection target / doctype / preferred doc / reload tick
+    // only — `connection` object identity churns with provider re-renders.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [baseURL, configDoctype, referenceDoctype, preferredName, version]);
+
+  return { ...state, reload };
+}
+
+// ---------------------------------------------------------------------------
+// Kanban Board
+// ---------------------------------------------------------------------------
+
+export interface KanbanBoardColumnConfig {
+  column_name?: string;
+  /** "Active" | "Archived" */
+  status?: string;
+  /** Desk indicator color name (Blue, Cyan, Gray, Green, Light Blue, …) */
+  indicator?: string;
+}
+
+export interface KanbanBoardDoc {
+  name: string;
+  kanban_board_name?: string;
+  reference_doctype?: string;
+  /** The Select field the board's columns map onto. */
+  field_name?: string;
+  columns?: KanbanBoardColumnConfig[];
+  /** Board-scoped data filters (JSON string of desk list-filter tuples). */
+  filters?: string;
+  /** 1 = visible to the owner only (desk permission model). */
+  private?: number;
+}
+
+/**
+ * Discover the desk Kanban Board doc(s) for a doctype. `preferredName`
+ * (the `?board=` search param) wins when it matches an existing board;
+ * otherwise the first board is used.
+ */
+export function useKanbanBoard(
+  connection: ViewConnection | undefined,
+  doctype: string,
+  preferredName?: string,
+): ConfigDocResult<KanbanBoardDoc> {
+  return useConfigDoc<KanbanBoardDoc>(connection, "Kanban Board", doctype, preferredName);
+}
+
+// ---------------------------------------------------------------------------
+// Calendar View
+// ---------------------------------------------------------------------------
+
+export interface CalendarViewDoc {
+  name: string;
+  reference_doctype?: string;
+  subject_field?: string;
+  start_date_field?: string;
+  end_date_field?: string;
+  all_day?: number;
+}
+
+/** Discover the desk Calendar View settings doc for a doctype (first wins). */
+export function useCalendarViewSettings(
+  connection: ViewConnection | undefined,
+  doctype: string,
+): ConfigDocResult<CalendarViewDoc> {
+  return useConfigDoc<CalendarViewDoc>(connection, "Calendar View", doctype);
+}