@avaya/infinity-elements-sdk

CLI tool for scaffolding InfinityElement projects.

Installation

npm install -g @avaya/infinity-elements-sdk

Usage

Initialize a new project

infinity init my-element
cd my-element

Custom Element Naming Rules

Your element name must follow the W3C Custom Elements specification:

| Rule | Valid | Invalid | |------|-------|---------| | Must contain a hyphen | my-element, user-profile | myelement, profile | | Must start with lowercase letter | my-element | 1-element, -element | | All lowercase | my-element | My-Element, myElement | | No reserved names | my-annotation | annotation-xml, font-face |

Reserved names (cannot be used): annotation-xml, color-profile, font-face, font-face-src, font-face-uri, font-face-format, font-face-name, missing-glyph

Start development server

infinity dev

Build for production

infinity build

What it creates

The CLI scaffolds a complete React project that compiles to a web component using r2wc:

• React component with TypeScript
• CSS Modules for styling
• Vite for building and dev server
• Ready-to-use web component

Generated Project Structure

my-element/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── index.html
└── src/
    ├── Element.tsx         # Your React component
    ├── Element.module.css   # CSS Module
    └── index.ts            # Web component wrapper

Element Properties (Variables)

InfinityElements support configurable properties that administrators set in the Infinity Configuration UI. These properties are passed to your web component as HTML attributes, which r2wc automatically converts to React props.

How It Works

1. Admin Configuration: In the Configuration UI, administrators add name/value pairs to the element's "Properties" section
2. Attribute Injection: When your element loads, these properties become HTML attributes
3. React Props: The r2wc library automatically maps these attributes to your element's props

Example

Admin sets properties: | Name | Value | |------|-------| | theme | dark | | customerName | John Doe |

Your element receives:

<my-element theme="dark" customerName="John Doe"></my-element>

Implementing Element Properties

1. Define props in your React component:

// src/Element.tsx
interface ElementProps {
  theme?: string;
  customerName?: string;
  maxItems?: string;  // Note: all values are strings
}

const Element: React.FC<ElementProps> = ({
  theme = "light",
  customerName,
  maxItems = "10"
}) => {
  const max = parseInt(maxItems, 10); // Convert to number if needed
  
  return (
    <div className={theme === "dark" ? styles.dark : styles.light}>
      {customerName && <h2>Welcome, {customerName}</h2>}
      {/* Your element content */}
    </div>
  );
};

2. Register props in the web component wrapper:

// src/index.ts
import r2wc from "@r2wc/react-to-web-component";
import Element from "./Element";

const WebElement = r2wc(Element, React, ReactDOM, {
  props: {
    theme: "string",
    customerName: "string",
    maxItems: "string",
  },
});

customElements.define("my-element", WebElement);

Important Notes

• ⚠️ All values are strings: HTML attributes are always strings; parse numbers/booleans in your element
• ⚠️ Props must be declared: Only props listed in the r2wc props object will be passed to React
• ✅ Provide defaults: Always set sensible defaults since properties are optional
• ✅ Use lowercase/kebab-case: Follow HTML attribute naming conventions

Common Property Use Cases

| Property | Example Use | |----------|-------------| | theme | Dark/light mode preference per element | | locale | Language/region for internationalization | | apiEndpoint | Custom backend URL for different environments | | customerId | Pre-populate with customer context | | debugMode | Enable verbose logging during development | | maxResults | Configure result limits |

Authentication

Web components can authenticate using Keycloak's OAuth 2.0 PKCE flow via popup window, enabling secure access to protected resources with session persistence in browser storage.

Sample

oauth README.md

Keycloak Setup

1. Configure Client:

   • Enable implicit PKCE flow
   • Set web origins to allowed domains

2. Configure Redirect URIs:

   • Keycloak requires exact URI matches (protocol, domain, port, path)
   • Add redirect URI for each domain hosting your element
   • The redirect callback page must post tokens back to the parent window (where your web component is embedded)
   • Example for multi-domain deployment:

     http://localhost:3000/callback
     https://app.example.com/callback
     https://portal.example.com/callback

3. Implement OAuth flow in your web component and store tokens in localStorage

License

MIT