@oxyhq/services 27.0.0 → 27.1.0

package/lib/typescript/module/ui/hooks/useFollowTarget.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `useFollowTarget` — the one hook every application uses to follow anything.
+ *
+ * Wraps the `/v2/follows` SDK methods with the store above, an optimistic
+ * update, and a rollback. Nothing in here knows what kind of thing it is
+ * following, which is the property that lets an application the SDK has never
+ * heard of use it without a release of this package.
+ *
+ * ## Optimism, and its one limit
+ *
+ * A follow flips the button immediately and rolls back if the server refuses,
+ * because the round trip is long enough to feel like a bug otherwise. But an
+ * optimistic follow has no relationship id until the server answers, and every
+ * other operation addresses the relationship — so those stay disabled for the
+ * width of one request rather than being sent with a guessed id.
+ */
+import type { FollowStatus } from '@oxyhq/contracts';
+export interface UseFollowTargetResult {
+    status: FollowStatus;
+    /**
+     * Whether the user follows this at all — NOT `effectiveState`, which reports
+     * `not_following` for a follow merely switched off in this application.
+     */
+    isFollowing: boolean;
+    /** True until the first read settles. Distinct from "not following". */
+    isUnknown: boolean;
+    isPending: boolean;
+    error: string | undefined;
+    follow: (options?: {
+        expiresIn?: number;
+    }) => Promise<void>;
+    unfollow: () => Promise<void>;
+    /** Stop acting on this follow HERE, without giving it up everywhere. */
+    disableHere: () => Promise<void>;
+    enableHere: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+export declare function useFollowTarget(targetId: string | undefined, options?: {
+    initialStatus?: FollowStatus;
+}): UseFollowTargetResult;
+//# sourceMappingURL=useFollowTarget.d.ts.map

package/lib/typescript/module/ui/hooks/useFollowTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFollowTarget.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useFollowTarget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AASrD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,wEAAwE;IACxE,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,GACzC,qBAAqB,CAgJvB"}

package/lib/typescript/module/ui/screens/AccountMembersScreen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccountMembersScreen.d.ts","sourceRoot":"","sources":["../../../../../src/ui/screens/AccountMembersScreen.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAiB/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAqB,CAAC;AAkB3D;;;;GAIG;AACH,QAAA,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAyXnD,CAAC;AAEF,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"AccountMembersScreen.d.ts","sourceRoot":"","sources":["../../../../../src/ui/screens/AccountMembersScreen.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAkB/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAqB,CAAC;AAkB3D;;;;GAIG;AACH,QAAA,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAgbnD,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/lib/typescript/module/ui/stores/followTargetStore.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The follow-graph store — the client's single cache authority for #809.
+ *
+ * The SDK caches none of these reads on purpose (a status cached across a write
+ * is the "follow reverts after navigating away and back" bug), which makes this
+ * store the one place a status lives between a write and the next read. If a
+ * second cache appears above it, the two will disagree the moment one is
+ * invalidated and the other is not.
+ *
+ * ## Keyed by target id, not by user id
+ *
+ * The legacy `followStore` is keyed by user id because the only followable
+ * thing was a user. Here a key is a target of any kind — a topic, a store, an
+ * artist, a channel — so nothing in this file may assume what it is looking at.
+ * That is the property that lets an application the SDK has never heard of use
+ * it without a release.
+ *
+ * ## Why the status is stored whole
+ *
+ * Not a boolean. `globalState`, `applicationMode` and `effectiveState` are
+ * three separate answers, and a UI that keeps only the last one cannot explain
+ * why a follow the user can see in their list does nothing in this app.
+ */
+import type { FollowApplicationMode, FollowStatus } from '@oxyhq/contracts';
+/** The status of one target, or `undefined` when it has never been read. */
+type StatusMap = Record<string, FollowStatus | undefined>;
+interface FollowTargetState {
+    statuses: StatusMap;
+    /** In-flight writes, per target. Reads do not set this — only mutations do. */
+    pending: Record<string, boolean>;
+    errors: Record<string, string | undefined>;
+    setStatus: (targetId: string, status: FollowStatus) => void;
+    /**
+     * Seed many statuses at once — from a follow list, a feed payload, anything
+     * that already knows. Saves one request per rendered row, which is the
+     * difference between a list that paints and a list that flickers.
+     */
+    seed: (entries: Record<string, FollowStatus>) => void;
+    setPending: (targetId: string, pending: boolean) => void;
+    setError: (targetId: string, error: string | undefined) => void;
+    /** Drop everything. Called on identity change — see the note below. */
+    reset: () => void;
+}
+/**
+ * The state one target is in before the server has been asked. Distinct from
+ * "not following": a button that renders a follow action while the answer is
+ * unknown invites a follow the user did not intend, so callers check
+ * `isUnknown` rather than reading this as an answer.
+ */
+export declare const UNKNOWN_FOLLOW_STATUS: FollowStatus;
+export declare const useFollowTargetStore: import("zustand").UseBoundStore<import("zustand").StoreApi<FollowTargetState>>;
+/**
+ * Whether the user follows this at all, anywhere.
+ *
+ * Deliberately NOT `effectiveState !== 'not_following'`: a follow switched off
+ * in this application reports `not_following` — correctly, since the question
+ * that field answers is "does this act here" — and a button that read it as
+ * "not followed" would offer to follow something already followed.
+ */
+export declare function isFollowedGlobally(status: FollowStatus): boolean;
+/**
+ * Apply a mode change to a cached status without a round trip.
+ *
+ * Exported because the optimistic path and the settled path must agree on what
+ * `effectiveState` becomes; deriving it in two places is how they drift. Mirrors
+ * the server's own derivation, which is the authority.
+ */
+export declare function withApplicationMode(status: FollowStatus, mode: FollowApplicationMode): FollowStatus;
+export {};
+//# sourceMappingURL=followTargetStore.d.ts.map

package/lib/typescript/module/ui/stores/followTargetStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"followTargetStore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/followTargetStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5E,4EAA4E;AAC5E,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAE1D,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAE3C,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAC;IACtD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAChE,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF,eAAO,MAAM,oBAAoB,gFAoB9B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,qBAAqB,GAC1B,YAAY,CAad"}

package/lib/typescript/module/ui/stores/resetSessionScopedStores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resetSessionScopedStores.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/resetSessionScopedStores.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}
+{"version":3,"file":"resetSessionScopedStores.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/resetSessionScopedStores.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "27.0.0",
+  "version": "27.1.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -138,7 +138,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.23.0",
+    "@oxyhq/contracts": "0.24.0",
     "@simplewebauthn/browser": "^13.3.0",
     "color": "^4.2.3"
   },
@@ -147,7 +147,7 @@
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/vector-icons": "^15.0.3",
-    "@oxyhq/core": "19.0.0",
+    "@oxyhq/core": "19.1.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
     "@react-native/babel-preset": "^0.86.0",

package/src/index.ts

@@ -278,6 +278,17 @@ export type { RequireOxyAuthProps, RequireOxyAuthPrompt } from './ui/components/
 
 export { default as FollowButton } from './ui/components/FollowButton';
 export type { FollowButtonProps, SingleFollowButtonProps, MultiFollowButtonProps } from './ui/components/FollowButton';
+// The follow graph (#809): follows anything registered, not just users.
+export { FollowTargetButton } from './ui/components/FollowTargetButton';
+export type {
+  FollowTargetButtonProps,
+  FollowVerb,
+  FollowLabels,
+  FollowDuration,
+} from './ui/components/FollowTargetButton';
+export { useFollowTarget } from './ui/hooks/useFollowTarget';
+export type { UseFollowTargetResult } from './ui/hooks/useFollowTarget';
+export { useFollowTargetStore, UNKNOWN_FOLLOW_STATUS } from './ui/stores/followTargetStore';
 export { default as OxyPayButton } from './ui/components/OxyPayButton';
 export { LogoIcon } from './ui/components/logo/LogoIcon';
 export { LogoText } from './ui/components/logo/LogoText';

package/src/ui/components/FollowButton.tsx

@@ -5,10 +5,10 @@ import type {
   TextStyle,
   StyleProp,
 } from 'react-native';
+import { ActivityIndicator } from 'react-native';
 import { useOxy } from '../context/OxyContext';
 import { toast } from '@oxyhq/bloom/toast';
 import { Button } from '@oxyhq/bloom/button';
-import { Loading } from '@oxyhq/bloom/loading';
 import { useFollow, useFollowForButton } from '../hooks/useFollow';
 import { useFollowStore } from '../stores/followStore';
 import { useTheme } from '@oxyhq/bloom/theme';
@@ -119,8 +119,7 @@ const FollowButtonInner = memo(function FollowButtonInner({
       style={style}
       textStyle={textStyle}
       icon={showSpinner ? (
-        <Loading
-          variant="inline"
+        <ActivityIndicator
           size="small"
           color={showFollowing ? colors.text : colors.primaryForeground}
         />
@@ -247,8 +246,7 @@ const FollowButtonMultiInner = memo(function FollowButtonMultiInner({
       style={style}
       textStyle={textStyle}
       icon={showSpinner ? (
-        <Loading
-          variant="inline"
+        <ActivityIndicator
           size="small"
           color={allFollowing ? colors.text : colors.primaryForeground}
         />

package/src/ui/components/FollowTargetButton.tsx

@@ -0,0 +1,326 @@
+/**
+ * `FollowTargetButton` — one button for everything an Oxy user can follow.
+ *
+ * Follows a TARGET of any registered kind: a person, a topic, a channel, a
+ * store, an artist. Nothing in this file branches on what the target is, which
+ * is the property that lets an application this package has never heard of use
+ * it without a release.
+ *
+ * ## Two controls, not one
+ *
+ * The main press does the obvious thing. The chevron beside it opens the
+ * choices that a single press cannot express — follow for a while, stop showing
+ * this here without giving it up everywhere — and those belong behind a
+ * disclosure precisely because they are not what most people want most of the
+ * time. Bloom's `Menu` renders as a bottom sheet on native and a dropdown on
+ * web, so this is one component and not a platform fork.
+ *
+ * ## Verbs
+ *
+ * "Follow" is wrong for half the things in the ecosystem: you subscribe to a
+ * channel, you join a community, you watch a listing. The verb is a prop with a
+ * small vocabulary of defaults and a full override, rather than a lookup keyed
+ * on kind — a kind→verb table in this package would need a release every time
+ * an application invents a kind, which is exactly the coupling #809 removes.
+ *
+ * ## Relationship to the legacy `FollowButton`
+ *
+ * `FollowButton` follows a USER through the Mongo-backed social graph and
+ * remains the correct component for that until the user graph is migrated onto
+ * `/v2/follows`. When it is, that component is deleted and this one takes the
+ * name — not aliased, not deprecated in place.
+ */
+
+import { memo, useCallback, useMemo } from 'react';
+import type { FollowApplicationMode } from '@oxyhq/contracts';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { View } from 'react-native';
+import { Button } from '@oxyhq/bloom/button';
+import { ChevronBottom_Stroke2_Corner0_Rounded as ChevronDown } from '@oxyhq/bloom/icons';
+import { Menu, MenuContent, MenuItem, MenuItemText, MenuTrigger } from '@oxyhq/bloom/menu';
+import { toast } from '@oxyhq/bloom/toast';
+import { useFollowTarget } from '../hooks/useFollowTarget';
+
+/**
+ * The small vocabulary of verbs the ecosystem actually uses. An application
+ * whose verb is not here passes `labels` instead — the escape hatch exists so
+ * this union never has to grow to accommodate one product's wording.
+ */
+export type FollowVerb = 'follow' | 'subscribe' | 'join' | 'watch';
+
+export interface FollowLabels {
+  /** Not following yet. */
+  idle: string;
+  /** Following, and this application acts on it. */
+  active: string;
+  /** Asked, waiting for the other side to accept. */
+  pending: string;
+  /** Following globally, but switched off in this application. */
+  disabled: string;
+}
+
+const VERB_LABELS: Record<FollowVerb, FollowLabels> = {
+  follow: { idle: 'Follow', active: 'Following', pending: 'Requested', disabled: 'Off here' },
+  subscribe: {
+    idle: 'Subscribe',
+    active: 'Subscribed',
+    pending: 'Requested',
+    disabled: 'Off here',
+  },
+  join: { idle: 'Join', active: 'Joined', pending: 'Requested', disabled: 'Off here' },
+  watch: { idle: 'Watch', active: 'Watching', pending: 'Requested', disabled: 'Off here' },
+};
+
+/** A timed-follow choice offered in the menu. */
+export interface FollowDuration {
+  label: string;
+  seconds: number;
+}
+
+const HOUR = 60 * 60;
+
+/**
+ * Defaults chosen for the cases a timed follow is actually for: a live event
+ * tonight, a story running this week. Not a general-purpose duration picker —
+ * an application that needs one passes its own.
+ */
+const DEFAULT_DURATIONS: FollowDuration[] = [
+  { label: '24 hours', seconds: 24 * HOUR },
+  { label: '72 hours', seconds: 72 * HOUR },
+  { label: 'A week', seconds: 7 * 24 * HOUR },
+];
+
+/** One line in the disclosure menu. */
+export interface FollowMenuItem {
+  key: string;
+  label: string;
+  /** What the component should call. Named so the table below stays pure. */
+  action:
+    | { type: 'follow-timed'; seconds: number; durationLabel: string }
+    | { type: 'enable-here' }
+    | { type: 'disable-here' }
+    | { type: 'unfollow' };
+}
+
+/**
+ * Which choices exist, given the state.
+ *
+ * Pure and exported because this is the product decision, not a rendering
+ * detail: a timed follow is only offered before following, turning it off here
+ * is only offered while following, and NEITHER is offered before the server has
+ * answered — every one of them addresses a relationship that does not exist
+ * yet, so offering them mid-write would mean sending a guessed id.
+ */
+export function buildFollowMenuItems(input: {
+  following: boolean;
+  applicationMode: FollowApplicationMode;
+  hasRelationship: boolean;
+  isPending: boolean;
+  durations: FollowDuration[] | false;
+  idleVerb: string;
+  applicationName: string;
+}): FollowMenuItem[] {
+  const items: FollowMenuItem[] = [];
+
+  if (!input.following) {
+    if (input.durations === false) return items;
+    for (const d of input.durations) {
+      items.push({
+        key: `for-${d.seconds}`,
+        label: `${input.idleVerb} for ${d.label.toLowerCase()}`,
+        action: { type: 'follow-timed', seconds: d.seconds, durationLabel: d.label },
+      });
+    }
+    return items;
+  }
+
+  if (!input.hasRelationship || input.isPending) return items;
+
+  items.push(
+    input.applicationMode === 'disabled'
+      ? { key: 'enable-here', label: `Show in ${input.applicationName}`, action: { type: 'enable-here' } }
+      : {
+          key: 'disable-here',
+          label: `Don’t show in ${input.applicationName}`,
+          action: { type: 'disable-here' },
+        }
+  );
+  items.push({
+    // Named for what it does. "Unfollow" beside "don't show here" would read as
+    // the same action twice, and the user would pick the wrong one.
+    key: 'unfollow-everywhere',
+    label: 'Unfollow everywhere',
+    action: { type: 'unfollow' },
+  });
+
+  return items;
+}
+
+export interface FollowTargetButtonProps {
+  /** The registered target's id. Registration is separate — see the SDK. */
+  targetId: string;
+  verb?: FollowVerb;
+  /** Full override, for a verb the vocabulary above does not carry. */
+  labels?: Partial<FollowLabels>;
+  size?: 'small' | 'medium' | 'large';
+  style?: StyleProp<ViewStyle>;
+  disabled?: boolean;
+  /**
+   * Hide the chevron. For a dense list row where the extra target is more
+   * likely to be hit by accident than used on purpose.
+   */
+  showOptions?: boolean;
+  /**
+   * Offer timed follows. Pass `false` where a temporary follow makes no sense —
+   * a store you buy from, an account you know.
+   */
+  durations?: FollowDuration[] | false;
+  /**
+   * This application's name, for the menu line that turns the follow off here.
+   * "Don't show in Mention" is a sentence the user can act on; "disable in this
+   * application" is not.
+   */
+  applicationName?: string;
+  onChange?: (following: boolean) => void;
+}
+
+export const FollowTargetButton = memo(function FollowTargetButton({
+  targetId,
+  verb = 'follow',
+  labels,
+  size = 'medium',
+  style,
+  disabled = false,
+  showOptions = true,
+  durations = DEFAULT_DURATIONS,
+  applicationName,
+  onChange,
+}: FollowTargetButtonProps) {
+  const { status, isFollowing, isUnknown, isPending, follow, unfollow, disableHere, enableHere } =
+    useFollowTarget(targetId);
+
+  const text = useMemo(() => ({ ...VERB_LABELS[verb], ...labels }), [verb, labels]);
+
+  const label = useMemo(() => {
+    if (status.globalState === 'requested') return text.pending;
+    if (!isFollowing) return text.idle;
+    // Followed globally but switched off here. `effectiveState` reports
+    // `not_following` for this, correctly — the question it answers is "does
+    // this act here" — so the label has to be derived from the other two.
+    return status.applicationMode === 'disabled' ? text.disabled : text.active;
+  }, [isFollowing, status.globalState, status.applicationMode, text]);
+
+  const handlePrimary = useCallback(async () => {
+    if (isFollowing) {
+      await unfollow();
+      onChange?.(false);
+      return;
+    }
+    await follow();
+    onChange?.(true);
+  }, [isFollowing, follow, unfollow, onChange]);
+
+  const handleTimed = useCallback(
+    async (seconds: number, durationLabel: string) => {
+      await follow({ expiresIn: seconds });
+      onChange?.(true);
+      // The confirmation is the point: a follow that ends on its own is a
+      // promise, and a user who does not see it made will not believe it.
+      toast.success(`Following for ${durationLabel.toLowerCase()}`);
+    },
+    [follow, onChange]
+  );
+
+  const menuItems = useMemo(
+    () =>
+      buildFollowMenuItems({
+        following: isFollowing,
+        applicationMode: status.applicationMode,
+        hasRelationship: Boolean(status.relationshipId),
+        isPending,
+        durations,
+        idleVerb: text.idle,
+        applicationName: applicationName ?? 'this app',
+      }),
+    [
+      isFollowing,
+      status.applicationMode,
+      status.relationshipId,
+      isPending,
+      durations,
+      text.idle,
+      applicationName,
+    ]
+  );
+
+  const runItem = useCallback(
+    (item: FollowMenuItem) => {
+      switch (item.action.type) {
+        case 'follow-timed':
+          void handleTimed(item.action.seconds, item.action.durationLabel);
+          return;
+        case 'enable-here':
+          void enableHere();
+          return;
+        case 'disable-here':
+          void disableHere();
+          return;
+        case 'unfollow':
+          void unfollow();
+          onChange?.(false);
+      }
+    },
+    [handleTimed, enableHere, disableHere, unfollow, onChange]
+  );
+
+  const primary = (
+    <Button
+      variant={isFollowing ? 'secondary' : 'primary'}
+      size={size}
+      // Unknown is not "not following": the button stays inert until the first
+      // read settles rather than inviting a follow that may already exist.
+      disabled={disabled || isUnknown}
+      loading={isPending}
+      onPress={() => void handlePrimary()}
+      accessibilityLabel={label}
+    >
+      {label}
+    </Button>
+  );
+
+  if (!showOptions || menuItems.length === 0) {
+    return <View style={style}>{primary}</View>;
+  }
+
+  return (
+    <View style={[{ flexDirection: 'row', alignItems: 'center', gap: 4 }, style]}>
+      {primary}
+      <Menu>
+        <MenuTrigger label={`${label} options`} hint="Opens follow options">
+          {({ props }) => (
+            // The trigger's props are mapped rather than spread: `MenuTrigger`
+            // hands back a DOM-ish bag (focus handlers, an accessibility role)
+            // and `Button` accepts a different set, so a spread would pass
+            // props it silently drops.
+            <Button
+              variant="secondary"
+              size={size === 'large' ? 'large' : 'small'}
+              icon={<ChevronDown width={16} />}
+              disabled={disabled || isUnknown}
+              onPress={props.onPress}
+              accessibilityLabel={props.accessibilityLabel}
+              accessibilityHint={props.accessibilityHint}
+            />
+          )}
+        </MenuTrigger>
+        <MenuContent showCancel>
+          {menuItems.map((item) => (
+            <MenuItem key={item.key} label={item.label} onPress={() => runItem(item)}>
+              <MenuItemText>{item.label}</MenuItemText>
+            </MenuItem>
+          ))}
+        </MenuContent>
+      </Menu>
+    </View>
+  );
+});

package/src/ui/components/__tests__/followTargetButton.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The follow button's product decisions, as a table.
+ *
+ * `buildFollowMenuItems` is pure and tested here rather than through a render
+ * because what matters is WHICH choices exist in which state — an assertion a
+ * rendering test would make about the DOM, one layout change away from being
+ * about nothing.
+ *
+ * `withApplicationMode` sits beside it because the two have to agree: the menu
+ * offers "don't show here", and the store computes what that does to the
+ * effective state. If they disagree the button offers something it then fails
+ * to reflect.
+ */
+
+import { buildFollowMenuItems } from '../FollowTargetButton';
+import {
+  isFollowedGlobally,
+  UNKNOWN_FOLLOW_STATUS,
+  withApplicationMode,
+} from '../../stores/followTargetStore';
+
+const DURATIONS = [
+  { label: '24 hours', seconds: 86400 },
+  { label: 'A week', seconds: 604800 },
+];
+
+const base = {
+  following: false,
+  applicationMode: 'inherit' as const,
+  hasRelationship: false,
+  isPending: false,
+  durations: DURATIONS,
+  idleVerb: 'Follow',
+  applicationName: 'Mention',
+};
+
+const keys = (items: ReturnType<typeof buildFollowMenuItems>) => items.map((i) => i.key);
+
+describe('buildFollowMenuItems', () => {
+  describe('before following', () => {
+    it('offers the timed follows and nothing else', () => {
+      const items = buildFollowMenuItems(base);
+      expect(keys(items)).toEqual(['for-86400', 'for-604800']);
+      // Nothing that addresses a relationship, because there is none.
+      expect(keys(items).some((k) => k.includes('unfollow') || k.includes('here'))).toBe(false);
+    });
+
+    it('phrases the option with the application’s own verb', () => {
+      expect(buildFollowMenuItems({ ...base, idleVerb: 'Subscribe' })[0].label).toBe(
+        'Subscribe for 24 hours'
+      );
+    });
+
+    it('offers nothing when the application turned timed follows off', () => {
+      expect(buildFollowMenuItems({ ...base, durations: false })).toEqual([]);
+    });
+  });
+
+  describe('while following', () => {
+    const following = { ...base, following: true, hasRelationship: true };
+
+    it('offers turning it off here, and unfollowing everywhere', () => {
+      expect(keys(buildFollowMenuItems(following))).toEqual([
+        'disable-here',
+        'unfollow-everywhere',
+      ]);
+    });
+
+    it('names the application, so the line is a sentence the user can act on', () => {
+      expect(buildFollowMenuItems(following)[0].label).toBe('Don’t show in Mention');
+    });
+
+    it('offers turning it back on once it is off here', () => {
+      const items = buildFollowMenuItems({ ...following, applicationMode: 'disabled' });
+      expect(keys(items)).toEqual(['enable-here', 'unfollow-everywhere']);
+      expect(items[0].label).toBe('Show in Mention');
+    });
+
+    it('never offers a timed follow', () => {
+      // Extending a follow is a different operation from starting one, and
+      // offering "Follow for 24 hours" to somebody already following would read
+      // as shortening it.
+      expect(keys(buildFollowMenuItems(following)).some((k) => k.startsWith('for-'))).toBe(false);
+    });
+
+    it('offers nothing while a write is in flight', () => {
+      // Every entry addresses the relationship id, which an optimistic follow
+      // does not have yet. Offering them here would mean sending a guess.
+      expect(buildFollowMenuItems({ ...following, isPending: true })).toEqual([]);
+    });
+
+    it('offers nothing when the relationship id is not known', () => {
+      expect(buildFollowMenuItems({ ...following, hasRelationship: false })).toEqual([]);
+    });
+  });
+});
+
+describe('withApplicationMode', () => {
+  const active = { ...UNKNOWN_FOLLOW_STATUS, globalState: 'active' as const };
+
+  it('makes a disabled follow inactive without giving up the follow', () => {
+    const next = withApplicationMode(active, 'disabled');
+    expect(next.effectiveState).toBe('not_following');
+    // The distinction the whole design exists for, and the reason a client must
+    // never read `effectiveState` as "does the user follow this": the follow is
+    // still there globally.
+    expect(next.globalState).toBe('active');
+    expect(isFollowedGlobally(next)).toBe(true);
+  });
+
+  it('restores the global state when enabled again', () => {
+    expect(withApplicationMode(withApplicationMode(active, 'disabled'), 'enabled')).toMatchObject({
+      applicationMode: 'enabled',
+      effectiveState: 'following',
+    });
+  });
+
+  it('keeps a requested follow requested rather than promoting it', () => {
+    const requested = { ...active, globalState: 'requested' as const };
+    expect(withApplicationMode(requested, 'enabled').effectiveState).toBe('requested');
+    // And a request in flight still counts as following, so the button offers
+    // to cancel rather than to ask again.
+    expect(isFollowedGlobally(requested)).toBe(true);
+  });
+
+  it('stays not-following when there is no global relationship to act on', () => {
+    expect(withApplicationMode(UNKNOWN_FOLLOW_STATUS, 'enabled').effectiveState).toBe(
+      'not_following'
+    );
+    expect(isFollowedGlobally(UNKNOWN_FOLLOW_STATUS)).toBe(false);
+  });
+});