chore: 🤖 support asset aliases with centralised resolver configuration

.changeset/dirty-facts-hammer.md

@@ -0,0 +1,33 @@
+---
+'@clickhouse/click-ui': minor
+---
+
+Introduces a centralised asset configuration with unified aliases and deprecated name mappings. This provides a single source of truth for asset name resolution across all asset types (Icons, Logos, Flags, and Payments), helping to resolve circular dependencies while offering a flexible aliasing system.
+
+### Why aliases?
+
+Asset naming conventions use kebab-case (e.g., `c-sharp`, `arrow-down`) to facilitate file organisation and ensure valid JavaScript identifiers. However, users may prefer more intuitive names that don't follow these conventions. Aliases bridge this gap.
+
+For example, `c#` contains a `#` character which is not a valid JavaScript identifier, but users might still prefer using `c#` over `c-sharp`.
+
+### How to use aliases
+
+Aliases are defined in `src/components/Assets/config.ts` under `ASSET_NAME_MAPPINGS.aliases`:
+
+```tsx
+export const ASSET_NAME_MAPPINGS = {
+  aliases: {
+    'c#': 'c-sharp',
+    // Add more aliases as needed
+  } as AssetAliasMap,
+  // ...
+};
+```
+
+The alias is then automatically resolved when using any asset component:
+
+```tsx
+// Both of these work identically:
+<Logo name="c#" />
+<Logo name="c-sharp" />
+```

src/components/Assets/Flags/system/Flag.tsx

@@ -2,12 +2,24 @@
 import { useTheme } from 'styled-components';
 import { getFallbackThemeName } from '@/theme/theme.utils';
 import { SvgImageElement } from '@/components/Icon/SvgImageElement';
-import { FlagProps } from './types';
-import { resolveFlagName } from './retroactiveNames';
+import { FlagName, FlagProps } from './types';
+import {
+  createAssetResolver,
+  type AssetAlias,
+  type AssetDeprecatedName,
+} from '@/components/Assets/config';
 import FlagsDark from './FlagsDark';
 import FlagsLight from './FlagsLight';
 
-const Flag = ({ name, theme, size, ...props }: FlagProps) => {
+const resolveFlagName = createAssetResolver<FlagName>();
+
+export { resolveFlagName };
+
+export interface FlagPropsWithAliases extends Omit<FlagProps, 'name'> {
+  name: FlagName | AssetAlias | AssetDeprecatedName;
+}
+
+const Flag = ({ name, theme, size, ...props }: FlagPropsWithAliases) => {
   const { name: themeName } = useTheme();
   const resolvedName = resolveFlagName(name);
   const resolvedTheme = getFallbackThemeName(theme ?? themeName);

src/components/Assets/Flags/system/FlagsDark.ts

@@ -30,7 +30,7 @@ import { FlagName } from './types';
 import type { SVGAssetProps } from '@/types';
 import type { ComponentType } from 'react';
 
-const FlagsLight: Record<FlagName, ComponentType<SVGAssetProps>> = {
+const FlagsDark: Record<FlagName, ComponentType<SVGAssetProps>> = {
   australia: Australia,
   brazil: Brazil,
   canada: Canada,
@@ -54,4 +54,4 @@ const FlagsLight: Record<FlagName, ComponentType<SVGAssetProps>> = {
   'united-states': United_States,
 };
 
-export default FlagsLight;
+export default FlagsDark;

src/components/Assets/Icons/system/Icon.tsx

@@ -1,13 +1,25 @@
 import { SVGAttributes } from 'react';
 import { useTheme } from 'styled-components';
 import { getFallbackThemeName } from '@/theme/theme.utils';
-import { resolveIconName } from './retroactiveNames';
-import IconsLight from './IconsLight';
-import IconsDark from './IconsDark';
 import { SvgImageElement } from '@/components/Icon/SvgImageElement';
-import { IconProps } from './types';
+import { IconName, IconProps } from './types';
+import {
+  createAssetResolver,
+  type AssetAlias,
+  type AssetDeprecatedName,
+} from '@/components/Assets/config';
+import IconsDark from './IconsDark';
+import IconsLight from './IconsLight';
+
+const resolveIconName = createAssetResolver<IconName>();
+
+export { resolveIconName };
+
+export interface IconPropsWithAliases extends Omit<IconProps, 'name'> {
+  name: IconName | AssetAlias | AssetDeprecatedName;
+}
 
-const Icon = ({ name, theme, size, ...props }: IconProps) => {
+const Icon = ({ name, theme, size, ...props }: IconPropsWithAliases) => {
   const { name: themeName } = useTheme();
   const resolvedName = resolveIconName(name);
   const resolvedTheme = getFallbackThemeName(theme ?? themeName);

src/components/Assets/Logos/system/Logo.tsx

@@ -3,21 +3,23 @@
 import { getFallbackThemeName } from '@/theme/theme.utils';
 import { SvgImageElement } from '@/components/Icon/SvgImageElement';
 import { LogoName, LogoProps } from './types';
+import {
+  createAssetResolver,
+  type AssetAlias,
+  type AssetDeprecatedName,
+} from '@/components/Assets/config';
 import LogosDark from './LogosDark';
 import LogosLight from './LogosLight';
 
-// TODO: This is introducing complexity and more to maintain
-// might be best to just deprecate (break change) instead of
-// keeping deprecated names, it's small find and replace.
-const resolveLogoName = (name: string): LogoName => {
-  if (name === 'c#') {
-    console.warn('Logo name "c#" is deprecated, use "c-sharp" instead');
-    return 'c-sharp' as LogoName;
-  }
-  return name as LogoName;
-};
+const resolveLogoName = createAssetResolver<LogoName>();
+
+export { resolveLogoName };
+
+export interface LogoPropsWithAliases extends Omit<LogoProps, 'name'> {
+  name: LogoName | AssetAlias | AssetDeprecatedName;
+}
 
-const Logo = ({ name, theme, size, ...props }: LogoProps) => {
+const Logo = ({ name, theme, size, ...props }: LogoPropsWithAliases) => {
   const { name: themeName } = useTheme();
   const resolvedName = resolveLogoName(name);
   const resolvedTheme = getFallbackThemeName(theme ?? themeName);