@xpufx/paseo-x-comms 0.3.0

package/client/vendor/paseo-plugin-helper/theme/provider.tsx

@@ -0,0 +1,214 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  useEffect,
+  type ReactNode,
+} from "react";
+import { StyleSheet, View, type LayoutChangeEvent } from "react-native";
+import type { PluginTheme } from "../../../../shared/vendor/paseo-plugin-helper/types";
+import type { HostLayout } from "../host";
+import { Appearance } from "react-native";
+import { defaultFlair, resolveRadius, type VisualFlair } from "./flair";
+import { alpha, getContrastColor, getStatusColor, getVariantPalette } from "./color-utils";
+import {
+  getTouchTargetMin,
+  isMobilePlatform,
+  resolveEffectiveCompact,
+  resolvePadding,
+} from "./responsive";
+import {
+  mergeThemeColors,
+  readHostThemeVariables,
+  type HostFontVariables,
+} from "./host-variables";
+import { resolveTypography, type TypographyScale } from "./tokens";
+import type { ResponsiveLayout, StatusVariant, ThemeColors } from "../../../../shared/vendor/paseo-plugin-helper/types";
+
+export interface PluginThemeContextValue {
+  theme: PluginTheme;
+  colors: ThemeColors;
+  fonts: HostFontVariables;
+  layout: ResponsiveLayout;
+  flair: VisualFlair;
+  isCompact: boolean;
+  isMobile: boolean;
+  touchTargetMin: number;
+  alpha: (color: string, opacity: number) => string;
+  getContrastColor: (bgHex: string, light?: string, dark?: string) => string;
+  getStatusColor: (variant: StatusVariant) => string;
+  getVariantPalette: (variant: StatusVariant) => { bg: string; text: string; border: string };
+  resolveRadius: (size?: "xs" | "sm" | "md" | "lg" | "pill") => number;
+  padding: { horizontal: number; vertical: number; gap: number };
+  typography: TypographyScale;
+}
+
+const defaultLayout: ResponsiveLayout = {
+  compact: false,
+  platform: "web",
+};
+
+export const defaultDarkTheme: PluginTheme = {
+  colors: {
+    surface0: "#18181b",
+    surface1: "#27272a",
+    surface2: "#3f3f46",
+    border: "#3f3f46",
+    foreground: "#fafafa",
+    foregroundMuted: "#a1a1aa",
+    accent: "#3b82f6",
+    accentForeground: "#ffffff",
+    statusSuccess: "#22c55e",
+    statusWarning: "#eab308",
+    statusDanger: "#ef4444",
+  },
+};
+
+export const defaultLightTheme: PluginTheme = {
+  colors: {
+    surface0: "#ffffff",
+    surface1: "#f4f4f5",
+    surface2: "#e4e4e7",
+    border: "#e4e4e7",
+    foreground: "#09090b",
+    foregroundMuted: "#71717a",
+    accent: "#2563eb",
+    accentForeground: "#ffffff",
+    statusSuccess: "#16a34a",
+    statusWarning: "#ca8a04",
+    statusDanger: "#dc2626",
+  },
+};
+
+export function getDefaultTheme(scheme?: string): PluginTheme {
+  if (scheme === "light") {
+    return defaultLightTheme;
+  }
+  return defaultDarkTheme;
+}
+
+export function useAppearanceScheme(): [string | undefined, (s: string | undefined) => void] {
+  const [scheme, setScheme] = useState<string | undefined>(Appearance.getColorScheme?.() ?? undefined);
+  useEffect(() => {
+    const sub = Appearance.addChangeListener?.(({colorScheme}) => {
+      setScheme(colorScheme ?? undefined);
+    });
+    return () => {
+      // remove listener if possible
+      // Appearance.addChangeListener returns an object with remove method in RN
+      // but in web we may not have it; ignore safely
+      if (sub && typeof (sub as any).remove === "function") {
+        (sub as any).remove();
+      }
+    };
+  }, []);
+  return [scheme, setScheme];
+}
+
+const initialDefaultTheme = getDefaultTheme();
+const PluginThemeContext = createContext<PluginThemeContextValue>({
+  theme: initialDefaultTheme,
+  colors: initialDefaultTheme.colors,
+  fonts: {},
+  layout: defaultLayout,
+  flair: defaultFlair,
+  isCompact: false,
+  isMobile: false,
+  touchTargetMin: 28,
+  alpha: (color, op) => alpha(color, op),
+  getContrastColor: (bg, l, d) => getContrastColor(bg, l, d),
+  getStatusColor: (v) => getStatusColor(v, initialDefaultTheme.colors),
+  getVariantPalette: (v) => getVariantPalette(v, initialDefaultTheme.colors),
+  resolveRadius: (s) => resolveRadius("rounded", s),
+  padding: resolvePadding(defaultLayout, "comfortable"),
+  typography: resolveTypography(defaultLayout, "comfortable"),
+});
+
+export interface PluginThemeProviderProps {
+  theme: PluginTheme;
+  layout?: HostLayout;
+  flair?: Partial<VisualFlair>;
+  children: ReactNode;
+}
+
+export function PluginThemeProvider({
+  theme,
+  layout = defaultLayout,
+  flair: userFlair,
+  children,
+}: PluginThemeProviderProps) {
+  const hostWidth =
+    typeof layout.width === "number" && layout.width > 0 ? layout.width : undefined;
+  const needsMeasurement = hostWidth === undefined;
+  const [measuredWidth, setMeasuredWidth] = useState<number | undefined>(undefined);
+  const [appearanceScheme] = useAppearanceScheme();
+
+  const handleLayout = useCallback((event: LayoutChangeEvent) => {
+    const width = event.nativeEvent?.layout?.width;
+    if (typeof width !== "number" || width <= 0) return;
+    setMeasuredWidth((prev) => (prev === width ? prev : width));
+  }, []);
+
+  const effectiveWidth = hostWidth ?? measuredWidth;
+
+  const value = useMemo<PluginThemeContextValue>(() => {
+    const flair: VisualFlair = { ...defaultFlair, ...userFlair };
+    const hostVariables = readHostThemeVariables();
+    const effectiveColors = mergeThemeColors(
+      getDefaultTheme(appearanceScheme).colors,
+      hostVariables.colors,
+      theme.colors,
+      flair.accentColor,
+    );
+
+    const isCompact = resolveEffectiveCompact(layout, effectiveWidth);
+    const effectiveLayout: ResponsiveLayout =
+      effectiveWidth !== undefined
+        ? { ...layout, width: effectiveWidth, compact: isCompact }
+        : { ...layout, compact: isCompact };
+    const isMobile = isMobilePlatform(effectiveLayout.platform);
+    const touchTargetMin = getTouchTargetMin(effectiveLayout);
+    const padding = resolvePadding(effectiveLayout, flair.density);
+    const typography = resolveTypography(effectiveLayout, flair.density);
+
+    return {
+      theme,
+      colors: effectiveColors,
+      fonts: hostVariables.fonts,
+      layout: effectiveLayout,
+      flair,
+      isCompact,
+      isMobile,
+      touchTargetMin,
+      alpha: (c, o) => alpha(c, o),
+      getContrastColor: (bg, l, d) => getContrastColor(bg, l, d),
+      getStatusColor: (v) => getStatusColor(v, effectiveColors, flair.accentColor),
+      getVariantPalette: (v) => getVariantPalette(v, effectiveColors, flair.accentColor),
+      resolveRadius: (size = "md") => resolveRadius(flair.radius, size),
+      padding,
+      typography,
+    };
+  }, [theme, layout, userFlair, effectiveWidth, appearanceScheme]);
+
+  return (
+    <PluginThemeContext.Provider value={value}>
+      {needsMeasurement ? (
+        <View style={styles.measureContainer} onLayout={handleLayout}>
+          {children}
+        </View>
+      ) : (
+        children
+      )}
+    </PluginThemeContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  measureContainer: { flex: 1 },
+});
+
+export function usePluginTheme(): PluginThemeContextValue {
+  return useContext(PluginThemeContext);
+}

package/client/vendor/paseo-plugin-helper/theme/responsive.ts

@@ -0,0 +1,213 @@
+import type { DensityStyle } from "./flair";
+import type { PlatformType, ResponsiveLayout } from "../../../../shared/vendor/paseo-plugin-helper/types";
+
+/**
+ * Container width (px) at or below which a surface steps down to the compact
+ * scale. Mirrors the host's `COMPACT_FORM_FACTOR_WIDTH` so plugin typography
+ * in narrow popovers matches full-screen mobile surfaces.
+ */
+export const COMPACT_FORM_FACTOR_WIDTH = 500;
+
+/**
+ * Resolves compact mode from the actual container width when it is known,
+ * falling back to the host's viewport-derived `compact` flag otherwise.
+ *
+ * A host-declared compact surface stays compact at any width; a known width at
+ * or below {@link COMPACT_FORM_FACTOR_WIDTH} forces compact even when the host
+ * viewport is wide (e.g. a narrow header-button popover on desktop).
+ */
+export function resolveEffectiveCompact(
+  layout: ResponsiveLayout,
+  widthOverride?: number,
+): boolean {
+  const width = widthOverride ?? layout.width;
+  if (typeof width === "number" && width > 0) {
+    return width <= COMPACT_FORM_FACTOR_WIDTH || Boolean(layout.compact);
+  }
+  return Boolean(layout.compact);
+}
+
+/**
+ * Checks if the current platform is mobile (iOS or Android).
+ */
+export function isMobilePlatform(platform: PlatformType): boolean {
+  return platform === "ios" || platform === "android";
+}
+
+/**
+ * Interactive target floor for a compact surface on a non-mobile platform
+ * (e.g. a narrow desktop popover). Sits between the full-desktop floor and the
+ * 44pt touch target: a mouse pointer needs a little more room than a wide
+ * panel, but nothing like a finger-sized hit area.
+ */
+export const COMPACT_DESKTOP_TOUCH_TARGET = 36;
+
+/**
+ * Returns the recommended minimum interactive target size (in pt/px).
+ * Real touch platforms follow Apple HIG / Android Material (min 44pt); a
+ * compact desktop surface gets a modest bump over the 28pt desktop floor.
+ */
+export function getTouchTargetMin(layout: ResponsiveLayout): number {
+  if (isMobilePlatform(layout.platform)) return 44;
+  return resolveEffectiveCompact(layout) ? COMPACT_DESKTOP_TOUCH_TARGET : 28;
+}
+
+/**
+ * Selects a value based on compact/mobile vs desktop screen constraints.
+ */
+export function responsiveValue<T>(layout: ResponsiveLayout, desktopVal: T, compactVal: T): T {
+  return resolveEffectiveCompact(layout) ? compactVal : desktopVal;
+}
+
+/**
+ * Calculates adaptive padding based on compact mode and density preset.
+ */
+export function resolvePadding(
+  layout: ResponsiveLayout,
+  density: DensityStyle,
+): { horizontal: number; vertical: number; gap: number } {
+  const isCompact = resolveEffectiveCompact(layout);
+
+  switch (density) {
+    case "compact":
+      return {
+        horizontal: isCompact ? 10 : 12,
+        vertical: isCompact ? 6 : 8,
+        gap: isCompact ? 6 : 8,
+      };
+    case "spacious":
+      return {
+        horizontal: isCompact ? 16 : 24,
+        vertical: isCompact ? 14 : 20,
+        gap: isCompact ? 12 : 16,
+      };
+    case "comfortable":
+    default:
+      return {
+        horizontal: isCompact ? 12 : 16,
+        vertical: isCompact ? 10 : 14,
+        gap: isCompact ? 8 : 12,
+      };
+  }
+}
+
+export interface GridColumnOptions {
+  /** Requested (and maximum) column count. */
+  columns: number;
+  /** Horizontal gap between cells, in px. Default: 0. */
+  gap?: number;
+  /** Measured container width, when the host reports one. */
+  width?: number;
+  /**
+   * Minimum width each column should keep before wrapping to fewer columns.
+   * Only applied when a positive container width is known; `columns` stays the
+   * upper bound.
+   */
+  minColumnWidth?: number;
+  /**
+   * How a compact surface treats the requested column count.
+   * - "never" (default): keep the requested columns; flexbox wraps as needed.
+   * - "compact": collapse to a single column on a compact surface.
+   */
+  collapse?: "compact" | "never";
+  /** Whether the current surface is compact. */
+  isCompact?: boolean;
+}
+
+/**
+ * Resolves the effective column count for a responsive grid.
+ *
+ * A `minColumnWidth` plus a known container width yields as many columns as
+ * fit, capped at the requested count — so a narrow container wraps down to
+ * fewer columns instead of the requested count being forced through.
+ */
+export function resolveGridColumns(options: GridColumnOptions): number {
+  const requested = Math.max(1, Math.floor(options.columns));
+  if ((options.collapse ?? "never") === "compact" && options.isCompact) return 1;
+
+  const { minColumnWidth, width } = options;
+  const gap = options.gap ?? 0;
+  if (
+    typeof minColumnWidth === "number" &&
+    minColumnWidth > 0 &&
+    typeof width === "number" &&
+    width > 0
+  ) {
+    const fit = Math.floor((width + gap) / (minColumnWidth + gap));
+    return Math.max(1, Math.min(requested, fit));
+  }
+  return requested;
+}
+
+export interface ResponsiveSelectOptions<T> {
+  /**
+   * Default fallback value, used on desktop/wide viewports if no more specific option matches.
+   */
+  desktop?: T;
+  /**
+   * Value to use on mobile platforms ('ios' | 'android').
+   */
+  mobile?: T;
+  /**
+   * Value to use when in compact mode (layout.compact === true), such as on mobile or narrow split panes.
+   */
+  compact?: T;
+  /**
+   * Value to use when not in compact mode (layout.compact === false).
+   */
+  wide?: T;
+  /**
+   * Platform-specific overrides ('web', 'desktop', 'ios', 'android', 'macos', 'windows', 'linux').
+   */
+  platform?: Partial<Record<PlatformType, T>>;
+}
+
+/**
+ * Selects a value based on responsive criteria with priority:
+ * 1. Platform-specific override (`options.platform?.[platform]`)
+ * 2. Mobile platform match (`options.mobile` if mobile OS)
+ * 3. Compact mode match (`options.compact` if layout.compact)
+ * 4. Wide mode match (`options.wide` if !layout.compact)
+ * 5. Desktop / Default (`options.desktop`)
+ */
+export function responsiveSelect<T>(
+  layout: ResponsiveLayout,
+  options: ResponsiveSelectOptions<T>,
+): T | undefined {
+  const isMobile = isMobilePlatform(layout.platform);
+  const isCompact = resolveEffectiveCompact(layout);
+
+  // 1. Specific platform override
+  if (options.platform && layout.platform in options.platform) {
+    const val = options.platform[layout.platform];
+    if (val !== undefined) return val;
+  }
+
+  // 2. Mobile platform match
+  if (isMobile && options.mobile !== undefined) {
+    return options.mobile;
+  }
+
+  // 3. Compact layout match
+  if (isCompact && options.compact !== undefined) {
+    return options.compact;
+  }
+
+  // 4. Wide (non-compact) layout match
+  if (!isCompact && options.wide !== undefined) {
+    return options.wide;
+  }
+
+  // 5. Desktop fallback
+  if (options.desktop !== undefined) {
+    return options.desktop;
+  }
+
+  // 6. Secondary fallbacks
+  if (options.wide !== undefined) return options.wide;
+  if (options.compact !== undefined) return options.compact;
+  if (options.mobile !== undefined) return options.mobile;
+
+  return undefined;
+}
+

package/client/vendor/paseo-plugin-helper/theme/tokens.ts

@@ -0,0 +1,161 @@
+import type { PlatformType } from "../../../../shared/vendor/paseo-plugin-helper/types";
+import type { DensityStyle } from "./flair";
+import type { ResponsiveLayout } from "../../../../shared/vendor/paseo-plugin-helper/types";
+import { resolveEffectiveCompact } from "./responsive";
+
+/**
+ * Standard spacing scale (pt/px) shared by every helper surface.
+ * Density rule: compact viewports step exactly one rung down the scale.
+ */
+export const spacing = {
+  xxs: 2,
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 24,
+} as const;
+
+export type SpacingKey = keyof typeof spacing;
+
+/**
+ * A gap/size value: either a named spacing token or a raw px number. Layout
+ * primitives accept this so callers never have to invent their own scale.
+ */
+export type SpacingValue = SpacingKey | number;
+
+/**
+ * Resolves a {@link SpacingValue} to px, falling back to the theme-derived
+ * value when the caller did not specify one.
+ */
+export function resolveSpacing(value: SpacingValue | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  return typeof value === "number" ? value : spacing[value];
+}
+
+export interface TypographyToken {
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: "400" | "500" | "600" | "700";
+}
+
+export interface TypographyScale {
+  title: TypographyToken;
+  heading: TypographyToken;
+  body: TypographyToken;
+  bodyStrong: TypographyToken;
+  /**
+   * Value text that pairs with a {@link TypographyScale.label}: same size as
+   * the label, normal weight, so a value never outranks its own label.
+   */
+  bodySmall: TypographyToken;
+  caption: TypographyToken;
+  label: TypographyToken;
+}
+
+/**
+ * Semantic text sizes keep helper components visually coherent while still
+ * allowing compact panes and plugin density preferences to breathe.
+ */
+export function resolveTypography(
+  layout: ResponsiveLayout,
+  density: DensityStyle,
+): TypographyScale {
+  const compact = resolveEffectiveCompact(layout);
+  const densityStep = density === "compact" ? -1 : density === "spacious" ? 1 : 0;
+  const size = (regular: number, minimum = 10) =>
+    Math.max(minimum, regular + (compact ? -1 : 0) + densityStep);
+
+  const label: TypographyToken = {
+    fontSize: size(12, 11),
+    lineHeight: size(16, 14),
+    fontWeight: "600",
+  };
+  // Derived, not a fresh literal: a paired value shares the label's metrics
+  // and drops to normal weight, so it can never render larger than its label.
+  const bodySmall: TypographyToken = {
+    fontSize: label.fontSize,
+    lineHeight: label.lineHeight,
+    fontWeight: "400",
+  };
+
+  return {
+    title: { fontSize: size(16, 14), lineHeight: size(22, 18), fontWeight: "600" },
+    heading: { fontSize: size(14, 12), lineHeight: size(20, 16), fontWeight: "600" },
+    body: { fontSize: size(13, 12), lineHeight: size(19, 16), fontWeight: "400" },
+    bodyStrong: { fontSize: size(13, 12), lineHeight: size(19, 16), fontWeight: "600" },
+    bodySmall,
+    caption: { fontSize: size(11, 10), lineHeight: size(15, 14), fontWeight: "400" },
+    label,
+  };
+}
+
+/** Fallback text color on accent fills when the host omits accentForeground. */
+export const FALLBACK_ACCENT_FOREGROUND = "#ffffff";
+
+export type ElevationLevel = "none" | "sm" | "md" | "lg";
+
+export interface ElevationStyle {
+  shadowColor: string;
+  shadowOpacity: number;
+  shadowRadius: number;
+  shadowOffset: { width: number; height: number };
+  elevation: number;
+}
+
+/**
+ * Standard shadow/elevation presets. shadowColor lives here once so client
+ * components never hardcode their own.
+ */
+export function resolveElevation(level: ElevationLevel): ElevationStyle {
+  switch (level) {
+    case "none":
+      return {
+        shadowColor: "#000",
+        shadowOpacity: 0,
+        shadowRadius: 0,
+        shadowOffset: { width: 0, height: 0 },
+        elevation: 0,
+      };
+    case "sm":
+      return {
+        shadowColor: "#000",
+        shadowOpacity: 0.12,
+        shadowRadius: 3,
+        shadowOffset: { width: 0, height: 1 },
+        elevation: 1,
+      };
+    case "lg":
+      return {
+        shadowColor: "#000",
+        shadowOpacity: 0.24,
+        shadowRadius: 12,
+        shadowOffset: { width: 0, height: 4 },
+        elevation: 4,
+      };
+    case "md":
+    default:
+      return {
+        shadowColor: "#000",
+        shadowOpacity: 0.18,
+        shadowRadius: 6,
+        shadowOffset: { width: 0, height: 2 },
+        elevation: 2,
+      };
+  }
+}
+
+/**
+ * Native `elevation` is Android-only; iOS renders the shadow props.
+ * Kept as a helper so call sites read consistently.
+ */
+export function elevationForPlatform(
+  level: ElevationLevel,
+  platform: PlatformType,
+): ElevationStyle {
+  const style = resolveElevation(level);
+  if (platform !== "android") {
+    return { ...style, elevation: 0 };
+  }
+  return style;
+}

package/client/vendor/paseo-plugin-helper/theme/useResponsive.ts

@@ -0,0 +1,57 @@
+import { usePluginTheme } from "./provider";
+import {
+  responsiveSelect,
+  type ResponsiveSelectOptions,
+} from "./responsive";
+import type { PlatformType } from "../../../../shared/vendor/paseo-plugin-helper/types";
+
+export interface UseResponsiveResult {
+  /**
+   * Whether the container or viewport is in compact mode (narrow trackbar, mobile screen, or split-pane).
+   */
+  isCompact: boolean;
+  /**
+   * Whether the current OS platform is mobile ('ios' | 'android').
+   */
+  isMobile: boolean;
+  /**
+   * The platform identifier ('web' | 'desktop' | 'ios' | 'android' | 'macos' | 'windows' | 'linux').
+   */
+  platform: PlatformType;
+  /**
+   * Container width if reported by Paseo's layout.
+   */
+  width?: number;
+  /**
+   * Container height if reported by Paseo's layout.
+   */
+  height?: number;
+  /**
+   * Recommended minimum interactive touch target (44pt on mobile/compact, 28pt on desktop).
+   */
+  touchTargetMin: number;
+  /**
+   * Helper function to select a value based on the current responsive environment.
+   */
+  select: <T>(options: ResponsiveSelectOptions<T>) => T | undefined;
+}
+
+/**
+ * Universal hook for responsive plugin UI across composer pills, modals, panels, and surfaces.
+ * Automatically adapts based on Paseo's layout context (compact mode, mobile OS, touch targets).
+ */
+export function useResponsive(): UseResponsiveResult {
+  const { layout, isCompact, isMobile, touchTargetMin } = usePluginTheme();
+
+  return {
+    isCompact,
+    isMobile,
+    platform: layout.platform,
+    width: layout.width,
+    height: layout.height,
+    touchTargetMin,
+    select: <T>(options: ResponsiveSelectOptions<T>): T | undefined => {
+      return responsiveSelect(layout, options);
+    },
+  };
+}