convex-feedback-ui 0.1.4 → 0.1.6

package/src/native/expo/FeedbackCreateStackLayout.tsx

@@ -0,0 +1,62 @@
+import {
+  Stack,
+  useNavigation,
+  type NativeStackNavigationOptions,
+} from "expo-router";
+import { useCallback, useMemo } from "react";
+
+import { useFeedbackBody } from "../../shared/context/FeedbackBodyProvider.js";
+import { useFeedbackUi } from "../../shared/context/FeedbackProvider.js";
+import { RoutedFeedbackModalProvider } from "./RoutedFeedbackModalContext.js";
+import { useRoutedFeedback } from "./RoutedFeedbackContext.js";
+import type { FeedbackCreateStackLayoutProps } from "./types.js";
+
+export function FeedbackCreateStackLayout({
+  screenOptions,
+  createOptions,
+  entryOptions,
+}: FeedbackCreateStackLayoutProps) {
+  const parentNavigation = useNavigation();
+  const { enabledKinds } = useFeedbackBody();
+  const { messages, theme } = useFeedbackUi();
+  const { routes } = useRoutedFeedback();
+  const dismiss = useCallback(
+    () => parentNavigation.goBack(),
+    [parentNavigation],
+  );
+  const modal = useMemo(() => ({ dismiss }), [dismiss]);
+  const createTitle =
+    enabledKinds.length === 1
+      ? messages.newFeedback[enabledKinds.at(0)!]
+      : messages.board.createEntry;
+  const defaults: NativeStackNavigationOptions = {
+    headerShown: true,
+    headerBackButtonDisplayMode: "minimal",
+    contentStyle: { backgroundColor: theme.colors.background },
+  };
+
+  return (
+    <RoutedFeedbackModalProvider value={modal}>
+      <Stack>
+        <Stack.Screen
+          name="index"
+          options={{
+            ...defaults,
+            headerTitle: createTitle,
+            ...screenOptions,
+            ...createOptions,
+          }}
+        />
+        <Stack.Screen
+          name={routes.entry}
+          options={{
+            ...defaults,
+            headerTitle: messages.board.title,
+            ...screenOptions,
+            ...entryOptions,
+          }}
+        />
+      </Stack>
+    </RoutedFeedbackModalProvider>
+  );
+}

package/src/native/expo/FeedbackRoutes.tsx

@@ -0,0 +1,204 @@
+import { Stack, useLocalSearchParams, useRouter } from "expo-router";
+import { useEffect, useRef, useState } from "react";
+import type { SearchBarCommands } from "react-native-screens";
+import type { EntryKind } from "convex-feedback";
+
+import { useFeedbackBody } from "../../shared/context/FeedbackBodyProvider.js";
+import { useFeedbackUi } from "../../shared/context/FeedbackProvider.js";
+import { EntryDetail } from "../shared/ui/EntryDetail.js";
+import { FeedbackScreenList } from "../shared/ui/FeedbackScreenList.js";
+import { CreateEntryForm } from "../shared/ui/NewEntry.js";
+import { FeedbackBoard } from "../shared/ui/primitives.js";
+import { feedbackRouteHref } from "./routes.js";
+import { useRoutedFeedbackModal } from "./RoutedFeedbackModalContext.js";
+import { useRoutedFeedback } from "./RoutedFeedbackContext.js";
+
+export function FeedbackBoardScreen() {
+  const { query, isSearching, setQuery, setIsSearching } = useFeedbackBody();
+  const { messages, theme } = useFeedbackUi();
+  const { routes, colors, androidToolbarIcons } = useRoutedFeedback();
+  const router = useRouter();
+  const searchRef = useRef<SearchBarCommands>(null);
+
+  useEffect(() => {
+    const searching = query.trim().length > 0;
+    if (searching !== isSearching) setIsSearching(searching);
+  }, [query, isSearching, setIsSearching]);
+
+  const openEntry = (entryId: string) => {
+    if ((query || isSearching) && searchRef.current) {
+      searchRef.current.blur();
+    }
+    router.push(feedbackRouteHref(routes.entry, { entryId }), {
+      relativeToDirectory: true,
+    });
+  };
+
+  return (
+    <>
+      <FeedbackBoard.Root {...colors}>
+        <FeedbackScreenList
+          showSelectedEntry={false}
+          hideBackButton
+          onEntryOpen={openEntry}
+        />
+      </FeedbackBoard.Root>
+
+      <Stack.Toolbar placement="right">
+        <Stack.Toolbar.Button
+          icon={
+            process.env.EXPO_OS === "ios" ? "plus" : androidToolbarIcons.create
+          }
+          variant="prominent"
+          accessibilityLabel={messages.board.createEntry}
+          onPress={() =>
+            router.push(feedbackRouteHref(routes.create), {
+              relativeToDirectory: true,
+            })
+          }
+          tintColor={theme.colors.primary}
+        >
+          {messages.board.createEntry}
+        </Stack.Toolbar.Button>
+      </Stack.Toolbar>
+      <Stack.Toolbar placement="left">
+        <Stack.Toolbar.Button
+          hidden={!router.canGoBack()}
+          icon={
+            process.env.EXPO_OS === "ios"
+              ? "chevron.backward"
+              : androidToolbarIcons.back
+          }
+          accessibilityLabel={messages.entry.back}
+          onPress={() => router.back()}
+        >
+          {messages.entry.back}
+        </Stack.Toolbar.Button>
+      </Stack.Toolbar>
+      <Stack.SearchBar
+        ref={searchRef}
+        placeholder={messages.board.searchPlaceholder}
+        onChangeText={(event) => setQuery(event.nativeEvent.text)}
+        onFocus={() => setIsSearching(true)}
+        onBlur={() => setIsSearching(query.trim().length > 0)}
+        obscureBackground={false}
+        allowToolbarIntegration
+        hideNavigationBar={false}
+        textColor={theme.colors.text}
+      />
+      <Stack.Toolbar placement="bottom">
+        <Stack.Toolbar.SearchBarSlot />
+      </Stack.Toolbar>
+    </>
+  );
+}
+
+export function FeedbackEntryScreen() {
+  const params = useLocalSearchParams<{
+    entryId?: string | string[];
+  }>();
+  const entryId = Array.isArray(params.entryId)
+    ? params.entryId[0]
+    : params.entryId;
+
+  if (!entryId) {
+    throw new Error(
+      'FeedbackEntryScreen requires an "entryId" dynamic route parameter.',
+    );
+  }
+
+  return <FeedbackEntryRouteContent entryId={entryId} />;
+}
+
+function FeedbackEntryRouteContent({ entryId }: { entryId: string }) {
+  const { hooks } = useFeedbackBody();
+  const { messages, theme } = useFeedbackUi();
+  const { colors, androidToolbarIcons } = useRoutedFeedback();
+  const modal = useRoutedFeedbackModal();
+  const router = useRouter();
+  const entry = hooks.useEntry(entryId);
+
+  return (
+    <>
+      {entry && <Stack.Screen options={{ headerTitle: entry.title }} />}
+      <FeedbackBoard.Root {...colors}>
+        <FeedbackBoard.List style={{ padding: theme.spacing }}>
+          <EntryDetail
+            entryId={entryId}
+            hideBackButton
+            onBack={() => router.back()}
+          />
+        </FeedbackBoard.List>
+      </FeedbackBoard.Root>
+      {modal && (
+        <Stack.Toolbar placement="right">
+          <Stack.Toolbar.Button
+            icon={
+              process.env.EXPO_OS === "ios"
+                ? "xmark"
+                : androidToolbarIcons.close
+            }
+            accessibilityLabel={messages.form.cancel}
+            onPress={modal.dismiss}
+          >
+            {messages.form.cancel}
+          </Stack.Toolbar.Button>
+        </Stack.Toolbar>
+      )}
+    </>
+  );
+}
+
+export function CreateFeedbackScreen() {
+  const { enabledKinds } = useFeedbackBody();
+  const { messages, theme } = useFeedbackUi();
+  const { routes, colors, androidToolbarIcons } = useRoutedFeedback();
+  const modal = useRoutedFeedbackModal();
+  const router = useRouter();
+  const [kind, setKind] = useState<EntryKind>(enabledKinds[0] ?? "feedback");
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+
+  const entryHref = (entryId: string) =>
+    feedbackRouteHref(routes.entry, { entryId });
+
+  return (
+    <>
+      <FeedbackBoard.Root {...colors}>
+        <FeedbackBoard.List
+          style={{
+            padding: theme.spacing,
+            paddingBottom: theme.spacing * 2,
+          }}
+        >
+          <CreateEntryForm
+            kind={kind}
+            onKindChange={setKind}
+            title={title}
+            onTitleChange={setTitle}
+            body={body}
+            onBodyChange={setBody}
+            onOpenSuggestion={(entryId) =>
+              router.push(entryHref(entryId), { relativeToDirectory: true })
+            }
+            onCreated={(entryId) => {
+              router.dismissTo(entryHref(entryId));
+            }}
+          />
+        </FeedbackBoard.List>
+      </FeedbackBoard.Root>
+
+      <Stack.Toolbar placement="left">
+        <Stack.Toolbar.Button
+          icon={
+            process.env.EXPO_OS === "ios" ? "xmark" : androidToolbarIcons.close
+          }
+          accessibilityLabel={messages.form.cancel}
+          onPress={() => (modal ? modal.dismiss() : router.dismiss())}
+        >
+          {messages.form.cancel}
+        </Stack.Toolbar.Button>
+      </Stack.Toolbar>
+    </>
+  );
+}

package/src/native/expo/FeedbackScreen.tsx

@@ -3,6 +3,7 @@ import { FeedbackProvider } from "../../shared/context/FeedbackProvider";
 import { kinds } from "../../shared/helpers";
 import { ExpoFeedbackBody } from "./ExpoFeedbackBody";
 import type { ExpoFeedbackScreenProps } from "./types";
+import { collectExpoMetadata } from "./metadata";
 
 export function FeedbackScreen({
   hooks,
@@ -14,6 +15,7 @@ export function FeedbackScreen({
   enabledKinds = kinds,
   maxCommentDepth = 5,
   debounceDuration = 300,
+  collectMetadata,
   transformComments,
   renderActor,
   ...props
@@ -27,6 +29,8 @@ export function FeedbackScreen({
         enabledKinds={enabledKinds}
         maxCommentDepth={maxCommentDepth}
         debounceDuration={debounceDuration}
+        collectMetadata={collectMetadata}
+        collectStandardMetadata={collectExpoMetadata}
         transformComments={transformComments}
         renderActor={renderActor}
       >

package/src/native/expo/FeedbackStack.tsx

@@ -6,6 +6,7 @@ import type { FeedbackStackProps } from "./types";
 export function FeedbackStack({
   searchRef,
   stackOptions,
+  androidToolbarIcons = {},
   children,
 }: FeedbackStackProps) {
   const {
@@ -54,19 +55,30 @@ export function FeedbackStack({
       />
       <Stack.Toolbar placement="right">
         <Stack.Toolbar.Button
-          icon="plus"
+          icon={
+            process.env.EXPO_OS === "ios" ? "plus" : androidToolbarIcons.create
+          }
           variant="prominent"
           accessibilityLabel={messages.board.createEntry}
           onPress={() => setShowForm(true)}
           tintColor={theme.colors.primary}
-        />
+        >
+          {messages.board.createEntry}
+        </Stack.Toolbar.Button>
       </Stack.Toolbar>
       <Stack.Toolbar placement="left">
         <Stack.Toolbar.Button
           hidden={!canGoBack}
-          icon="chevron.backward"
+          icon={
+            process.env.EXPO_OS === "ios"
+              ? "chevron.backward"
+              : androidToolbarIcons.back
+          }
+          accessibilityLabel={messages.entry.back}
           onPress={handleBackPress}
-        />
+        >
+          {messages.entry.back}
+        </Stack.Toolbar.Button>
       </Stack.Toolbar>
 
       {children}

package/src/native/expo/FeedbackStackLayout.tsx

@@ -0,0 +1,116 @@
+import { Stack, type NativeStackNavigationOptions } from "expo-router";
+
+import { FeedbackBodyProvider } from "../../shared/context/FeedbackBodyProvider.js";
+import { FeedbackProvider } from "../../shared/context/FeedbackProvider.js";
+import { kinds } from "../../shared/helpers.js";
+import { mergeFeedbackMessages } from "../../shared/messages.js";
+import { mergeFeedbackTheme } from "../../shared/theme.js";
+import { collectExpoMetadata } from "./metadata.js";
+import { RoutedFeedbackProvider } from "./RoutedFeedbackContext.js";
+import { resolveFeedbackRoutes } from "./routes.js";
+import type { FeedbackStackLayoutProps } from "./types.js";
+
+export function FeedbackStackLayout({
+  hooks,
+  messages,
+  theme,
+  unstyled,
+  entrySort = "top",
+  commentSort = "top",
+  enabledKinds = kinds,
+  maxCommentDepth = 5,
+  debounceDuration = 300,
+  collectMetadata,
+  transformComments,
+  renderActor,
+  routes: routeOverrides,
+  screenOptions,
+  boardOptions,
+  entryOptions,
+  createOptions,
+  androidToolbarIcons = {},
+  primaryColor,
+  primaryForeground,
+  backgroundColor,
+  surfaceColor,
+  textColor,
+  mutedColor,
+  borderColor,
+  dangerColor,
+}: FeedbackStackLayoutProps) {
+  const routes = resolveFeedbackRoutes(routeOverrides);
+  const resolvedMessages = mergeFeedbackMessages(messages);
+  const resolvedTheme = mergeFeedbackTheme(theme);
+  const colors = {
+    primaryColor,
+    primaryForeground,
+    backgroundColor,
+    surfaceColor,
+    textColor,
+    mutedColor,
+    borderColor,
+    dangerColor,
+  };
+  const background = backgroundColor ?? resolvedTheme.colors.background;
+  const boardTitle =
+    enabledKinds.length === 1
+      ? resolvedMessages.kindsPlural[enabledKinds.at(0)!]
+      : resolvedMessages.board.title;
+  const defaults: NativeStackNavigationOptions = {
+    headerShown: true,
+    headerBackButtonDisplayMode: "minimal",
+    contentStyle: { backgroundColor: background },
+  };
+
+  return (
+    <FeedbackProvider messages={messages} theme={theme} unstyled={unstyled}>
+      <FeedbackBodyProvider
+        hooks={hooks}
+        entrySort={entrySort}
+        commentSort={commentSort}
+        enabledKinds={enabledKinds}
+        maxCommentDepth={maxCommentDepth}
+        debounceDuration={debounceDuration}
+        collectMetadata={collectMetadata}
+        collectStandardMetadata={collectExpoMetadata}
+        transformComments={transformComments}
+        renderActor={renderActor}
+      >
+        <RoutedFeedbackProvider value={{ routes, colors, androidToolbarIcons }}>
+          <Stack>
+            <Stack.Screen
+              name={routes.board}
+              options={{
+                ...defaults,
+                headerTitle: boardTitle,
+                headerTransparent: true,
+                headerShadowVisible: true,
+                ...screenOptions,
+                ...boardOptions,
+              }}
+            />
+            <Stack.Screen
+              name={routes.entry}
+              options={{
+                ...defaults,
+                headerTitle: boardTitle,
+                ...screenOptions,
+                ...entryOptions,
+              }}
+            />
+            <Stack.Screen
+              name={routes.create}
+              options={{
+                ...defaults,
+                headerShown: false,
+                presentation: "modal",
+                ...screenOptions,
+                ...createOptions,
+              }}
+            />
+          </Stack>
+        </RoutedFeedbackProvider>
+      </FeedbackBodyProvider>
+    </FeedbackProvider>
+  );
+}

package/src/native/expo/README.md

@@ -15,3 +15,27 @@ To replace a control with Expo UI, use render-function children on an interactiv
 ```
 
 Containers such as `FeedbackEntry.Content`, `FeedbackForm.Root`, and `Comment.Children` accept arbitrary children, so custom Expo UI fields/buttons can also be placed directly inside the compound layout.
+
+## Routed screens
+
+Use `FeedbackStackLayout` with `FeedbackBoardScreen`,
+`FeedbackCreateStackLayout`, `FeedbackEntryScreen`, and
+`CreateFeedbackScreen` when board state should be shared across real Expo
+Router routes. Consumer applications must create the corresponding board and
+entry files plus a nested create directory containing `_layout.tsx`,
+`index.tsx`, and `[entryId].tsx`, because Expo Router discovers pages from the
+application's route directory.
+
+Re-export `feedbackStackSettings` from the route layout as
+`unstable_settings` so a deep link to the create modal anchors the board behind
+it. Re-export `feedbackCreateStackSettings` from the nested create layout so
+suggested entries retain the form behind them. Use
+`createFeedbackStackSettings(routes)` when overriding the default route names.
+
+Toolbar actions retain their package-provided SF Symbols on iOS. Pass
+`androidToolbarIcons` to `FeedbackScreen` or `FeedbackStackLayout` with Android
+`ImageSourcePropType` values for the create, back, and close actions. Missing
+Android images fall back to text labels.
+
+The existing `FeedbackScreen` remains the self-contained API for conditional
+in-screen navigation.

package/src/native/expo/RoutedFeedbackContext.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext } from "react";
+import type { RoutedFeedbackContextValue } from "./types.js";
+
+const RoutedFeedbackContext = createContext<RoutedFeedbackContextValue | null>(
+  null,
+);
+
+export const RoutedFeedbackProvider = RoutedFeedbackContext.Provider;
+
+export function useRoutedFeedback(): RoutedFeedbackContextValue {
+  const value = useContext(RoutedFeedbackContext);
+
+  if (value === null) {
+    throw new Error(
+      "Routed feedback screens must be rendered inside FeedbackStackLayout.",
+    );
+  }
+
+  return value;
+}

package/src/native/expo/RoutedFeedbackModalContext.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+
+interface RoutedFeedbackModalContextValue {
+  dismiss: () => void;
+}
+
+const RoutedFeedbackModalContext =
+  createContext<RoutedFeedbackModalContextValue | null>(null);
+
+export const RoutedFeedbackModalProvider = RoutedFeedbackModalContext.Provider;
+
+export function useRoutedFeedbackModal() {
+  return useContext(RoutedFeedbackModalContext);
+}

package/src/native/expo/index.ts

@@ -1,8 +1,14 @@
 export * from "../../shared/context/FeedbackBodyProvider.js";
 export * from "../../shared/context/FeedbackProvider.js";
 export * from "../../shared/messages.js";
+export * from "../../shared/metadata.js";
 export * from "../../shared/theme.js";
 export type * from "../../shared/types/index.js";
 export * from "../shared/ui/primitives.js";
+export * from "./metadata.js";
 export * from "./FeedbackScreen.js";
+export * from "./FeedbackCreateStackLayout.js";
+export * from "./FeedbackStackLayout.js";
+export * from "./FeedbackRoutes.js";
+export * from "./routes.js";
 export type * from "./types.js";

package/src/native/expo/metadata.ts

@@ -0,0 +1,62 @@
+import type { FeedbackMetadataValue } from "convex-feedback";
+import Constants from "expo-constants";
+import { Platform } from "react-native";
+
+import type {
+  StandardMetadataKey,
+  EnabledStandardMetadataSelection,
+} from "../../shared/types/metadata.js";
+import {
+  collectNativeMetadata,
+  defaultNativeMetadataKeys,
+} from "../shared/metadata.js";
+
+const defaultExpoMetadataKeys: readonly StandardMetadataKey[] = [
+  ...defaultNativeMetadataKeys,
+  "appVersion",
+  "buildNumber",
+  "applicationId",
+  "expoRuntimeVersion",
+  "executionEnvironment",
+];
+
+export function collectExpoMetadata(
+  selection: EnabledStandardMetadataSelection,
+): Partial<Record<StandardMetadataKey, FeedbackMetadataValue>> {
+  const selected = selection === true ? defaultExpoMetadataKeys : selection;
+  const keys = new Set(selected);
+  const metadata = collectNativeMetadata(selected);
+  const config = Constants.expoConfig;
+
+  if (keys.has("appVersion") && config?.version)
+    metadata.appVersion = config.version;
+
+  if (keys.has("buildNumber")) {
+    const buildNumber =
+      Platform.OS === "ios"
+        ? (Constants.platform?.ios?.buildNumber ?? config?.ios?.buildNumber)
+        : Platform.OS === "android"
+          ? (Constants.platform?.android?.versionCode ??
+            config?.android?.versionCode)
+          : undefined;
+    if (buildNumber !== undefined && buildNumber !== null)
+      metadata.buildNumber = buildNumber;
+  }
+
+  if (keys.has("applicationId")) {
+    const applicationId =
+      Platform.OS === "ios"
+        ? config?.ios?.bundleIdentifier
+        : Platform.OS === "android"
+          ? config?.android?.package
+          : undefined;
+    if (applicationId) metadata.applicationId = applicationId;
+  }
+
+  if (keys.has("expoRuntimeVersion") && Constants.expoRuntimeVersion)
+    metadata.expoRuntimeVersion = Constants.expoRuntimeVersion;
+  if (keys.has("executionEnvironment"))
+    metadata.executionEnvironment = Constants.executionEnvironment;
+
+  return metadata;
+}

package/src/native/expo/routes.ts

@@ -0,0 +1,41 @@
+import type { Href } from "expo-router";
+import type { FeedbackRouteNames } from "./types.js";
+
+export const defaultFeedbackRoutes: FeedbackRouteNames = {
+  board: "index",
+  entry: "[entryId]",
+  create: "new",
+};
+
+export function resolveFeedbackRoutes(
+  routes: Partial<FeedbackRouteNames> = {},
+): FeedbackRouteNames {
+  const resolved = { ...defaultFeedbackRoutes, ...routes };
+
+  if (!resolved.entry.includes("[entryId]")) {
+    throw new Error(
+      'The routed feedback entry route must contain the "[entryId]" dynamic segment.',
+    );
+  }
+
+  return resolved;
+}
+
+export function createFeedbackStackSettings(
+  routes?: Partial<FeedbackRouteNames>,
+) {
+  return { anchor: resolveFeedbackRoutes(routes).board };
+}
+
+export const feedbackStackSettings = createFeedbackStackSettings();
+
+/** Anchor the create form beneath suggested-entry detail screens. */
+export const feedbackCreateStackSettings = { anchor: "index" };
+
+export function feedbackRouteHref(
+  route: string,
+  params?: Record<string, string>,
+): Href {
+  const pathname = route.startsWith(".") ? route : `./${route}`;
+  return params === undefined ? pathname : { pathname, params };
+}