flowboard-react 0.6.2 → 0.6.3

package/README.md

@@ -1,42 +1,137 @@
 # flowboard-react
 
-Flowboard React Native SDK. JSON-driven onboarding flows with custom screens and full SDUI rendering parity with the Flutter package.
+Flowboard React Native SDK for SDUI onboarding flows.
 
-## Installation
+It supports:
+
+- Expo development builds and prebuild/EAS workflows
+- React Native CLI apps
+- JSON-driven onboarding with custom screens and full Flowboard renderer support
+
+## Quick Start
+
+Install the SDK:
 
 ```sh
 npm install flowboard-react
 ```
 
-Install compatible versions of the peer/native dependencies for your app that satisfy these minimums:
+Install the native peer dependencies in one step:
 
 ```sh
-npm install \
-  @react-native-async-storage/async-storage \
-  @react-native-masked-view/masked-view \
-  lottie-react-native \
-  react-native-device-info \
-  react-native-get-random-values \
-  react-native-in-app-review \
-  react-native-linear-gradient \
-  react-native-mask-input \
-  react-native-pager-view \
-  react-native-permissions \
-  react-native-safe-area-context \
-  react-native-svg \
-  react-native-vector-icons
+npx --package flowboard-react flowboard-setup
 ```
 
-`flowboard-react` ships `expr-eval` and `uuid` itself, so host apps do not need to install them separately.
-
-iOS:
+Preview the commands first:
 
 ```sh
-cd ios && pod install
+npx --package flowboard-react flowboard-setup --dry-run
+```
+
+`flowboard-react` keeps heavy native modules as peer dependencies to avoid duplicate binaries and version conflicts in host apps. The setup command installs the required peer set for you.
+
+## Expo Support
+
+Expo Go is not supported. This SDK depends on custom native modules, so Expo users need a development build, `expo prebuild`, or EAS Build.
+
+After running `flowboard-setup`, add the plugin to your app config:
+
+```json
+{
+  "expo": {
+    "plugins": ["flowboard-react"]
+  }
+}
 ```
 
+If your onboarding flow uses `request_permission` actions, configure the plugin with permission options:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "flowboard-react",
+        {
+          "permissions": ["camera", "photos", "microphone"],
+          "permissionMessages": {
+            "camera": "Allow $(PRODUCT_NAME) to access the camera during onboarding.",
+            "photos": "Allow $(PRODUCT_NAME) to access your photo library during onboarding.",
+            "microphone": "Allow $(PRODUCT_NAME) to access the microphone during onboarding."
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+Supported plugin options:
+
+- `permissions`: `notifications`, `contacts`, `location`, `camera`, `microphone`, `photos`
+- `permissionMessages`: override default iOS usage descriptions for supported Flowboard permissions
+- `iosPermissions`: append advanced `react-native-permissions` iOS entries directly
+- `androidPermissions`: append raw Android permissions directly
+- `includeVectorIconFonts`: defaults to `true`
+- `iconFonts`: override the bundled FontAwesome6 font file list
+
+The plugin does three things:
+
+- Composes `react-native-permissions` for iOS permission Podfile setup when needed
+- Adds Android manifest permissions for Flowboard permission actions
+- Bundles FontAwesome 6 fonts through `expo-font` so icons work in Expo builds
+
+## React Native CLI Support
+
+`flowboard-setup` installs the validated peer set for React Native CLI apps too, but some native configuration still belongs to the host app.
+
+After installation:
+
+1. Run `cd ios && pod install`.
+2. Configure `react-native-permissions` in your `Podfile`, `Info.plist`, and `AndroidManifest.xml` if your flow uses permission actions.
+3. Configure `react-native-vector-icons` font bundling if your host app does not already do it.
+
+The SDK does not edit your app config files automatically in this phase. It installs the packages and prints the exact next steps.
+
+## What `flowboard-setup` Installs
+
+| Package                                     | Why it stays a peer            |
+| ------------------------------------------- | ------------------------------ |
+| `@react-native-async-storage/async-storage` | Native persistence backend     |
+| `@react-native-masked-view/masked-view`     | Native masked rendering        |
+| `lottie-react-native`                       | Native animation runtime       |
+| `react-native-device-info`                  | Native device/app metadata     |
+| `react-native-in-app-review`                | Native review prompt support   |
+| `react-native-linear-gradient`              | Native gradient rendering      |
+| `react-native-pager-view`                   | Native paged screen containers |
+| `react-native-permissions`                  | Native permissions bridge      |
+| `react-native-safe-area-context`            | Native safe-area insets        |
+| `react-native-svg`                          | Native vector rendering        |
+| `react-native-vector-icons`                 | Native font/icon bundling      |
+
+Expo apps also get `expo-font` so the plugin can bundle the FontAwesome 6 fonts used by Flowboard icons.
+
+These JS-only helpers are bundled by the SDK itself and do not need to be installed by host apps:
+
+- `react-native-get-random-values`
+- `react-native-mask-input`
+- `expr-eval`
+- `uuid`
+
+## Installation Flags
+
+The setup command supports:
+
+- `--dry-run`: print commands without installing anything
+- `--yes`: skip the confirmation prompt
+- `--upgrade`: force reinstall of the validated package set
+- `--verbose`: print each command before it runs
+- `--project-root <path>`: target a different host app directory
+
 ## Usage
 
+Initialize Flowboard once near app startup:
+
 ```tsx
 import React from 'react';
 import { Flowboard, FlowboardProvider } from 'flowboard-react';
@@ -53,13 +148,18 @@ export default function App() {
 }
 ```
 
-Launch onboarding:
+Launch the default onboarding:
 
 ```tsx
 await Flowboard.launchOnboarding({
   customScreenBuilder: (ctx) => {
     if (ctx.screenData.id === 'paywall') {
-      return <MyPaywall onClose={ctx.onNext} onSignup={() => ctx.onJumpTo('signup')} />;
+      return (
+        <MyPaywall
+          onClose={ctx.onNext}
+          onSignup={() => ctx.onJumpTo('signup')}
+        />
+      );
     }
     return null;
   },
@@ -69,7 +169,7 @@ await Flowboard.launchOnboarding({
 });
 ```
 
-Launch a specific onboarding by ID (without replacing default cached onboarding used by `launchOnboarding`):
+Launch a specific onboarding by ID:
 
 ```tsx
 await Flowboard.launchOnboardingById('YOUR_ONBOARDING_ID', {
@@ -81,7 +181,7 @@ await Flowboard.launchOnboardingById('YOUR_ONBOARDING_ID', {
 });
 ```
 
-Re-initialize:
+Re-initialize if you rotate credentials or environment:
 
 ```tsx
 await Flowboard.reinit();
@@ -93,11 +193,11 @@ await Flowboard.reinit();
 - `Flowboard.launchOnboarding({ customScreenBuilder, customActionBuilder, onOnboardEnd, onStepChange, enableAnalytics, alwaysRestart, resumeProgress })`
 - `Flowboard.launchOnboardingById(onboardingId, { locale, version, customScreenBuilder, customActionBuilder, onOnboardEnd, onStepChange, enableAnalytics, alwaysRestart, resumeProgress })`
 - `Flowboard.reinit()`
-- `FlowboardProvider` (required to host modal flow)
+- `FlowboardProvider`
 
-## Jump To Action
+## Jump To Actions
 
-Configure direct screen navigation in JSON with `action: "jump_to"` and an `actionData.screenId` target:
+Use `jump_to` in Flowboard JSON:
 
 ```json
 {
@@ -117,25 +217,53 @@ Inside custom screens, use `ctx.onJumpTo(screenId)`:
 ```tsx
 customScreenBuilder: (ctx) => {
   if (ctx.screenData.id === 'paywall') {
-    return <Button title="Jump to Sign Up" onPress={() => ctx.onJumpTo('signup')} />;
+    return (
+      <Button title="Jump to Sign Up" onPress={() => ctx.onJumpTo('signup')} />
+    );
   }
   return null;
 };
 ```
 
-## Parity Checklist
+## Runtime Resilience
+
+Flowboard wraps its native peers behind defensive adapters.
+
+If a native module is installed but not linked or configured correctly:
+
+- the SDK logs a development warning once
+- storage falls back to memory
+- permissions return `unavailable`
+- in-app review is skipped
+- gradients, masks, paging, SVG, and Lottie fall back to simplified rendering where possible
 
-- [x] Flowboard init/launch/reinit
-- [x] Client context capture + resolver payload
-- [x] Analytics events (onboard_loaded, onboard_started, screen_view, onboard_ended)
-- [x] Cache + progress persistence
-- [x] SDUI components (layout, visual, inputs, advanced)
-- [x] Custom screens/actions
-- [x] Deeplink/weblink, rate_app, request_permission, jump_to
-- [x] Feature showcase example app
-- [x] Jest unit tests for critical logic
+This does not replace installation. Metro still requires the peer packages to exist in the host app dependency graph.
 
-## Testing
+## Troubleshooting
+
+`Plugin "flowboard-react" was not found`
+
+- Make sure `flowboard-react` is installed in the host app.
+- Re-run `npx --package flowboard-react flowboard-setup`.
+
+Icons render as empty boxes
+
+- Expo: confirm `plugins: ["flowboard-react"]` is present and rebuild the development client.
+- React Native CLI: confirm `react-native-vector-icons` fonts are bundled in the native app.
+
+Permission requests do nothing on iOS
+
+- Make sure `react-native-permissions` is configured in the host app Podfile.
+- Confirm the matching `Info.plist` usage descriptions exist.
+- Re-run `pod install`.
+
+Warnings about unavailable native modules
+
+- The package is present, but native setup is incomplete.
+- Rebuild the app after installing peers.
+- Verify `pod install`, Android permissions, and Expo plugin setup for the affected module.
+
+## Development
 
 ```sh
 yarn typecheck
@@ -143,18 +271,6 @@ yarn test
 yarn lint
 ```
 
-## Notes
-
-- Custom fonts must be available in the host app when using `fontFamily`.
-- Asset images/Lottie ("source": "asset") should be provided as `uri` or through a custom loader in the host app.
-- Radar charts support optional `autoFitLabels` (default `true`) and `labelOffset` (default `max(20, fontSize * 1.5)`) to keep axis labels inside bounds.
-
-## Contributing
-
-- [Development workflow](CONTRIBUTING.md#development-workflow)
-- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
-- [Code of conduct](CODE_OF_CONDUCT.md)
-
 ## License
 
 MIT

package/app.plugin.js

@@ -0,0 +1,341 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_ICON_FONTS = [
+  'FontAwesome6_Brands.ttf',
+  'FontAwesome6_Regular.ttf',
+  'FontAwesome6_Solid.ttf',
+];
+
+const FLOWBOARD_PERMISSION_MAP = {
+  camera: {
+    android: [{ name: 'android.permission.CAMERA' }],
+    infoPlistKey: 'NSCameraUsageDescription',
+    infoPlistMessage:
+      'Allow $(PRODUCT_NAME) to access the camera during onboarding.',
+    ios: 'Camera',
+  },
+  contacts: {
+    android: [{ name: 'android.permission.READ_CONTACTS' }],
+    infoPlistKey: 'NSContactsUsageDescription',
+    infoPlistMessage:
+      'Allow $(PRODUCT_NAME) to access your contacts during onboarding.',
+    ios: 'Contacts',
+  },
+  location: {
+    android: [{ name: 'android.permission.ACCESS_FINE_LOCATION' }],
+    infoPlistKey: 'NSLocationWhenInUseUsageDescription',
+    infoPlistMessage:
+      'Allow $(PRODUCT_NAME) to access your location during onboarding.',
+    ios: 'LocationWhenInUse',
+  },
+  microphone: {
+    android: [{ name: 'android.permission.RECORD_AUDIO' }],
+    infoPlistKey: 'NSMicrophoneUsageDescription',
+    infoPlistMessage:
+      'Allow $(PRODUCT_NAME) to access the microphone during onboarding.',
+    ios: 'Microphone',
+  },
+  notifications: {
+    android: [{ name: 'android.permission.POST_NOTIFICATIONS' }],
+    ios: 'Notifications',
+  },
+  photos: {
+    android: [
+      { name: 'android.permission.READ_MEDIA_IMAGES' },
+      {
+        attributes: { 'android:maxSdkVersion': '32' },
+        name: 'android.permission.READ_EXTERNAL_STORAGE',
+      },
+    ],
+    infoPlistKey: 'NSPhotoLibraryUsageDescription',
+    infoPlistMessage:
+      'Allow $(PRODUCT_NAME) to access your photo library during onboarding.',
+    ios: 'PhotoLibrary',
+  },
+};
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function getProjectRoot(config) {
+  return config?._internal?.projectRoot || process.cwd();
+}
+
+function warn(message) {
+  console.warn(`[flowboard-react/plugin] ${message}`);
+}
+
+function normalizeFlowboardPermissions(permissions) {
+  if (!Array.isArray(permissions)) return [];
+  return unique(
+    permissions
+      .map((permission) =>
+        String(permission || '')
+          .trim()
+          .toLowerCase()
+      )
+      .filter((permission) => FLOWBOARD_PERMISSION_MAP[permission])
+  );
+}
+
+function resolveIosPermissions(options) {
+  const inferred = normalizeFlowboardPermissions(options.permissions).map(
+    (permission) => FLOWBOARD_PERMISSION_MAP[permission].ios
+  );
+  const extras = Array.isArray(options.iosPermissions)
+    ? options.iosPermissions.map((permission) =>
+        String(permission || '').trim()
+      )
+    : [];
+  return unique([...inferred, ...extras]);
+}
+
+function resolveAndroidPermissions(options) {
+  const inferred = normalizeFlowboardPermissions(options.permissions).flatMap(
+    (permission) => FLOWBOARD_PERMISSION_MAP[permission].android || []
+  );
+  const extras = Array.isArray(options.androidPermissions)
+    ? options.androidPermissions
+        .map((permission) => String(permission || '').trim())
+        .filter(Boolean)
+        .map((name) => ({ name }))
+    : [];
+
+  return [...inferred, ...extras].reduce((acc, entry) => {
+    const name = entry.name;
+    const attributes = entry.attributes || {};
+    const duplicate = acc.some(
+      (candidate) =>
+        candidate.name === name &&
+        JSON.stringify(candidate.attributes || {}) ===
+          JSON.stringify(attributes)
+    );
+    if (!duplicate) {
+      acc.push({ attributes, name });
+    }
+    return acc;
+  }, []);
+}
+
+function resolveInfoPlistEntries(options) {
+  const overrides = options.permissionMessages || {};
+  return normalizeFlowboardPermissions(options.permissions).reduce(
+    (acc, permission) => {
+      const config = FLOWBOARD_PERMISSION_MAP[permission];
+      if (!config.infoPlistKey) return acc;
+      acc[config.infoPlistKey] =
+        overrides[permission] || config.infoPlistMessage;
+      return acc;
+    },
+    {}
+  );
+}
+
+function resolveOptionalModule(projectRoot, requests) {
+  const candidates = Array.isArray(requests) ? requests : [requests];
+  for (const request of candidates) {
+    try {
+      const resolvedPath = require.resolve(request, { paths: [projectRoot] });
+      return {
+        module: require(resolvedPath),
+        resolvedPath,
+      };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function createEnvironment(projectRoot) {
+  const configPlugins = resolveOptionalModule(
+    projectRoot,
+    '@expo/config-plugins'
+  );
+  return {
+    configPlugins: configPlugins ? configPlugins.module : null,
+    loadOptionalModule: (requests) =>
+      resolveOptionalModule(projectRoot, requests),
+    projectRoot,
+    warn,
+  };
+}
+
+function applyPermissionsPlugin(config, options, env) {
+  const iosPermissions = resolveIosPermissions(options);
+  if (iosPermissions.length === 0) return config;
+
+  const pluginModule = env.loadOptionalModule([
+    'react-native-permissions/app.plugin.js',
+    'react-native-permissions',
+  ]);
+  if (!pluginModule) {
+    env.warn(
+      'react-native-permissions was not found in the host app. iOS Podfile setup was skipped.'
+    );
+    return config;
+  }
+
+  const plugin = pluginModule.module.default || pluginModule.module;
+  if (typeof plugin !== 'function') {
+    env.warn(
+      'react-native-permissions did not expose a valid Expo plugin. iOS Podfile setup was skipped.'
+    );
+    return config;
+  }
+
+  return plugin(config, { iosPermissions });
+}
+
+function resolveVectorIconFontPaths(options, env) {
+  if (options.includeVectorIconFonts === false) return [];
+
+  const iconFonts =
+    Array.isArray(options.iconFonts) && options.iconFonts.length > 0
+      ? options.iconFonts
+      : DEFAULT_ICON_FONTS;
+
+  const packageJson = env.loadOptionalModule(
+    'react-native-vector-icons/package.json'
+  );
+  if (!packageJson) {
+    env.warn(
+      'react-native-vector-icons was not found in the host app. Font bundling for Expo was skipped.'
+    );
+    return [];
+  }
+
+  const packageRoot = path.dirname(packageJson.resolvedPath);
+  return iconFonts
+    .map((fontFile) => path.join(packageRoot, 'Fonts', fontFile))
+    .filter((fontPath) => {
+      if (fs.existsSync(fontPath)) return true;
+      env.warn(`Missing vector icon font file: ${fontPath}`);
+      return false;
+    });
+}
+
+function applyExpoFontPlugin(config, options, env) {
+  const fonts = resolveVectorIconFontPaths(options, env);
+  if (fonts.length === 0) return config;
+
+  const pluginModule = env.loadOptionalModule([
+    'expo-font/app.plugin.js',
+    'expo-font',
+  ]);
+  if (!pluginModule) {
+    env.warn(
+      'expo-font was not found in the host app. Font bundling for Expo was skipped.'
+    );
+    return config;
+  }
+
+  const plugin = pluginModule.module.default || pluginModule.module;
+  if (typeof plugin !== 'function') {
+    env.warn(
+      'expo-font did not expose a valid Expo plugin. Font bundling was skipped.'
+    );
+    return config;
+  }
+
+  return plugin(config, { fonts });
+}
+
+function ensureAndroidPermission(manifest, permission) {
+  const usesPermissions = manifest.manifest['uses-permission'] || [];
+  const nextEntry = {
+    $: {
+      'android:name': permission.name,
+      ...(permission.attributes || {}),
+    },
+  };
+
+  const duplicate = usesPermissions.some((entry) => {
+    const current = entry.$ || {};
+    return (
+      current['android:name'] === nextEntry.$['android:name'] &&
+      current['android:maxSdkVersion'] === nextEntry.$['android:maxSdkVersion']
+    );
+  });
+
+  if (!duplicate) {
+    usesPermissions.push(nextEntry);
+  }
+
+  manifest.manifest['uses-permission'] = usesPermissions;
+  return manifest;
+}
+
+function applyFlowboardPlugin(config, options = {}, env) {
+  const configPlugins = env.configPlugins;
+  if (
+    !configPlugins ||
+    typeof configPlugins.withAndroidManifest !== 'function' ||
+    typeof configPlugins.withInfoPlist !== 'function'
+  ) {
+    env.warn(
+      '@expo/config-plugins was not found in the host app. Flowboard Expo configuration was skipped.'
+    );
+    return config;
+  }
+
+  let nextConfig = config;
+  nextConfig = applyPermissionsPlugin(nextConfig, options, env);
+  nextConfig = applyExpoFontPlugin(nextConfig, options, env);
+
+  nextConfig = configPlugins.withInfoPlist(nextConfig, (infoConfig) => {
+    const entries = resolveInfoPlistEntries(options);
+    infoConfig.modResults = infoConfig.modResults || {};
+
+    Object.entries(entries).forEach(([key, value]) => {
+      if (!infoConfig.modResults[key]) {
+        infoConfig.modResults[key] = value;
+      }
+    });
+
+    return infoConfig;
+  });
+
+  nextConfig = configPlugins.withAndroidManifest(
+    nextConfig,
+    (androidConfig) => {
+      androidConfig.modResults = androidConfig.modResults || { manifest: {} };
+      androidConfig.modResults.manifest =
+        androidConfig.modResults.manifest || {};
+
+      resolveAndroidPermissions(options).forEach((permission) => {
+        ensureAndroidPermission(androidConfig.modResults, permission);
+      });
+
+      return androidConfig;
+    }
+  );
+
+  return nextConfig;
+}
+
+function withFlowboardReact(config, options = {}) {
+  const projectRoot = getProjectRoot(config);
+  const env = createEnvironment(projectRoot);
+  return applyFlowboardPlugin(config, options, env);
+}
+
+module.exports = withFlowboardReact;
+module.exports._internal = {
+  DEFAULT_ICON_FONTS,
+  FLOWBOARD_PERMISSION_MAP,
+  applyExpoFontPlugin,
+  applyFlowboardPlugin,
+  applyPermissionsPlugin,
+  createEnvironment,
+  ensureAndroidPermission,
+  getProjectRoot,
+  normalizeFlowboardPermissions,
+  resolveAndroidPermissions,
+  resolveInfoPlistEntries,
+  resolveIosPermissions,
+  resolveOptionalModule,
+  resolveVectorIconFontPaths,
+};