@ubidots/react-html-canvas

React library to interact with Ubidots dashboards from HTML Canvas widgets.

Instalación

pnpm add @ubidots/react-html-canvas

Peer Dependencies

• react >= 16.8
• react-dom >= 16.8

Basic Usage

Wrap your app with the Provider and use hooks to access dashboard data/events:

import {
  UbidotsProvider,
  useUbidotsReady,
  useUbidotsSelectedDevice,
  useUbidotsActions,
} from '@ubidots/react-html-canvas';

function DeviceInfo() {
  const ready = useUbidotsReady();
  const device = useUbidotsSelectedDevice();
  const { setDashboardDevice } = useUbidotsActions();

  if (!ready) return <span>Loading...</span>;
  return (
    <div>
      <pre>{JSON.stringify(device, null, 2)}</pre>
      <button onClick={() => setDashboardDevice('device-id')}>
        Select Device
      </button>
    </div>
  );
}

export default function App() {
  return (
    <UbidotsProvider readyEvents={['receivedToken']}>
      <DeviceInfo />
    </UbidotsProvider>
  );
}

API

• Provider

  • UbidotsProvider(props)
    • props:
      • onReady?: () => void
      • readyEvents?: ("receivedToken" | "receivedJWTToken" | "selectedDevice" | ...)[]
      • validateOrigin?: (origin: string) => boolean
      • initialStateOverride?: Partial

• Hooks

  • useUbidotsReady(): boolean
  • useUbidotsToken(): string | null
  • useUbidotsSelectedDevice(): Device | null
  • useUbidotsSelectedDevices(): Device[] | null
  • useUbidotsDashboardDateRange(): DateRange | null
  • useUbidotsRealTimeStatus(): boolean | null
  • useUbidotsDeviceObject(): DeviceObject | null
  • useUbidotsDashboardObject(): DashboardObject | null
  • useUbidotsSelectedFilters(): Filter[] | null
  • useUbidotsWidget(): { settings: object; id: string } | null
  • useUbidotsActions(): Actions
  • useUbidotsAPI(): Ubidots API client (autenticado con token)

• Acciones (useUbidotsActions)

  • setDashboardDevice(deviceId: string)
  • setDashboardMultipleDevices(deviceIds: string[])
  • setDashboardDateRange(range: { startTime: number; endTime: number })
  • setDashboardLayer(layerId: string)
  • setRealTime(rt: boolean)
  • refreshDashboard()
  • openDrawer({ url: string; width: number })
  • setFullScreen('toggle' | 'enable' | 'disable')
  • getHeaders(): { Authorization | X-Auth-Token, Content-type }

Examples & Documentation

📚 Complete Documentation

See the docs/ folder for comprehensive API documentation:

• Provider: UbidotsProvider
• Hooks: Individual documentation for each hook
• Types: TypeScript interfaces and types
• Guides: Setup, patterns, and best practices

🎯 Working Examples

See the examples/ folder for complete working examples:

• Basic Usage - Simple setup and device display
• Device Selector - Interactive device selection with single/multi-select
• Real-time Dashboard - Live data streaming and controls
• Complete Widget - Comprehensive example testing all features
• With HOCs - Higher-Order Components usage

Configurable Ready State

You can control which events must occur before considering the system "ready":

<UbidotsProvider readyEvents={['receivedToken', 'selectedDevice']} />

Notes

• The vanilla library (ubidots-html-canvas) was used as reference for events/methods. It's not a runtime dependency.
• The useUbidotsAPI hook exposes an SDK client and authenticates it when the token arrives.

Development

Code Quality

This project uses ESLint for linting and Prettier for code formatting to ensure consistent code style.

Available Scripts

# Install dependencies
pnpm install

# Run linter
pnpm run lint

# Run linter with automatic fixes
pnpm run lint:fix

# Format code with Prettier
pnpm run format

# Check if code is properly formatted
pnpm run format:check

VS Code Integration

If you're using VS Code, the project includes settings that will:

• Format code automatically on save
• Run ESLint fixes on save
• Show linting errors and warnings inline

Make sure you have the following VS Code extensions installed:

• ESLint
• Prettier

Configuration Files

• eslint.config.js - ESLint configuration with React, TypeScript, and accessibility rules
• .prettierrc - Prettier formatting configuration
• .editorconfig - Editor configuration for consistent coding styles
• .vscode/settings.json - VS Code specific settings

CI/CD Pipelines

This project uses GitHub Actions for continuous integration and deployment:

Pull Request Checks (.github/workflows/pr-checks.yml)

Runs on every PR and push to main/develop branches:

• Code Quality & Tests: Runs on Node.js 18 and 20
  • TypeScript compilation check
  • ESLint code quality check
  • Prettier formatting verification
  • Unit tests execution
  • Build verification
• Security Audit: Checks for vulnerabilities in dependencies
• PR Summary: Posts automated summary comment on PRs

Deployment Pipeline (.github/workflows/deploy.yml)

Manual deployment workflow with the following features:

• Manual Trigger: Only runs when manually triggered from GitHub Actions
• Version Selection: Choose patch, minor, or major version bump
• Pre-release Support: Optional tag for beta/alpha releases
• Quality Checks: Full linting, testing, and build verification
• Automated Versioning: Bumps version and creates git tags
• NPM Publishing: Publishes to NPM with appropriate tags
• GitHub Release: Creates release with installation instructions

How to Deploy

To deploy a new version:

1. Go to the Actions tab in GitHub
2. Select the Deploy workflow
3. Click Run workflow
4. Choose the version bump type (patch/minor/major)
5. Optionally add a pre-release tag (e.g., "beta")
6. Click Run workflow

The deployment will:

• Run all quality checks
• Bump the version in package.json
• Create a git tag
• Publish to NPM
• Create a GitHub release

License

MIT