convex-feedback-ui 0.1.1

package/src/shared/types/entry.ts

@@ -0,0 +1,48 @@
+import type { FeedbackEntry } from "convex-feedback";
+
+import type { RenderChildren } from "./render.js";
+
+/**
+ * Platform-neutral props shared by `FeedbackEntry.Root` implementations.
+ */
+export interface EntryRootBaseProps {
+  /** Entry exposed to every nested `FeedbackEntry.*` primitive. */
+  entry: FeedbackEntry;
+}
+
+/**
+ * State and actions exposed to a custom `FeedbackEntry.Upvote` renderer.
+ */
+export interface EntryUpvoteState {
+  /** Current entry. */
+  entry: FeedbackEntry;
+
+  /** Whether the current viewer has upvoted the entry. */
+  active: boolean;
+
+  /** Current total upvote count. */
+  count: number;
+
+  /** Requests the opposite of the current upvote state. */
+  toggle: () => void | Promise<void>;
+}
+
+/**
+ * Platform-neutral props shared by `FeedbackEntry.Upvote` implementations.
+ */
+export interface EntryUpvoteBaseProps {
+  /**
+   * Called with the desired final upvote state.
+   *
+   * `true` means ensure the viewer has upvoted the entry. `false` means ensure
+   * the viewer has not upvoted it. The server mutation is state-setting rather
+   * than toggle-based so it remains idempotent.
+   */
+  onToggle: (desiredState: boolean) => void | Promise<void>;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete control and receives `EntryUpvoteState`.
+   */
+  children?: RenderChildren<EntryUpvoteState> | undefined;
+}

package/src/shared/types/form.ts

@@ -0,0 +1,27 @@
+import type { RenderChildren } from "./render.js";
+
+/**
+ * State exposed to a custom `FeedbackForm.Submit` renderer.
+ */
+export interface FormSubmitState {
+  /** Whether form submission is currently in progress. */
+  submitting: boolean;
+}
+
+/**
+ * Platform-neutral props shared by `FeedbackForm.Submit` implementations.
+ */
+export interface FormSubmitBaseProps {
+  /**
+   * Whether form submission is currently in progress.
+   *
+   * @default false
+   */
+  submitting?: boolean | undefined;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete control and receives `FormSubmitState`.
+   */
+  children?: RenderChildren<FormSubmitState> | undefined;
+}

package/src/shared/types/helpers.ts

@@ -0,0 +1 @@
+export type Require<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;

package/src/shared/types/index.ts

@@ -0,0 +1,45 @@
+export type {
+  BoardRootBaseProps,
+  BoardSearchBaseProps,
+  BoardSearchState,
+} from "./board.js";
+export type {
+  CommentActionBaseProps,
+  CommentActionState,
+  CommentLikeBaseProps,
+  CommentLikeState,
+  CommentRootBaseProps,
+  RepliesButtonBaseProps,
+  RepliesButtonState,
+} from "./comment.js";
+export type {
+  FeedbackColorProps,
+  FeedbackProviderProps,
+  FeedbackUiContextValue,
+} from "./context.js";
+export type {
+  EntryRootBaseProps,
+  EntryUpvoteBaseProps,
+  EntryUpvoteState,
+} from "./entry.js";
+export type { FormSubmitBaseProps, FormSubmitState } from "./form.js";
+export type { FeedbackMessageOverrides, FeedbackMessages } from "./messages.js";
+export type { RenderChildren } from "./render.js";
+export type {
+  FeedbackActorRenderer,
+  FeedbackCommentTransform,
+  FeedbackScreenBaseProps,
+  FeedbackScreenBodyProps,
+  FeedbackScreenCommentBranchProps,
+  FeedbackScreenEntryBaseProps,
+  FeedbackScreenEntryCardProps,
+  FeedbackScreenEntryDetailProps,
+  FeedbackScreenEntryModalProps,
+  FeedbackScreenReplyListProps,
+  FeedbackScreenRootProps,
+} from "./screen.js";
+export type {
+  FeedbackColors,
+  FeedbackTheme,
+  FeedbackThemeOverride,
+} from "./theme.js";

package/src/shared/types/messages.ts

@@ -0,0 +1,160 @@
+import type { EntryKind, EntryStatus } from "convex-feedback";
+
+/**
+ * Localizable package-owned UI copy used by both React DOM and React Native.
+ *
+ * User-generated entry and comment content is never translated or rewritten
+ * by the UI package.
+ */
+export interface FeedbackMessages {
+  /** Feedback-board copy. */
+  board: {
+    /** Main board heading. */
+    title: string;
+
+    /** Supporting copy shown near the board heading. */
+    subtitle: string;
+
+    /** Search input placeholder. */
+    searchPlaceholder: string;
+
+    /** CTA for opening the create-entry flow. */
+    createEntry: string;
+
+    /** Empty-state copy when no entries exist. */
+    noEntries: string;
+
+    /** Empty-state copy when a search produces no results. */
+    noSearchResults: string;
+
+    /** Generic loading copy. */
+    loading: string;
+
+    /** Entry pagination CTA. */
+    loadMore: string;
+  };
+
+  /** Localized display labels for each fixed entry kind. */
+  kinds: Record<EntryKind, string>;
+
+  /** Localized display labels for each fixed workflow status. */
+  statuses: Record<EntryStatus, string>;
+
+  /** Entry-level action and counter copy. */
+  entry: {
+    /** Accessible/default label for adding an upvote. */
+    upvote: string;
+
+    /** Accessible/default label for removing an upvote. */
+    removeUpvote: string;
+
+    /** Formats the total comment count. */
+    comments: (count: number) => string;
+
+    /** Label for opening an entry. */
+    open: string;
+
+    /** Label for returning to the feedback list. */
+    back: string;
+  };
+
+  /** Create-entry form copy. */
+  form: {
+    /** Entry-kind field label. */
+    kind: string;
+
+    /** Entry-title field label. */
+    title: string;
+
+    /** Entry-title placeholder. */
+    titlePlaceholder: string;
+
+    /** Entry-body field label. */
+    body: string;
+
+    /** Entry-body placeholder. */
+    bodyPlaceholder: string;
+
+    /** Create-entry submit CTA. */
+    submit: string;
+
+    /** Generic form/dialog cancel action. */
+    cancel: string;
+
+    /** Heading shown when likely duplicate entries are found. */
+    possibleDuplicates: string;
+
+    /** Heading shown when an exact normalized-title match exists. */
+    exactDuplicate: string;
+
+    /** Warning shown before submitting while duplicate suggestions exist. */
+    duplicateWarning: string;
+
+    /** Confirmation action that submits despite duplicate suggestions. */
+    submitAnyway: string;
+  };
+
+  /** Comment-thread copy. */
+  comments: {
+    /** Discussion/thread heading. */
+    title: string;
+
+    /** Comment/reply input placeholder. */
+    placeholder: string;
+
+    /** Top-level comment submit action. */
+    submit: string;
+
+    /** Reply action. */
+    reply: string;
+
+    /** Cancels an in-progress reply. */
+    cancelReply: string;
+
+    /** Adds a comment like. */
+    like: string;
+
+    /** Removes a comment like. */
+    unlike: string;
+
+    /** Formats the lazy-load-replies action for a direct-reply count. */
+    viewReplies: (count: number) => string;
+
+    /** Collapses an expanded reply branch. */
+    hideReplies: string;
+
+    /** Placeholder copy for a soft-deleted comment. */
+    deleted: string;
+
+    /** Empty-state copy when no comments exist. */
+    noComments: string;
+
+    /** Comment/reply pagination CTA. */
+    loadMore: string;
+  };
+}
+
+/**
+ * Partial localization/copy overrides for the feedback UI.
+ *
+ * Values not supplied here fall back to the package's built-in English copy.
+ */
+export interface FeedbackMessageOverrides {
+  /** Board copy overrides. */
+  board?: Partial<FeedbackMessages["board"]> | undefined;
+
+  /** Entry-kind label overrides. */
+  kinds?: Partial<FeedbackMessages["kinds"]> | undefined;
+
+  /** Workflow-status label overrides. */
+  statuses?: Partial<FeedbackMessages["statuses"]> | undefined;
+
+  /** Entry action/counter copy overrides. */
+  entry?: Partial<FeedbackMessages["entry"]> | undefined;
+
+  /** Create-entry form copy overrides. */
+  form?: Partial<FeedbackMessages["form"]> | undefined;
+
+  /** Comment-thread copy overrides. */
+  comments?: Partial<FeedbackMessages["comments"]> | undefined;
+}

package/src/shared/types/render.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+
+/**
+ * Children accepted by replaceable feedback UI primitives.
+ *
+ * Pass normal React children to replace only the primitive's default content,
+ * or pass a render function to replace the complete visual implementation
+ * while retaining the primitive's typed state and actions.
+ *
+ * @typeParam State - State and actions exposed to a render-function child.
+ */
+export type RenderChildren<State> = ReactNode | ((state: State) => ReactNode);

package/src/shared/types/screen.ts

@@ -0,0 +1,123 @@
+import type {
+  CommentSort,
+  EntryKind,
+  EntrySort,
+  FeedbackComment,
+  FeedbackEntry,
+} from "convex-feedback";
+import type { FeedbackHooks } from "convex-feedback/react";
+import type { ReactNode } from "react";
+
+import type { FeedbackColorProps, FeedbackProviderProps } from "./context.js";
+import type { Require } from "./helpers.js";
+
+/**
+ * Presentation-only transform applied to one currently loaded comment page.
+ *
+ * This does not affect Convex ordering, pagination, or which descendants are
+ * loaded. It is intended only for host-specific presentation transforms.
+ */
+export type FeedbackCommentTransform = (
+  comments: readonly FeedbackComment[],
+) => readonly FeedbackComment[];
+
+/**
+ * Host renderer for actor information associated with entries/comments.
+ *
+ * The feedback component stores only stable actor IDs; profile data remains
+ * owned by the host application.
+ */
+export type FeedbackActorRenderer = (actorId: string) => ReactNode;
+
+export interface FeedbackScreenBaseProps extends FeedbackColorProps {
+  /** Hooks created with `createFeedbackHooks`. */
+  hooks: FeedbackHooks;
+
+  /**
+   * Server-side ordering used by the feedback board.
+   *
+   * @default "top"
+   */
+  entrySort?: EntrySort;
+
+  /**
+   * Server-side ordering used independently at every loaded comment/reply
+   * level.
+   *
+   * @default "top"
+   */
+  commentSort?: CommentSort;
+
+  /**
+   * Entry kinds visible in the board/search and available in the create form.
+   *
+   * The prebuilt screen passes these kinds into the Convex list/search queries;
+   * filtering must not be performed after pagination on the client.
+   *
+   * @default ["feedback", "feature_request", "bug_report"]
+   */
+  enabledKinds?: readonly EntryKind[];
+
+  /**
+   * Maximum nesting depth for which the prebuilt UI exposes a Reply action.
+   *
+   * The server-side component configuration remains authoritative and may
+   * reject a reply if this value exceeds the configured backend maximum.
+   *
+   * @default 5
+   */
+  maxCommentDepth?: number;
+
+  /**
+   * Optional presentation-only transform applied to each loaded page of
+   * comments/replies before rendering.
+   */
+  transformComments?: FeedbackCommentTransform;
+
+  /**
+   * Optional host renderer for actor IDs, useful for names, avatars, or other
+   * host-owned profile information.
+   */
+  renderActor?: FeedbackActorRenderer;
+}
+
+export interface FeedbackScreenRootProps
+  extends Omit<FeedbackProviderProps, "children">, FeedbackScreenBaseProps {}
+
+export type FeedbackScreenBodyProps = Require<
+  FeedbackScreenBaseProps,
+  "entrySort" | "commentSort" | "enabledKinds" | "maxCommentDepth"
+>;
+
+export interface FeedbackScreenEntryCardProps {
+  entry: FeedbackEntry;
+  hooks: FeedbackHooks;
+  onOpen: () => void;
+}
+
+export interface FeedbackScreenEntryModalProps {
+  hooks: FeedbackHooks;
+  enabledKinds: readonly EntryKind[];
+  onCreated: (id: string) => void;
+}
+
+export interface FeedbackScreenEntryBaseProps {
+  entryId: string;
+  hooks: FeedbackHooks;
+  commentSort: CommentSort;
+  maxCommentDepth: number;
+  transformComments?: FeedbackScreenBaseProps["transformComments"];
+  renderActor?: FeedbackScreenBaseProps["renderActor"];
+}
+
+export interface FeedbackScreenEntryDetailProps extends FeedbackScreenEntryBaseProps {
+  onBack: () => void;
+}
+
+export interface FeedbackScreenCommentBranchProps extends FeedbackScreenEntryBaseProps {
+  comment: FeedbackComment;
+}
+
+export interface FeedbackScreenReplyListProps extends FeedbackScreenEntryBaseProps {
+  parentCommentId: string;
+}

package/src/shared/types/theme.ts

@@ -0,0 +1,61 @@
+/**
+ * Semantic colors used by the feedback UI on both React DOM and React Native.
+ */
+export interface FeedbackColors {
+  /** Primary interaction and accent color. */
+  primary: string;
+
+  /** Main screen or board background color. */
+  background: string;
+
+  /** Default card and control surface color. */
+  surface: string;
+
+  /** Secondary or muted surface color. */
+  surfaceMuted: string;
+
+  /** Primary text color. */
+  text: string;
+
+  /** Secondary, metadata, and helper text color. */
+  mutedText: string;
+
+  /** Border and separator color. */
+  border: string;
+
+  /** Destructive and error-state color. */
+  danger: string;
+
+  /** Positive and success-state color. */
+  success: string;
+}
+
+/**
+ * Fully resolved visual theme consumed by feedback UI primitives.
+ */
+export interface FeedbackTheme {
+  /** Semantic feedback color palette. */
+  colors: FeedbackColors;
+
+  /** Base corner radius in logical pixels. */
+  radius: number;
+
+  /** Base spacing unit in logical pixels. */
+  spacing: number;
+}
+
+/**
+ * Partial theme accepted by feedback providers and prebuilt screens.
+ *
+ * Missing values fall back to the package's default feedback theme.
+ */
+export interface FeedbackThemeOverride {
+  /** Partial semantic color overrides. */
+  colors?: Partial<FeedbackColors> | undefined;
+
+  /** Base corner-radius override. */
+  radius?: number | undefined;
+
+  /** Base spacing-unit override. */
+  spacing?: number | undefined;
+}