@odx/assets-utils

The @odx/assets-utils library provides utility functions, types, and base classes for managing and rendering assets (such as icons) in the ODX ecosystem. It includes a global asset registry, subscription hooks, and a Web Component base class for custom asset elements.

Installation

Install the library via npm:

npm i @odx/assets-utils

Core Concepts

Asset Registry

Assets are stored in a global registry and identified by a unique ID in the format: namespace::set::name

• namespace: The asset namespace (e.g., odx-icon, odx-pictogram)
• set: The asset set/category (e.g., core, medical, safety)
• name: The individual asset name (e.g., user, alarm)

Asset Format

Each asset contains:

• id: Unique identifier
• content: SVG string (required for rendering)
• metadata: Optional tags, description (used by tooling, not required at runtime)

Usage

Creating a Custom Asset Element

Extend OdxAssetElement to create a Web Component for rendering assets:

import { OdxAssetElement } from '@odx/assets-utils/element';

class OdxIconElement extends OdxAssetElement {
  static override defaultSet: string = 'core';
  readonly namespace = 'odx-icon';
}

customElements.define('odx-icon', OdxIconElement);

Then use it in HTML:

<odx-icon name="core::user"></odx-icon>
<odx-icon name="safety::alarm"></odx-icon>

Registering Assets

Assets can be registered programmatically:

import { registerAsset, registerAssetMetadata } from '@odx/assets-utils';

// Register SVG content
registerAsset('odx-icon::core::user', '<svg>...</svg>');

// Register metadata (optional, used by documentation tools)
registerAssetMetadata('odx-icon::core::user', {
  description: 'A simple user icon',
  tags: ['people', 'person', 'profile'],
});

Retrieving Assets

import { getAsset, getAssets } from '@odx/assets-utils';

// Get a single asset
const userIcon = getAsset('odx-icon::core::user');
console.log(userIcon.content); // SVG string

// Get all assets in a set
const coreIcons = getAssets({ namespace: 'odx-icon', set: 'core' });

// Get all assets in a namespace
const allIcons = getAssets({ namespace: 'odx-icon' });

Setting Asset Aliases

import { setAssetAlias } from '@odx/assets-utils';

// Create an alias for an existing asset
setAssetAlias('odx-icon::core::user', 'odx-icon::core::profile');

Subscribing to Asset Updates

Use useAsset to subscribe to asset changes:

import { useAsset } from '@odx/assets-utils';

const unsubscribe = useAsset('odx-icon::core::user', (asset) => {
  console.log('Asset updated:', asset);
});

// Cleanup when done
unsubscribe?.();

Parsing SVG

Parse an SVG string into an SVG DOM element:

import { parseSvg } from '@odx/assets-utils';

const svgElement = parseSvg('<svg viewBox="0 0 24 24"><path.../></svg>');
document.body.appendChild(svgElement);

Generating Asset HTML

Generate the HTML code snippet for an asset:

import { assetCode } from '@odx/assets-utils';

const code = assetCode(userIcon);
// Returns: <odx-icon name="core::user"></odx-icon>