@gogitcms/design-system 0.15.0-next.3

package/src/components/MediaField.tsx

@@ -0,0 +1,670 @@
+import React from "react";
+import { View, Pressable, Modal, ScrollView, ActivityIndicator, TextInput } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+import { Icon } from "./Icon";
+import { Button } from "./Button";
+import { MediaPreview, MediaChip, fileName } from "./MediaPreview";
+import {
+  MediaApi,
+  MediaAsset,
+  MediaKind,
+  MediaResolution,
+  MediaValue,
+  StoreAs,
+  isMediaValue,
+  formatBytes,
+  kindIcon,
+} from "../media";
+
+// The media picker control, for both value shapes a media field can hold:
+//
+//   string  — a path, in whichever form the field's `store_as` declares. Needs
+//             resolution to find the asset it names, because the same file can
+//             be written as a repo path, a public path, or a CDN URL.
+//   object  — {id, public_path, cdn_path}. Carries the asset id, so no
+//             resolution is needed and no ambiguity is possible.
+//
+// Resolution is a read-only side channel: this component never rewrites a string
+// it merely resolved. The stored value changes only when the author picks a
+// different asset, and then it is written in the field's declared form.
+
+// MediaContext carries the host's data seam down to the field controls, which
+// sit several layers inside ContentBrowser's render tree. Null means no host
+// wiring (or no object store), which renders media fields read-only.
+const MediaContext = React.createContext<MediaApi | null>(null);
+
+export function MediaProvider({ api, children }: { api?: MediaApi; children: React.ReactNode }) {
+  return <MediaContext.Provider value={api ?? null}>{children}</MediaContext.Provider>;
+}
+
+export function useMediaApi(): MediaApi | null {
+  return React.useContext(MediaContext);
+}
+
+// DocumentPathContext carries the open document's file path to media fields at
+// any nesting depth. It is separate from MediaContext because it is per-document
+// and MediaContext is per-repository: the desktop browser has several documents
+// open at once, so a single root value could not be right for all of them.
+const DocumentPathContext = React.createContext<string | undefined>(undefined);
+
+export function DocumentPathProvider({ path, children }: { path?: string; children: React.ReactNode }) {
+  return <DocumentPathContext.Provider value={path}>{children}</DocumentPathContext.Provider>;
+}
+
+export type MediaFieldProps = {
+  value: unknown;
+  onChange: (value: unknown) => void;
+  // Which value shape this field stores, from its schema type. It comes from the
+  // config rather than being inferred from the current value, because an empty
+  // object field and an empty string field look identical at runtime — and
+  // guessing would write the wrong shape into the document on first pick.
+  shape: "string" | "object";
+  // The media set this field browses, from the config's display.media.
+  set?: string;
+  // Which form a string field writes. Ignored for the object form, which stores
+  // the asset id.
+  storeAs?: StoreAs;
+  // Restrict the picker to particular render kinds.
+  kinds?: MediaKind[];
+  // The document's path, needed to interpret relative references correctly.
+  // Falls back to DocumentPathProvider, which is how nested fields (inside a
+  // group or a list item) get it without every level drilling the prop.
+  documentPath?: string;
+  readOnly?: boolean;
+  error?: boolean;
+};
+
+export function MediaField({
+  value,
+  onChange,
+  shape,
+  set,
+  storeAs = "public",
+  kinds,
+  documentPath: documentPathProp,
+  readOnly,
+  error,
+}: MediaFieldProps) {
+  const t = useTheme();
+  const api = useMediaApi();
+  const contextPath = React.useContext(DocumentPathContext);
+  const documentPath = documentPathProp ?? contextPath;
+  const [picking, setPicking] = React.useState(false);
+  const [resolution, setResolution] = React.useState<MediaResolution | null>(null);
+  const [resolving, setResolving] = React.useState(false);
+  // The object form carries the id, so its asset is fetched by id rather than
+  // resolved. Held separately so a switch between shapes cannot show a stale one.
+  const [objectAsset, setObjectAsset] = React.useState<MediaAsset | null>(null);
+
+  const isObject = shape === "object";
+  const objectValue = isMediaValue(value) ? value : null;
+  const stringValue = !isObject && typeof value === "string" ? value : "";
+
+  // Resolve the string form. Skipped entirely for the object form and for an
+  // empty value — neither has anything to look up.
+  React.useEffect(() => {
+    if (!api || isObject || !stringValue.trim()) {
+      setResolution(null);
+      return;
+    }
+    let cancelled = false;
+    setResolving(true);
+    api
+      .resolve([stringValue], documentPath)
+      .then((results) => {
+        if (!cancelled) setResolution(results[0] ?? null);
+      })
+      .catch(() => {
+        // A failed resolution is not a failed field: fall back to showing the
+        // raw string, the same as an unmanaged reference.
+        if (!cancelled) setResolution(null);
+      })
+      .finally(() => {
+        if (!cancelled) setResolving(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api, isObject, stringValue, documentPath]);
+
+  // The object form's asset, fetched by its id — no resolution involved, because
+  // the id is authoritative and cannot be ambiguous.
+  React.useEffect(() => {
+    if (!api || !isObject || !objectValue) {
+      setObjectAsset(null);
+      return;
+    }
+    const id = objectValue.id;
+    let cancelled = false;
+    api
+      .byId(id)
+      .then((found) => {
+        if (!cancelled) setObjectAsset(found);
+      })
+      .catch(() => {
+        // The asset was removed from the repository since this document
+        // referenced it. The stored value is left alone; the field shows the
+        // dangling-reference state below.
+        if (!cancelled) setObjectAsset(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api, isObject, objectValue?.id]);
+
+  const select = (asset: MediaAsset) => {
+    setPicking(false);
+    if (isObject) {
+      // Object form: the id is authoritative; the paths are denormalized copies
+      // the built site can use without consulting the CMS.
+      onChange({
+        id: asset.id,
+        public_path: asset.publicPath ?? null,
+        cdn_path: asset.cdnPath ?? null,
+      } satisfies MediaValue);
+      return;
+    }
+    onChange(pathForStoreAs(asset, storeAs));
+  };
+
+  const clear = () => onChange(isObject ? null : "");
+
+  const asset = isObject ? objectAsset : resolution?.media ?? null;
+  // A string that resolved to nothing is unmanaged (external URL or outside
+  // every set); an object whose id no longer exists is a dangling reference.
+  // Both keep their stored value — neither is a reason to mutate the document.
+  const unmanaged = !isObject && !!stringValue.trim() && !resolving && !asset && !resolution?.ambiguous;
+  const dangling = isObject && !!objectValue && !asset;
+
+  return (
+    <View style={{ gap: t.space(2) }}>
+      {asset ? (
+        <MediaPreview media={asset} />
+      ) : resolving ? (
+        <PlaceholderBox>
+          <ActivityIndicator size="small" color={t.color.textTertiary} />
+        </PlaceholderBox>
+      ) : resolution?.ambiguous ? (
+        <AmbiguousNotice resolution={resolution} onPick={select} readOnly={readOnly} />
+      ) : unmanaged ? (
+        <UnmanagedNotice value={stringValue} />
+      ) : dangling ? (
+        <MissingNotice id={objectValue!.id} />
+      ) : (
+        <PlaceholderBox>
+          <Icon name="image" size={20} color={t.color.textTertiary} />
+          <Text variant="xs" color="tertiary">No media selected</Text>
+        </PlaceholderBox>
+      )}
+
+      {/* The stored string stays visible: an author needs to see what actually
+          goes into the file, especially when it resolved by a weak basename
+          match or did not resolve at all. */}
+      {!isObject && stringValue ? (
+        <Text variant="xs" color="tertiary" numberOfLines={1}>
+          {stringValue}
+          {resolution?.aliasKind === "basename" && asset ? " · matched by filename" : ""}
+        </Text>
+      ) : null}
+
+      {!readOnly ? (
+        <View style={{ flexDirection: "row", gap: t.space(2) }}>
+          <Button
+            title={asset ? "Replace" : "Choose media"}
+            onPress={() => setPicking(true)}
+            variant="default"
+            size="sm"
+            iconLeft="image"
+            disabled={!api}
+            testID="media-choose"
+          />
+          {stringValue || isObject ? (
+            <Button title="Clear" onPress={clear} variant="ghost" size="sm" iconLeft="x" testID="media-clear" />
+          ) : null}
+        </View>
+      ) : null}
+
+      {error ? (
+        <Text variant="xs" color="tertiary" style={{ color: t.color.diffDelFg }}>
+          This field is required.
+        </Text>
+      ) : null}
+
+      <MediaPicker
+        visible={picking}
+        onClose={() => setPicking(false)}
+        onSelect={select}
+        set={set}
+        kinds={kinds}
+      />
+    </View>
+  );
+}
+
+// pathForStoreAs writes the asset in the form the field's config declares. This
+// is what keeps the CMS from inventing a path shape the site does not serve —
+// and why reverse resolution is only ever needed for content the CMS did not
+// write.
+export function pathForStoreAs(asset: MediaAsset, storeAs: StoreAs): string {
+  switch (storeAs) {
+    case "cdn":
+      return asset.cdnPath || asset.publicPath || asset.repoPath;
+    case "repo":
+      return asset.repoPath;
+    default:
+      return asset.publicPath || asset.repoPath;
+  }
+}
+
+function PlaceholderBox({ children }: { children: React.ReactNode }) {
+  const t = useTheme();
+  return (
+    <View
+      style={{
+        height: 96,
+        alignItems: "center",
+        justifyContent: "center",
+        gap: t.space(2),
+        borderWidth: 1,
+        borderStyle: "dashed",
+        borderColor: t.color.borderDefault,
+        borderRadius: t.radius.md,
+        backgroundColor: t.color.surfaceSunken,
+      }}
+    >
+      {children}
+    </View>
+  );
+}
+
+// UnmanagedNotice covers the honest miss: an external URL, or a path pointing
+// outside every configured media set. The field still works — the value is
+// preserved exactly — there is simply nothing to preview.
+function UnmanagedNotice({ value }: { value: string }) {
+  const t = useTheme();
+  const external = value.includes("://");
+  return (
+    <View
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: t.space(3),
+        padding: t.space(3),
+        borderWidth: 1,
+        borderColor: t.color.borderDefault,
+        borderRadius: t.radius.md,
+        backgroundColor: t.color.surfaceSunken,
+      }}
+    >
+      <Icon name={external ? "link" : "alert"} size={18} color={t.color.textSecondary} />
+      <View style={{ flex: 1, minWidth: 0 }}>
+        <Text variant="body" numberOfLines={1}>
+          {external ? "External link" : "Not a managed asset"}
+        </Text>
+        <Text variant="xs" color="tertiary">
+          {external
+            ? "This URL points outside your repository."
+            : "No file in a configured media set matches this path."}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+// MissingNotice covers an object reference whose asset is gone — the file was
+// removed from the repository after this document pointed at it. The stored
+// value is preserved so the author can see what it referenced before replacing
+// it; silently blanking the field would destroy that evidence.
+function MissingNotice({ id }: { id: string }) {
+  const t = useTheme();
+  return (
+    <View
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: t.space(3),
+        padding: t.space(3),
+        borderWidth: 1,
+        borderColor: t.color.borderDefault,
+        borderRadius: t.radius.md,
+        backgroundColor: t.color.surfaceSunken,
+      }}
+    >
+      <Icon name="alert" size={18} color={t.color.textSecondary} />
+      <View style={{ flex: 1, minWidth: 0 }}>
+        <Text variant="body">Missing asset</Text>
+        <Text variant="xs" color="tertiary" numberOfLines={1}>
+          {`No media with id ${id} — it may have been removed from the repository.`}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+// AmbiguousNotice is what a bare-filename match gets when several assets share
+// that name. Asking is strictly better than picking: a silently wrong image in a
+// published page is far more expensive than one extra click here.
+function AmbiguousNotice({
+  resolution,
+  onPick,
+  readOnly,
+}: {
+  resolution: MediaResolution;
+  onPick: (asset: MediaAsset) => void;
+  readOnly?: boolean;
+}) {
+  const t = useTheme();
+  return (
+    <View style={{ gap: t.space(2) }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+        <Icon name="alert" size={16} color={t.color.textSecondary} />
+        <Text variant="xs" color="tertiary">
+          {resolution.candidates.length} files share this name — pick the right one.
+        </Text>
+      </View>
+      {resolution.candidates.map((c) => (
+        <Pressable
+          key={c.id}
+          onPress={() => (readOnly ? undefined : onPick(c))}
+          disabled={readOnly}
+          testID={`media-candidate-${c.id}`}
+        >
+          <MediaChip media={c} />
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+
+// ---- picker ----------------------------------------------------------------
+
+const PAGE_SIZE = 40;
+
+export type MediaPickerProps = {
+  visible: boolean;
+  onClose: () => void;
+  onSelect: (asset: MediaAsset) => void;
+  set?: string;
+  kinds?: MediaKind[];
+};
+
+export function MediaPicker({ visible, onClose, onSelect, set, kinds }: MediaPickerProps) {
+  const t = useTheme();
+  const api = useMediaApi();
+  const [activeSet, setActiveSet] = React.useState<string | undefined>(set);
+  const [search, setSearch] = React.useState("");
+  const [items, setItems] = React.useState<MediaAsset[]>([]);
+  const [loading, setLoading] = React.useState(false);
+  const [uploading, setUploading] = React.useState(false);
+  const [uploadError, setUploadError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (visible) setActiveSet(set);
+  }, [visible, set]);
+
+  // Debounced so typing a filename doesn't fire a request per keystroke.
+  React.useEffect(() => {
+    if (!visible || !api) return;
+    let cancelled = false;
+    setLoading(true);
+    const timer = setTimeout(() => {
+      api
+        .list({ set: activeSet, kinds, search: search.trim() || undefined, limit: PAGE_SIZE })
+        .then((rows) => {
+          if (!cancelled) setItems(rows);
+        })
+        .catch(() => {
+          if (!cancelled) setItems([]);
+        })
+        .finally(() => {
+          if (!cancelled) setLoading(false);
+        });
+    }, 250);
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, [visible, api, activeSet, kinds, search]);
+
+  const handleUpload = async (file: File) => {
+    if (!api?.upload || !activeSet) return;
+    setUploading(true);
+    setUploadError(null);
+    try {
+      const asset = await api.upload({ set: activeSet, file });
+      onSelect(asset);
+    } catch (err) {
+      setUploadError(err instanceof Error ? err.message : "Upload failed.");
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const sets = api?.sets ?? [];
+
+  return (
+    <Modal visible={visible} transparent animationType="fade" onRequestClose={onClose}>
+      <View
+        style={{
+          flex: 1,
+          backgroundColor: t.color.overlay,
+          alignItems: "center",
+          justifyContent: "center",
+          padding: t.space(4),
+        }}
+      >
+        <View
+          style={{
+            width: "100%",
+            maxWidth: 720,
+            maxHeight: "85%",
+            backgroundColor: t.color.surfacePage,
+            borderRadius: t.radius.lg,
+            borderWidth: 1,
+            borderColor: t.color.borderDefault,
+            overflow: "hidden",
+          }}
+        >
+          <View
+            style={{
+              flexDirection: "row",
+              alignItems: "center",
+              gap: t.space(3),
+              padding: t.space(4),
+              borderBottomWidth: 1,
+              borderBottomColor: t.color.borderSubtle,
+            }}
+          >
+            <Text variant="h3" style={{ flex: 1 }}>
+              Choose media
+            </Text>
+            <Pressable onPress={onClose} accessibilityLabel="Close">
+              <Icon name="x" size={18} color={t.color.textSecondary} />
+            </Pressable>
+          </View>
+
+          {/* Set switcher — only when there is a choice to make. */}
+          {sets.length > 1 ? (
+            <ScrollView
+              horizontal
+              showsHorizontalScrollIndicator={false}
+              contentContainerStyle={{ gap: t.space(2), padding: t.space(3) }}
+            >
+              {sets.map((s) => (
+                <Pressable
+                  key={s.name}
+                  onPress={() => setActiveSet(s.name)}
+                  style={{
+                    paddingHorizontal: t.space(3),
+                    height: t.control.sm,
+                    justifyContent: "center",
+                    borderRadius: t.radius.pill,
+                    borderWidth: 1,
+                    borderColor: activeSet === s.name ? t.color.borderActive : t.color.borderDefault,
+                    backgroundColor: activeSet === s.name ? t.color.surfaceActive : "transparent",
+                  }}
+                >
+                  <Text variant="xs" color="tertiary">{`${s.name} (${s.count})`}</Text>
+                </Pressable>
+              ))}
+            </ScrollView>
+          ) : null}
+
+          <View style={{ padding: t.space(3), gap: t.space(3) }}>
+            <TextInput
+              value={search}
+              onChangeText={setSearch}
+              placeholder="Search by file name or folder"
+              placeholderTextColor={t.color.textTertiary}
+              // @ts-expect-error react-native-web accepts outlineStyle
+              style={{
+                height: t.control.md,
+                paddingHorizontal: t.space(3),
+                borderWidth: 1,
+                borderColor: t.color.borderDefault,
+                borderRadius: t.radius.md,
+                backgroundColor: t.color.surfaceRaised,
+                color: t.color.textPrimary,
+                fontSize: 13,
+                outlineStyle: "none",
+              }}
+            />
+            {api?.upload && activeSet ? (
+              <UploadControl onPick={handleUpload} uploading={uploading} />
+            ) : null}
+            {uploadError ? (
+              <Text variant="xs" color="tertiary" style={{ color: t.color.diffDelFg }}>
+                {uploadError}
+              </Text>
+            ) : null}
+          </View>
+
+          <ScrollView contentContainerStyle={{ padding: t.space(3), gap: t.space(2) }}>
+            {loading ? (
+              <View style={{ padding: t.space(6), alignItems: "center" }}>
+                <ActivityIndicator size="small" color={t.color.textTertiary} />
+              </View>
+            ) : items.length === 0 ? (
+              <View style={{ padding: t.space(6), alignItems: "center", gap: t.space(2) }}>
+                <Text variant="xs" color="tertiary">
+                  {search ? "Nothing matches that search." : "This set has no files yet."}
+                </Text>
+              </View>
+            ) : (
+              items.map((asset) => (
+                <Pressable key={asset.id} onPress={() => onSelect(asset)} testID={`media-row-${asset.id}`}>
+                  <MediaRow asset={asset} />
+                </Pressable>
+              ))
+            )}
+          </ScrollView>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+// MediaRow is one asset in the picker list: a thumbnail for images, an icon for
+// everything else, plus the path and size.
+function MediaRow({ asset }: { asset: MediaAsset }) {
+  const t = useTheme();
+  const thumbable = asset.kind === "image" || asset.kind === "svg";
+  return (
+    <View
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        gap: t.space(3),
+        padding: t.space(2),
+        borderWidth: 1,
+        borderColor: t.color.borderSubtle,
+        borderRadius: t.radius.md,
+        backgroundColor: t.color.surfaceRaised,
+      }}
+    >
+      <View
+        style={{
+          width: 48,
+          height: 48,
+          borderRadius: t.radius.sm,
+          backgroundColor: t.color.surfaceSunken,
+          alignItems: "center",
+          justifyContent: "center",
+          overflow: "hidden",
+        }}
+      >
+        {thumbable ? (
+          <Thumbnail asset={asset} />
+        ) : (
+          <Icon name={kindIcon(asset.kind)} size={20} color={t.color.textSecondary} />
+        )}
+      </View>
+      <View style={{ flex: 1, minWidth: 0 }}>
+        <Text variant="body" numberOfLines={1}>
+          {fileName(asset.repoPath)}
+        </Text>
+        <Text variant="xs" color="tertiary" numberOfLines={1}>
+          {[asset.repoPath, formatBytes(asset.size)].filter(Boolean).join(" · ")}
+        </Text>
+      </View>
+      {asset.pending ? (
+        <View
+          style={{
+            paddingHorizontal: t.space(2),
+            paddingVertical: 2,
+            borderRadius: t.radius.pill,
+            backgroundColor: t.color.surfaceActive,
+          }}
+        >
+          {/* Uploaded but not yet committed to git; it works in the editor and
+              lands in the repository on the next export. */}
+          <Text variant="xs" color="tertiary">not in git yet</Text>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+function Thumbnail({ asset }: { asset: MediaAsset }) {
+  return <MediaPreview media={asset} compact maxHeight={48} />;
+}
+
+// UploadControl is the file input. It is web-only in effect: react-native has no
+// <input type="file">, and a native image picker would be another dependency, so
+// on native the control simply does not render.
+function UploadControl({
+  onPick,
+  uploading,
+}: {
+  onPick: (file: File) => void;
+  uploading: boolean;
+}) {
+  const t = useTheme();
+  const inputRef = React.useRef<HTMLInputElement | null>(null);
+  if (typeof document === "undefined") return null;
+
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+      <Button
+        title={uploading ? "Uploading…" : "Upload a file"}
+        onPress={() => inputRef.current?.click()}
+        variant="default"
+        size="sm"
+        iconLeft="upload"
+        disabled={uploading}
+      />
+      <input
+        ref={inputRef}
+        type="file"
+        style={{ display: "none" }}
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          // Reset so re-picking the same file fires change again.
+          e.target.value = "";
+          if (file) onPick(file);
+        }}
+      />
+    </View>
+  );
+}