@polarityio/pi-shared

v1.8.1

Published

8 days ago

Shared utilities, design tokens, base classes, and styles for the Polarity Integration Component Library

Downloads

9,541

0High
0Medium
0Low

spline3d

radar989

Polarity Integration Component Library

Shared Utilities

Foundation package providing design tokens, shared styles, base classes, and utilities for the Polarity Integration Component Library.

Installation

npm install @polarityio/pi-shared

Peer Dependencies

lit ^3.0.0

Overview

@polarityio/pi-shared is the shared foundation used by all Polarity Integration components. It provides:

Design Tokens — CSS custom properties for colors, spacing, typography, shadows, and more with dark/light theme support
Shared Styles — Reusable Lit CSS for focus rings and typography
Base Classes — IntegrationComponentBase, a LitElement subclass with built-in property bindings and service access; EntityLifecycleController, a Lit ReactiveController for subscribing to entity lifecycle events
Utilities — Helpers for defining, creating, and rendering custom elements
TypeScript Interfaces — Contracts for blocks, configs, services, and component properties

Package Exports

| Export Path | Description | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | @polarityio/pi-shared | Main entry — utilities, base classes, interfaces, tokens, and styles | | @polarityio/pi-shared/tokens | Isolated design token exports (paletteCSS, baseTokensCSS, darkThemeCSS, lightThemeCSS, injectPiTokens) | | @polarityio/pi-shared/pi-tokens.css | Pre-built CSS file containing all token definitions — use as a plain stylesheet |

Design Tokens

The token system uses a three-layer architecture:

Palette — Raw color values (grays, blues, teals, greens, yellows, oranges, reds, purples). Theme-independent.
Theme — Dark and light theme layers that map palette colors to semantic theme variables.
Base — Semantic tokens that components consume. These reference theme tokens via var() and remain stable across themes.

Dark theme is active by default (applied at :root). Switch to light theme by adding data-pi-theme="light" to any ancestor element.

Injecting Tokens

The simplest way to load all design tokens into the page:

import { injectPiTokens } from '@polarityio/pi-shared';

// Injects palette, dark/light themes, and base tokens into <head>.
// Safe to call multiple times — will not duplicate the <style> element.
injectPiTokens();

Or import the pre-built CSS file directly:

@import '@polarityio/pi-shared/pi-tokens.css';

Using Tokens in CSS

Components should reference the semantic base tokens:

.my-element {
  color: var(--pi-color-font-primary);
  background: var(--pi-color-background-application-0);
  padding: var(--pi-size-spacing-sm);
  border-radius: var(--pi-size-radius-base);
  font-family: var(--pi-font-family-base);
  font-size: var(--pi-size-font-base);
  transition: background var(--pi-transition-fast);
}

Token Reference

Colors

| Category | Tokens | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | Background — Application | --pi-color-background-application-0 through application-4 | | Background — Container | -base, -danger, -disabled, -info, -neutral, -success, -warning | | Background — Semantic | -primary, -secondary, -table-header, -transparent | | Border | -container, -danger, -element, -info, -success, -warning | | Font | -danger, -disabled, -info, -inverse, -primary, -secondary, -success, -urgent, -warning | | Interactive | -hover, -active, -primary-hover | | Gradient | -regenai-start, -regenai-end |

Typography

| Token | Value | | --------------------------- | -------------------------- | | --pi-size-font-xs | 0.75rem | | --pi-size-font-sm | 0.875rem | | --pi-size-font-base | 0.8125rem | | --pi-size-font-md | 1rem | | --pi-size-font-lg | 1.25rem | | --pi-size-font-xl | 1.5rem | | --pi-size-font-xxl | 2rem | | --pi-font-family-base | 'Noto Sans', sans-serif | | --pi-font-family-mono | 'Courier New', monospace | | --pi-font-weight-regular | 400 | | --pi-font-weight-medium | 500 | | --pi-font-weight-semibold | 600 | | --pi-font-weight-bold | 700 |

Font Size Scale: Set --pi-font-size-scale to compensate for non-16px root font sizes. For example, if html { font-size: 14px }, set --pi-font-size-scale: 1.143 (16 ÷ 14).

Spacing

| Token | Value | | ----------------------- | -------- | | --pi-size-spacing-xxs | 0.125rem | | --pi-size-spacing-xs | 0.25rem | | --pi-size-spacing-sm | 0.5rem | | --pi-size-spacing-md | 0.75rem | | --pi-size-spacing-lg | 1rem | | --pi-size-spacing-xl | 1.5rem | | --pi-size-spacing-xxl | 2rem |

Border Radius

| Token | Value | | ----------------------- | ------ | | --pi-size-radius-sm | 2px | | --pi-size-radius-base | 4px | | --pi-size-radius-lg | 8px | | --pi-size-radius-full | 9999px |

Transitions

| Token | Value | | ---------------------- | ----------------- | | --pi-transition-fast | 150ms ease-in-out | | --pi-transition-base | 200ms ease-in-out |

Shadows

Composed shadow tokens at various elevation depths:

--pi-shadow-sm, --pi-shadow-2, --pi-shadow-4, --pi-shadow-8, --pi-shadow-16, --pi-shadow-24

Focus

| Token | Value | | --------------------------- | ------------------------------------ | | --pi-color-border-focus | var(--pi-color-background-primary) | | --pi-border-width-focus | 2px | | --pi-outline-offset-focus | -1px |

Exports

Utilities

`injectPiTokens()`

Injects all design tokens (palette, dark/light themes, and base semantic tokens) into the document <head>. Safe to call multiple times.

`libraryCustomElementName(name, version)`

Generates a versioned custom element name in the format pi-{name}-v{version} (e.g., pi-my-component-v1-0-0). Used internally by component packages to produce unique, collision-free element names.

import { libraryCustomElementName } from '@polarityio/pi-shared';

const tagName = libraryCustomElementName('my-component', '1.0.0');
// → 'pi-my-component-v1-0-0'

`defineCustomElementOnce(name, elementClass)`

Registers a custom element only if it hasn't already been defined. Prevents duplicate registration errors.

import { defineCustomElementOnce } from '@polarityio/pi-shared';

defineCustomElementOnce('pi-my-component-v1-0-0', MyComponent);

`appendCustomElement(parentElement, customElementName, properties)`

Creates a custom element via document.createElement, sets the given properties, and appends it to the parent.

import { appendCustomElement } from '@polarityio/pi-shared';

appendCustomElement(container, 'pi-my-component-v1-0-0', [
  { name: 'block', value: blockData },
  { name: 'services', value: servicesProxy },
  { name: 'context', value: context }
]);

`renderCustomElement(parentElement, customElementName, properties)`

Renders a custom element into a parent using Lit's render() and the SpreadPropsDirective for reactive property binding.

import { renderCustomElement } from '@polarityio/pi-shared';

renderCustomElement(container, 'pi-my-component-v1-0-0', [
  { name: 'block', value: blockData },
  { name: 'services', value: servicesProxy },
  { name: 'context', value: context }
]);

`getComponentElementName(config, type)`

Looks up a component's custom element name from an IConfig object by type ('summary' or 'details').

`SpreadPropsDirective`

A Lit directive that spreads an array of ICustomElementProperty objects onto an element as properties.

Base Classes

`IntegrationComponentBase`

A LitElement subclass that all integration components should extend. Provides:

| Property | Type | Description | | ------------- | ------------------------------ | ----------------------------------------------------------- | | isCollapsed | boolean | Whether the component is in a collapsed state | | block | IBlock | The integration block data (summary tags, details, acronym) | | services | IServicesProxy | Proxy to all Polarity platform services | | context | IntegrationComponentContext | Provided by the Polarity host — typed access to entity data, lifecycle events, user info, notifications, and cross-integration data |

| Member | Description | | --------------------------------- | ------------------------------------------------------------ | | integrationId | Getter — returns block.integrationId | | sendIntegrationMessage(message) | Sends a message to the integration's onMessage server hook |

The connectedCallback validates that block, services, and context are set, and that block.integrationId is present.

import { IntegrationComponentBase } from '@polarityio/pi-shared';
import { html, css } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-summary')
export class MySummary extends IntegrationComponentBase {
  static styles = css`
    :host {
      display: block;
    }
  `;

  render() {
    return html`<span>${this.block.acronym}</span>`;
  }
}

`EntityLifecycleController`

A Lit ReactiveController that subscribes to the four notification-window lifecycle events exposed by context.on. Handles subscribe in hostConnected and dispose in hostDisconnected automatically — no manual cleanup required.

Pass an EntityLifecycleHandlers object to the constructor. All four handlers are optional — provide only the ones you need.

EntityLifecycleHandlers interface

| Handler | Scope | Receives | Description | | ---------------------- | ------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | entityAdded | Window-level | entityValue: string | A new entity was added to the notification window (including annotation-only entities). Use to reset per-entity UI state. | | entityRemoved | Window-level | entityValue: string | An entity was dismissed, pruned, or cleared from the window. | | integrationDataAdded | Current-entity only | blocks: IntegrationBlock[] | New integration blocks arrived for this entity. Never fires with the component's own block — a component is instantiated only after its own first block is received. | | annotationDataAdded | Current-entity only | annotations: PolarityAnnotation[] | New Polarity annotations arrived for this entity. |

import { IntegrationComponentBase, EntityLifecycleController } from '@polarityio/pi-shared';

class MyDetails extends IntegrationComponentBase {
  private _lifecycle = new EntityLifecycleController(this, {
    entityAdded: (entityValue) => {
      // A new entity was looked up — reset any UI state tied to the previous entity
      this._alerts = [];
      this.requestUpdate();
    },
    integrationDataAdded: (blocks) => {
      // New integration data arrived for this entity from another integration
      if (!blocks.some(b => b.integrationId === 'jira')) return;
      this._relatedBlocks = this.context.data.integration();
      this.requestUpdate();
    },
    annotationDataAdded: (annotations) => {
      this._annotationCount = annotations.length;
      this.requestUpdate();
    },
  });
}

context availability in tests: EntityLifecycleController guards against context being absent at connect time. In unit tests, use ContextMock to provide a concrete context value, or simply omit lifecycle handlers you aren't testing.

Interfaces

Public Interfaces

| Interface | Description | | ------------------------------ | ------------------------------------------------------------------------------------ | | IBlock | Integration block data — integrationId, acronym, and data (details + summary) | | IConfig | Component configuration mapping types ('summary' | 'details') to element names | | ICustomElementProperty | Name/value pair for setting properties on custom elements | | IIntegrationBlockIntegration | Shape of integration data containing details (object) and summary (string array) |

Component Interfaces

| Interface | Description | | ------------------------------------ | --------------------------------------------------------- | | IIntegrationComponentProperties | Base component props — isCollapsed, block, services, context | | IDefaultSummaryComponentProperties | Extends base props with optional color (IPiTagColors) | | IPiTagColors | Tag color set — background, text, textBold | | IServicesProxy | Read-only proxy to all Polarity platform services |

Service Interfaces

IServicesProxy exposes the following services:

| Service | Interface | Description | | ---------------------- | ------------------------------ | ------------------------------------------------------ | | currentServer | ICurrentServerService | Server state and edition info | | currentUser | ICurrentUserService | User loading and state | | flashMessages | IFlashMessagesService | Success, info, warning, and danger notifications | | moment | IMomentService | Date/time locale and timezone utilities | | notificationsData | INotificationsDataService | Notification and block data management | | polarityx | IPolarityxService | Core Polarity platform control (HUD, windows, lookups) | | searchData | ISearchDataService | Search state and operations | | session | ISessionService | Authentication and session management | | store | IStoreService | Data store operations | | windowService | IWindowService | Application window state and control | | log | ILogService | Logging (trace, debug, info, warn, error, fatal) | | integrationMessenger | IIntegrationMessengerService | Messaging with the integration server |

Context API

IntegrationComponentContext is a unified, fully-typed object available on every integration component as this.context. It replaces the fragmented this.services bag and all (this.block as any).xxx cast patterns — grouping every host capability by domain.

`IntegrationComponentContext<TOptions>`

The primary interface. TOptions defaults to Record<string, unknown> — provide a concrete interface to get typed context.userOptions.

| Property | Type | Description | | -------------- | ------------------------- | --------------------------------------------------------------------------------------------- | | entity | Entity | The entity that triggered this lookup. Replaces (this.block as any).entity. | | userOptions | TOptions | The integration's configured user options. Replaces (this.block as any).userOptions. | | integration | IntegrationInfo | Integration identity (id, name, acronym, polarityIntegrationUuid). | | notify | NotifyService | Display toast notifications (danger, success, info, warning). | | user | UserInfo | Currently logged-in user. Synchronously available at mount time. | | users | UsersService | Resolve arbitrary user IDs → UserInfo records (may be async). | | search | (entityValue: string) => void | Trigger an entity search. Routes to the correct platform API automatically. | | data | DataService | Access cross-integration blocks and Polarity annotations for entities in the notification window. | | platform | PlatformInfo | Runtime environment info (isClientWindow). | | on | LifecycleEvents | Low-level lifecycle subscription API. Prefer EntityLifecycleController over direct use. | | state | ComponentStateInfo | Platform-managed loading state (isLoadingDetails, detailsLoaded). |

interface MyOptions {
  apiKey: string;
  enableFeature: boolean;
}

export class MyDetails extends IntegrationComponentBase {
  // Typed userOptions — access is: this.context.userOptions.enableFeature (boolean)
}

// Inside render() or any lifecycle method:
render() {
  const entity = this.context.entity.value;           // e.g. '8.8.8.8'
  const acronym = this.context.integration.acronym;  // e.g. 'VT'
  const user = this.context.user.displayName;         // always non-empty

  if (this.context.state.isLoadingDetails) {
    return html`<pi-spinner label="Loading..."></pi-spinner>`;
  }

  return html`<div>${entity} — ${acronym}</div>`;
}

`NoopContextBase<TOptions>`

Abstract base class for host adapters. Provides safe no-op defaults for all service capabilities so that integrations never encounter a runtime error from an unimplemented capability. The four abstract properties (entity, userOptions, integration, user) have no safe default and must be provided by the host.

Host applications extend this class rather than implementing IntegrationComponentContext from scratch:

import { NoopContextBase } from '@polarityio/pi-shared';

class MyHostContext extends NoopContextBase<MyOptions> {
  entity = this._resolvedEntity;
  userOptions = this._resolvedOptions;
  integration = { id: 'my-integration', polarityIntegrationUuid: 'uuid-...', name: 'My Integration', acronym: 'MI' };
  user = { id: this._session.userId, displayName: this._session.username ?? 'Unknown' };

  // Override only the capabilities this host supports
  override notify = new MyHostNotifyService();
  override search = (value: string) => this._triggerSearch(value);
}

Supporting Types

| Type | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | IntegrationInfo | Integration identity — id (slug), polarityIntegrationUuid, name, acronym | | UserInfo | User record — id, displayName (always non-empty), username?, email?, fullName? | | NotifyService | Toast notifications — danger, success, info, warning (each accepts message + optional NotifyOptions) | | NotifyOptions | timeout?: number — auto-dismiss delay in ms | | UsersService | getById(id): Promise<UserInfo \| null> — resolves a user ID to a record | | DataService | integration(entityValue?): IntegrationBlock[], integrations(): IntegrationBlock[], annotations(entityValue?): PolarityAnnotation[] \| null | | IntegrationBlock | A block from another integration — entityValue, entityType, entityTypes, integrationId, polarityIntegrationUuid, integrationName, acronym, data.summary, data.details | | PolarityAnnotation | A user annotation — tagName, channelName, userId, username, applied | | PlatformInfo | isClientWindow: boolean | | ComponentStateInfo | isLoadingDetails: boolean, detailsLoaded: boolean | | LifecycleEvents | Low-level event subscriptions — see EntityLifecycleController for the high-level wrapper |

Styles

`focusStyles`

A Lit css tagged template providing consistent focus ring styles. Import and spread into your component's static styles, then add the pi-focus class to focusable elements.

import { focusStyles } from '@polarityio/pi-shared';
import { css } from 'lit';

class MyComponent extends LitElement {
  static styles = [
    focusStyles,
    css`
      /* component styles */
    `
  ];
}

The focus ring uses outline with a negative offset so there is no layout shift.

`scrollbarStyles`

A Lit css tagged template that applies thin, themed scrollbars to a component and its descendants. Uses the --pi-color-border-element token for the thumb color. Import and spread into your component's static styles:

import { scrollbarStyles } from '@polarityio/pi-shared';
import { css } from 'lit';

class MyComponent extends LitElement {
  static styles = [
    scrollbarStyles,
    css`
      /* component styles */
    `
  ];
}

`scrollbarCSS`

A plain CSS string that applies thin, themed scrollbars within the [data-pi-theme] subtree. Intended for light DOM content without affecting the host app outside that themed boundary.

`injectPiScrollbar(doc?)`

Injects the scrollbar stylesheet into the document <head>. Safe to call multiple times.

import { injectPiScrollbar } from '@polarityio/pi-shared';

injectPiScrollbar();

`typographyCSS`

A plain CSS string that styles native HTML elements (h1–h6, p, small, code, pre, a, hr) using Polarity design tokens. Intended for light DOM content.

`injectPiTypography(doc?)`

Injects the typography stylesheet into the document <head>. Safe to call multiple times.

import { injectPiTypography } from '@polarityio/pi-shared';

injectPiTypography();

Test Mocks

The package includes comprehensive service mocks under src/base/mocks/ for use in this repo's own test suite. These are internal implementation details, not part of the published @polarityio/pi-shared API — they aren't re-exported from the package barrel and must be imported by relative path from within this repository:

ServicesProxyMock — Complete mock of IServicesProxy composing all individual service mocks
Individual mocks for each service (CurrentServerServiceMock, FlashMessagesServiceMock, LogServiceMock, etc.)
ContextMock — Concrete NoopContextBase implementation for unit tests. Provides safe no-op implementations of all IntegrationComponentContext capabilities; override individual properties to inject test-specific values.

// Path is relative to a test file under packages/shared/src/base/
// (e.g. IntegrationComponentBase.test.ts) — the only place these mocks are used today.
import { ContextMock } from './mocks/ContextMock.js';

// In a test — assign context before connectedCallback fires
element.context = new ContextMock();

// Override properties for specific test scenarios
const ctx = new ContextMock();
ctx.entity = { value: '8.8.8.8', type: 'IPv4', ...rest };
ctx.userOptions = { apiKey: 'test-key', showAvatars: true };
element.context = ctx;

Usage

Building a Component Package

A typical integration component imports from @polarityio/pi-shared for registration, base class, and tokens:

import {
  IntegrationComponentBase,
  libraryCustomElementName,
  defineCustomElementOnce,
  injectPiTokens,
  focusStyles
} from '@polarityio/pi-shared';
import { html, css } from 'lit';
import { version, name } from '../package.json';

// Inject design tokens into the page
injectPiTokens();

// Generate a versioned element name
const TAG = libraryCustomElementName(name, version);

export class MyDetails extends IntegrationComponentBase {
  static styles = [
    focusStyles,
    css`
      :host {
        display: block;
        color: var(--pi-color-font-primary);
        background: var(--pi-color-background-application-0);
        padding: var(--pi-size-spacing-sm);
      }
    `
  ];

  render() {
    return html`<pre>${JSON.stringify(this.block.data.details, null, 2)}</pre>`;
  }

  async onRefresh() {
    const result = await this.sendIntegrationMessage({ action: 'refresh' });
    // handle result
  }
}

// Register the element (safe to call multiple times)
defineCustomElementOnce(TAG, MyDetails);

Theme Switching

Dark theme is active by default. To switch to light theme, set the data-pi-theme attribute:

<!-- Dark theme (default) -->
<div>...</div>

<!-- Light theme -->
<div data-pi-theme="light">...</div>

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme