@gogitcms/design-system 0.15.0-next.3

package/src/components/CollabField.tsx

@@ -0,0 +1,388 @@
+import React, { useSyncExternalStore } from "react";
+import { View, TextInput, Pressable } from "react-native";
+import { Text } from "./Text";
+import { Input } from "./Input";
+import { useTheme } from "../ThemeProvider";
+import type { CollabApi, CollabParticipant, CollabPeer, CollabRegister, CollabText } from "./ContentBrowser";
+
+// useCollabText subscribes a component to one text field's shared CRDT value and
+// the peers focused on it. Value/peers come straight from the binding so all
+// clients converge; setValue writes back to the CRDT.
+export function useCollabText(binding: CollabText) {
+  const value = useSyncExternalStore(binding.subscribe, binding.get, binding.get);
+  const peers = useSyncExternalStore(binding.subscribe, binding.peers, binding.peers);
+  return { value, peers, setValue: binding.set };
+}
+
+// useCollabRegister binds a scalar field (select/boolean/…) to its shared
+// last-writer-wins register.
+export function useCollabRegister(binding: CollabRegister) {
+  const value = useSyncExternalStore(binding.subscribe, binding.get, binding.get);
+  return { value, setValue: binding.set };
+}
+
+// useCollabSynced reports whether the shared document reflects the server room
+// yet. Until it does, every binding reads empty — not because the field is
+// empty, but because nothing has arrived — and a control that trusts that shows
+// a document's saved value as blank.
+//
+// A host with no synced notion (tests, older impls) omits the pair; those
+// consumers act immediately, as they did before it existed.
+export function useCollabSynced(collab: CollabApi): boolean {
+  const subscribe = React.useCallback(
+    (cb: () => void) => collab.subscribeSynced?.(cb) ?? (() => {}),
+    [collab],
+  );
+  const get = React.useCallback(() => collab.synced?.() ?? true, [collab]);
+  return useSyncExternalStore(subscribe, get, get);
+}
+
+/**
+ * Holds a control together across the gap between it mounting and the shared
+ * document arriving.
+ *
+ * Two things went wrong in that window, both from the same mistake — reading an
+ * empty binding as though it were the field's value. The control showed a saved
+ * document as blank for as long as the handshake took. And an edit made in that
+ * moment went into the shared doc *before* the server's seeded value did, where
+ * it did not replace it but merged with it: typing "draft" into a field that
+ * turns out to hold "shipped" left "shippeddraft" behind, in the document, with
+ * nothing on screen to say where it came from.
+ *
+ * So until the doc has arrived the field is an ordinary local control. It shows
+ * the value the host loaded from the document, and an edit is held rather than
+ * written. Arrival writes the held edit through as a single replacement — which
+ * is what the user meant by it — and hands the field to the CRDT for good.
+ *
+ * Arrival is once-only, and a value in hand counts as proof of it whatever the
+ * provider reports. A later disconnect therefore changes nothing: edits keep
+ * going straight into the doc, so an offline stretch still merges the way a CRDT
+ * is meant to rather than being replayed over whatever happened meanwhile.
+ */
+export function useCollabValue<T>(
+  collab: CollabApi,
+  shared: T,
+  local: T,
+  write: (next: T) => void,
+): { value: T; set: (next: T) => void } {
+  const synced = useCollabSynced(collab);
+  const everSynced = React.useRef(false);
+  if (synced) everSynced.current = true;
+  // `undefined` is a register nobody has written yet; "" is a Y.Text that has
+  // either not arrived or is genuinely empty — which of the two is what `synced`
+  // is here to settle.
+  const unset = shared === undefined || shared === null || shared === "";
+  const arrived = everSynced.current || !unset;
+  const [held, setHeld] = React.useState<[T] | null>(null);
+  // Held in a ref: the caller passes a fresh closure over its bindings each
+  // render, and in the effect's dependencies that would replay the flush.
+  const writeRef = React.useRef(write);
+  writeRef.current = write;
+
+  React.useEffect(() => {
+    if (!arrived || !held) return;
+    writeRef.current(held[0]);
+    setHeld(null);
+  }, [arrived, held]);
+
+  return {
+    // A register still unwritten after arrival falls back to the local value
+    // too: nothing has claimed the field, so the document's own value is the
+    // best answer. An arrived *text* reading "" is an answer — the field is
+    // empty, possibly because a peer just cleared it — and stands.
+    value: held ? held[0] : arrived && shared !== undefined ? shared : local,
+    set: (next: T) => {
+      if (arrived) writeRef.current(next);
+      else setHeld([next]);
+    },
+  };
+}
+
+/**
+ * Reports a collaborator's change to the host as though the user had made it.
+ *
+ * A collab-bound control has two sources of truth and only ever told the host
+ * about one of them. Typing called `onChange`, so the host's value map, its save
+ * state and the draft it feeds the preview all moved. A change arriving over the
+ * CRDT re-rendered the control — through `useSyncExternalStore`, which is what
+ * makes the text on screen correct — and stopped there. The field showed the new
+ * value while every consumer of `onChange` still held the old one.
+ *
+ * Two things fell out of that. The preview never rebuilt for anyone but the
+ * author of the edit, because a draft is only sent when `onChange` fires. And
+ * the host's map stayed stale, so the next save wrote this field back as it was
+ * before the collaborator touched it — losing their work in the committed
+ * document, silently, with both screens showing the newer text.
+ *
+ * So: return an `emit` for the local path to call in place of `onChange`, and
+ * fire `onChange` for anything that changes the value without going through it.
+ * `emit` is what keeps a local edit from arriving twice — it settles the value
+ * on the way out, so the CRDT echo of the user's own keystroke is not read back
+ * as somebody else's change.
+ *
+ * The value is settled on the first render as well, so a field that mounts
+ * already in sync announces nothing: at that point the host seeded the map from
+ * the same document, and an edit event there would mark an untouched document
+ * unsaved.
+ */
+export function useCollabMirror<T>(value: T, onChange: (v: T) => void): (v: T) => void {
+  const settled = React.useRef(value);
+  // Held in a ref because the host passes a fresh arrow each render — in the
+  // effect's dependencies it would re-run on every render of the form, and the
+  // guard below is the only reason that would be harmless rather than a loop.
+  const cb = React.useRef(onChange);
+  cb.current = onChange;
+
+  React.useEffect(() => {
+    if (Object.is(settled.current, value)) return;
+    settled.current = value;
+    cb.current(value);
+  }, [value]);
+
+  return React.useCallback((next: T) => {
+    settled.current = next;
+    cb.current(next);
+  }, []);
+}
+
+// useCollabPeers re-renders on any awareness change (tick-based) and returns the
+// peers focused exactly at a field path — for presence on non-text controls.
+export function useCollabPeers(collab: CollabApi, path: string): CollabPeer[] {
+  useSyncExternalStore(collab.subscribeAwareness, collab.awarenessVersion, collab.awarenessVersion);
+  return collab.peersAt(path);
+}
+
+// useCollabPeersUnder is like useCollabPeers but for a group prefix (any peer
+// focused on a descendant field), driving the group's presence highlight.
+export function useCollabPeersUnder(collab: CollabApi, prefix: string): CollabPeer[] {
+  useSyncExternalStore(collab.subscribeAwareness, collab.awarenessVersion, collab.awarenessVersion);
+  return collab.peersUnder(prefix);
+}
+
+// useCollabParticipants re-renders on awareness changes and returns everyone
+// connected to the document (excluding self).
+export function useCollabParticipants(collab: CollabApi): CollabParticipant[] {
+  useSyncExternalStore(collab.subscribeAwareness, collab.awarenessVersion, collab.awarenessVersion);
+  return collab.participants();
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/[\s._-]+/).filter(Boolean);
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+
+// PresenceAvatars renders overlapping, colored avatars for everyone connected to
+// the document. Clicking one that is editing a field calls onFocusPeer with that
+// field's path so the host can jump to it.
+export function PresenceAvatars({
+  collab,
+  onFocusPeer,
+}: {
+  collab: CollabApi;
+  onFocusPeer: (path: string) => void;
+}) {
+  const t = useTheme();
+  const people = useCollabParticipants(collab);
+  if (people.length === 0) return null;
+  const size = 24;
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center" }}>
+      {people.map((p, i) => {
+        const editing = !!p.focus;
+        return (
+          <Pressable
+            key={p.id}
+            onPress={() => p.focus && onFocusPeer(p.focus)}
+            disabled={!editing}
+            accessibilityLabel={editing ? `${p.name} — editing ${p.focus}` : p.name}
+            style={[
+              {
+                width: size,
+                height: size,
+                borderRadius: size / 2,
+                backgroundColor: p.color,
+                borderWidth: 2,
+                borderColor: t.color.surfaceRaised,
+                alignItems: "center",
+                justifyContent: "center",
+                marginLeft: i === 0 ? 0 : -8,
+              },
+              // react-native-web accepts CSS cursor; not in the RN ViewStyle type.
+              { cursor: editing ? "pointer" : "default" } as unknown as object,
+            ]}
+          >
+            <Text variant="monoSm" color="inverted" style={{ fontSize: 10, lineHeight: 12 }}>
+              {initials(p.name)}
+            </Text>
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}
+
+// PresenceField wraps a control with a colored outline and floating name chips
+// while one or more peers are focused on it. With no peers it renders its child
+// unchanged (no layout shift beyond a transparent border).
+export function PresenceField({
+  peers,
+  children,
+}: {
+  peers: CollabPeer[];
+  children: React.ReactNode;
+}) {
+  const t = useTheme();
+  const active = peers.length > 0;
+  const accent = active ? peers[0].color : "transparent";
+  return (
+    <View style={{ position: "relative" }}>
+      <View
+        style={{
+          borderWidth: 2,
+          borderColor: accent,
+          borderRadius: t.radius.md,
+          // Negative margin keeps the control's own layout box unchanged whether
+          // or not the presence border is showing.
+          margin: -2,
+          padding: 0,
+        }}
+      >
+        {children}
+      </View>
+      {active ? (
+        <View
+          pointerEvents="none"
+          style={{ position: "absolute", top: -16, right: 0, flexDirection: "row", gap: 4 }}
+        >
+          {peers.map((p) => (
+            <View
+              key={p.id}
+              style={{
+                backgroundColor: p.color,
+                borderRadius: 4,
+                paddingHorizontal: 6,
+                paddingVertical: 1,
+              }}
+            >
+              <Text variant="monoSm" color="inverted" style={{ fontSize: 10, lineHeight: 14 }}>
+                {p.name}
+              </Text>
+            </View>
+          ))}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+// CollabInput is a single-line text field bound to a shared CRDT value. Local
+// edits write to the CRDT and mirror to onChange (so the host's autosave/
+// validation see the converged value); focus/blur announce presence. `local` is
+// the host's own value for the field, which stands in until the shared document
+// arrives (see useCollabValue).
+export function CollabInput({
+  collab,
+  path,
+  local,
+  label,
+  mono,
+  keyboardType,
+  readOnly,
+  error,
+  onChange,
+  focusSignal,
+}: {
+  collab: CollabApi;
+  path: string;
+  local: string;
+  label?: string;
+  mono?: boolean;
+  keyboardType?: "default" | "numeric";
+  readOnly?: boolean;
+  error?: boolean;
+  onChange: (v: string) => void;
+  focusSignal?: number;
+}) {
+  const { value: shared, peers, setValue } = useCollabText(collab.text(path));
+  const { value, set } = useCollabValue(collab, shared, local, setValue);
+  const emit = useCollabMirror(value, onChange);
+  return (
+    <PresenceField peers={peers}>
+      <Input
+        label={label}
+        value={value}
+        onChangeText={(v) => {
+          set(v);
+          emit(v);
+        }}
+        mono={mono}
+        keyboardType={keyboardType}
+        size="md"
+        editable={!readOnly}
+        error={error}
+        onFocus={() => collab.setFocus(path)}
+        onBlur={() => collab.setFocus(null)}
+        focusSignal={focusSignal}
+      />
+    </PresenceField>
+  );
+}
+
+// CollabTextarea is the multi-line counterpart of CollabInput.
+export function CollabTextarea({
+  collab,
+  path,
+  local,
+  readOnly,
+  error,
+  onChange,
+  focusSignal,
+}: {
+  collab: CollabApi;
+  path: string;
+  local: string;
+  readOnly?: boolean;
+  error?: boolean;
+  onChange: (v: string) => void;
+  focusSignal?: number;
+}) {
+  const t = useTheme();
+  const { value: shared, peers, setValue } = useCollabText(collab.text(path));
+  const { value, set } = useCollabValue(collab, shared, local, setValue);
+  const emit = useCollabMirror(value, onChange);
+  const ref = React.useRef<TextInput>(null);
+  React.useEffect(() => {
+    if (focusSignal) ref.current?.focus();
+  }, [focusSignal]);
+  return (
+    <PresenceField peers={peers}>
+      <TextInput
+        ref={ref}
+        multiline
+        editable={!readOnly}
+        value={value}
+        onChangeText={(v) => {
+          set(v);
+          emit(v);
+        }}
+        onFocus={() => collab.setFocus(path)}
+        onBlur={() => collab.setFocus(null)}
+        // @ts-expect-error react-native-web
+        style={{
+          minHeight: 96,
+          padding: t.space(3),
+          borderWidth: 1,
+          borderColor: error ? t.color.diffDelFg : t.color.borderDefault,
+          borderRadius: t.radius.md,
+          backgroundColor: readOnly ? t.color.surfaceSunken : t.color.surfaceRaised,
+          color: readOnly ? t.color.textSecondary : t.color.textPrimary,
+          fontSize: 13,
+          textAlignVertical: "top",
+          outlineStyle: "none",
+        }}
+      />
+    </PresenceField>
+  );
+}