convex-feedback-ui 0.1.4 → 0.1.6

package/src/shared/metadata.ts

@@ -0,0 +1,84 @@
+import type {
+  EntryKind,
+  FeedbackMetadata,
+  FeedbackMetadataValue,
+} from "convex-feedback";
+
+import type {
+  CollectMetadata,
+  EnabledStandardMetadataSelection,
+  MetadataCollectionContext,
+  MetadataSource,
+  StandardMetadataKey,
+} from "./types/metadata.js";
+
+export type StandardMetadataCollector = (
+  selection: EnabledStandardMetadataSelection,
+) => Partial<Record<StandardMetadataKey, FeedbackMetadataValue>>;
+
+async function resolveAdditionalMetadata(
+  source: MetadataSource | undefined,
+  context: MetadataCollectionContext,
+): Promise<Record<string, FeedbackMetadataValue>> {
+  if (source === undefined) return {};
+
+  try {
+    return typeof source === "function" ? await source(context) : source;
+  } catch {
+    return {};
+  }
+}
+
+export async function collectEntryMetadata(
+  config: CollectMetadata | undefined,
+  kind: EntryKind,
+  collectStandard: StandardMetadataCollector,
+): Promise<FeedbackMetadata | undefined> {
+  if (config === undefined || config === false) return undefined;
+
+  const root = config === true ? { standard: true as const } : config;
+  const kindConfig = root.kinds?.[kind];
+  if (kindConfig === false) return undefined;
+
+  const kindOptions =
+    kindConfig === true ? { standard: true as const } : kindConfig;
+  const standardSelection = kindOptions?.standard ?? root.standard ?? false;
+  const context = { kind } satisfies MetadataCollectionContext;
+  const [globalAdditional, kindAdditional] = await Promise.all([
+    resolveAdditionalMetadata(root.additional, context),
+    resolveAdditionalMetadata(kindOptions?.additional, context),
+  ]);
+
+  let standard: FeedbackMetadata["standard"];
+  try {
+    standard =
+      standardSelection === false
+        ? undefined
+        : collectStandard(standardSelection);
+  } catch {
+    standard = undefined;
+  }
+
+  const additional = { ...globalAdditional, ...kindAdditional };
+  const hasStandard =
+    standard !== undefined && Object.keys(standard).length > 0;
+  const hasAdditional = Object.keys(additional).length > 0;
+
+  if (!hasStandard && !hasAdditional) return undefined;
+
+  return {
+    ...(hasStandard ? { standard } : {}),
+    ...(hasAdditional ? { additional } : {}),
+  };
+}
+
+export function formatMetadataKey(key: string): string {
+  const words = key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim();
+
+  return words.length === 0
+    ? key
+    : words.charAt(0).toLocaleUpperCase("en-US") + words.slice(1);
+}

package/src/shared/types/index.ts

@@ -4,6 +4,7 @@ export type * from "./context.js";
 export type * from "./entry.js";
 export type * from "./form.js";
 export type * from "./messages.js";
+export type * from "./metadata.js";
 export type * from "./render.js";
 export type * from "./screen.js";
 export type * from "./theme.js";

package/src/shared/types/messages.ts

@@ -67,6 +67,27 @@ export interface FeedbackMessages {
     back: string;
   };
 
+  /** Moderator-only diagnostic metadata copy. */
+  metadata: {
+    /** Action that opens the metadata viewer. */
+    view: string;
+
+    /** Metadata viewer heading. */
+    title: string;
+
+    /** Heading for automatically collected values. */
+    standard: string;
+
+    /** Heading for host-provided values. */
+    additional: string;
+
+    /** Empty state for a metadata object without values. */
+    empty: string;
+
+    /** Closes the metadata viewer. */
+    close: string;
+  };
+
   /** Create-entry form copy. */
   form: {
     /** Entry-kind field label. */
@@ -167,6 +188,9 @@ export interface FeedbackMessageOverrides {
   /** Entry action/counter copy overrides. */
   entry?: Partial<FeedbackMessages["entry"]> | undefined;
 
+  /** Diagnostic metadata copy overrides. */
+  metadata?: Partial<FeedbackMessages["metadata"]> | undefined;
+
   /** Create-entry form copy overrides. */
   form?: Partial<FeedbackMessages["form"]> | undefined;
 

package/src/shared/types/metadata.ts

@@ -0,0 +1,55 @@
+import type { EntryKind, FeedbackMetadataValue } from "convex-feedback";
+
+export type StandardMetadataKey =
+  | "platform"
+  | "userAgent"
+  | "language"
+  | "timezone"
+  | "screenWidth"
+  | "screenHeight"
+  | "viewportWidth"
+  | "viewportHeight"
+  | "devicePixelRatio"
+  | "osVersion"
+  | "deviceModel"
+  | "pixelRatio"
+  | "fontScale"
+  | "appVersion"
+  | "buildNumber"
+  | "applicationId"
+  | "expoRuntimeVersion"
+  | "executionEnvironment";
+
+export type EnabledStandardMetadataSelection =
+  true | readonly StandardMetadataKey[];
+
+export type StandardMetadataSelection =
+  false | EnabledStandardMetadataSelection;
+
+export interface MetadataCollectionContext {
+  kind: EntryKind;
+}
+
+export type AdditionalMetadata = Record<string, FeedbackMetadataValue>;
+
+export type MetadataSource =
+  | AdditionalMetadata
+  | ((
+      context: MetadataCollectionContext,
+    ) => AdditionalMetadata | Promise<AdditionalMetadata>);
+
+export interface MetadataCollectionOptions {
+  /** Standard platform fields to collect. `true` selects platform defaults. */
+  standard?: StandardMetadataSelection;
+
+  /** Static or submission-time host metadata. */
+  additional?: MetadataSource;
+}
+
+export interface MetadataCollectionConfig extends MetadataCollectionOptions {
+  /** Per-entry-kind overrides. `false` disables all collection for that kind. */
+  kinds?: Partial<Record<EntryKind, boolean | MetadataCollectionOptions>>;
+}
+
+/** Metadata collection configuration accepted by prebuilt feedback screens. */
+export type CollectMetadata = boolean | MetadataCollectionConfig;

package/src/shared/types/screen.ts

@@ -9,6 +9,8 @@ import type { FeedbackHooks } from "convex-feedback/react";
 import type { ReactNode } from "react";
 
 import type { FeedbackColorProps, FeedbackProviderProps } from "./context.js";
+import type { CollectMetadata } from "./metadata.js";
+import type { StandardMetadataCollector } from "../metadata.js";
 
 /**
  * Presentation-only transform applied to one currently loaded comment page.
@@ -87,6 +89,12 @@ export interface FeedbackScreenBaseProps {
    * @default 300
    */
   debounceDuration?: number;
+
+  /**
+   * Enables creation-time diagnostic metadata collection globally and/or by
+   * entry kind. Disabled by default.
+   */
+  collectMetadata?: CollectMetadata;
 }
 
 export interface FeedbackScreenRootProps
@@ -98,8 +106,11 @@ export interface FeedbackScreenRootProps
 
 export interface FeedbackScreenProviderProps
   extends
-    Required<FeedbackScreenBaseProps>,
-    FeedbackScreenTransformationProps {}
+    Required<Omit<FeedbackScreenBaseProps, "collectMetadata">>,
+    FeedbackScreenTransformationProps {
+  collectMetadata?: CollectMetadata;
+  collectStandardMetadata: StandardMetadataCollector;
+}
 
 export interface FeedbackScreenBodyContextValue
   extends FeedbackScreenTransformationProps, FeedbackScreenProviderProps {
@@ -128,6 +139,10 @@ export interface FeedbackScreenListProps {
   hideBackButton?: boolean;
   /** Callback when the EntryCard is opened. */
   onEntryOpen: (entryId: string) => void;
+  /** Whether provider-selected entries are rendered in place of the list.
+   * @default true
+   */
+  showSelectedEntry?: boolean;
 }
 
 export interface FeedbackScreenContentProps