convex-feedback-ui 0.1.1

package/src/react/styles.css

@@ -0,0 +1,299 @@
+:where(.cf-board) {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 920px;
+  margin: 0 auto;
+  padding: calc(var(--cf-space) * 1.5);
+  color: var(--cf-text);
+  background: var(--cf-background);
+  font: inherit;
+}
+
+:where(.cf-board *),
+:where(.cf-board *::before),
+:where(.cf-board *::after) {
+  box-sizing: border-box;
+}
+:where(.cf-board) :where(.cf-board__header) {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--cf-space);
+  margin-bottom: calc(var(--cf-space) * 1.5);
+}
+:where(.cf-board) :where(.cf-board__title) {
+  margin: 0;
+  font-size: 1.65rem;
+  line-height: 1.15;
+}
+:where(.cf-board) :where(.cf-board__subtitle) {
+  margin: 0.4rem 0 0;
+  color: var(--cf-muted);
+}
+:where(.cf-board) :where(.cf-board__list),
+:where(.cf-board) :where(.cf-comments) {
+  display: grid;
+  gap: 10px;
+}
+:where(.cf-board) :where(.cf-search),
+:where(.cf-board) :where(.cf-input),
+:where(.cf-board) :where(.cf-textarea),
+:where(.cf-board) :where(.cf-select) {
+  width: 100%;
+  border: 1px solid var(--cf-border);
+  border-radius: calc(var(--cf-radius) * 0.75);
+  background: var(--cf-surface);
+  color: var(--cf-text);
+  padding: 10px 12px;
+  font: inherit;
+  outline: none;
+}
+:where(.cf-board) :where(.cf-search) {
+  margin-bottom: var(--cf-space);
+}
+:where(.cf-board) :where(.cf-search:focus),
+:where(.cf-board) :where(.cf-input:focus),
+:where(.cf-board) :where(.cf-textarea:focus),
+:where(.cf-board) :where(.cf-select:focus) {
+  border-color: var(--cf-primary);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--cf-primary) 14%, transparent);
+}
+:where(.cf-board) :where(.cf-entry) {
+  display: grid;
+  grid-template-columns: 52px minmax(0, 1fr);
+  gap: 12px;
+  padding: 14px;
+  border: 1px solid var(--cf-border);
+  border-radius: var(--cf-radius);
+  background: var(--cf-surface);
+}
+:where(.cf-board) :where(.cf-entry__content) {
+  min-width: 0;
+  cursor: pointer;
+}
+:where(.cf-board) :where(.cf-entry__title) {
+  margin: 5px 0 3px;
+  font-size: 1rem;
+}
+:where(.cf-board) :where(.cf-entry__body) {
+  margin: 0;
+  color: var(--cf-muted);
+  line-height: 1.5;
+  white-space: pre-wrap;
+}
+:where(.cf-board) :where(.cf-entry__meta) {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  flex-wrap: wrap;
+  color: var(--cf-muted);
+  font-size: 0.8rem;
+}
+:where(.cf-board) :where(.cf-entry__kind) {
+  color: var(--cf-muted);
+  font-size: 0.78rem;
+  font-weight: 600;
+}
+:where(.cf-board) :where(.cf-status) {
+  display: inline-flex;
+  border-radius: 999px;
+  padding: 3px 8px;
+  background: var(--cf-surface-muted);
+  color: var(--cf-muted);
+  font-size: 0.78rem;
+  font-weight: 600;
+}
+:where(.cf-board) :where(.cf-upvote) {
+  width: 46px;
+  min-height: 54px;
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 2px;
+  border: 1px solid var(--cf-border);
+  border-radius: 10px;
+  background: var(--cf-surface-muted);
+  color: var(--cf-muted);
+  cursor: pointer;
+}
+:where(.cf-board) :where(.cf-upvote[data-active="true"]) {
+  border-color: var(--cf-primary);
+  color: var(--cf-primary);
+  background: color-mix(in srgb, var(--cf-primary) 8%, var(--cf-surface));
+}
+:where(.cf-board) :where(.cf-button) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  min-height: 38px;
+  border: 1px solid var(--cf-border);
+  border-radius: 9px;
+  padding: 8px 12px;
+  background: var(--cf-surface);
+  color: var(--cf-text);
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+:where(.cf-board) :where(.cf-button--primary) {
+  border-color: var(--cf-primary);
+  background: var(--cf-primary);
+  color: white;
+}
+:where(.cf-board) :where(.cf-button--link) {
+  border-color: transparent;
+  padding-inline: 0;
+  background: transparent;
+  color: var(--cf-primary);
+}
+:where(.cf-board) :where(.cf-form) {
+  display: grid;
+  gap: 10px;
+  padding: 14px;
+  border: 1px solid var(--cf-border);
+  border-radius: var(--cf-radius);
+  background: var(--cf-surface-muted);
+  margin-bottom: 14px;
+}
+:where(.cf-board) :where(.cf-field) {
+  display: grid;
+  gap: 5px;
+  font-size: 0.88rem;
+  font-weight: 600;
+}
+:where(.cf-board) :where(.cf-duplicates) {
+  display: grid;
+  gap: 5px;
+  padding: 10px;
+  border-radius: 9px;
+  background: color-mix(in srgb, var(--cf-primary) 7%, var(--cf-surface));
+  font-size: 0.86rem;
+}
+:where(.cf-board) :where(.cf-duplicates__list) {
+  display: grid;
+  gap: 8px;
+}
+
+:where(.cf-board) :where(.cf-duplicate) {
+  display: grid;
+  gap: 5px;
+  padding: 10px;
+  border: 1px solid var(--cf-border);
+  border-radius: calc(var(--cf-radius) * 0.75);
+  background: var(--cf-surface);
+}
+
+:where(.cf-board) :where(.cf-duplicate__body),
+:where(.cf-board) :where(.cf-duplicate__meta) {
+  color: var(--cf-muted);
+  font-size: 0.82rem;
+}
+
+:where(.cf-board) :where(.cf-duplicate__body) {
+  display: -webkit-box;
+  overflow: hidden;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+:where(.cf-board) :where(.cf-state) {
+  color: var(--cf-muted);
+  padding: 12px 2px;
+}
+:where(.cf-board) :where(.cf-detail),
+:where(.cf-board) :where(.cf-discussion) {
+  display: grid;
+  gap: 14px;
+}
+:where(.cf-board) :where(.cf-discussion) {
+  margin-top: 8px;
+}
+:where(.cf-board) :where(.cf-comment) {
+  padding: 12px;
+  border: 1px solid var(--cf-border);
+  border-radius: calc(var(--cf-radius) * 0.85);
+  background: var(--cf-surface);
+}
+:where(.cf-board) :where(.cf-comment__body) {
+  margin: 0 0 8px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+}
+:where(.cf-board) :where(.cf-comment__toolbar),
+:where(.cf-board) :where(.cf-inline-actions) {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+:where(.cf-board) :where(.cf-comment__like),
+:where(.cf-board) :where(.cf-comment__action),
+:where(.cf-board) :where(.cf-comment__replies) {
+  border: 0;
+  padding: 4px 6px;
+  background: transparent;
+  color: var(--cf-muted);
+  font: inherit;
+  font-size: 0.82rem;
+  cursor: pointer;
+}
+:where(.cf-board) :where(.cf-comment__like[data-active="true"]) {
+  color: var(--cf-primary);
+}
+:where(.cf-board) :where(.cf-comment__children) {
+  display: grid;
+  gap: 8px;
+  margin: 10px 0 0 16px;
+  padding-left: 10px;
+  border-left: 2px solid var(--cf-border);
+}
+:where(.cf-board) :where(.cf-comment__author) {
+  margin-bottom: 5px;
+  color: var(--cf-muted);
+  font-size: 0.8rem;
+}
+
+@media (max-width: 600px) {
+  :where(.cf-board) {
+    padding: var(--cf-space);
+  }
+  :where(.cf-board) :where(.cf-board__header) {
+    flex-direction: column;
+  }
+  :where(.cf-board) :where(.cf-entry) {
+    grid-template-columns: 44px minmax(0, 1fr);
+    padding: 10px;
+  }
+  :where(.cf-board) :where(.cf-upvote) {
+    width: 40px;
+    min-height: 48px;
+  }
+}
+:where(.cf-board) :where(.cf-confirm-backdrop) {
+  position: fixed;
+  z-index: 1000;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 20px;
+  background: rgb(0 0 0 / 0.35);
+}
+
+:where(.cf-board) :where(.cf-confirm) {
+  width: min(100%, 420px);
+  display: grid;
+  gap: 12px;
+  padding: 18px;
+  border: 1px solid var(--cf-border);
+  border-radius: var(--cf-radius);
+  background: var(--cf-surface);
+  color: var(--cf-text);
+  box-shadow: 0 20px 60px rgb(0 0 0 / 0.18);
+}
+
+:where(.cf-board) :where(.cf-confirm p) {
+  margin: 0;
+  color: var(--cf-muted);
+  line-height: 1.5;
+}

package/src/shared/README.md

@@ -0,0 +1,9 @@
+# Shared UI contracts
+
+This directory contains platform-neutral contracts used by both web and native UI layers.
+
+- `messages.ts`: typed, overrideable package-owned UI copy. User-generated content is never translated or rewritten.
+- `theme.ts`: fallback theme tokens and override contracts.
+- `render.ts`: shared render-child types for replaceable primitive implementations.
+
+Do not introduce an i18n runtime dependency here. Localization is provided by typed message injection so hosts can use any localization library.

package/src/shared/messages.ts

@@ -0,0 +1,99 @@
+import type { FeedbackMessageOverrides, FeedbackMessages } from "./types";
+
+export const englishFeedbackMessages: FeedbackMessages = {
+  board: {
+    title: "Feedback",
+    subtitle: "Share ideas, report problems, and help shape what comes next.",
+    searchPlaceholder: "Search feedback…",
+    createEntry: "Create feedback",
+    noEntries: "No feedback yet.",
+    noSearchResults: "No matching feedback found.",
+    loading: "Loading…",
+    loadMore: "Load more",
+  },
+  kinds: {
+    feedback: "Feedback",
+    feature_request: "Feature request",
+    bug_report: "Bug report",
+  },
+  statuses: {
+    open: "Open",
+    under_review: "Under review",
+    planned: "Planned",
+    in_progress: "In progress",
+    completed: "Completed",
+    closed: "Closed",
+  },
+  entry: {
+    upvote: "Upvote",
+    removeUpvote: "Remove upvote",
+    comments: (count) => `${count} ${count === 1 ? "comment" : "comments"}`,
+    open: "Open",
+    back: "Back to feedback",
+  },
+  form: {
+    kind: "Type",
+    title: "Title",
+    titlePlaceholder: "Summarize your feedback",
+    body: "Details",
+    bodyPlaceholder: "Tell us more…",
+    submit: "Submit feedback",
+    cancel: "Cancel",
+    possibleDuplicates: "Possible existing feedback",
+    exactDuplicate: "This may already exist",
+    duplicateWarning:
+      "Similar feedback already exists. Are you sure you want to submit another entry?",
+    submitAnyway: "Submit anyways",
+  },
+  comments: {
+    title: "Discussion",
+    placeholder: "Add a comment…",
+    submit: "Comment",
+    reply: "Reply",
+    cancelReply: "Cancel reply",
+    like: "Like",
+    unlike: "Unlike",
+    viewReplies: (count) =>
+      `View ${count} ${count === 1 ? "reply" : "replies"}`,
+    hideReplies: "Hide replies",
+    deleted: "Comment deleted",
+    noComments: "No comments yet.",
+    loadMore: "Load more comments",
+  },
+};
+
+export function mergeFeedbackMessages(
+  overrides: FeedbackMessageOverrides = {},
+): FeedbackMessages {
+  return {
+    board: { ...englishFeedbackMessages.board, ...overrides.board },
+    kinds: {
+      feedback:
+        overrides.kinds?.feedback ?? englishFeedbackMessages.kinds.feedback,
+      feature_request:
+        overrides.kinds?.feature_request ??
+        englishFeedbackMessages.kinds.feature_request,
+      bug_report:
+        overrides.kinds?.bug_report ?? englishFeedbackMessages.kinds.bug_report,
+    },
+    statuses: {
+      open: overrides.statuses?.open ?? englishFeedbackMessages.statuses.open,
+      under_review:
+        overrides.statuses?.under_review ??
+        englishFeedbackMessages.statuses.under_review,
+      planned:
+        overrides.statuses?.planned ?? englishFeedbackMessages.statuses.planned,
+      in_progress:
+        overrides.statuses?.in_progress ??
+        englishFeedbackMessages.statuses.in_progress,
+      completed:
+        overrides.statuses?.completed ??
+        englishFeedbackMessages.statuses.completed,
+      closed:
+        overrides.statuses?.closed ?? englishFeedbackMessages.statuses.closed,
+    },
+    entry: { ...englishFeedbackMessages.entry, ...overrides.entry },
+    form: { ...englishFeedbackMessages.form, ...overrides.form },
+    comments: { ...englishFeedbackMessages.comments, ...overrides.comments },
+  };
+}

package/src/shared/render.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+import type { RenderChildren } from "./types";
+
+export function renderChildren<State>(
+  children: RenderChildren<State> | undefined,
+  state: State,
+  fallback: ReactNode,
+): ReactNode {
+  return typeof children === "function"
+    ? children(state)
+    : (children ?? fallback);
+}

package/src/shared/theme.ts

@@ -0,0 +1,27 @@
+import type { FeedbackTheme, FeedbackThemeOverride } from "./types";
+
+export const defaultFeedbackTheme: FeedbackTheme = {
+  colors: {
+    primary: "#5b5bd6",
+    background: "#ffffff",
+    surface: "#ffffff",
+    surfaceMuted: "#f6f6f8",
+    text: "#17171a",
+    mutedText: "#68686f",
+    border: "#e2e2e8",
+    danger: "#c73535",
+    success: "#27834a",
+  },
+  radius: 12,
+  spacing: 12,
+};
+
+export function mergeFeedbackTheme(
+  override: FeedbackThemeOverride = {},
+): FeedbackTheme {
+  return {
+    colors: { ...defaultFeedbackTheme.colors, ...override.colors },
+    radius: override.radius ?? defaultFeedbackTheme.radius,
+    spacing: override.spacing ?? defaultFeedbackTheme.spacing,
+  };
+}

package/src/shared/types/board.ts

@@ -0,0 +1,48 @@
+import type { FeedbackColorProps } from "./context.js";
+import type { RenderChildren } from "./render.js";
+
+/**
+ * Platform-neutral props shared by `FeedbackBoard.Root` implementations.
+ *
+ * Platform-specific root props extend this interface with their native host
+ * element props (`HTMLAttributes` on web and `ViewProps` on React Native).
+ */
+export interface BoardRootBaseProps extends FeedbackColorProps {
+  /**
+   * Overrides provider-level `unstyled` for this board.
+   */
+  unstyled?: boolean;
+}
+
+/**
+ * State supplied to a custom `FeedbackBoard.Search` render-function child.
+ */
+export interface BoardSearchState {
+  /** Current controlled search value. */
+  value: string;
+
+  /** Updates the controlled search value. */
+  setValue: (value: string) => void;
+}
+
+/**
+ * Platform-neutral props shared by `FeedbackBoard.Search` implementations.
+ *
+ * Web and native search props should extend this interface and add only their
+ * host input props.
+ */
+export interface BoardSearchBaseProps {
+  /** Controlled search value. */
+  value: string;
+
+  /** Called whenever the user changes the search value. */
+  onValueChange: (value: string) => void;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete visual implementation while retaining controlled
+   * search state.
+   *
+   */
+  children?: RenderChildren<BoardSearchState> | undefined;
+}

package/src/shared/types/comment.ts

@@ -0,0 +1,101 @@
+import type { FeedbackComment } from "convex-feedback";
+
+import type { RenderChildren } from "./render.js";
+
+/**
+ * Platform-neutral props shared by `Comment.Root` implementations.
+ */
+export interface CommentRootBaseProps {
+  /** Comment exposed to every nested `Comment.*` primitive. */
+  comment: FeedbackComment;
+}
+
+/**
+ * State and actions exposed to a custom `Comment.Like` renderer.
+ */
+export interface CommentLikeState {
+  /** Current comment. */
+  comment: FeedbackComment;
+
+  /** Whether the current viewer currently likes the comment. */
+  active: boolean;
+
+  /** Current total like count. */
+  count: number;
+
+  /** Requests the opposite of the current like state. */
+  toggle: () => void | Promise<void>;
+}
+
+/**
+ * Platform-neutral props shared by `Comment.Like` implementations.
+ */
+export interface CommentLikeBaseProps {
+  /**
+   * Called with the desired final like state.
+   *
+   * `true` ensures the viewer likes the comment. `false` ensures the viewer
+   * does not like it. The server mutation is idempotent rather than toggle-
+   * based.
+   */
+  onToggle: (desiredState: boolean) => void | Promise<void>;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete control and receives `CommentLikeState`.
+   */
+  children?: RenderChildren<CommentLikeState> | undefined;
+}
+
+/**
+ * State exposed to simple comment action renderers such as `Comment.Reply`.
+ */
+export interface CommentActionState {
+  /** Current comment. */
+  comment: FeedbackComment;
+
+  /** Activates the action. */
+  activate: () => void;
+}
+
+/**
+ * Platform-neutral props shared by simple comment action primitives.
+ */
+export interface CommentActionBaseProps {
+  /** Called when the action is activated. */
+  onActivate: () => void;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete control and receives `CommentActionState`.
+   */
+  children?: RenderChildren<CommentActionState> | undefined;
+}
+
+/**
+ * State exposed to a custom lazy-replies control.
+ */
+export interface RepliesButtonState extends CommentActionState {
+  /** Whether this direct-reply branch is currently expanded. */
+  expanded: boolean;
+
+  /** Number of direct replies available for the comment. */
+  count: number;
+}
+
+/**
+ * Platform-neutral props shared by `Comment.RepliesButton` implementations.
+ */
+export interface RepliesButtonBaseProps {
+  /** Whether direct replies are currently displayed. */
+  expanded: boolean;
+
+  /** Requests a new expanded/collapsed state. */
+  onExpandedChange: (expanded: boolean) => void;
+
+  /**
+   * Normal children replace the default content. A render-function child
+   * replaces the complete control and receives `RepliesButtonState`.
+   */
+  children?: RenderChildren<RepliesButtonState> | undefined;
+}

package/src/shared/types/context.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+import type { FeedbackMessageOverrides, FeedbackMessages } from "./messages";
+import type { FeedbackTheme, FeedbackThemeOverride } from "./theme";
+
+/**
+ * Resolved feedback UI configuration available through `useFeedbackUi`.
+ *
+ * This contract is shared by the React DOM and React Native implementations.
+ */
+export interface FeedbackUiContextValue {
+  /** Fully resolved and localized UI messages. */
+  messages: FeedbackMessages;
+
+  /** Fully resolved visual theme. */
+  theme: FeedbackTheme;
+
+  /**
+   * Whether package-provided default styling is disabled.
+   *
+   * Behavioral and structural functionality remains available when enabled.
+   */
+  unstyled: boolean;
+}
+
+/**
+ * Props shared by the React DOM and React Native feedback providers.
+ */
+export interface FeedbackProviderProps {
+  /** Feedback UI rendered within the provider. */
+  children: ReactNode;
+
+  /**
+   * Partial localization or copy overrides.
+   *
+   * Unspecified values fall back to the built-in English messages.
+   */
+  messages?: FeedbackMessageOverrides;
+
+  /**
+   * Partial visual-theme overrides.
+   *
+   * Unspecified values fall back to the default feedback theme.
+   */
+  theme?: FeedbackThemeOverride;
+
+  /**
+   * Disables package-provided default styling.
+   *
+   * @default false
+   */
+  unstyled?: boolean;
+}
+
+/**
+ * Convenient semantic color overrides accepted by feedback UI containers.
+ *
+ * These override equivalent values from the provider theme for the
+ * corresponding subtree.
+ */
+export interface FeedbackColorProps {
+  /** Primary interaction and accent color. */
+  primaryColor?: string;
+
+  /** Main background color. */
+  backgroundColor?: string;
+
+  /** Card and control surface color. */
+  surfaceColor?: string;
+
+  /** Primary text color. */
+  textColor?: string;
+
+  /** Secondary and helper text color. */
+  mutedColor?: string;
+
+  /** Border and separator color. */
+  borderColor?: string;
+
+  /** Destructive and error-state color. */
+  dangerColor?: string;
+}