@appsupportkit/support-sdk 0.1.2 → 0.3.0

package/src/theme.ts

@@ -1,5 +1,7 @@
 // The SDK consumes the same design tokens as the admin dashboard, so both
-// surfaces look like one product.
+// surfaces look like one product. On top of those it adds the few values
+// that only exist on mobile: sheet/bubble radii and the elevation used by
+// the launcher and the sheet (the web side gets those from CSS).
 import {
   darkColors,
   lightColors,
@@ -8,32 +10,177 @@ import {
   spacing,
   type ThemeColors,
 } from '@appsupportkit/design-tokens';
+import type { ViewStyle } from 'react-native';
 import type { ThemeName } from './types';
 
+/** Rounder than the dashboard: touch targets read better with more radius. */
+export const supportRadii = {
+  ...radii,
+  control: 10,
+  card: 14,
+  cardLg: 18,
+  /** Message bubbles. */
+  bubble: 18,
+  /** The tight corner on a bubble's sender side. */
+  bubbleTail: 6,
+  sheet: 24,
+  pill: 999,
+} as const;
+
+export interface SupportShadows {
+  /** Floating launcher button. */
+  launcher: ViewStyle;
+  /** The bottom sheet itself. */
+  sheet: ViewStyle;
+  /** Unread badge, so it lifts off the button. */
+  badge: ViewStyle;
+}
+
+/**
+ * The launcher sits on the host app's own background rather than on an SDK
+ * surface, so the two themes need different treatment: on near-black a
+ * solid fill needs a hairline to separate from the background and a black
+ * shadow, while on white the accent-tinted shadow does that work and a
+ * borderless mark has to be darkened to stay legible.
+ */
+export interface LauncherPalette {
+  /** Hairline drawn over the solid fill. */
+  solidRing: string;
+  /** Mark color for the borderless (minimal) variant. */
+  minimalMark: string;
+}
+
 export interface SupportTheme {
   name: ThemeName;
   colors: ThemeColors;
   spacing: typeof spacing;
-  radii: typeof radii;
+  radii: typeof supportRadii;
   motion: typeof motion;
+  shadows: SupportShadows;
+  launcher: LauncherPalette;
 }
 
-export const supportDarkTheme: SupportTheme = {
-  name: 'dark',
-  colors: darkColors,
-  spacing,
-  radii,
-  motion,
-};
+// Color helpers come first: the themes below are built at module load, so
+// anything they reach for has to already be initialized. (A `const` used
+// before its definition survives tsc but lands as `undefined` on Hermes.)
+const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
 
-export const supportLightTheme: SupportTheme = {
-  name: 'light',
-  colors: lightColors,
-  spacing,
-  radii,
-  motion,
-};
+function parseHex(color: string): [number, number, number] | null {
+  const match = HEX.exec(color.trim());
+  const digits = match?.[1];
+  if (digits === undefined) return null;
+  const hex =
+    digits.length === 3
+      ? digits
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : digits;
+  return [
+    parseInt(hex.slice(0, 2), 16),
+    parseInt(hex.slice(2, 4), 16),
+    parseInt(hex.slice(4, 6), 16),
+  ];
+}
+
+function mix([r, g, b]: [number, number, number], target: number, amount: number) {
+  const channel = (c: number) => Math.round(c + (target - c) * amount);
+  return `rgb(${channel(r)}, ${channel(g)}, ${channel(b)})`;
+}
+
+function shadowsFor(name: ThemeName, accent: string): SupportShadows {
+  const dark = name === 'dark';
+  return {
+    launcher: {
+      // Tinting the launcher's shadow with the accent is what makes it read
+      // as lifted rather than pasted on.
+      shadowColor: dark ? '#000000' : accent,
+      shadowOpacity: dark ? 0.45 : 0.3,
+      shadowRadius: 14,
+      shadowOffset: { width: 0, height: 6 },
+      elevation: 8,
+    },
+    sheet: {
+      shadowColor: '#000000',
+      shadowOpacity: dark ? 0.5 : 0.16,
+      shadowRadius: 24,
+      shadowOffset: { width: 0, height: -6 },
+      elevation: 24,
+    },
+    badge: {
+      shadowColor: '#000000',
+      shadowOpacity: 0.25,
+      shadowRadius: 3,
+      shadowOffset: { width: 0, height: 1 },
+      elevation: 3,
+    },
+  };
+}
+
+function launcherFor(name: ThemeName, accent: string): LauncherPalette {
+  const rgb = parseHex(accent);
+  return {
+    solidRing:
+      name === 'dark' ? 'rgba(255, 255, 255, 0.14)' : 'rgba(0, 0, 0, 0.06)',
+    // On a dark app background the raw accent is too close to the surface
+    // to read as a glyph; lift it toward white.
+    minimalMark:
+      name === 'dark' && rgb !== null ? mix(rgb, 255, 0.35) : accent,
+  };
+}
+
+function buildTheme(name: ThemeName, colors: ThemeColors): SupportTheme {
+  return {
+    name,
+    colors,
+    spacing,
+    radii: supportRadii,
+    motion,
+    shadows: shadowsFor(name, colors.accent),
+    launcher: launcherFor(name, colors.accent),
+  };
+}
+
+export const supportDarkTheme: SupportTheme = buildTheme('dark', darkColors);
+export const supportLightTheme: SupportTheme = buildTheme('light', lightColors);
+
+/**
+ * Derives the accent family from a single brand color: a pressed shade, the
+ * 12% wash used behind chips and own-message bubbles, and a foreground that
+ * stays legible on top (dark text on light brands, white on dark ones).
+ */
+function withAccent(theme: SupportTheme, accent: string): SupportTheme {
+  const rgb = parseHex(accent);
+  if (!rgb) return theme;
+  const [r, g, b] = rgb;
+  // Relative luminance, sRGB coefficients — good enough to pick a foreground.
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  const colors: ThemeColors = {
+    ...theme.colors,
+    accent,
+    accentHover: mix(rgb, theme.name === 'dark' ? 255 : 0, 0.12),
+    accentMuted: `rgba(${r}, ${g}, ${b}, 0.12)`,
+    accentForeground: luminance > 0.62 ? '#111113' : '#FFFFFF',
+    statusOpen: accent,
+    statusOpenBg: `rgba(${r}, ${g}, ${b}, 0.10)`,
+    focusRing: accent,
+  };
+  return {
+    ...theme,
+    colors,
+    shadows: shadowsFor(theme.name, accent),
+    launcher: launcherFor(theme.name, accent),
+  };
+}
 
-export function resolveTheme(name: ThemeName | undefined): SupportTheme {
-  return name === 'light' ? supportLightTheme : supportDarkTheme;
+/**
+ * @param name  "light" | "dark" (default dark).
+ * @param accentColor Optional brand color (hex) replacing the default accent.
+ */
+export function resolveTheme(
+  name: ThemeName | undefined,
+  accentColor?: string,
+): SupportTheme {
+  const base = name === 'light' ? supportLightTheme : supportDarkTheme;
+  return accentColor ? withAccent(base, accentColor) : base;
 }

package/src/types.ts

@@ -1,9 +1,20 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { Language } from './i18n/languages';
+
 export type QueryType = 'feedback' | 'feature_request' | 'bug_report';
 export type QueryStatus = 'open' | 'resolved';
 export type MessageSender = 'user' | 'admin';
 export type ThemeName = 'dark' | 'light';
 export type PushPermissionStatus = 'undetermined' | 'granted' | 'denied';
 
+/**
+ * How the launcher renders:
+ *   solid   — accent fill, elevated. The floating action button.
+ *   soft    — app surface + hairline border. Sits in a header or toolbar.
+ *   minimal — bare mark, no fill or border. Sits in a nav bar.
+ */
+export type LauncherVariant = 'solid' | 'soft' | 'minimal';
+
 export interface SupportUser {
   /** Display name shown to the support team. */
   name: string;
@@ -30,6 +41,20 @@ export interface SupportButtonProps {
   supabaseUrl: string;
   /** Visual theme. Matches the admin dashboard tokens. Default "dark". */
   theme?: ThemeName;
+  /**
+   * Brand color (hex, e.g. "#FF5A1F") replacing the default accent across
+   * the launcher, buttons, and the user's own message bubbles. The pressed
+   * shade, the 12% wash, and a legible foreground are derived from it.
+   */
+  accentColor?: string;
+  /** Launcher style. Default "solid" — the floating action button. */
+  variant?: LauncherVariant;
+  /** Launcher diameter in px (height when `label` is set). Default 52. */
+  size?: number;
+  /** Renders the launcher as a pill with this text beside the mark. */
+  label?: string;
+  /** Style applied to the launcher — position it, add margins, etc. */
+  style?: StyleProp<ViewStyle>;
   /**
    * Idle poll interval (ms) — how often the unread badge is refreshed while
    * the sheet is CLOSED, using a lightweight count-only endpoint. Default
@@ -47,23 +72,45 @@ export interface SupportButtonProps {
    * installed — it is an optional peer dependency.
    */
   expoProjectId?: string;
+  /**
+   * Pre-selects a language in the picker the first time a user opens support.
+   * Pass it when the host app already knows what the user reads — an in-app
+   * language setting beats the device locale, which is what the SDK falls
+   * back to. It is a default, not an override: the user still chooses, and a
+   * choice they have already made always wins.
+   */
+  defaultLanguage?: Language;
 }
 
 export interface ThreadMessage {
   id: string;
   sender: MessageSender;
+  /**
+   * Already in the user's language: their own messages as they wrote them,
+   * support replies translated. The server does the choosing — see the
+   * get-threads function.
+   */
   body: string;
   created_at: string;
-  admin_name: string | null;
+  /**
+   * A support reply whose translation hasn't landed yet. `body` currently
+   * holds the English original; it will change under the reader shortly, so
+   * the UI says so rather than letting it flicker.
+   */
+  translation_pending: boolean;
 }
 
+/**
+ * Note the absence of any admin identity: end users see one support team,
+ * not the people staffing it, so the names never leave the server. The
+ * dashboard still shows who wrote and who resolved what.
+ */
 export interface Thread {
   id: string;
   type: QueryType;
   status: QueryStatus;
   created_at: string;
   resolved_at: string | null;
-  resolved_by_name: string | null;
   app_version: string;
   unread_count: number;
   last_message: {
@@ -77,8 +124,15 @@ export interface Thread {
 export interface ThreadsResponse {
   threads: Thread[];
   total_unread: number;
+  /** Null when this user has never picked one — the SDK then asks. */
+  language: string | null;
 }
 
+/**
+ * English labels, kept for host apps that render their own entry points.
+ * Inside the sheet the labels come from the string table instead, so they
+ * follow the user's language.
+ */
 export const QUERY_TYPE_LABEL: Record<QueryType, string> = {
   feedback: 'Feedback',
   feature_request: 'Feature request',

package/src/unread.ts

@@ -0,0 +1,91 @@
+// Unread accounting.
+//
+// The server counts a thread's unread as "admin messages newer than the
+// user's read receipt". That number is authoritative, but it is always a
+// little behind the device: between the moment the user opens a thread and
+// the moment `mark-read` lands, every already-in-flight poll still reports
+// the old count — which is what made the badge flicker back on after being
+// cleared, and what made a thread the user was actively reading accumulate
+// unread replies.
+//
+// So the client keeps its own watermark per thread: the `created_at` of the
+// newest admin message the user has actually seen. Those are *server*
+// timestamps, so nothing here compares against the device clock.
+//
+// Displayed unread is then the stricter of the two counts, which is correct
+// in both directions:
+//
+//   read here, receipt not written yet  → local watermark wins  (0)
+//   read on another device              → server count wins     (0)
+
+import type { Thread } from './types';
+
+/** Watermark map: thread id → `created_at` (ms) of the newest seen reply. */
+export type ReadWatermarks = Map<string, number>;
+
+/** `created_at` (ms) of the newest admin message, or 0 if there are none. */
+export function latestAdminMessageAt(thread: Thread): number {
+  let latest = 0;
+  for (const message of thread.messages) {
+    if (message.sender !== 'admin') continue;
+    const at = Date.parse(message.created_at);
+    if (Number.isFinite(at) && at > latest) latest = at;
+  }
+  return latest;
+}
+
+/** Admin messages in `thread` newer than `watermark`. */
+export function unreadSince(thread: Thread, watermark: number): number {
+  let count = 0;
+  for (const message of thread.messages) {
+    if (message.sender !== 'admin') continue;
+    const at = Date.parse(message.created_at);
+    if (Number.isFinite(at) && at > watermark) count += 1;
+  }
+  return count;
+}
+
+/**
+ * Returns `thread` with `unread_count` narrowed by what this device knows
+ * the user has read. Identity is preserved when nothing changes so lists
+ * stay referentially stable between polls.
+ */
+export function reconcileThread(
+  thread: Thread,
+  watermarks: ReadWatermarks,
+): Thread {
+  const watermark = watermarks.get(thread.id);
+  if (watermark === undefined || thread.unread_count === 0) return thread;
+  const unread = Math.min(thread.unread_count, unreadSince(thread, watermark));
+  return unread === thread.unread_count ? thread : { ...thread, unread_count: unread };
+}
+
+export function reconcileThreads(
+  threads: Thread[],
+  watermarks: ReadWatermarks,
+): Thread[] {
+  return threads.map((thread) => reconcileThread(thread, watermarks));
+}
+
+export function sumUnread(threads: Thread[]): number {
+  return threads.reduce((total, thread) => total + thread.unread_count, 0);
+}
+
+/**
+ * Drops watermarks the server has caught up on (its own count is already 0)
+ * and ones for threads that no longer exist, so the map can't grow without
+ * bound over a long session.
+ */
+export function pruneWatermarks(
+  watermarks: ReadWatermarks,
+  serverThreads: Thread[],
+): ReadWatermarks {
+  const keep: ReadWatermarks = new Map();
+  for (const thread of serverThreads) {
+    const watermark = watermarks.get(thread.id);
+    if (watermark !== undefined && thread.unread_count > 0) {
+      keep.set(thread.id, watermark);
+    }
+  }
+  return keep;
+}