@multiplatform.one/frappe-ui 7.23.1 → 7.24.0

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);
+}

package/src/list/RecordCard.native.tsx

@@ -0,0 +1,126 @@
+import { Card, Text, XStack, YStack } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { HeartIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { FacetBadge } from "./FacetBadge";
+import { ImageWell } from "./ImageWell";
+import type { RecordCardProps } from "./RecordCard";
+
+export type { RecordCardBadge, RecordCardProps } from "./RecordCard";
+
+/**
+ * Native twin of RecordCard. On React Native an Anchor is a Text node whose
+ * press the Card (a View with its own responder) claims, so the card's
+ * press sits on the Card itself and the heart stops it from bubbling there.
+ */
+export function RecordCard({
+  title,
+  subtitle,
+  code,
+  images,
+  tints,
+  badges = [],
+  onPress,
+  favorite,
+  testID,
+  favoriteTestID,
+}: RecordCardProps) {
+  const { t } = useTranslation();
+  const { knobProps, elevation: elevationState } = useResolvedKnobs({ component: "Card" });
+
+  const handleToggleFavorite = (event?: { stopPropagation?: () => void }) => {
+    event?.stopPropagation?.();
+    favorite?.toggle();
+  };
+
+  return (
+    <Card
+      testID={testID}
+      {...knobProps.cardSurface}
+      elevation={knobProps.elevation}
+      transition={knobProps.transition}
+      pressStyle={{ scale: 0.98, ...elevationState.pressKnobProps }}
+      role="button"
+      aria-label={title}
+      onPress={() => onPress?.()}
+    >
+      <YStack gap="$1.5">
+        <YStack position="relative">
+          <ImageWell sources={images} alt={title} tints={tints} inset={0.04} />
+          {code ? (
+            <XStack
+              position="absolute"
+              top="$2"
+              left="$2"
+              {...knobProps.borderRadius}
+              borderWidth={0}
+              backgroundColor="$background08"
+              paddingHorizontal="$1.5"
+              paddingVertical="$0.5"
+              zIndex={1}
+            >
+              <Text fontSize="$1" fontWeight="800" letterSpacing={1} color="$color12">
+                {code}
+              </Text>
+            </XStack>
+          ) : null}
+          {favorite ? (
+            <XStack position="absolute" top="$1" right="$1" zIndex={2}>
+              <Button
+                size="$3"
+                circular
+                chromeless
+                minWidth={knobProps.sizeToken}
+                minHeight={knobProps.sizeToken}
+                transition={knobProps.transition}
+                backgroundColor="$background08"
+                pressStyle={{ backgroundColor: "$background", scale: 0.92 }}
+                onPress={handleToggleFavorite}
+                col={(favorite.active ? "$red9" : "$color11") as never}
+                icon={<HeartIcon size={20} weight={favorite.active ? "fill" : "regular"} />}
+                aria-label={
+                  favorite.active
+                    ? t("Remove {{name}} from favorites", { name: title })
+                    : t("Add {{name}} to favorites", { name: title })
+                }
+                aria-pressed={favorite.active}
+                testID={favoriteTestID}
+              />
+            </XStack>
+          ) : null}
+          {badges.length > 0 ? (
+            <XStack
+              position="absolute"
+              bottom="$2"
+              left="$2"
+              right="$2"
+              gap="$1.5"
+              flexWrap="wrap"
+              zIndex={1}
+              pointerEvents="none"
+            >
+              {badges.map((badge) => (
+                <FacetBadge key={badge.value} label={badge.label} tint={badge.tint} compact />
+              ))}
+            </XStack>
+          ) : null}
+        </YStack>
+        <YStack gap="$0.5">
+          <Text
+            {...knobProps.heading}
+            fontWeight="700"
+            fontSize="$4"
+            numberOfLines={1}
+            color="$color12"
+          >
+            {title}
+          </Text>
+          <Text {...knobProps.body} fontSize="$2" color="$color10" numberOfLines={1}>
+            {subtitle || " "}
+          </Text>
+        </YStack>
+      </YStack>
+    </Card>
+  );
+}