@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 base class for custom asset elements.

Installation

Install using NPM:

npm i @odx/assets-utils

Install using PNPM:

pnpm add @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

Usage

Create a custom element for an asset

Extend OdxAssetElement to create a custom element for rendering assets:

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

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 } from '@odx/assets-utils';

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

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 aAsset aliases

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

// Create an alias for an existing asset
registerAsset('odx-icon::core::user', getAsset('odx-icon::core::profile').content);

Subscribing to asset updates

Use the useAsset hook 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?.();

Resolve an asset ID

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

const assetId = resolveAssetId('odx-icon', 'core', 'user');
console.log(assetId); // 'odx-icon::core::user'

Create a Blob from an asset

import { assetToBlob } from '@odx/assets-utils';
import userIcon from '@odx/icons/core/user';

const assetBlob = await assetToBlob(userIcon);

Parse SVG (browser only)

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);

Create HTML code snippet for an asset

Generate the HTML code snippet for an asset:

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

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

Generate the SSR HTML code snippet for an asset:

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

const code = assetCode(userIcon, `<template shadowrootmode="open">${userIcon.content}</template>`);