@quantabit/floating-widget-sdk

QuantaBit Floating Widget SDK - A premium, dynamic honeycomb-style floating menu designed for smooth plug-and-play SDK integrations.

📦 Installation

npm install @quantabit/floating-widget-sdk
# or
yarn add @quantabit/floating-widget-sdk

🚀 Key Features

• Adaptive Honeycomb Layout: Seamlessly calculates 2D coordinates for an arbitrary number of SDK features on a hexagonal grid, avoiding hardcoded position limitations.
• Pluggable Architecture: Easily register/unregister custom actions and widgets at runtime from separate micro-frontend SDKs (e.g. VIP subscriptions, crash-reporting widgets, order status checkers).
• Decoupled Modals: SDKs can register their own React modal/dialog components. The container orchestrates their visible state automatically.
• Micro-interactions: Vibrant gradient designs, hovering micro-animations, and full RTL/light/dark mode compatibility.

📚 Quick Start

1. Register the Context Provider

Wrap your application root with FloatingWidgetProvider and place the QuickActionsWidget at the bottom layout.

import React from 'react';
import { FloatingWidgetProvider, QuickActionsWidget } from '@quantabit/floating-widget-sdk';
import '@quantabit/floating-widget-sdk/styles';

function MyApp({ Component, pageProps }) {
  return (
    <FloatingWidgetProvider>
      <div className="app-container">
        <Component {...pageProps} />
      </div>
      
      {/* Renders the honeycomb floating bubble */}
      <QuickActionsWidget position="bottom-right" theme="dark" language="en" />
    </FloatingWidgetProvider>
  );
}

export default MyApp;

🔌 Registering Custom SDKs

You can dynamically insert widgets using the Global JS Registry or the React Context hook.

Approach A: Global JS Registry (Best for independent JS bundles)

import { floatingWidgetRegistry } from '@quantabit/floating-widget-sdk';
import MyCustomModal from '@quantabit/my-custom-sdk/components/Modal';

// Register widget dynamically
floatingWidgetRegistry.register('my-custom-feature', {
  icon: '🚀',
  color: '#2563eb',
  title: {
    en: 'Launch Console',
    zh: '运行控制台'
  },
  order: 15, // Display order weight
  component: MyCustomModal, // Custom React component
  enabled: true
});

To remove the module dynamically:

floatingWidgetRegistry.unregister('my-custom-feature');

Approach B: React Hook Integration (Best for component-bound lifetimes)

import React, { useEffect } from 'react';
import { useFloatingWidgetContext } from '@quantabit/floating-widget-sdk';

function LiveSupport() {
  const { registerPlugin, unregisterPlugin } = useFloatingWidgetContext();

  useEffect(() => {
    registerPlugin('live-chat', {
      icon: '💬',
      color: '#10b981',
      title: 'Live Chat',
      onClick: () => {
        console.log('Initiating live chat session...');
      }
    });

    return () => unregisterPlugin('live-chat');
  }, [registerPlugin, unregisterPlugin]);

  return <section>Live Chat Hub</section>;
}

🛠️ API Reference

Data Structures: Feature

interface Feature {
  key: string;               // Unique feature identifier
  icon: string | ReactNode;  // Bubble icon (emoji or React node)
  color: string;             // Theme color background
  enabled?: boolean;         // Active state (default true)
  order?: number;            // Sorting index (default 100)
  title?: string | Record<string, string>; // Multi-lingual labels
  onClick?: (feature: Feature) => void;     // Direct trigger handler
  component?: ComponentType<any>;           // Modal/Panel component to show on click
}

🎨 Themes & Custom CSS Variables

Override layout variables inside your global CSS stylesheet:

:root {
  --fw-primary: #7c3aed;         /* Primary bubble gradient base */
  --fw-bg: #ffffff;              /* Light mode card background */
  --fw-bg-dark: #1f2937;         /* Dark mode card background */
  --fw-btn-size: 56px;           /* Main floating action button size */
  --fw-feature-size: 48px;       /* Individual feature button size */
}

📄 License

MIT License

🌐 Brand & Links

• Official Mainnet: QuantaBit Chain
• Developer Platform: Developer Platform
• Open Platform: Open Platform
• Payment Platform: Pay Platform
• Feedback: Feedback