@multiplatform.one/frappe-ui 7.23.2 → 7.24.0

package/src/list/FacetRail.tsx

@@ -0,0 +1,235 @@
+import { ScrollView, Text, XStack, isWeb } from "@multiplatform.one/components";
+import {
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  pressTargetHitSlop,
+  transitionProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { useRef, useState } from "react";
+
+export interface FacetRailOption {
+  /** Facet value; "" is the chip that clears the facet. */
+  value: string;
+  label: string;
+  /** Theme hue (`"grass"`) painting the chip from its ramp. */
+  tint?: string;
+  count?: number;
+}
+
+export interface FacetRailProps {
+  /** Names the radiogroup. */
+  label: string;
+  /** Active value, or "" for none. */
+  value: string;
+  options: readonly FacetRailOption[];
+  onChange: (value: string) => void;
+  testID?: string;
+}
+
+interface RailChipProps {
+  option: FacetRailOption;
+  selected: boolean;
+  tabStop: boolean;
+  onPress: () => void;
+  onFocusChip: () => void;
+  onBlurChip: () => void;
+  onMove: (direction: -1 | 1 | "home" | "end") => void;
+  testID?: string;
+  register: (node: { focus?: () => void } | null) => void;
+}
+
+// Chips paint a notch under the ~40px toolbar controls; hitSlop restores the
+// 44px press target (DG-LAY-04, ViewSwitcher precedent).
+const chipVisualHeight = 38;
+const chipHitSlop = pressTargetHitSlop(chipVisualHeight);
+const pipSize = "$1";
+
+/**
+ * One chip. Neutral until active; the active chip fills from its tint ramp
+ * (DF-04 pairing: tint fill, step-12 text), so selected is fill, never a
+ * sibling border (LC-71). An unselected tinted chip carries a hue pip.
+ */
+function RailChip({
+  option,
+  selected,
+  tabStop,
+  onPress,
+  onFocusChip,
+  onBlurChip,
+  onMove,
+  testID,
+  register,
+}: RailChipProps) {
+  const { knobProps } = useResolvedKnobs();
+  const [kbFocus, setKbFocus] = useState(false);
+  if (isWeb) ensureKeyboardModalityTracking();
+  const hue = option.tint;
+  const fill = selected ? (hue ? `$${hue}5` : "$color5") : hue ? `$${hue}3` : "$color3";
+  const hoverFill = selected ? fill : hue ? `$${hue}4` : "$color4";
+  const textColor = selected ? (hue ? `$${hue}12` : "$color12") : hue ? `$${hue}11` : "$color11";
+  const keys: Record<string, -1 | 1 | "home" | "end"> = {
+    ArrowRight: 1,
+    ArrowLeft: -1,
+    Home: "home",
+    End: "end",
+  };
+
+  return (
+    <XStack
+      ref={register}
+      {...knobProps.borderRadius}
+      backgroundColor={fill as never}
+      borderWidth={0}
+      paddingHorizontal="$3"
+      minHeight={chipVisualHeight}
+      hitSlop={chipHitSlop}
+      alignItems="center"
+      gap="$1.5"
+      cursor="pointer"
+      role="radio"
+      aria-checked={selected}
+      {...(isWeb ? { tabIndex: tabStop ? 0 : -1 } : undefined)}
+      {...transitionProps(knobProps.transition)}
+      hoverStyle={{ backgroundColor: hoverFill as never }}
+      pressStyle={{ backgroundColor: fill as never }}
+      outlineWidth={0}
+      focusStyle={{ outlineWidth: 0, backgroundColor: fill as never }}
+      focusVisibleStyle={{ outlineWidth: 0 }}
+      {...(isWeb
+        ? {
+            onFocus: () => {
+              onFocusChip();
+              if (wasKeyboardFocus()) setKbFocus(true);
+            },
+            onBlur: () => {
+              onBlurChip();
+              setKbFocus(false);
+            },
+            onKeyDown: (event: { key?: string; preventDefault?: () => void }) => {
+              const direction = event.key ? keys[event.key] : undefined;
+              if (direction !== undefined) {
+                event.preventDefault?.();
+                onMove(direction);
+                return;
+              }
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault?.();
+                onPress();
+              }
+            },
+          }
+        : undefined)}
+      {...(kbFocus ? keyboardFocusRingProps : undefined)}
+      onPress={onPress}
+      testID={testID}
+    >
+      {hue ? (
+        <XStack
+          width={pipSize}
+          height={pipSize}
+          borderRadius={1000}
+          backgroundColor={`$${hue}9` as never}
+          flexShrink={0}
+        />
+      ) : null}
+      <Text
+        {...knobProps.label}
+        fontWeight={selected ? "700" : "500"}
+        color={textColor as never}
+        textTransform="capitalize"
+        userSelect="none"
+      >
+        {option.label}
+      </Text>
+      {typeof option.count === "number" ? (
+        <Text
+          {...knobProps.label}
+          fontSize="$1"
+          fontWeight="700"
+          color={textColor as never}
+          opacity={0.7}
+          userSelect="none"
+        >
+          {option.count}
+        </Text>
+      ) : null}
+    </XStack>
+  );
+}
+
+/**
+ * A single-select facet as a horizontally scrolling chip rail. One tap
+ * narrows, a second tap on the active chip clears. One tab stop (LC-49):
+ * arrows, Home and End move and select like a radiogroup, and the focused
+ * chip paints the only ring (LC-71). Scrolls on narrow viewports instead of
+ * wrapping into a wall of chips.
+ */
+export function FacetRail({ label, value, options, onChange, testID }: FacetRailProps) {
+  const itemRefs = useRef<Record<string, { focus?: () => void } | null>>({});
+  const [focusValue, setFocusValue] = useState<string | null>(null);
+  if (isWeb) ensureKeyboardModalityTracking();
+
+  const anchor =
+    focusValue !== null && options.some((option) => option.value === focusValue)
+      ? focusValue
+      : value;
+
+  const focusAndSelect = (next: string) => {
+    setFocusValue(next);
+    onChange(next);
+    if (!isWeb) return;
+    requestAnimationFrame(() => {
+      const node = itemRefs.current[next] as
+        | ({ focus?: () => void } & { scrollIntoView?: (options: object) => void })
+        | null;
+      node?.focus?.();
+      node?.scrollIntoView?.({ inline: "nearest", block: "nearest" });
+    });
+  };
+
+  const moveFrom = (from: string, direction: -1 | 1 | "home" | "end") => {
+    if (options.length === 0) return;
+    if (direction === "home") return focusAndSelect(options[0].value);
+    if (direction === "end") return focusAndSelect(options[options.length - 1].value);
+    const index = Math.max(
+      0,
+      options.findIndex((option) => option.value === from),
+    );
+    focusAndSelect(options[(index + direction + options.length) % options.length].value);
+  };
+
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false} flexShrink={0}>
+      <XStack
+        role="radiogroup"
+        aria-label={label}
+        aria-orientation="horizontal"
+        gap="$1.5"
+        alignItems="center"
+        paddingVertical="$1"
+        testID={testID}
+      >
+        {options.map((option) => (
+          <RailChip
+            key={option.value || "__all"}
+            option={option}
+            selected={option.value === value}
+            tabStop={option.value === anchor}
+            onPress={() =>
+              onChange(option.value === value && option.value !== "" ? "" : option.value)
+            }
+            onFocusChip={() => setFocusValue(option.value)}
+            onBlurChip={() => setFocusValue((prev) => (prev === option.value ? null : prev))}
+            onMove={(direction) => moveFrom(option.value, direction)}
+            testID={testID ? `${testID}-${option.value || "all"}` : undefined}
+            register={(node) => {
+              itemRefs.current[option.value] = node;
+            }}
+          />
+        ))}
+      </XStack>
+    </ScrollView>
+  );
+}

package/src/list/ImageWell.tsx

@@ -0,0 +1,110 @@
+import {
+  Image,
+  Text,
+  XStack,
+  YStack,
+  isWeb,
+  type YStackProps,
+} from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useEffect, useState } from "react";
+
+export interface ImageWellProps extends Omit<YStackProps, "children"> {
+  /** Candidate URLs in order; a failed load moves to the next. */
+  sources: readonly string[];
+  alt: string;
+  /**
+   * Theme hues (`"grass"`) painting the well from their ramps: one fills it,
+   * two split it down the middle.
+   */
+  tints?: readonly (string | undefined)[];
+  /** Nearest-neighbor upscaling, for pixel art. */
+  pixelated?: boolean;
+  /** Gap between the well's edge and the image, as a fraction of its width. */
+  inset?: number;
+  /** Fetch only as the image nears the viewport (web). */
+  lazy?: boolean;
+}
+
+/**
+ * A square image well: a tinted surface (the tint is data, from the theme's
+ * ramps) holding an image that walks its candidate list on error and fades
+ * in on web, with a "?" when every candidate fails.
+ */
+export function ImageWell({
+  sources,
+  alt,
+  tints,
+  pixelated = false,
+  inset = 0.06,
+  lazy = false,
+  ...wellProps
+}: ImageWellProps) {
+  const { knobProps } = useResolvedKnobs();
+  const [sourceIndex, setSourceIndex] = useState(0);
+  const [revealedSrc, setRevealedSrc] = useState<string | null>(null);
+  const hue = tints?.[0] ?? "gray";
+  const secondHue = tints?.[1];
+
+  const sourceKey = sources.join("|");
+  useEffect(() => {
+    setSourceIndex(0);
+  }, [sourceKey]);
+
+  const src = sources[sourceIndex] ?? "";
+  // onLoad can be missed for a cached or server-rendered image, so a short
+  // timer reveals it anyway: a slow image may pop, but none stays invisible.
+  const revealed = !isWeb || !src || revealedSrc === src;
+  useEffect(() => {
+    if (!isWeb || !src || revealedSrc === src) return;
+    const timer = setTimeout(() => setRevealedSrc(src), 350);
+    return () => clearTimeout(timer);
+  }, [src, revealedSrc]);
+
+  const imageSize = `${Math.round((1 - inset * 2) * 100)}%`;
+
+  return (
+    <YStack
+      {...knobProps.borderRadius}
+      borderWidth={0}
+      backgroundColor={secondHue ? "transparent" : (`$${hue}5` as never)}
+      aspectRatio={1}
+      width="100%"
+      alignItems="center"
+      justifyContent="center"
+      overflow="hidden"
+      position="relative"
+      {...wellProps}
+    >
+      {secondHue ? (
+        <XStack fullscreen zIndex={0} pointerEvents="none">
+          <YStack flex={1} backgroundColor={`$${hue}5` as never} />
+          <YStack flex={1} backgroundColor={`$${secondHue}5` as never} />
+        </XStack>
+      ) : null}
+      {src ? (
+        <Image
+          key={src}
+          src={src}
+          alt={alt}
+          width={imageSize as never}
+          height={imageSize as never}
+          objectFit="contain"
+          opacity={revealed ? 1 : 0}
+          transition={knobProps.transition}
+          zIndex={1}
+          {...((isWeb ? { loading: lazy ? "lazy" : "eager", decoding: "async" } : undefined) as
+            | Record<string, unknown>
+            | undefined)}
+          {...(pixelated && isWeb ? { style: { imageRendering: "pixelated" } as never } : null)}
+          onLoad={() => setRevealedSrc(src)}
+          onError={() => setSourceIndex((index) => index + 1)}
+        />
+      ) : (
+        <Text fontSize="$10" color={`$${hue}8` as never} fontWeight="700" aria-hidden zIndex={1}>
+          ?
+        </Text>
+      )}
+    </YStack>
+  );
+}

package/src/list/ListControls.tsx

@@ -0,0 +1,208 @@
+import { Badge, Separator, Tooltip, XStack, YStack } from "@multiplatform.one/components";
+import { Button, SearchInput, Select } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { DiceFiveIcon, HeartIcon } from "@phosphor-icons/react";
+import type React from "react";
+import { useTranslation } from "react-i18next";
+import { FacetRail } from "./FacetRail";
+import { isListNarrowed, type FrappeListControls } from "./listState";
+import { RangeFilter, rangeCeiling } from "./RangeFilter";
+import type { ListControlsResult } from "./useListControls";
+
+export interface ListControlsProps {
+  controls: FrappeListControls;
+  list: ListControlsResult;
+  /** DOM id of the search box's wrapper, which the "/" shortcut focuses. */
+  searchId: string;
+  searchPlaceholder?: string;
+  showSearch: boolean;
+  showFavorites: boolean;
+  /** Present when the list offers a random pick. */
+  shuffle?: { open: boolean; toggle: () => void; panelId: string };
+  /** The random pick, under the search row while open. */
+  shufflePanel?: React.ReactNode;
+  /** A hairline under the band, when the list below paints no surface. */
+  separator: boolean;
+  testID: string;
+}
+
+const searchBasis = 260;
+const searchMinWidth = 220;
+const sortMinWidth = 170;
+const rangeMaxWidth = 340;
+
+/**
+ * The band above a list: search growing on the left, sort, favorites and
+ * shuffle anchored right; then one chip rail per facet; then the range
+ * sliders with Clear filters. Under sm the search takes its own row.
+ */
+export function ListControls({
+  controls,
+  list,
+  searchId,
+  searchPlaceholder,
+  showSearch,
+  showFavorites,
+  shuffle,
+  shufflePanel,
+  separator,
+  testID,
+}: ListControlsProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const { state, update, favorites } = list;
+  const sorts = controls.sorts ?? [];
+  const narrowed = isListNarrowed(state);
+  const favoritesLabel = t("Favorites");
+
+  return (
+    <>
+      <YStack {...knobProps.gap} testID={`${testID}-controls`}>
+        <XStack
+          {...knobProps.gap}
+          alignItems="center"
+          flexWrap="wrap"
+          justifyContent="space-between"
+        >
+          {showSearch ? (
+            <XStack
+              id={searchId}
+              flexGrow={1}
+              flexShrink={1}
+              flexBasis={searchBasis}
+              minWidth={searchMinWidth}
+              alignItems="center"
+              $max-sm={{ flexBasis: "100%", maxWidth: "100%" }}
+            >
+              <YStack flexGrow={1} flexShrink={1} minWidth={0}>
+                <SearchInput
+                  value={list.searchText}
+                  onChange={list.setSearchText}
+                  onSearch={(text) => update({ search: text })}
+                  placeholder={searchPlaceholder ?? t("Search...")}
+                  aria-label={searchPlaceholder ?? t("Search...")}
+                  debounceMs={200}
+                  compact
+                  clearable
+                />
+              </YStack>
+            </XStack>
+          ) : null}
+          <XStack
+            {...knobProps.gap}
+            alignItems="center"
+            flexWrap="wrap"
+            $max-sm={{ width: "100%" }}
+          >
+            {sorts.length > 0 ? (
+              <XStack minWidth={sortMinWidth} flexGrow={1} flexShrink={1}>
+                <Select
+                  value={state.sort}
+                  onChange={(value) => update({ sort: String(value) })}
+                  options={sorts.map((sort) => ({ label: sort.label, value: sort.value }))}
+                  placeholder={t("Sort by")}
+                  aria-label={t("Sort by")}
+                />
+              </XStack>
+            ) : null}
+            {showFavorites ? (
+              <Badge count={favorites.count}>
+                <Tooltip content={t("Show only your favorites")}>
+                  <Button
+                    outlined={!state.favoritesOnly}
+                    theme={state.favoritesOnly ? "accent" : undefined}
+                    onPress={() => update({ favoritesOnly: !state.favoritesOnly })}
+                    aria-pressed={state.favoritesOnly}
+                    aria-label={
+                      favorites.count > 0
+                        ? t("Favorites ({{count}})", { count: favorites.count })
+                        : favoritesLabel
+                    }
+                    icon={<HeartIcon size={16} weight={state.favoritesOnly ? "fill" : "regular"} />}
+                    testID={`${testID}-favorites-filter`}
+                  >
+                    {favoritesLabel}
+                  </Button>
+                </Tooltip>
+              </Badge>
+            ) : null}
+            {shuffle ? (
+              <Tooltip content={t("Open a random record")}>
+                <Button
+                  outlined={!shuffle.open}
+                  theme={shuffle.open ? "accent" : undefined}
+                  circular
+                  onPress={shuffle.toggle}
+                  icon={<DiceFiveIcon size={16} />}
+                  aria-label={t("Surprise me")}
+                  aria-expanded={shuffle.open}
+                  aria-controls={shuffle.panelId}
+                  testID={`${testID}-shuffle-toggle`}
+                />
+              </Tooltip>
+            ) : null}
+          </XStack>
+        </XStack>
+        {shufflePanel}
+        {(controls.facets ?? []).map((facet) => {
+          const reading = list.facets[facet.param];
+          return (
+            <FacetRail
+              key={facet.param}
+              label={facet.label}
+              value={state.facets[facet.param] ?? ""}
+              onChange={(value) => update({ facets: { [facet.param]: value } })}
+              testID={`${testID}-${facet.param}`}
+              options={[
+                {
+                  value: "",
+                  label: facet.allLabel ?? t("All"),
+                  count: list.total,
+                },
+                ...facet.options.map((value) => ({
+                  value,
+                  label: facet.optionLabel?.(value) ?? value,
+                  tint: facet.tint?.(value),
+                  count: reading?.counts[value],
+                })),
+              ]}
+            />
+          );
+        })}
+        {(controls.ranges?.length ?? 0) > 0 || narrowed ? (
+          <XStack
+            {...knobProps.gap}
+            alignItems="center"
+            flexWrap="wrap"
+            justifyContent="space-between"
+          >
+            {(controls.ranges ?? []).map((range) => (
+              <XStack
+                key={range.param}
+                maxWidth={rangeMaxWidth}
+                flexGrow={1}
+                $max-sm={{ maxWidth: "100%", width: "100%" }}
+              >
+                <RangeFilter
+                  label={range.label}
+                  value={state.ranges[range.param] ?? 0}
+                  max={rangeCeiling(list.highest[range.param] ?? 0)}
+                  step={range.step}
+                  onChange={(value) => update({ ranges: { [range.param]: value } })}
+                />
+              </XStack>
+            ))}
+            <XStack {...knobProps.gap} alignItems="center" flexShrink={0}>
+              {narrowed ? (
+                <Button size="$2" chromeless onPress={list.clear} testID={`${testID}-clear`}>
+                  {t("Clear filters")}
+                </Button>
+              ) : null}
+            </XStack>
+          </XStack>
+        ) : null}
+      </YStack>
+      {separator ? <Separator /> : null}
+    </>
+  );
+}

package/src/list/ListToastHost.tsx

@@ -0,0 +1,27 @@
+import { Suspense, lazy, type ComponentType } from "react";
+
+// The house ToastViewport rides the @tamagui/toast portal machinery, which
+// the curated GNOME components shim omits. Resolve it lazily and check the
+// barrel: a target without it renders nothing instead of dragging portals
+// into the eager module graph.
+const ToastViewportLazy = lazy(async () => {
+  const components = await import("@multiplatform.one/components");
+  const Viewport = (components as Partial<typeof components>).ToastViewport as
+    | ComponentType<object>
+    | undefined;
+  const Absent: ComponentType<object> = () => null;
+  return { default: Viewport ?? Absent };
+});
+
+/**
+ * A list page's toast viewport, for its favorites feedback. `showToast`
+ * writes to a module store either way; a host without a root viewport (the
+ * One app mounts none) would otherwise never paint the entries.
+ */
+export function ListToastHost() {
+  return (
+    <Suspense fallback={null}>
+      <ToastViewportLazy />
+    </Suspense>
+  );
+}

package/src/list/RangeFilter.tsx

@@ -0,0 +1,83 @@
+import { Text, XStack, YStack } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Suspense, lazy, type ComponentType } from "react";
+import { useTranslation } from "react-i18next";
+
+export interface RangeFilterProps {
+  label: string;
+  /** Current minimum; 0 is no minimum. */
+  value: number;
+  /** Upper bound of the slider. */
+  max: number;
+  step?: number;
+  onChange: (value: number) => void;
+}
+
+const readoutWidth = 44;
+const trackMinWidth = 100;
+
+// The forms Slider is not in the curated GNOME forms shim, so the row
+// resolves lazily and checks the barrel: a target without a Slider renders
+// no row (a label without its control is worse than nothing).
+const RangeRowLazy = lazy(async () => {
+  const forms = await import("@multiplatform.one/forms");
+  const MaybeSlider = (forms as Partial<typeof forms>).Slider;
+  if (!MaybeSlider) {
+    const Absent: ComponentType<RangeFilterProps> = () => null;
+    return { default: Absent };
+  }
+  const Slider = MaybeSlider;
+
+  function RangeRow({ label, value, max, step = 5, onChange }: RangeFilterProps) {
+    const { t } = useTranslation();
+    const { knobProps } = useResolvedKnobs();
+    return (
+      <XStack {...knobProps.gap} alignItems="center" flexGrow={1} minWidth={0}>
+        <Text fontSize="$2" color="$color11" flexShrink={0} userSelect="none">
+          {label}
+        </Text>
+        {/* A column on purpose: the Slider's %-width chain collapses to 0
+            inside a row; a column's cross-axis stretch hands the track the
+            flexed width. */}
+        <YStack flexGrow={1} flexShrink={1} minWidth={trackMinWidth} justifyContent="center">
+          <Slider
+            value={[value]}
+            min={0}
+            max={max}
+            step={step}
+            onChange={(values) => {
+              if (typeof values[0] === "number") onChange(values[0]);
+            }}
+            aria-label={label}
+            compact
+          />
+        </YStack>
+        <Text
+          fontSize="$2"
+          fontWeight="600"
+          color={value > 0 ? "$color12" : "$color10"}
+          minWidth={readoutWidth}
+          textAlign="right"
+          userSelect="none"
+        >
+          {value > 0 ? `${value}+` : t("Any")}
+        </Text>
+      </XStack>
+    );
+  }
+  return { default: RangeRow };
+});
+
+/** A "minimum value" filter for a numeric field: label, slider, readout. */
+export function RangeFilter(props: RangeFilterProps) {
+  return (
+    <Suspense fallback={null}>
+      <RangeRowLazy {...props} />
+    </Suspense>
+  );
+}
+
+/** A slider ceiling that follows the data, rounded up to a tidy stop. */
+export function rangeCeiling(highest: number, stop = 25, floor = 50): number {
+  return Math.max(floor, Math.ceil(Math.max(0, highest) / stop) * stop);
+}