@polarityio/pi-error 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2026 ThreatConnect, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# Polarity Integration Component Library
+
+## Error Component
+
+An error alert component that displays error information with a close button, optional title and icon, automatic message resolution from error objects, expandable JSON details, and clipboard copy.
+
+## Installation
+
+```bash
+npm install @polarityio/pi-error
+```
+
+### Peer Dependencies
+
+- [lit](https://lit.dev/) ^3.0.0
+
+## Usage
+
+```javascript
+import '@polarityio/pi-error';
+```
+
+### Basic Error
+
+```html
+<pi-error open error-title="Error" message="An unexpected error occurred."></pi-error>
+```
+
+### No Title (Message-Only Header)
+
+When no `error-title` is provided, the message is displayed inline in the header row. This is useful for compact, single-line error alerts.
+
+```html
+<pi-error open message="Something went wrong. Please try again."></pi-error>
+```
+
+### With an Error Object
+
+When an `error` object is provided, the component resolves the message automatically:
+
+1. If the error has a `detail` property, it is displayed as the message.
+2. Otherwise, if the error has a `message` property, that is displayed.
+
+The full error object is available in the expandable "View Details" section and can be copied to the clipboard.
+
+```javascript
+import { html } from 'lit';
+
+html`
+  <pi-error
+    open
+    error-title="Request Failed"
+    .error=${{
+      status: 500,
+      detail: 'The upstream service returned an invalid response.',
+      requestId: 'abc-123-def-456'
+    }}
+  ></pi-error>
+`;
+```
+
+### Explicit Message Override
+
+When both a `message` property and an `error` object are provided, the explicit `message` takes priority over the error's `detail` or `message` fields.
+
+```javascript
+import { html } from 'lit';
+
+html`
+  <pi-error
+    open
+    error-title="API Error"
+    message="This explicit message overrides the error object."
+    .error=${{ detail: 'Original detail', status: 403 }}
+  ></pi-error>
+`;
+```
+
+### Warning Variant
+
+```html
+<pi-error
+  open
+  variant="warning"
+  error-title="Warning"
+  message="This action may have unintended consequences."
+></pi-error>
+```
+
+### Custom Prefix Icon
+
+```javascript
+import { html } from 'lit';
+import { faBug } from '@fortawesome/free-solid-svg-icons';
+
+html`
+  <pi-error open error-title="Bug Detected" message="An internal error was detected." .prefixIcon=${faBug}></pi-error>
+`;
+```
+
+### No Prefix Icon
+
+Set `prefixIcon` to `null` to hide the icon entirely.
+
+```javascript
+import { html } from 'lit';
+
+html` <pi-error open error-title="Error" message="No icon displayed." .prefixIcon=${null}></pi-error> `;
+```
+
+### No Title and No Icon
+
+Combine both to show a minimal message-only alert with no icon.
+
+```javascript
+import { html } from 'lit';
+
+html` <pi-error open message="Something went wrong. Please try again." .prefixIcon=${null}></pi-error> `;
+```
+
+## API Reference
+
+### Properties
+
+| Property     | Attribute     | Type                      | Default               | Description                                                                                                                                                            |
+| ------------ | ------------- | ------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`       | `open`        | `boolean`                 | `false`               | Controls the visibility of the error component.                                                                                                                        |
+| `variant`    | `variant`     | `'danger' \| 'warning'`   | `'danger'`            | Visual style variant. Controls background, border, and accent colors.                                                                                                  |
+| `errorTitle` | `error-title` | `string`                  | `''`                  | Title text displayed in the error header. Leave empty to show only the message in the header row.                                                                      |
+| `prefixIcon` | —             | `IconDefinition \| null`  | `faCircleExclamation` | FontAwesome icon displayed before the title. Set to `null` to hide.                                                                                                    |
+| `error`      | —             | `Record<string, unknown>` | `undefined`           | The error object. If it has a `detail` property, that is used as the message. Otherwise `message` is used. The full object is shown in the expandable details section. |
+| `message`    | `message`     | `string`                  | `''`                  | Explicit message text. Overrides any message derived from the error object.                                                                                            |
+
+### Events
+
+| Event Name                | Detail                  | Description                                              |
+| ------------------------- | ----------------------- | -------------------------------------------------------- |
+| `pi-error-close`          | `{}`                    | Fired when the close button is clicked.                  |
+| `pi-error-details-toggle` | `{ expanded: boolean }` | Fired when the details section is expanded or collapsed. |
+
+### CSS Custom Properties
+
+| Property                        | Default                         | Description                                             |
+| ------------------------------- | ------------------------------- | ------------------------------------------------------- |
+| `--pi-error-background`         | _(variant token)_               | Override the container background color.                |
+| `--pi-error-border-color`       | _(variant token)_               | Override the container border color.                    |
+| `--pi-error-border-radius`      | `var(--pi-size-radius-lg, 8px)` | Container border radius.                                |
+| `--pi-error-icon-size`          | `1em`                           | Title icon size.                                        |
+| `--pi-error-icon-color`         | _(variant token)_               | Override the title icon color.                          |
+| `--pi-error-title-color`        | _(variant token)_               | Override the title text color.                          |
+| `--pi-error-message-color`      | `var(--pi-color-font-primary)`  | Message text color.                                     |
+| `--pi-error-details-max-height` | `300px`                         | Maximum height of the details section before scrolling. |
+
+## Accessibility
+
+- The error container has `role="alert"` to announce content to screen readers.
+- The close button is a `pi-button` with `icon-only` and a `label` of "Close Error", providing full keyboard and screen reader accessibility.
+- The View Details / Hide Details button is a standard `pi-button` with visible text.
+- Copy button provides a "Copied error" success message.
+
+## Theming
+
+Customize the appearance using CSS custom properties or the `variant` property. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.
+
+The `danger` variant uses `--pi-color-*-danger` tokens and the `warning` variant uses `--pi-color-*-warning` tokens. You can override individual styles via the `--pi-error-*` CSS custom properties listed above.
+
+## License
+
+MIT

package/dist/component-registry.json

@@ -0,0 +1,7 @@
+{
+  "pi-error": {
+    "element": "pi-error-v1-0-0",
+    "className": "PiError",
+    "package": "@polarityio/pi-error"
+  }
+}

package/dist/error.d.ts

@@ -0,0 +1,54 @@
+import { LitElement, nothing } from 'lit';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+export declare const CUSTOM_ELEMENT_NAME: string;
+export type PiErrorVariant = 'danger' | 'warning';
+export interface PiErrorProps {
+    open: boolean;
+    variant: PiErrorVariant;
+    errorTitle: string;
+    prefixIcon: IconDefinition | null;
+    error?: Record<string, unknown>;
+    message: string;
+}
+/**
+ * An error alert component that displays error information with optional detail expansion and clipboard copy.
+ *
+ * @element pi-error
+ * @fires {CustomEvent} pi-error-close - Fired when the close button is clicked. detail: `{}`
+ * @fires {CustomEvent} pi-error-details-toggle - Fired when the details section is expanded or collapsed. detail: `{ expanded: boolean }`
+ * @cssproperty [--pi-error-background] - Override container background (defaults to variant token)
+ * @cssproperty [--pi-error-border-color] - Override container border color (defaults to variant token)
+ * @cssproperty [--pi-error-border-radius=var(--pi-size-radius-lg, 8px)] - Container border radius
+ * @cssproperty [--pi-error-icon-size=1em] - Title icon size
+ * @cssproperty [--pi-error-icon-color] - Override title icon color (defaults to variant token)
+ * @cssproperty [--pi-error-title-color] - Override title text color (defaults to variant token)
+ * @cssproperty [--pi-error-message-color=var(--pi-color-font-primary)] - Message text color
+ * @cssproperty [--pi-error-details-max-height=300px] - Maximum height of the details section before scrolling
+ */
+export declare class PiError extends LitElement {
+    /** Controls visibility of the error component. */
+    open: boolean;
+    /** Visual style variant. Controls background, border, and accent colors. */
+    variant: PiErrorVariant;
+    /** Title text displayed in the error header. Leave empty to show only the message in the header. */
+    errorTitle: string;
+    /** Icon displayed before the title. Defaults to exclamation-circle. Set to `null` to hide. */
+    prefixIcon: IconDefinition | null;
+    /**
+     * The error object to display. If the error has a `detail` property, it is shown as the message.
+     * Otherwise, if it has a `message` property, that is displayed. The full error object can be
+     * viewed in the expandable details section.
+     */
+    error?: Record<string, unknown>;
+    /**
+     * Explicit message text. When set, this overrides any message derived from the error object.
+     */
+    message: string;
+    private _detailsExpanded;
+    static styles: import('lit').CSSResult;
+    private get _displayMessage();
+    private get _errorString();
+    private _handleClose;
+    private _handleDetailsToggle;
+    render(): typeof nothing | import('lit').TemplateResult;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PiError, CUSTOM_ELEMENT_NAME } from './error.js';
+export type { PiErrorProps, PiErrorVariant } from './error.js';

package/dist/index.js

@@ -0,0 +1,268 @@
+import { css, LitElement, nothing } from "lit";
+import { property, state } from "lit/decorators.js";
+import { unsafeStatic, html } from "lit/static-html.js";
+import { faCircleExclamation, faXmark, faChevronUp, faChevronDown } from "@fortawesome/free-solid-svg-icons";
+import { libraryCustomElementName, defineCustomElementOnce } from "@polarityio/pi-shared";
+import { CUSTOM_ELEMENT_NAME as CUSTOM_ELEMENT_NAME$1, PiIcon } from "@polarityio/pi-icon";
+import { CUSTOM_ELEMENT_NAME as CUSTOM_ELEMENT_NAME$2, PiButton } from "@polarityio/pi-button";
+import { CUSTOM_ELEMENT_NAME as CUSTOM_ELEMENT_NAME$3, PiCopyButton } from "@polarityio/pi-copy-button";
+const version = "1.0.0";
+const packageJson = {
+  version
+};
+const errorStyles = css`
+  :host {
+    display: block;
+    font-family: var(--pi-font-family-base, 'NotoSans', sans-serif);
+    font-size: var(--pi-size-font-base, 0.8125rem);
+    color: var(--pi-color-font-primary, #e2e3ea);
+
+    /* Variant tokens — components reference these, variants override them */
+    --_pi-error-accent: var(--pi-color-font-danger);
+    --_pi-error-bg: var(--pi-color-background-container-danger);
+    --_pi-error-border: var(--pi-color-border-danger);
+  }
+
+  :host([hidden]) {
+    display: none !important;
+  }
+
+  /* ── Variant overrides ── */
+
+  :host([variant='danger']) {
+    --_pi-error-accent: var(--pi-color-font-danger);
+    --_pi-error-bg: var(--pi-color-background-container-danger);
+    --_pi-error-border: var(--pi-color-border-danger);
+  }
+
+  :host([variant='warning']) {
+    --_pi-error-accent: var(--pi-color-font-warning);
+    --_pi-error-bg: var(--pi-color-background-container-warning);
+    --_pi-error-border: var(--pi-color-border-warning);
+  }
+
+  /* ── Layout ── */
+
+  .error-container {
+    background: var(--pi-error-background, var(--_pi-error-bg));
+    border: 1px solid var(--pi-error-border-color, var(--_pi-error-border));
+    border-radius: var(--pi-error-border-radius, var(--pi-size-radius-lg, 8px));
+    padding: var(--pi-size-spacing-md, 0.75rem);
+    display: flex;
+    flex-direction: column;
+    gap: var(--pi-size-spacing-sm, 0.5rem);
+  }
+
+  .header {
+    display: flex;
+    align-items: center;
+    gap: var(--pi-size-spacing-sm, 0.5rem);
+  }
+
+  .title-icon {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+    --pi-icon-size: var(--pi-error-icon-size, 1em);
+    --pi-icon-color: var(--pi-error-icon-color, var(--_pi-error-accent));
+  }
+
+  .title-content {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .title {
+    font-family: var(--pi-font-family-base, 'NotoSans', sans-serif);
+    font-size: var(--pi-size-font-sm, 0.875rem);
+    font-weight: var(--pi-font-weight-bold, 700);
+    color: var(--pi-error-title-color, var(--_pi-error-accent));
+    line-height: 1.3;
+    margin: 0;
+  }
+
+  .close-button {
+    flex-shrink: 0;
+    margin-left: auto;
+    --pi-button-icon-color: var(--pi-color-font-secondary, #9ba1b0);
+  }
+
+  .message {
+    color: var(--pi-error-message-color, var(--pi-color-font-primary, #e2e3ea));
+    font-size: var(--pi-size-font-base, 0.8125rem);
+    line-height: 1.5;
+    margin: 0;
+  }
+
+  .actions {
+    display: flex;
+    align-items: center;
+    gap: var(--pi-size-spacing-sm, 0.5rem);
+    margin-top: var(--pi-size-spacing-xs, 0.25rem);
+  }
+
+  .details {
+    background: var(--pi-color-background-application-1, #1e2330);
+    border: 1px solid var(--pi-color-border-container, #3a3f4b);
+    border-radius: var(--pi-size-radius-base, 4px);
+    padding: var(--pi-size-spacing-sm, 0.5rem) var(--pi-size-spacing-md, 0.75rem);
+    margin-top: var(--pi-size-spacing-xs, 0.25rem);
+    overflow: auto;
+    max-height: var(--pi-error-details-max-height, 300px);
+  }
+
+  .details pre {
+    margin: 0;
+    font-family: var(--pi-font-family-mono, 'Courier New', monospace);
+    font-size: var(--pi-size-font-xs, 0.75rem);
+    color: var(--pi-color-font-secondary, #9ba1b0);
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+`;
+var __defProp = Object.defineProperty;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = void 0;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(target, key, result) || result;
+  if (result) __defProp(target, key, result);
+  return result;
+};
+const CUSTOM_ELEMENT_NAME = libraryCustomElementName("error", packageJson.version);
+defineCustomElementOnce(CUSTOM_ELEMENT_NAME$1, PiIcon);
+defineCustomElementOnce(CUSTOM_ELEMENT_NAME$2, PiButton);
+defineCustomElementOnce(CUSTOM_ELEMENT_NAME$3, PiCopyButton);
+const iconTag = unsafeStatic(CUSTOM_ELEMENT_NAME$1);
+const buttonTag = unsafeStatic(CUSTOM_ELEMENT_NAME$2);
+const copyButtonTag = unsafeStatic(CUSTOM_ELEMENT_NAME$3);
+const _PiError = class _PiError extends LitElement {
+  constructor() {
+    super(...arguments);
+    this.open = false;
+    this.variant = "danger";
+    this.errorTitle = "";
+    this.prefixIcon = faCircleExclamation;
+    this.message = "";
+    this._detailsExpanded = false;
+    this._handleClose = () => {
+      this.open = false;
+      this.dispatchEvent(
+        new CustomEvent("pi-error-close", {
+          detail: {},
+          bubbles: true,
+          composed: true
+        })
+      );
+    };
+    this._handleDetailsToggle = () => {
+      this._detailsExpanded = !this._detailsExpanded;
+      this.dispatchEvent(
+        new CustomEvent("pi-error-details-toggle", {
+          detail: { expanded: this._detailsExpanded },
+          bubbles: true,
+          composed: true
+        })
+      );
+    };
+  }
+  get _displayMessage() {
+    if (this.message) return this.message;
+    if (!this.error) return "";
+    if (typeof this.error.detail === "string") return this.error.detail;
+    if (typeof this.error.message === "string") return this.error.message;
+    return "";
+  }
+  get _errorString() {
+    if (!this.error) return "";
+    try {
+      return JSON.stringify(this.error, null, 2);
+    } catch {
+      return "[Unable to serialize error]";
+    }
+  }
+  render() {
+    if (!this.open) return nothing;
+    const displayMessage = this._displayMessage;
+    const errorString = this._errorString;
+    const hasError = !!this.error;
+    return html`
+      <div class="error-container" role="alert">
+        <div class="header">
+          ${this.prefixIcon ? html`
+          <span class="title-icon">
+            <${iconTag} .icon=${this.prefixIcon}></${iconTag}>
+          </span>
+          ` : nothing}
+          <div class="title-content">
+            ${this.errorTitle ? html`<h2 class="title">${this.errorTitle}</h2>` : displayMessage ? html`<p class="message">${displayMessage}</p>` : nothing}
+          </div>
+          <${buttonTag}
+            class="close-button"
+            type="tertiary"
+            icon-only
+            condensed
+            .prefixIcon=${faXmark}
+            label="Close Error"
+            @pi-click=${this._handleClose}
+          ></${buttonTag}>
+        </div>
+
+        ${this.errorTitle && displayMessage ? html`<p class="message">${displayMessage}</p>` : nothing}
+
+        ${hasError ? html`
+          <div class="actions">
+            <${buttonTag}
+              type="tertiary"
+              condensed
+              .prefixIcon=${this._detailsExpanded ? faChevronUp : faChevronDown}
+              @pi-click=${this._handleDetailsToggle}
+            >
+              ${this._detailsExpanded ? "Hide Details" : "View Details"}
+            </${buttonTag}>
+            <${copyButtonTag}
+              .copyData=${errorString}
+              button-type="tertiary"
+              button-text=""
+              condensed
+              success-message="Copied error"
+            ></${copyButtonTag}>
+          </div>
+        ` : nothing}
+
+        ${this._detailsExpanded && hasError ? html`
+          <div class="details">
+            <pre>${errorString}</pre>
+          </div>
+        ` : nothing}
+      </div>
+    `;
+  }
+};
+_PiError.styles = errorStyles;
+let PiError = _PiError;
+__decorateClass([
+  property({ type: Boolean, reflect: true })
+], PiError.prototype, "open");
+__decorateClass([
+  property({ type: String, reflect: true })
+], PiError.prototype, "variant");
+__decorateClass([
+  property({ type: String, attribute: "error-title" })
+], PiError.prototype, "errorTitle");
+__decorateClass([
+  property({ attribute: false })
+], PiError.prototype, "prefixIcon");
+__decorateClass([
+  property({ attribute: false })
+], PiError.prototype, "error");
+__decorateClass([
+  property({ type: String })
+], PiError.prototype, "message");
+__decorateClass([
+  state()
+], PiError.prototype, "_detailsExpanded");
+export {
+  CUSTOM_ELEMENT_NAME,
+  PiError
+};

package/dist/styles/error.d.ts

@@ -0,0 +1 @@
+export declare const errorStyles: import('lit').CSSResult;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@polarityio/pi-error",
+  "version": "1.0.0",
+  "description": "Error alert component with dismissible behavior, detail expansion, and clipboard copy support",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polarityio/integration-component-library.git",
+    "directory": "packages/error"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./component-registry.json": "./dist/component-registry.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fortawesome/fontawesome-svg-core": "^7.0.0",
+    "@fortawesome/free-solid-svg-icons": "^7.0.0",
+    "@polarityio/pi-shared": "1.0.3",
+    "@polarityio/pi-icon": "1.0.3",
+    "@polarityio/pi-button": "1.0.4",
+    "@polarityio/pi-copy-button": "1.0.4"
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  }
+}