@multiplatform.one/backoffice 6.3.0

package/src/chrome/CommandPalette.tsx

@@ -0,0 +1,520 @@
+// Command palette (MOD-01) — the backoffice's global search / command
+// surface. One section model (useCommandPaletteModel) rendered through two
+// containers:
+//   ≥sm web  → centered modal overlay (~640px, top-anchored ~15vh) via the
+//              house Dialog surface (LC-06 overlay anatomy, LC-24 transitions)
+//   <sm/native → full-height SheetModal (same mechanics as the list tools
+//              sheet and the native search sheet)
+//
+// Keyboard-first: the search input is the single tab stop (D-23); ArrowUp/
+// ArrowDown move one roving highlight across sections, Enter opens, Escape
+// closes and returns focus to the pre-open element (D-22). The highlight
+// renders on the accent channel (LC-05). COMMIT-class dismissal (LC-21):
+// picking a row commits and closes; otherwise only backdrop click / Escape
+// dismiss.
+import {
+  Dialog,
+  DialogContent,
+  ScrollView,
+  SheetModal,
+  SizableText,
+  Spinner,
+  Text,
+  XStack,
+  YStack,
+  isWeb,
+} from "@multiplatform.one/components";
+import { SearchInput } from "@multiplatform.one/forms";
+import { addToRecent } from "@multiplatform.one/frappe-ui";
+import { useLayoutSizeClass, useReadableTextOn, useResolvedKnobs } from "@multiplatform.one/theme";
+import type { ComponentProps, RefObject } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useBackofficeNavigator } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import {
+  useCommandPaletteModel,
+  type CommandPaletteItem,
+  type CommandPaletteModel,
+} from "./command-palette-model";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PANEL_WIDTH = 640;
+const RESULTS_MAX_HEIGHT = 400;
+/** Minimum press target for result rows (house 44px floor). */
+const ROW_MIN_HEIGHT = 44;
+const LISTBOX_ID = "backoffice-command-palette-listbox";
+
+const optionId = (index: number) => `backoffice-command-palette-option-${index}`;
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export interface CommandPaletteProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const { knobProps } = useResolvedKnobs();
+  const isCompact = useLayoutSizeClass() === "compact";
+  const asSheet = !isWeb || isCompact;
+
+  const [query, setQuery] = useState("");
+  const [debouncedQuery, setDebouncedQuery] = useState("");
+  const [highlight, setHighlight] = useState(0);
+
+  const model = useCommandPaletteModel({ query, debouncedQuery, open });
+  const { items } = model;
+
+  const rootRef = useRef<unknown>(null);
+  const itemNodesRef = useRef<Array<unknown>>([]);
+
+  // ── D-22 FOCUS-RETURN: render-phase capture on the opening render (before
+  // the overlay mounts and moves focus), restore on close. ─────────────────
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const wasOpenRef = useRef(false);
+  if (open && !wasOpenRef.current && isWeb && typeof document !== "undefined") {
+    restoreFocusRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  }
+  wasOpenRef.current = open;
+
+  const close = useCallback(() => {
+    setQuery("");
+    setDebouncedQuery("");
+    setHighlight(0);
+    onOpenChange(false);
+  }, [onOpenChange]);
+
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) close();
+      else onOpenChange(true);
+    },
+    [close, onOpenChange],
+  );
+
+  useEffect(() => {
+    if (open || !isWeb || typeof document === "undefined") return;
+    // Runs on close (and unmount-after-close): put focus back where it was.
+    const target = restoreFocusRef.current;
+    restoreFocusRef.current = null;
+    if (target?.isConnected) target.focus();
+  }, [open]);
+
+  // Focus the palette input on open (fallback behind the Dialog focus scope;
+  // the sheet has no scope of its own on web).
+  useEffect(() => {
+    if (!open || !isWeb || typeof document === "undefined") return;
+    const timer = setTimeout(() => {
+      const root = rootRef.current as HTMLElement | null;
+      root?.querySelector("input")?.focus();
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [open]);
+
+  // Keep the highlight on a real row as results stream in/out.
+  useEffect(() => {
+    setHighlight((current) => (current < items.length ? current : 0));
+  }, [items]);
+
+  // Keep the keyboard-highlighted row scrolled into view (web).
+  useEffect(() => {
+    if (!isWeb) return;
+    const node = itemNodesRef.current[highlight] as HTMLElement | undefined | null;
+    node?.scrollIntoView?.({ block: "nearest" });
+  }, [highlight]);
+
+  const activate = useCallback(
+    (item: CommandPaletteItem | undefined) => {
+      if (!item) return;
+      navigator.navigate(item.path);
+      addToRecent({ label: item.label, path: item.path });
+      close();
+    },
+    [navigator, close],
+  );
+
+  // ── Input key handling (roving highlight, commit, dismiss) ───────────────
+  const handleKeyDown = useCallback(
+    (event: { key?: string; nativeEvent?: { key?: string }; preventDefault?: () => void }) => {
+      const key = event.key ?? event.nativeEvent?.key;
+      if (key === "ArrowDown") {
+        event.preventDefault?.();
+        setHighlight((current) => (items.length ? (current + 1) % items.length : 0));
+      } else if (key === "ArrowUp") {
+        event.preventDefault?.();
+        setHighlight((current) => (items.length ? (current - 1 + items.length) % items.length : 0));
+      } else if (key === "Enter") {
+        event.preventDefault?.();
+        activate(items[highlight] ?? items[0]);
+      } else if (key === "Escape") {
+        event.preventDefault?.();
+        close();
+      } else if (key === "Tab") {
+        // D-23 ONE-TAB-STOP: the input is the palette's only tab stop.
+        event.preventDefault?.();
+      }
+    },
+    [items, highlight, activate, close],
+  );
+
+  // Sheet mode leaves Escape dismissal to the consumer (LC-21) — cover the
+  // case where focus is outside the input (list-tools-sheet precedent).
+  useEffect(() => {
+    if (!asSheet || !isWeb || typeof document === "undefined" || !open) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") close();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [asSheet, open, close]);
+
+  const handleChange = useCallback((text: string) => {
+    setQuery(text);
+    setHighlight(0);
+  }, []);
+
+  const handleSearch = useCallback((text: string) => {
+    setDebouncedQuery(text.trim());
+  }, []);
+
+  const handleClear = useCallback(() => {
+    setDebouncedQuery("");
+    setHighlight(0);
+  }, []);
+
+  const activeOptionId = items[highlight] ? optionId(highlight) : undefined;
+
+  const inputProps = useMemo(
+    () =>
+      ({
+        onKeyDown: handleKeyDown,
+        onSubmitEditing: () => activate(items[highlight] ?? items[0]),
+        role: "combobox",
+        "aria-expanded": true,
+        "aria-haspopup": "listbox",
+        "aria-controls": LISTBOX_ID,
+        "aria-activedescendant": activeOptionId,
+      }) as ComponentProps<typeof SearchInput>["inputProps"],
+    [handleKeyDown, activate, items, highlight, activeOptionId],
+  );
+
+  const searchInput = (
+    <SearchInput
+      value={query}
+      onChange={handleChange}
+      onSearch={handleSearch}
+      onClear={handleClear}
+      debounceMs={300}
+      size="$3"
+      placeholder={t("awesomebar.placeholder", "Search or type a command…")}
+      aria-label={t("awesomebar.label", "Search or type a command")}
+      inputProps={inputProps}
+    />
+  );
+
+  const results = (
+    <PaletteResults
+      model={model}
+      highlight={highlight}
+      onHighlight={setHighlight}
+      onActivate={activate}
+      itemNodesRef={itemNodesRef}
+    />
+  );
+
+  // ── <sm / native: full-height sheet (native search sheet pattern) ────────
+  if (asSheet) {
+    return (
+      <SheetModal
+        open={open}
+        onOpenChange={handleOpenChange}
+        snapPoint={92}
+        scrollable
+        header={
+          <YStack
+            ref={rootRef as never}
+            paddingBottom="$2"
+            data-testid="backoffice-command-palette"
+          >
+            {searchInput}
+          </YStack>
+        }
+      >
+        <YStack
+          id={LISTBOX_ID}
+          role={"listbox" as "list"}
+          aria-label={t("awesomebar.results", "Search results")}
+          paddingBottom="$4"
+          data-dismiss-class="commit"
+        >
+          {results}
+        </YStack>
+      </SheetModal>
+    );
+  }
+
+  // ── ≥sm web: centered top-anchored modal overlay ─────────────────────────
+  const topOffset = typeof window !== "undefined" ? Math.round(window.innerHeight * 0.15) : 120;
+
+  return (
+    <Dialog modal open={open} onOpenChange={handleOpenChange}>
+      <Dialog.Portal justifyContent="flex-start" alignItems="center" paddingTop={topOffset}>
+        <Dialog.Overlay
+          key="overlay"
+          backgroundColor="$shadow6"
+          transition={knobProps.transition}
+          enterStyle={{ opacity: 0 }}
+          exitStyle={{ opacity: 0 }}
+        />
+        <DialogContent
+          key="content"
+          ref={rootRef as never}
+          width={PANEL_WIDTH}
+          maxWidth="92%"
+          // SP-EDGE: the container owns only its border — the input band,
+          // rows, and footer own their insets, so row highlights run edge
+          // to edge and overflow hidden clips them to the radius.
+          padding={0}
+          gap={0}
+          overflow="hidden"
+          aria-label={t("awesomebar.label", "Search or type a command")}
+          data-dismiss-class="commit"
+          data-testid="backoffice-command-palette"
+        >
+          <YStack padding="$2.5" borderBottomWidth={1} borderBottomColor="$borderColor">
+            {searchInput}
+          </YStack>
+          <ScrollView maxHeight={RESULTS_MAX_HEIGHT}>
+            <YStack
+              id={LISTBOX_ID}
+              role={"listbox" as "list"}
+              aria-label={t("awesomebar.results", "Search results")}
+              paddingVertical="$1.5"
+            >
+              {results}
+            </YStack>
+          </ScrollView>
+          <PaletteFooter />
+        </DialogContent>
+      </Dialog.Portal>
+    </Dialog>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Shared section list (one renderer for both containers)
+// ---------------------------------------------------------------------------
+
+interface PaletteResultsProps {
+  model: CommandPaletteModel;
+  highlight: number;
+  onHighlight: (index: number) => void;
+  onActivate: (item: CommandPaletteItem) => void;
+  itemNodesRef: RefObject<Array<unknown>>;
+}
+
+function PaletteResults({
+  model,
+  highlight,
+  onHighlight,
+  onActivate,
+  itemNodesRef,
+}: PaletteResultsProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  // LC-05: the roving highlight rides the accent channel with a
+  // luminance-computed readable foreground (Sidebar active-row precedent).
+  const onAccent = useReadableTextOn("$accentBackground");
+  const { sections, searching, hasQuery, noResults } = model;
+
+  let flatIndex = -1;
+
+  return (
+    <>
+      {sections.map((section) => (
+        <YStack key={section.id} data-testid={`backoffice-palette-section-${section.id}`}>
+          <Text
+            fontSize="$1"
+            color="$color10"
+            textTransform="uppercase"
+            letterSpacing={0.5}
+            paddingHorizontal="$3"
+            paddingTop="$2.5"
+            paddingBottom="$1.5"
+            {...knobProps.body}
+          >
+            {section.label}
+          </Text>
+          {section.items.map((item) => {
+            flatIndex += 1;
+            const index = flatIndex;
+            const highlighted = index === highlight;
+            const Icon = item.icon;
+            return (
+              <XStack
+                key={item.id}
+                id={optionId(index)}
+                ref={
+                  ((node: unknown) => {
+                    itemNodesRef.current[index] = node;
+                  }) as never
+                }
+                role={"option" as "listitem"}
+                aria-selected={highlighted}
+                alignItems="center"
+                gap="$2.5"
+                paddingHorizontal="$3"
+                paddingVertical="$2"
+                minHeight={ROW_MIN_HEIGHT}
+                cursor="pointer"
+                backgroundColor={highlighted ? "$accentBackground" : "transparent"}
+                hoverStyle={{
+                  backgroundColor: highlighted ? "$accentBackground" : "$color3",
+                }}
+                pressStyle={{ backgroundColor: "$accentBackground" }}
+                onPress={() => onActivate(item)}
+                onMouseEnter={() => onHighlight(index)}
+              >
+                {/* LC-08: one uniform leading media slot */}
+                <XStack width={20} justifyContent="center" flexShrink={0}>
+                  <Icon size={16} color={highlighted && onAccent ? onAccent : undefined} />
+                </XStack>
+                <YStack flex={1} minWidth={0}>
+                  <Text
+                    numberOfLines={1}
+                    fontSize="$3"
+                    color={highlighted && onAccent ? onAccent : "$color12"}
+                    {...knobProps.body}
+                  >
+                    {item.label}
+                  </Text>
+                  {item.description ? (
+                    <Text
+                      numberOfLines={1}
+                      fontSize="$2"
+                      color={highlighted && onAccent ? onAccent : "$color10"}
+                      opacity={highlighted ? 0.8 : 1}
+                      {...knobProps.body}
+                    >
+                      {item.description}
+                    </Text>
+                  ) : null}
+                </YStack>
+                {item.badge ? (
+                  <XStack
+                    borderWidth={1}
+                    borderColor={highlighted && onAccent ? onAccent : "$borderColor"}
+                    borderRadius="$2"
+                    paddingHorizontal="$1.5"
+                    paddingVertical={2}
+                    flexShrink={0}
+                    opacity={highlighted ? 0.9 : 1}
+                  >
+                    <Text
+                      fontSize="$1"
+                      color={highlighted && onAccent ? onAccent : "$color10"}
+                      {...knobProps.body}
+                    >
+                      {item.badge}
+                    </Text>
+                  </XStack>
+                ) : null}
+              </XStack>
+            );
+          })}
+        </YStack>
+      ))}
+
+      {hasQuery && searching && (
+        <XStack alignItems="center" gap="$2.5" paddingHorizontal="$3" paddingVertical="$2">
+          <Spinner size="small" color="$color10" />
+          <Text fontSize="$2" color="$color10" {...knobProps.body}>
+            {t("awesomebar.searching", "Searching…")}
+          </Text>
+        </XStack>
+      )}
+
+      {noResults && (
+        <XStack paddingHorizontal="$3" paddingVertical="$3">
+          <Text fontSize="$2" color="$color10" {...knobProps.body}>
+            {t("awesomebar.noResults", {
+              defaultValue: "No results for “{{query}}”",
+              query: model.query,
+            })}
+          </Text>
+        </XStack>
+      )}
+
+      {!hasQuery && sections.length === 0 && (
+        <XStack paddingHorizontal="$3" paddingVertical="$3">
+          <Text fontSize="$2" color="$color10" {...knobProps.body}>
+            {t("awesomebar.empty", "Type to search…")}
+          </Text>
+        </XStack>
+      )}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Footer hint bar (overlay container only — keyboard hints, DG discoverable)
+// ---------------------------------------------------------------------------
+
+function KeyCap({ label }: { label: string }) {
+  return (
+    <XStack
+      borderWidth={1}
+      borderColor="$borderColor"
+      backgroundColor="$color2"
+      borderRadius="$2"
+      paddingHorizontal="$1.5"
+      justifyContent="center"
+    >
+      <SizableText size="$1" fontWeight="600" color="$color11">
+        {label}
+      </SizableText>
+    </XStack>
+  );
+}
+
+function PaletteFooter() {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  return (
+    <XStack
+      alignItems="center"
+      gap="$3"
+      paddingHorizontal="$3"
+      paddingVertical="$2"
+      borderTopWidth={1}
+      borderTopColor="$borderColor"
+    >
+      <XStack alignItems="center" gap="$1.5">
+        <KeyCap label="↑↓" />
+        <SizableText size="$1" color="$color10">
+          {t("awesomebar.hintNavigate", "navigate")}
+        </SizableText>
+      </XStack>
+      <XStack alignItems="center" gap="$1.5">
+        <KeyCap label="↵" />
+        <SizableText size="$1" color="$color10">
+          {t("awesomebar.hintOpen", "open")}
+        </SizableText>
+      </XStack>
+      <XStack alignItems="center" gap="$1.5">
+        <KeyCap label="esc" />
+        <SizableText size="$1" color="$color10">
+          {t("awesomebar.hintClose", "close")}
+        </SizableText>
+      </XStack>
+    </XStack>
+  );
+}

package/src/chrome/HelpMenu.tsx

@@ -0,0 +1,119 @@
+// Navbar help dropdown (docs, keyboard shortcuts dialog, about; desk parity).
+//
+// Desk parity items: Documentation, User Forum, Report an Issue (external,
+// via the platform-split openUrl — web new tab / native Linking / GNOME Gio),
+// Keyboard Shortcuts and About (dialogs, all platforms). Dialogs are mounted
+// as siblings of the popover so they survive the menu closing.
+import { Button, Popover, PopoverContent, Separator, YStack } from "@multiplatform.one/components";
+import { openUrl } from "@multiplatform.one/platform";
+import {
+  BookOpenIcon,
+  BugIcon,
+  ChatsCircleIcon,
+  InfoIcon,
+  KeyboardIcon,
+  QuestionIcon,
+} from "@phosphor-icons/react";
+import { useState, type ComponentProps } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { HelpAboutDialog } from "./help-about-dialog";
+import { HelpShortcutsDialog } from "./help-shortcuts-dialog";
+
+const DOCUMENTATION_URL = "https://docs.frappe.io";
+const USER_FORUM_URL = "https://discuss.frappe.io";
+const REPORT_ISSUE_URL = "https://github.com/frappe/frappe/issues";
+
+interface HelpMenuItemProps {
+  icon: ComponentProps<typeof Button>["icon"];
+  label: string;
+  onPress: () => void;
+  testID: string;
+}
+
+function HelpMenuItem({ icon, label, onPress, testID }: HelpMenuItemProps) {
+  return (
+    <Button
+      chromeless
+      size="$3"
+      icon={icon}
+      justifyContent="flex-start"
+      width="100%"
+      onPress={onPress}
+      data-testid={testID}
+    >
+      {label}
+    </Button>
+  );
+}
+
+export function HelpMenu() {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [aboutOpen, setAboutOpen] = useState(false);
+  const [shortcutsOpen, setShortcutsOpen] = useState(false);
+
+  const openLink = (url: string) => {
+    setMenuOpen(false);
+    openUrl(url, "_blank");
+  };
+
+  const openDialog = (setOpen: (open: boolean) => void) => {
+    setMenuOpen(false);
+    setOpen(true);
+  };
+
+  return (
+    <>
+      <Popover open={menuOpen} onOpenChange={setMenuOpen} placement="bottom-end" stayInFrame>
+        <Popover.Trigger asChild>
+          <Button
+            chromeless
+            circular
+            size="$3"
+            icon={QuestionIcon}
+            aria-label={t("help.label", "Help")}
+            data-testid="backoffice-help-trigger"
+          />
+        </Popover.Trigger>
+        <PopoverContent padding="$2" data-testid="backoffice-help-menu">
+          <YStack minWidth={220}>
+            <HelpMenuItem
+              icon={BookOpenIcon}
+              label={t("help.documentation", "Documentation")}
+              onPress={() => openLink(DOCUMENTATION_URL)}
+              testID="backoffice-help-documentation"
+            />
+            <HelpMenuItem
+              icon={ChatsCircleIcon}
+              label={t("help.userForum", "User Forum")}
+              onPress={() => openLink(USER_FORUM_URL)}
+              testID="backoffice-help-forum"
+            />
+            <HelpMenuItem
+              icon={BugIcon}
+              label={t("help.reportIssue", "Report an Issue")}
+              onPress={() => openLink(REPORT_ISSUE_URL)}
+              testID="backoffice-help-report-issue"
+            />
+            <Separator marginVertical="$1" />
+            <HelpMenuItem
+              icon={KeyboardIcon}
+              label={t("help.keyboardShortcuts", "Keyboard Shortcuts")}
+              onPress={() => openDialog(setShortcutsOpen)}
+              testID="backoffice-help-shortcuts"
+            />
+            <HelpMenuItem
+              icon={InfoIcon}
+              label={t("help.about", "About")}
+              onPress={() => openDialog(setAboutOpen)}
+              testID="backoffice-help-about"
+            />
+          </YStack>
+        </PopoverContent>
+      </Popover>
+      <HelpShortcutsDialog open={shortcutsOpen} onOpenChange={setShortcutsOpen} />
+      <HelpAboutDialog open={aboutOpen} onOpenChange={setAboutOpen} />
+    </>
+  );
+}