@hsuite/native-connect-angular 1.0.0 → 2.1.1

package/src/lib/utils/ledger-icons.util.ts

@@ -8,70 +8,101 @@
  * visit https://hsuite.finance/licensing
  */
 
+import { LedgerUIRegistry } from './ledger-ui-registry';
+
 /**
  * @module LedgerIconsUtil
- * Utilities for getting default icon URLs for ledgers and their native tokens.
  *
- * Uses CoinGecko's public CDN for reliable, high-quality token icons.
- * Shared across wallet and dApp for consistency.
+ * Backward-compatible facade over {@link LedgerUIRegistry}.
+ *
+ * Every value here is **derived from the registry** so there is exactly one
+ * source of truth for ledger presentation. New code should prefer
+ * {@link LedgerUIRegistry} directly (it is open/extensible and richer); these
+ * getters and constant maps remain for the existing public API surface.
+ *
+ * The constant maps below are snapshots taken at module load — they include the
+ * built-in ledgers (Hedera, XRPL). Ledgers registered later at runtime are
+ * always reachable through the getters and {@link LedgerUIRegistry}, but will
+ * not retroactively appear in these legacy snapshots; prefer the registry when
+ * extensibility matters.
+ */
+
+/**
+ * Default raster icon URLs for native ledger tokens, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.tokenIconUrl}.
  */
+export const DEFAULT_LEDGER_ICONS: Record<string, string> = Object.fromEntries(
+  LedgerUIRegistry.list()
+    .filter((descriptor) => descriptor.tokenIconUrl)
+    .map((descriptor) => [descriptor.id, descriptor.tokenIconUrl as string]),
+);
 
 /**
- * Default icon URLs for native ledger tokens
+ * Brand colours (hex) for each ledger, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.brandColor}.
  */
-export const DEFAULT_LEDGER_ICONS: Record<string, string> = {
-  hedera: 'https://assets.coingecko.com/coins/images/3688/standard/hbar.png?1696504364',
-  xrpl: 'https://assets.coingecko.com/coins/images/44/standard/xrp-symbol-white-128.png?1696501442',
-};
+export const LEDGER_COLORS: Record<string, string> = Object.fromEntries(
+  LedgerUIRegistry.list().map((descriptor) => [descriptor.id, descriptor.brandColor]),
+);
 
 /**
- * Brand colors for each ledger
+ * Display names for each ledger, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.displayName}.
  */
-export const LEDGER_COLORS: Record<string, string> = {
-  hedera: '#8259ef',
-  xrpl: '#23292f',
-};
+export const LEDGER_NAMES: Record<string, string> = Object.fromEntries(
+  LedgerUIRegistry.list().map((descriptor) => [descriptor.id, descriptor.displayName]),
+);
 
 /**
- * Display names for each ledger
+ * Ionicons names under which each ledger's brand SVG is registered, keyed by
+ * ledger id. Reference these from `<ion-icon [name]="...">`.
+ * Derived from {@link LedgerUiDescriptor.iconName}.
  */
-export const LEDGER_NAMES: Record<string, string> = {
-  hedera: 'Hedera',
-  xrpl: 'XRP Ledger',
-};
+export const LEDGER_ICON_NAMES: Record<string, string> = Object.fromEntries(
+  LedgerUIRegistry.list().map((descriptor) => [descriptor.id, descriptor.iconName]),
+);
+
+/**
+ * Register the ledger brand SVGs with Ionicons so they can be referenced by name
+ * (see {@link LEDGER_ICON_NAMES}). Idempotent; safe to call from multiple
+ * consumers. Delegates to {@link LedgerUIRegistry.registerIcons}.
+ */
+export function registerLedgerIcons(): void {
+  LedgerUIRegistry.registerIcons();
+}
 
 /**
- * Get the default icon URL for a ledger
- * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
- * @returns Icon URL or empty string if not found
+ * Get the default raster token icon URL for a ledger.
+ * @param ledgerId - Ledger identifier (e.g. `'hedera'`, `'xrpl'`)
+ * @returns Icon URL, or empty string if the ledger has none.
  */
 export function getLedgerIcon(ledgerId: string): string {
-  return DEFAULT_LEDGER_ICONS[ledgerId?.toLowerCase()] || '';
+  return LedgerUIRegistry.get(ledgerId?.toLowerCase())?.tokenIconUrl ?? '';
 }
 
 /**
- * Get the brand color for a ledger
+ * Get the brand colour (hex) for a ledger.
  * @param ledgerId - Ledger identifier
- * @returns Hex color string or primary color fallback
+ * @returns Hex colour string, or the Ionic primary CSS variable as fallback.
  */
 export function getLedgerColor(ledgerId: string): string {
-  return LEDGER_COLORS[ledgerId?.toLowerCase()] || 'var(--ion-color-primary)';
+  return LedgerUIRegistry.get(ledgerId?.toLowerCase())?.brandColor ?? 'var(--ion-color-primary)';
 }
 
 /**
- * Get the display name for a ledger
+ * Get the display name for a ledger.
  * @param ledgerId - Ledger identifier
- * @returns Human-readable ledger name
+ * @returns Human-readable ledger name, or the raw id if unknown.
  */
 export function getLedgerName(ledgerId: string): string {
-  return LEDGER_NAMES[ledgerId?.toLowerCase()] || ledgerId;
+  return LedgerUIRegistry.get(ledgerId?.toLowerCase())?.displayName ?? ledgerId;
 }
 
 /**
- * Get token icon URL, falling back to ledger default if not provided
+ * Get a token icon URL, falling back to the ledger default if not provided.
  * @param tokenIconUrl - Specific token icon URL (optional)
  * @param ledgerId - Ledger identifier for fallback
- * @returns Icon URL or empty string
+ * @returns Icon URL, or empty string.
  */
 export function getTokenIcon(tokenIconUrl: string | undefined, ledgerId: string): string {
   return tokenIconUrl || getLedgerIcon(ledgerId);

package/src/lib/utils/ledger-ui-registry.ts

@@ -0,0 +1,197 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+import type { LedgerId } from '@hsuite/native-connect-types';
+import { addIcons } from 'ionicons';
+
+/**
+ * @module LedgerUiRegistry
+ *
+ * Single source of truth for **how a ledger is presented** in the Angular SDK —
+ * its display name, native currency, brand colours, and brand icon.
+ *
+ * ## Why a registry
+ *
+ * The core SDK keys everything off the canonical, open {@link LedgerId} type
+ * (`z.string().min(1)` in `@hsuite/native-connect-types`) and discovers chains
+ * dynamically via `WalletCore.registerLedger(adapter)` / `LedgerRegistry`. This
+ * registry mirrors that pattern for the **presentation layer**: ledgers are
+ * registered, not hard-coded into closed `'hedera' | 'xrpl'` maps. Adding a new
+ * chain is a single {@link LedgerUIRegistry.register} call — no union to widen,
+ * no scattered `Record<>` literals to keep in sync.
+ *
+ * Presentation lives in the presentation package (this Angular SDK) so the core
+ * SDK stays headless: the descriptor carries the framework-agnostic data plus
+ * the Ionic-specific icon binding ({@link LedgerUiDescriptor.iconName} /
+ * {@link LedgerUiDescriptor.iconSvg}) that `<ion-icon>` renders.
+ *
+ * @see {@link LedgerUiDescriptor} for the per-ledger contract.
+ * @see `docs/guides/adding-a-new-chain.md` for the end-to-end "add a chain" flow.
+ */
+
+/**
+ * Presentation contract for one ledger.
+ *
+ * Keyed by the canonical {@link LedgerId} (open `string`) so the registry is
+ * extensible to any number of chains. Built-in ledgers are registered at module
+ * load; first-party chains add a descriptor here, third-party/plugin chains call
+ * {@link LedgerUIRegistry.register} at runtime.
+ */
+export interface LedgerUiDescriptor {
+  /** Canonical ledger identity, e.g. `'hedera'`, `'xrpl'` (see {@link LedgerId}). */
+  readonly id: LedgerId;
+  /** Full human-readable name, e.g. `'Hedera'`, `'XRP Ledger'`. */
+  readonly displayName: string;
+  /** Compact name for badges/dense surfaces, e.g. `'Hedera'`, `'XRPL'`. */
+  readonly shortName: string;
+  /** Native currency ticker, e.g. `'HBAR'`, `'XRP'`. */
+  readonly currencySymbol: string;
+  /** Native currency decimal places, e.g. `8` (Hedera), `6` (XRPL). */
+  readonly currencyDecimals: number;
+  /** Brand colour as a hex string, used for CSS accents, e.g. `'#8259ef'`. */
+  readonly brandColor: string;
+  /** Ionic semantic colour name for `<ion-badge color="...">`, e.g. `'success'`. */
+  readonly badgeColor: string;
+  /**
+   * Ionicons name under which {@link iconSvg} is registered, e.g.
+   * `'ledger-hedera'`. Reference it from `<ion-icon [name]="...">`. The SVG is
+   * flushed to Ionicons by {@link LedgerUIRegistry.registerIcons}.
+   */
+  readonly iconName: string;
+  /**
+   * Self-contained brand SVG markup. Inlined (rather than shipped as an asset
+   * file) so the packaged library needs no runtime asset pipeline or external
+   * CDN. `currentColor` fills inherit the host `<ion-icon>` colour; explicit
+   * fills are preserved.
+   */
+  readonly iconSvg: string;
+  /**
+   * Optional CDN URL for a raster icon of the native token, used as a fallback
+   * when an inline brand SVG is not the right surface (e.g. token lists).
+   */
+  readonly tokenIconUrl?: string;
+}
+
+/**
+ * Open, string-keyed registry of {@link LedgerUiDescriptor}s.
+ *
+ * A static registry (like `AccountLabelManager`) because ledger presentation is
+ * process-global — Ionicons' own icon table is global too. Mirrors the core
+ * `LedgerRegistry` shape (`register` / `get` / `has` / `list`) so the two read
+ * the same way.
+ */
+export class LedgerUIRegistry {
+  private static readonly descriptors = new Map<LedgerId, LedgerUiDescriptor>();
+
+  /** Whether {@link registerIcons} has already flushed SVGs to Ionicons. */
+  private static iconsFlushed = false;
+
+  /**
+   * Register (or replace) the presentation descriptor for a ledger.
+   *
+   * If icons were already flushed to Ionicons (i.e. {@link registerIcons} ran),
+   * the new ledger's SVG is registered immediately so late registrations still
+   * render.
+   *
+   * @param descriptor - The ledger's presentation contract.
+   */
+  static register(descriptor: LedgerUiDescriptor): void {
+    LedgerUIRegistry.descriptors.set(descriptor.id, descriptor);
+    if (LedgerUIRegistry.iconsFlushed) {
+      addIcons({ [descriptor.iconName]: descriptor.iconSvg });
+    }
+  }
+
+  /**
+   * Look up a ledger's presentation descriptor.
+   *
+   * @param ledgerId - Canonical ledger id (case-sensitive; callers normalise).
+   * @returns The descriptor, or `undefined` if the ledger is not registered.
+   */
+  static get(ledgerId: LedgerId): LedgerUiDescriptor | undefined {
+    return LedgerUIRegistry.descriptors.get(ledgerId);
+  }
+
+  /**
+   * @param ledgerId - Canonical ledger id.
+   * @returns `true` if a descriptor is registered for `ledgerId`.
+   */
+  static has(ledgerId: LedgerId): boolean {
+    return LedgerUIRegistry.descriptors.has(ledgerId);
+  }
+
+  /**
+   * @returns All registered descriptors, in registration order.
+   */
+  static list(): LedgerUiDescriptor[] {
+    return Array.from(LedgerUIRegistry.descriptors.values());
+  }
+
+  /**
+   * Flush every registered ledger's brand SVG to Ionicons so the icons resolve
+   * by name from `<ion-icon>`. Idempotent and cheap to call repeatedly — call it
+   * before the icons are first rendered (e.g. from a component constructor or
+   * once at app bootstrap).
+   */
+  static registerIcons(): void {
+    if (LedgerUIRegistry.iconsFlushed) {
+      return;
+    }
+
+    const icons: Record<string, string> = {};
+    for (const descriptor of LedgerUIRegistry.descriptors.values()) {
+      icons[descriptor.iconName] = descriptor.iconSvg;
+    }
+
+    addIcons(icons);
+    LedgerUIRegistry.iconsFlushed = true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Built-in ledgers
+//
+// The only place the first-party ledger set is enumerated. Adding a new
+// first-party chain is one more `register(...)` here; everything downstream
+// (icons, colours, names, the connection modal's "Choose Blockchain" step)
+// derives from these descriptors.
+// ---------------------------------------------------------------------------
+
+LedgerUIRegistry.register({
+  id: 'hedera',
+  displayName: 'Hedera',
+  shortName: 'Hedera',
+  currencySymbol: 'HBAR',
+  currencyDecimals: 8,
+  brandColor: '#8259ef',
+  badgeColor: 'success',
+  iconName: 'ledger-hedera',
+  // Brand disc themed with `brandColor` (#8259ef) + a white "H" so the mark stays
+  // brand-correct and legible on any background (incl. the dark modal card).
+  iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><g fill="none"><path fill="#8259ef" d="M12 4a8 8 0 1 0 0 16a8 8 0 0 0 0-16"/><path fill="#fff" d="M15.252 15.46h-1.016V13.3H9.764v2.16H8.748V8.456h1.016v2.108h4.472V8.456h1.016zm-5.44-2.968h4.472v-1.116H9.812z"/></g></svg>`,
+  tokenIconUrl: 'https://assets.coingecko.com/coins/images/3688/standard/hbar.png?1696504364',
+});
+
+LedgerUIRegistry.register({
+  id: 'xrpl',
+  displayName: 'XRP Ledger',
+  shortName: 'XRPL',
+  currencySymbol: 'XRP',
+  currencyDecimals: 6,
+  brandColor: '#23292f',
+  badgeColor: 'tertiary',
+  iconName: 'ledger-xrpl',
+  // `currentColor` so the mark adopts the host `<ion-icon>` colour — the XRPL
+  // brand black (#23292f) is invisible on the dark modal card, so the icon
+  // inherits the theme colour while `brandColor` stays the canonical accent.
+  iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M21.778 4h-2.837l-4.49 4.371a3.52 3.52 0 0 1-2.451.99a3.52 3.52 0 0 1-2.452-.99L5.062 4h-2.84L8.13 9.754c2.14 2.083 5.607 2.083 7.745 0zM2.223 20H5.05l4.508-4.385a3.5 3.5 0 0 1 2.443-.985c.914 0 1.792.354 2.443.985L18.952 20h2.826l-5.92-5.761c-2.132-2.073-5.585-2.073-7.715 0z"/></svg>`,
+  tokenIconUrl:
+    'https://assets.coingecko.com/coins/images/44/standard/xrp-symbol-white-128.png?1696501442',
+});