convex-feedback-ui 0.1.4 → 0.1.6

package/README.md

@@ -4,9 +4,9 @@
 
 # convex-feedback-ui
 
-| Expo                                 | React Native                                   |
-| ------------------------------------ | ---------------------------------------------- |
-| ![Expo](./docs/screenshots/expo.png) | ![React Native](./docs/screenshots/native.png) |
+| Expo                                                                                                | React Native                                                                                                  |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| ![Expo](https://raw.githubusercontent.com/Moumen-io/convex-feedback/main/docs/screenshots/expo.png) | ![React Native](https://raw.githubusercontent.com/Moumen-io/convex-feedback/main/docs/screenshots/native.png) |
 
 Optional React DOM, React Native, and Expo Router UI for `convex-feedback`.
 
@@ -121,6 +121,20 @@ Stack options can be customized through `StackOptions`:
 />
 ```
 
+iOS toolbar actions keep their package-provided SF Symbols. Android accepts
+host-provided image sources; when an image is omitted, the action falls back to
+its text label:
+
+```tsx
+<FeedbackScreen
+  hooks={feedbackHooks}
+  androidToolbarIcons={{
+    create: require("./assets/add.png"),
+    back: require("./assets/back.png"),
+  }}
+/>
+```
+
 ### Using the Expo screen without stack integration
 
 Expo projects do not have to use the native stack integration.
@@ -135,6 +149,165 @@ When `useStack={false}`, the Expo convenience screen behaves like the regular Re
 
 `StackOptions` is only available when stack integration is enabled.
 
+### Routed Expo navigation
+
+For real stacked routes, use the additive routed API. Expo Router discovers
+routes from the application's `app` directory, so the host application supplies
+small route files while the package supplies their layouts and screens:
+
+```text
+app/feedback/
+├── _layout.tsx
+├── index.tsx
+├── [entryId].tsx
+└── new/
+    ├── _layout.tsx
+    ├── index.tsx
+    └── [entryId].tsx
+```
+
+The layout owns the feedback providers and keeps them mounted across the board,
+entry-detail, and create-entry routes:
+
+```tsx
+// app/feedback/_layout.tsx
+import {
+  FeedbackStackLayout,
+  feedbackStackSettings,
+} from "convex-feedback-ui/expo";
+import { feedbackHooks } from "../../feedback";
+
+export const unstable_settings = feedbackStackSettings;
+
+export default function Layout() {
+  return (
+    <FeedbackStackLayout
+      hooks={feedbackHooks}
+      androidToolbarIcons={{
+        create: require("../../assets/add.png"),
+        back: require("../../assets/back.png"),
+        close: require("../../assets/close.png"),
+      }}
+      screenOptions={{ headerTintColor: "#5b5bd6" }}
+      boardOptions={{ headerLargeTitleEnabled: true }}
+      entryOptions={{ headerBackTitle: "Feedback" }}
+      createOptions={{ presentation: "formSheet" }}
+    />
+  );
+}
+```
+
+Each page file only needs to re-export its package screen:
+
+```tsx
+// app/feedback/index.tsx
+export { FeedbackBoardScreen as default } from "convex-feedback-ui/expo";
+
+// app/feedback/[entryId].tsx
+export { FeedbackEntryScreen as default } from "convex-feedback-ui/expo";
+
+// app/feedback/new/_layout.tsx
+import {
+  FeedbackCreateStackLayout,
+  feedbackCreateStackSettings,
+} from "convex-feedback-ui/expo";
+
+export const unstable_settings = feedbackCreateStackSettings;
+export default FeedbackCreateStackLayout;
+
+// app/feedback/new/index.tsx
+export { CreateFeedbackScreen as default } from "convex-feedback-ui/expo";
+
+// app/feedback/new/[entryId].tsx
+export { FeedbackEntryScreen as default } from "convex-feedback-ui/expo";
+```
+
+`FeedbackStackLayout` uses these route names by default:
+
+```ts
+{
+  board: "index",
+  entry: "[entryId]",
+  create: "new",
+}
+```
+
+Names can be partially overridden when the files use a different structure.
+The create name identifies its nested route directory, and the entry route must
+exist both beside that directory and inside it while retaining the `[entryId]`
+dynamic segment:
+
+```tsx
+const routes = {
+  entry: "entry/[entryId]",
+  create: "create",
+};
+
+export const unstable_settings = createFeedbackStackSettings(routes);
+
+export default function Layout() {
+  return <FeedbackStackLayout hooks={feedbackHooks} routes={routes} />;
+}
+```
+
+The board's search and loaded list remain mounted when another screen is
+pushed, so returning restores the prior query and scroll position. The create
+route is a modal navigator by default. Duplicate suggestions push the normal
+detail screen inside that modal's stack, with back and close controls. After
+creation, the complete modal is dismissed and the created entry replaces it on
+the board stack.
+
+See `packages/example-expo-routed` for a complete application.
+
+## Diagnostic metadata
+
+Prebuilt screens can collect creation-time diagnostic metadata for feedback entries. Collection is disabled by default and never applies to comments.
+
+Enable the platform defaults for every entry kind:
+
+```tsx
+<FeedbackScreen hooks={feedbackHooks} collectMetadata />
+```
+
+Or combine global defaults with per-kind behavior:
+
+```tsx
+<FeedbackScreen
+  hooks={feedbackHooks}
+  collectMetadata={{
+    standard: true,
+    additional: { releaseChannel: "production" },
+    kinds: {
+      feedback: false,
+      feature_request: {
+        standard: ["platform", "appVersion"],
+      },
+      bug_report: {
+        standard: true,
+        additional: async ({ kind }) => ({
+          kind,
+          accountTier: await getAccountTier(),
+        }),
+      },
+    },
+  }}
+/>
+```
+
+- A kind-specific `standard` selection replaces the global selection. Global and kind-specific `additional` values are merged, with kind-specific keys taking precedence.
+- A kind set to `false` disables all metadata collection for that kind.
+- Collection happens only when the user finally submits.
+- Unavailable or failed collection sources are omitted without blocking feedback submission.
+
+- Web defaults include `platform`, `user agent`, `language`, `timezone`, `screen` and `viewport` dimensions, and `device pixel ratio`.
+- React Native defaults include `platform`, `OS` version, available device model, screen `dimensions`, `pixel ratio`, and `font scale`.
+- The Expo entry point additionally uses `expo-constants` for app `version`, `build` number, `application ID`, `Expo runtime version`, and execution `environment` when available.
+- Generic React Native apps can provide app `version` and `build` values through `additional`.
+
+Metadata is stored in separate `standard` and `additional` sections. It is omitted from list and search results and from non-moderator reads. When the host's server-side actor resolver identifies a moderator, `getEntry` includes the metadata and the entry detail screen shows a metadata viewer.
+
+The platform collectors and `formatMetadataKey` helper are exported from their respective package entry points for custom integrations.
+
 ## Choosing an API
 
 For a complete implementation with minimal setup: