@electric-ai/electric-sdk-stencil

v1.5.0

Published

a month ago

Framework-agnostic Electric SDK web components built with Stencil

Downloads

225

0High
0Medium
0Low

electric_ai_engineering

tommcgurlelectric

devinviss_electric

matthew.haeberle

Electric SDK - Stencil Web Components

Framework-agnostic web components for the Electric SDK, built with Stencil. Use with React, Vue, Angular, or vanilla JavaScript.

Features

🚀 Framework-agnostic - Works with any framework or vanilla JavaScript
🔐 Built-in Authentication - Integrated Auth0 authentication
🎨 Shadow DOM - Encapsulated styles, no CSS conflicts
📦 Small Bundle Size - No framework dependencies
🔧 TypeScript Support - Full type definitions included
🌐 Native Web Components - Standards-based, future-proof

Installation

npm install electric-sdk-stencil

For SDK Development: This project uses pnpm for package management. If you're contributing to the SDK or building from source, use pnpm install instead of npm install.

Components

electric-asset-list

Displays a list of user assets with built-in authentication.

<electric-asset-list environment="staging" auto-login="true" use-popup-auth="true"></electric-asset-list>

Props:

environment - Environment: "staging", "demo", or "production" (default: "staging")
organization-id - Organization ID
auto-login - Automatically attempt login (default: true)
use-popup-auth - Use popup instead of redirect (default: true)
login-redirect-uri - Custom redirect URI after login
custom-class - Custom CSS class name

Events:

errorOccurred - Emitted when an error occurs
loadingChanged - Emitted when loading state changes

electric-asset-item

Displays a single asset/device (used internally by electric-asset-list).

<electric-asset-item .device="${deviceObject}"></electric-asset-item>

electric-purchase-hardware

Embeds the hardware purchase interface via iframe.

<electric-purchase-hardware iframe-url="https://example.com/purchase" width="100%" height="600px" iframe-title="Purchase Hardware"></electric-purchase-hardware>

electric-auth-provider

Optional wrapper for initializing SDK configuration once for multiple components.

<electric-auth-provider environment="staging" organization-id="org-123">
  <electric-asset-list></electric-asset-list>
  <electric-purchase-hardware></electric-purchase-hardware>
</electric-auth-provider>

Usage

Vanilla JavaScript / HTML

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="https://unpkg.com/electric-sdk-stencil/dist/electric-sdk-stencil/electric-sdk-stencil.esm.js"></script>
  </head>
  <body>
    <electric-asset-list environment="staging" auto-login="true"></electric-asset-list>

    <script>
      const assetList = document.querySelector('electric-asset-list');

      assetList.addEventListener('errorOccurred', e => {
        console.error('Error:', e.detail);
      });

      assetList.addEventListener('loadingChanged', e => {
        console.log('Loading:', e.detail);
      });
    </script>
  </body>
</html>

React

Recommended: Use the auto-generated React components:

import { defineCustomElements } from 'electric-sdk-stencil/loader';
import { ElectricAssetList } from 'electric-sdk-stencil/react';
import { authStore } from 'electric-sdk-stencil';
import { useEffect, useState } from 'react';

// Call once in your app (e.g., in index.tsx or App.tsx)
defineCustomElements();

function App() {
  const [authState, setAuthState] = useState(authStore.state);

  useEffect(() => {
    const unsubscribe = authStore.onChange('isAuthenticated', () => {
      setAuthState({ ...authStore.state });
    });
    return () => unsubscribe();
  }, []);

  if (authState.isLoading) return <div>Loading...</div>;

  return <ElectricAssetList environment="staging" autoLogin={true} onErrorOccurred={e => console.error(e.detail)} />;
}

The React integration provides:

Auto-generated React components via @stencil/react-output-target
Full TypeScript support
Event handling through props
Access to auth state via authStore

See the React documentation for more details.

Vue 3

<template>
  <electric-asset-list environment="staging" :auto-login="true" :use-popup-auth="true" @errorOccurred="handleError" @loadingChanged="handleLoadingChange" />
</template>

<script setup lang="ts">
import { defineCustomElements } from 'electric-sdk-stencil/loader';

// Call once
defineCustomElements();

const handleError = (e: CustomEvent<string>) => {
  console.error('Error:', e.detail);
};

const handleLoadingChange = (e: CustomEvent<boolean>) => {
  console.log('Loading:', e.detail);
};
</script>

Configure Vue to ignore custom elements:

// main.ts or vite.config.ts
app.config.compilerOptions.isCustomElement = tag => tag.startsWith('electric-');

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { defineCustomElements } from 'electric-sdk-stencil/loader';

defineCustomElements();

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})
export class AppModule {}

<!-- component.html -->
<electric-asset-list
  environment="staging"
  [auto-login]="true"
  [use-popup-auth]="true"
  (errorOccurred)="handleError($event)"
  (loadingChanged)="handleLoadingChange($event)"
></electric-asset-list>

// component.ts
export class AppComponent {
  handleError(event: CustomEvent<string>) {
    console.error('Error:', event.detail);
  }

  handleLoadingChange(event: CustomEvent<boolean>) {
    console.log('Loading:', event.detail);
  }
}

Advanced Usage

Programmatic API Access

import { getAuthService, getApiService, authStore, initializeElectricSDK } from 'electric-sdk-stencil';

// Initialize SDK
initializeElectricSDK({
  environment: 'staging',
  organizationId: 'org-123',
});

// Access auth service
const authService = getAuthService();
await authService.loginWithPopup();
const isAuthenticated = authService.isAuthenticated();

// Access API service
const apiService = getApiService();
const devices = await apiService.fetchUserDevices('user-id', 'org-id');

// Subscribe to auth state changes
authStore.onChange('isAuthenticated', isAuth => {
  console.log('Auth changed:', isAuth);
});

Custom Configuration

import { initializeElectricSDK } from 'electric-sdk-stencil';

initializeElectricSDK({
  environment: 'production',
  organizationId: 'your-org-id',
  customConfig: {
    coreEntityUrl: 'https://custom-api.example.com',
    auth0Domain: 'custom-auth.example.com',
    auth0ClientId: 'your-client-id',
    auth0CallbackUrl: 'https://your-app.com/callback',
    auth0Audience: 'https://your-api.example.com',
    auth0Connection: 'your-auth0-connection', // Optional: specify Auth0 connection (e.g., 'adp-workforce-now')
  },
});

Development

Note: This project uses pnpm for package management. Please use pnpm instead of npm for all commands.

# Install dependencies
pnpm install

# Start development server with live reload
pnpm start

# Build for production
pnpm run build

# Run tests
pnpm test

# Run tests in watch mode
pnpm run test.watch

# Generate a new component
pnpm run generate

Building from Source

git clone https://github.com/electric-ai/electric-sdk-stencil.git
cd electric-sdk-stencil
pnpm install
pnpm run build

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

TypeScript Support

Full TypeScript definitions are included. Import types:

import type { Employee, Device, ElectricSDKConfig, ElectricSDKOptions } from 'electric-sdk-stencil';

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT

Support

For issues and questions, please open an issue on GitHub.