convex-feedback-ui 0.2.0-beta.2 → 0.2.0-beta.4

package/src/native/expo/README.md

@@ -52,5 +52,13 @@ The existing `FeedbackScreen` remains the self-contained API for conditional
 in-screen navigation.
 
 `RoadmapScreen` is also exported from this entry point for public roadmap
-browsing. Pass `onEntryOpen` for host navigation and `onUnauthenticated` for
-the host's sign-in UI.
+browsing. It uses the current Expo Router stack by default, including its
+native Stack title, search bar, and toolbar back action; pass `useStack={false}`
+for the plain React Native implementation. Pass `onEntryOpen` for host navigation and
+`onUnauthenticated` for the host's sign-in UI. For real Expo Router pages, use
+`RoadmapStackLayout` with `RoadmapBoardScreen` and `RoadmapItemScreen`, just
+as the routed feedback integration uses its own stack layout.
+
+The routed entry page includes an explicit Stack back action so navigation into
+feedback from a roadmap item remains reversible even when the host uses nested
+Expo Router stacks.

package/src/native/expo/RoadmapRoutes.tsx

@@ -0,0 +1,171 @@
+import { Stack, useLocalSearchParams, useRouter } from "expo-router";
+import { useRef, useState } from "react";
+import { ActivityIndicator } from "react-native";
+import type { SearchBarCommands } from "react-native-screens";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+import { useFeedbackBody } from "../../shared/context/FeedbackBodyProvider.js";
+import { useFeedbackUi } from "../../shared/context/FeedbackProvider.js";
+import { FeedbackBoard } from "../shared/ui/primitives.js";
+import {
+  RoadmapBoardContent,
+  RoadmapItemContent,
+} from "../shared/ui/RoadmapScreen.js";
+import {
+  roadmapRouteHref,
+  roadmapRouteParams,
+  parseRoadmapRouteItem,
+} from "./routes.js";
+import { useRoutedRoadmap } from "./RoutedRoadmapContext.js";
+
+export function RoadmapBoardScreen() {
+  const { messages, theme } = useFeedbackUi();
+  const { routes, colors, androidToolbarIcons, pageSize } = useRoutedRoadmap();
+  const router = useRouter();
+  const [query, setQuery] = useState("");
+  const searchRef = useRef<SearchBarCommands>(null);
+
+  return (
+    <>
+      <Stack.Screen
+        options={{
+          headerTitle: messages.roadmap.title,
+          headerBackVisible: false,
+        }}
+      />
+      <FeedbackBoard.Root {...colors}>
+        <RoadmapBoardContent
+          pageSize={pageSize}
+          query={query}
+          onQueryChange={setQuery}
+          showHeader={false}
+          onItemOpen={(item) => {
+            searchRef.current?.blur();
+            router.push(
+              roadmapRouteHref(routes.item, roadmapRouteParams(item)),
+              { relativeToDirectory: true },
+            );
+          }}
+        />
+      </FeedbackBoard.Root>
+
+      <Stack.SearchBar
+        ref={searchRef}
+        placeholder={messages.roadmap.searchPlaceholder}
+        onChangeText={(event) =>
+          setQuery(
+            (event as unknown as { nativeEvent: { text: string } }).nativeEvent
+              .text,
+          )
+        }
+        obscureBackground={false}
+        allowToolbarIntegration
+        hideNavigationBar={false}
+        textColor={theme.colors.text}
+      />
+      <Stack.Toolbar placement="bottom">
+        <Stack.Toolbar.SearchBarSlot />
+      </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()}
+          tintColor={theme.colors.text}
+        >
+          {messages.entry.back}
+        </Stack.Toolbar.Button>
+      </Stack.Toolbar>
+    </>
+  );
+}
+
+export function RoadmapItemScreen() {
+  const params = useLocalSearchParams<{
+    roadmapId?: string | string[];
+    item?: string | string[];
+  }>();
+  const { hooks } = useFeedbackBody();
+  const { messages, theme } = useFeedbackUi();
+  const { routes, colors, androidToolbarIcons, entryPageSize, onEntryOpen } =
+    useRoutedRoadmap();
+  const router = useRouter();
+  const insets = useSafeAreaInsets();
+  const roadmapId = Array.isArray(params.roadmapId)
+    ? params.roadmapId[0]
+    : params.roadmapId;
+  const routeItem = parseRoadmapRouteItem(params.item);
+  const roadmap = hooks.useRoadmap();
+  const item =
+    roadmap.results.find((candidate) => candidate.id === roadmapId) ??
+    routeItem;
+
+  if (!roadmapId) {
+    throw new Error(
+      'RoadmapItemScreen requires a "roadmapId" dynamic route parameter.',
+    );
+  }
+
+  return (
+    <>
+      {item ? (
+        <>
+          <Stack.Screen
+            options={{ headerTitle: item.title, headerBackVisible: false }}
+          />
+          <FeedbackBoard.Root {...colors}>
+            <FeedbackBoard.List
+              style={{
+                padding: theme.spacing,
+                paddingBottom: insets.bottom + theme.spacing * 2,
+                backgroundColor: theme.colors.background,
+              }}
+            >
+              <RoadmapItemContent
+                item={item}
+                entryPageSize={entryPageSize}
+                onEntryOpen={onEntryOpen}
+              />
+            </FeedbackBoard.List>
+          </FeedbackBoard.Root>
+        </>
+      ) : (
+        <FeedbackBoard.Root {...colors}>
+          <FeedbackBoard.State>
+            {roadmap.status === "LoadingFirstPage" ? (
+              <ActivityIndicator color={theme.colors.primary} />
+            ) : (
+              messages.roadmap.noItems
+            )}
+          </FeedbackBoard.State>
+        </FeedbackBoard.Root>
+      )}
+
+      <Stack.Toolbar placement="left">
+        <Stack.Toolbar.Button
+          icon={
+            process.env.EXPO_OS === "ios"
+              ? "chevron.backward"
+              : androidToolbarIcons.back
+          }
+          accessibilityLabel={messages.entry.back}
+          onPress={() => {
+            if (router.canGoBack()) {
+              router.back();
+            } else {
+              router.replace(roadmapRouteHref(routes.board));
+            }
+          }}
+          tintColor={theme.colors.text}
+        >
+          {messages.entry.back}
+        </Stack.Toolbar.Button>
+      </Stack.Toolbar>
+    </>
+  );
+}

package/src/native/expo/RoadmapScreen.tsx

@@ -0,0 +1,177 @@
+import { Stack, useRouter } from "expo-router";
+import { useRef, useState } from "react";
+import type { SearchBarCommands } from "react-native-screens";
+
+import { useFeedbackUi } from "../../shared/context/FeedbackProvider.js";
+import type { mergeFeedbackMessages } from "../../shared/messages.js";
+import type { mergeFeedbackTheme } from "../../shared/theme.js";
+import type { RoadmapScreenProps } from "../../shared/types/index.js";
+import {
+  RoadmapProvider,
+  RoadmapScreen as NativeRoadmapScreen,
+  RoadmapScreenContent,
+} from "../shared/ui/RoadmapScreen.js";
+import type {
+  RoadmapAndroidToolbarIcons,
+  RoadmapStackScreenOptions,
+} from "./types.js";
+
+interface RoadmapScreenWithStack {
+  /** Enables the current Expo Router stack integration. @default true */
+  useStack?: true;
+  /** Options applied to the current Expo Router screen. */
+  StackOptions?: RoadmapStackScreenOptions;
+  /** Android image source for the toolbar back action. */
+  androidToolbarIcons?: RoadmapAndroidToolbarIcons;
+}
+
+interface RoadmapScreenWithoutStack {
+  useStack: false;
+  StackOptions?: never;
+  androidToolbarIcons?: never;
+}
+
+export type ExpoRoadmapScreenProps = RoadmapScreenProps &
+  (RoadmapScreenWithStack | RoadmapScreenWithoutStack);
+
+/**
+ * Convenience roadmap screen for a single Expo route. Use
+ * `RoadmapStackLayout` when the board and item detail should be separate
+ * discovered Expo Router pages.
+ */
+export function RoadmapScreen(props: ExpoRoadmapScreenProps) {
+  if (props.useStack === false) {
+    return <NativeRoadmapScreen {...props} />;
+  }
+
+  return (
+    <RoadmapProvider
+      hooks={props.hooks}
+      messages={props.messages}
+      theme={props.theme}
+      unstyled={props.unstyled}
+      commentSort={props.commentSort}
+      maxCommentDepth={props.maxCommentDepth}
+      transformComments={props.transformComments}
+      renderActor={props.renderActor}
+      onUnauthenticated={props.onUnauthenticated}
+    >
+      <StackedRoadmapScreen props={props} />
+    </RoadmapProvider>
+  );
+}
+
+function StackedRoadmapScreen({
+  props,
+}: {
+  props: RoadmapScreenWithStack & RoadmapScreenProps;
+}) {
+  const {
+    androidToolbarIcons = {},
+    hooks,
+    pageSize,
+    entryPageSize,
+    onEntryOpen,
+    onUnauthenticated,
+    primaryColor,
+    primaryForeground,
+    backgroundColor,
+    surfaceColor,
+    textColor,
+    mutedColor,
+    borderColor,
+    dangerColor,
+  } = props;
+  const { messages, theme } = useFeedbackUi();
+  const [query, setQuery] = useState("");
+  const searchRef = useRef<SearchBarCommands>(null);
+
+  return (
+    <>
+      <Stack.Screen
+        options={{
+          headerTitle: messages.roadmap.title,
+          headerShown: true,
+          headerTransparent: false,
+          headerShadowVisible: true,
+          headerBackButtonDisplayMode: "minimal",
+          headerBackVisible: false,
+          headerTintColor: textColor ?? theme.colors.text,
+          contentStyle: {
+            backgroundColor: backgroundColor ?? theme.colors.background,
+          },
+          ...props.StackOptions,
+        }}
+      />
+      <Stack.SearchBar
+        ref={searchRef}
+        placeholder={messages.roadmap.searchPlaceholder}
+        onChangeText={(event) =>
+          setQuery(
+            (event as unknown as { nativeEvent: { text: string } }).nativeEvent
+              .text,
+          )
+        }
+        obscureBackground={false}
+        allowToolbarIntegration
+        hideNavigationBar={false}
+        textColor={theme.colors.text}
+      />
+      <Stack.Toolbar placement="bottom">
+        <Stack.Toolbar.SearchBarSlot />
+      </Stack.Toolbar>
+      <RoadmapToolbar
+        androidToolbarIcons={androidToolbarIcons}
+        messages={messages}
+        theme={theme}
+      />
+      <RoadmapScreenContent
+        pageSize={pageSize ?? hooks.pageSizes.roadmap}
+        entryPageSize={entryPageSize ?? hooks.pageSizes.entries}
+        query={query}
+        onQueryChange={setQuery}
+        showBoardHeader={false}
+        onEntryOpen={onEntryOpen}
+        onUnauthenticated={onUnauthenticated}
+        primaryColor={primaryColor}
+        primaryForeground={primaryForeground}
+        backgroundColor={backgroundColor}
+        surfaceColor={surfaceColor}
+        textColor={textColor}
+        mutedColor={mutedColor}
+        borderColor={borderColor}
+        dangerColor={dangerColor}
+      />
+    </>
+  );
+}
+
+function RoadmapToolbar({
+  androidToolbarIcons,
+  messages,
+  theme,
+}: {
+  androidToolbarIcons: RoadmapAndroidToolbarIcons;
+  messages: ReturnType<typeof mergeFeedbackMessages>;
+  theme: ReturnType<typeof mergeFeedbackTheme>;
+}) {
+  const router = useRouter();
+
+  return (
+    <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()}
+        tintColor={theme.colors.text}
+      >
+        {messages.entry.back}
+      </Stack.Toolbar.Button>
+    </Stack.Toolbar>
+  );
+}

package/src/native/expo/RoadmapStackLayout.tsx

@@ -0,0 +1,110 @@
+import { Stack, type NativeStackNavigationOptions } from "expo-router";
+
+import { mergeFeedbackMessages } from "../../shared/messages.js";
+import { mergeFeedbackTheme } from "../../shared/theme.js";
+import { RoadmapProvider } from "../shared/ui/RoadmapScreen.js";
+import { RoutedRoadmapProvider } from "./RoutedRoadmapContext.js";
+import { resolveRoadmapRoutes } from "./routes.js";
+import type { RoadmapStackLayoutProps } from "./types.js";
+
+/**
+ * Provider and native-stack layout for real Expo Router roadmap pages.
+ * Consumers supply the small route files; this component keeps the roadmap
+ * query and entry-detail context mounted while a detail page is pushed.
+ */
+export function RoadmapStackLayout({
+  hooks,
+  messages,
+  theme,
+  unstyled,
+  onEntryOpen,
+  onUnauthenticated,
+  commentSort,
+  maxCommentDepth,
+  transformComments,
+  renderActor,
+  pageSize = hooks.pageSizes.roadmap,
+  entryPageSize = hooks.pageSizes.entries,
+  routes: routeOverrides,
+  screenOptions,
+  boardOptions,
+  itemOptions,
+  androidToolbarIcons = {},
+  primaryColor,
+  primaryForeground,
+  backgroundColor,
+  surfaceColor,
+  textColor,
+  mutedColor,
+  borderColor,
+  dangerColor,
+}: RoadmapStackLayoutProps) {
+  const routes = resolveRoadmapRoutes(routeOverrides);
+  const resolvedMessages = mergeFeedbackMessages(messages);
+  const resolvedTheme = mergeFeedbackTheme(theme);
+  const colors = {
+    primaryColor,
+    primaryForeground,
+    backgroundColor,
+    surfaceColor,
+    textColor,
+    mutedColor,
+    borderColor,
+    dangerColor,
+  };
+  const defaults: NativeStackNavigationOptions = {
+    headerShown: true,
+    headerShadowVisible: true,
+    headerBackButtonDisplayMode: "minimal",
+    headerTintColor: textColor ?? resolvedTheme.colors.text,
+    contentStyle: {
+      backgroundColor: backgroundColor ?? resolvedTheme.colors.background,
+    },
+  };
+
+  return (
+    <RoadmapProvider
+      hooks={hooks}
+      messages={messages}
+      theme={theme}
+      unstyled={unstyled}
+      commentSort={commentSort}
+      maxCommentDepth={maxCommentDepth}
+      transformComments={transformComments}
+      renderActor={renderActor}
+      onUnauthenticated={onUnauthenticated}
+    >
+      <RoutedRoadmapProvider
+        value={{
+          routes,
+          colors,
+          androidToolbarIcons,
+          pageSize,
+          entryPageSize,
+          onEntryOpen,
+        }}
+      >
+        <Stack>
+          <Stack.Screen
+            name={routes.board}
+            options={{
+              ...defaults,
+              headerTitle: resolvedMessages.roadmap.title,
+              ...screenOptions,
+              ...boardOptions,
+            }}
+          />
+          <Stack.Screen
+            name={routes.item}
+            options={{
+              ...defaults,
+              headerTitle: resolvedMessages.roadmap.title,
+              ...screenOptions,
+              ...itemOptions,
+            }}
+          />
+        </Stack>
+      </RoutedRoadmapProvider>
+    </RoadmapProvider>
+  );
+}

package/src/native/expo/RoutedRoadmapContext.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+
+import type { RoutedRoadmapContextValue } from "./types.js";
+
+const RoutedRoadmapContext = createContext<RoutedRoadmapContextValue | null>(
+  null,
+);
+
+export const RoutedRoadmapProvider = RoutedRoadmapContext.Provider;
+
+export function useRoutedRoadmap(): RoutedRoadmapContextValue {
+  const value = useContext(RoutedRoadmapContext);
+
+  if (value === null) {
+    throw new Error(
+      "Routed roadmap screens must be rendered inside RoadmapStackLayout.",
+    );
+  }
+
+  return value;
+}

package/src/native/expo/index.ts

@@ -5,11 +5,20 @@ 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 "../shared/ui/RoadmapScreen.js";
+export * from "../shared/ui/RoadmapBoard.js";
+export {
+  RoadmapBoardContent,
+  RoadmapItemContent,
+  RoadmapProvider,
+  RoadmapScreenContent,
+} from "../shared/ui/RoadmapScreen.js";
 export * from "./metadata.js";
 export * from "./FeedbackScreen.js";
 export * from "./FeedbackCreateStackLayout.js";
 export * from "./FeedbackStackLayout.js";
 export * from "./FeedbackRoutes.js";
+export * from "./RoadmapScreen.js";
+export * from "./RoadmapStackLayout.js";
+export * from "./RoadmapRoutes.js";
 export * from "./routes.js";
 export type * from "./types.js";

package/src/native/expo/routes.ts

@@ -1,5 +1,6 @@
 import type { Href } from "expo-router";
-import type { FeedbackRouteNames } from "./types.js";
+import type { RoadmapItem } from "convex-feedback";
+import type { FeedbackRouteNames, RoadmapRouteNames } from "./types.js";
 
 export const defaultFeedbackRoutes: FeedbackRouteNames = {
   board: "index",
@@ -39,3 +40,70 @@ export function feedbackRouteHref(
   const pathname = route.startsWith(".") ? route : `./${route}`;
   return params === undefined ? pathname : { pathname, params };
 }
+
+export const defaultRoadmapRoutes: RoadmapRouteNames = {
+  board: "index",
+  item: "[roadmapId]",
+};
+
+export function resolveRoadmapRoutes(
+  routes: Partial<RoadmapRouteNames> = {},
+): RoadmapRouteNames {
+  const resolved = { ...defaultRoadmapRoutes, ...routes };
+
+  if (!resolved.item.includes("[roadmapId]")) {
+    throw new Error(
+      'The routed roadmap item route must contain the "[roadmapId]" dynamic segment.',
+    );
+  }
+
+  return resolved;
+}
+
+export function createRoadmapStackSettings(
+  routes?: Partial<RoadmapRouteNames>,
+) {
+  return { anchor: resolveRoadmapRoutes(routes).board };
+}
+
+export const roadmapStackSettings = createRoadmapStackSettings();
+
+export function roadmapRouteHref(
+  route: string,
+  params?: Record<string, string>,
+): Href {
+  const pathname = route.startsWith(".") ? route : `./${route}`;
+  return params === undefined ? pathname : { pathname, params };
+}
+
+/** Pass the already loaded item through a push so a detail route renders immediately. */
+export function roadmapRouteParams(item: RoadmapItem) {
+  return { roadmapId: item.id, item: JSON.stringify(item) };
+}
+
+function firstParam(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+export function parseRoadmapRouteItem(
+  value: string | string[] | undefined,
+): RoadmapItem | undefined {
+  const serialized = firstParam(value);
+  if (!serialized) return undefined;
+
+  try {
+    const parsed: unknown = JSON.parse(serialized);
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const item = parsed as Partial<RoadmapItem>;
+    if (
+      typeof item.id !== "string" ||
+      typeof item.title !== "string" ||
+      typeof item.status !== "string"
+    ) {
+      return undefined;
+    }
+    return item as RoadmapItem;
+  } catch {
+    return undefined;
+  }
+}

package/src/native/expo/types.ts

@@ -5,6 +5,7 @@ import type { SearchBarCommands } from "react-native-screens";
 import type {
   FeedbackColorProps,
   FeedbackScreenRootProps,
+  RoadmapScreenProps,
 } from "../../shared/types";
 
 /** Optional wrapper used around Expo Router bottom toolbars. */
@@ -65,6 +66,13 @@ export interface FeedbackAndroidToolbarIcons {
   filter?: ImageSourcePropType;
 }
 
+export interface RoadmapAndroidToolbarIcons {
+  /** Android image source for back actions. */
+  back?: ImageSourcePropType;
+  /** Android image source for modal close actions. */
+  close?: ImageSourcePropType;
+}
+
 export interface FeedbackStackLayoutProps extends FeedbackScreenRootProps {
   /** Partial overrides for the prescribed route file names. */
   routes?: Partial<FeedbackRouteNames>;
@@ -91,9 +99,44 @@ export interface FeedbackCreateStackLayoutProps {
   entryOptions?: FeedbackStackScreenOptions;
 }
 
+/** File names used by the routed public roadmap stack. */
+export interface RoadmapRouteNames {
+  /** Board route. @default "index" */
+  board: string;
+  /** Roadmap item route. Must contain `[roadmapId]`. @default "[roadmapId]" */
+  item: string;
+}
+
+export type RoadmapStackScreenOptions = Exclude<
+  NonNullable<StackScreenProps["options"]>,
+  (...args: never[]) => unknown
+>;
+
+export interface RoadmapStackLayoutProps extends RoadmapScreenProps {
+  /** Partial overrides for the prescribed route file names. */
+  routes?: Partial<RoadmapRouteNames>;
+  /** Options shared by every roadmap screen. */
+  screenOptions?: RoadmapStackScreenOptions;
+  /** Roadmap board screen option overrides. */
+  boardOptions?: RoadmapStackScreenOptions;
+  /** Roadmap item screen option overrides. */
+  itemOptions?: RoadmapStackScreenOptions;
+  /** Android image sources for toolbar actions. iOS continues to use SF Symbols. */
+  androidToolbarIcons?: RoadmapAndroidToolbarIcons;
+}
+
 export interface RoutedFeedbackContextValue {
   routes: FeedbackRouteNames;
   colors: FeedbackColorProps;
   androidToolbarIcons: FeedbackAndroidToolbarIcons;
   bottomToolbarWrapper?: BottomToolbarWrapper;
 }
+
+export interface RoutedRoadmapContextValue {
+  routes: RoadmapRouteNames;
+  colors: FeedbackColorProps;
+  androidToolbarIcons: RoadmapAndroidToolbarIcons;
+  pageSize: number;
+  entryPageSize: number;
+  onEntryOpen?: RoadmapScreenProps["onEntryOpen"];
+}

package/src/native/native/README.md

@@ -16,6 +16,12 @@ 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.
 
-`RoadmapScreen` provides the public roadmap and renders attached entries with
-the same `FeedbackEntry` primitives. Pass `onUnauthenticated` to handle auth
-when an anonymous visitor votes.
+`RoadmapScreen` provides the public roadmap, groups items by delivery stage,
+and renders attached entries with the existing `EntryCard` and `EntryDetail`
+views. Pass `onUnauthenticated` to handle auth when an anonymous visitor votes
+or comments.
+
+The exported `RoadmapBoard` is the reusable admin-style horizontal board
+layout. Supply ordered stages, colors, and a `renderItem` callback to share the
+same column scrolling behavior while customizing cards for an admin or public
+surface.

package/src/native/native/index.ts

@@ -5,6 +5,7 @@ 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 "../shared/ui/RoadmapBoard.js";
 export * from "../shared/metadata.js";
 export * from "./FeedbackScreen.js";
 export * from "../shared/ui/RoadmapScreen.js";