@velicons/core 0.3.0 → 0.4.0

package/README.md

@@ -1,56 +1,54 @@
 # @velicons/core
 
-Canonical local registry data for Velicons tooling and the Velicons Docs showcase.
+Framework-neutral Velicons catalog and explicit canonical registry API.
 
-## Installation
+## Lightweight catalog
 
-```bash
-npm install @velicons/core
-```
+The package root is intentionally metadata-only. Normal tooling can import it without loading the full artwork/integration registry.
+
+```ts
+import { getIcons, getFlags, getLibrary } from "@velicons/core";
 
-```bash
-bun add @velicons/core
+const icons = getIcons();
+const flags = getFlags();
 ```
 
-## Usage
+The root catalog contains identity, naming, geometry, search metadata, provenance references, and generated slug/route information.
 
-The package contains the canonical registry as JSON. It does not fetch registry data from the network, so Velicons Docs can use the complete icon and flag registry offline after installation.
+## Full canonical registry
 
-### Icons
+Consumers that explicitly need canonical artwork or generated integration data can opt into the heavy registry API:
 
 ```ts
-import registry from "@velicons/core/icons/registry.json";
+import { getRegistry } from "@velicons/core/registry";
 
-const icon = registry.icons.find((item) => item.id === "...");
+const registry = getRegistry();
 ```
 
-### Flags
+The JSON representations are also exposed explicitly:
 
 ```ts
-import registry from "@velicons/core/flags/registry.json";
-
-const flag = registry.icons.find((item) => item.id === "...");
+import icons from "@velicons/core/icons/registry.json";
+import flags from "@velicons/core/flags/registry.json";
 ```
 
-Both registries are generated from the same canonical build cache. `generated.integrations` is preserved in each icon/flag entry, so the showcase can render the exact generated framework integrations without another build or network request.
-
-Artwork payloads are intentionally omitted from these showcase registries to avoid duplicating the SVG payload in the core package. The canonical metadata, geometry, provenance references, and generated integration data remain available locally.
+These full registries are generated from the same canonical source as the lightweight catalog. They are not imported by the package root.
 
 ## Package layout
 
 ```text
 @velicons/core
-├── jsons/
-│   ├── icons/registry.json
-│   ├── flags/registry.json
-│   ├── provenance.json
-│   └── country-provenance.json
-└── dist/
-    └── index.d.ts
+├── dist/
+│   ├── index.js             # lightweight catalog API
+│   ├── registry.js          # explicit full registry API
+│   └── full-registry.js     # explicit compatibility alias
+└── jsons/
+    ├── icons/catalog.json
+    ├── flags/catalog.json
+    ├── icons/registry.json
+    └── flags/registry.json
 ```
 
-The two registry JSON files are the primary data API for Velicons Docs.
-
 ## License
 
-The Velicons package source and generated integration code are distributed under the MIT License. Third-party icon artwork remains subject to its applicable upstream license. Individual icon provenance and licensing information are preserved in the registry metadata.
+The Velicons package source and generated integration code are distributed under the MIT License. Third-party icon artwork remains subject to its applicable upstream license. Individual icon provenance and licensing information are preserved in the canonical registry.

package/dist/full-registry.d.ts

@@ -0,0 +1 @@
+export * from "./registry.js";

package/dist/full-registry.js

@@ -0,0 +1 @@
+export * from "./registry.js";

package/dist/index.d.ts

@@ -1,3 +1,21 @@
-export * from "./registry.js";
-export { default as iconsRegistry } from "../jsons/icons/registry.json";
-export { default as flagsRegistry } from "../jsons/flags/registry.json";
+export interface LibraryLicense { name: string; spdx?: string; url?: string; }
+export interface LibraryMetadata { id: string; name: string; [key: string]: unknown; }
+export interface CanonicalGeometry { viewBox: string; width?: number; height?: number; }
+export interface CanonicalPresentation { color?: string; colorMode?: "monochrome" | "multicolor"; }
+export interface CanonicalIcon { id: string; name: string; title: string; family: "icon" | "flag"; set: string; variant: string; aliases?: string[]; categories?: string[]; tags?: string[]; geometry: CanonicalGeometry; presentation?: CanonicalPresentation; metadata?: Record<string, unknown>; generated?: { slug: string; route: string }; [key: string]: unknown; }
+export interface CanonicalIconSet extends LibraryMetadata { path: string; iconCount: number; }
+export interface CanonicalRegistry { version: number; libraries: CanonicalIconSet[]; icons: CanonicalIcon[]; }
+export type VeliconsCatalog = { version: number; icons: CanonicalRegistry; flags: CanonicalRegistry };
+export declare const getIcons: () => CanonicalIcon[];
+export declare const getFlags: () => CanonicalIcon[];
+export declare const getLibraries: () => CanonicalIconSet[];
+export declare const getIcon: (idOrSlug: string, slug?: string) => CanonicalIcon | undefined;
+export declare const getFlag: (idOrSlug: string, slug?: string) => CanonicalIcon | undefined;
+export declare const getIconById: (id: string) => CanonicalIcon | undefined;
+export declare const getFlagById: (id: string) => CanonicalIcon | undefined;
+export declare const getLibrary: (id: string) => CanonicalIconSet | undefined;
+export declare const getIconProp: (iconOrId: CanonicalIcon | string, prop: string) => unknown;
+export declare const getIconProps: (iconOrId: CanonicalIcon | string, props?: readonly string[]) => Record<string, unknown> | CanonicalIcon | undefined;
+export declare const getFlagProp: (flagOrId: CanonicalIcon | string, prop: string) => unknown;
+export declare const getFlagProps: (flagOrId: CanonicalIcon | string, props?: readonly string[]) => Record<string, unknown> | CanonicalIcon | undefined;
+export declare const getCatalog: () => VeliconsCatalog;

package/dist/index.js

@@ -1 +1,22 @@
-export { getRegistry, getIcons, getFlags, getIcon, getFlag, getIconById, getFlagById, getLibrary, getIconProp, getIconProps, getFlagProp, getFlagProps, iconsRegistry, flagsRegistry } from "./registry.js";
+import iconsCatalog from "../jsons/icons/catalog.json" with { type: "json" };
+import flagsCatalog from "../jsons/flags/catalog.json" with { type: "json" };
+const icons = iconsCatalog.icons;
+const flags = flagsCatalog.icons;
+const decode = (value) => { try { return decodeURIComponent(value); } catch { return value; } };
+const slugOf = (entity) => entity.generated?.slug ?? entity.name;
+const find = (items, a, b) => { const first = decode(a); if (b === undefined) return items.find((entity) => entity.id === first || slugOf(entity) === first || entity.name === first); const second = decode(b); return items.find((entity) => entity.set === first && (entity.id === second || slugOf(entity) === second || entity.name === second)); };
+export const getIcons = () => icons;
+export const getFlags = () => flags;
+export const getLibraries = () => iconsCatalog.libraries;
+export const getIcon = (a, b) => find(icons, a, b);
+export const getFlag = (a, b) => find(flags, a, b);
+export const getIconById = (id) => icons.find((icon) => icon.id === id);
+export const getFlagById = (id) => flags.find((flag) => flag.id === id);
+export const getLibrary = (id) => [...iconsCatalog.libraries, ...flagsCatalog.libraries].find((library) => library.id === id);
+const resolve = (value, items) => value && typeof value === "object" ? value : find(items, value);
+const read = (value, prop) => prop.split(".").reduce((current, key) => current == null ? undefined : current[key], value);
+export const getIconProp = (value, prop) => read(resolve(value, icons), prop);
+export const getIconProps = (value, props) => { const icon = resolve(value, icons); if (!icon) return undefined; return props ? Object.fromEntries(props.map((prop) => [prop, read(icon, prop)])) : icon; };
+export const getFlagProp = (value, prop) => read(resolve(value, flags), prop);
+export const getFlagProps = (value, props) => { const flag = resolve(value, flags); if (!flag) return undefined; return props ? Object.fromEntries(props.map((prop) => [prop, read(flag, prop)])) : flag; };
+export const getCatalog = () => ({ version: 1, icons: iconsCatalog, flags: flagsCatalog });

package/dist/registry.d.ts

@@ -1,27 +1,20 @@
 export interface LibraryLicense { name: string; spdx?: string; url?: string; }
 export interface LibraryMetadata { id: string; name: string; [key: string]: unknown; }
 export interface CanonicalGeometry { viewBox: string; width?: number; height?: number; }
-export type CanonicalColorMode = "monochrome" | "multicolor";
-export interface CanonicalPresentation { color?: string; colorMode?: CanonicalColorMode; }
-export interface CanonicalSourceRef { url?: string; file?: string; adapter?: string; library?: string; author?: string; }
-export type FrameworkName = "react" | "svelte" | "angular" | "vue" | "solid" | "preact" | "lit" | "web" | "css" | "svg";
 export interface IntegrationFile { filename: string; language: string; code: string; }
-export interface GeneratedIntegration { framework: FrameworkName; files: IntegrationFile[]; }
+export interface GeneratedIntegration { framework: string; files: IntegrationFile[]; }
 export interface GeneratedData { slug: string; integrations: GeneratedIntegration[]; svg: string; coloredSvg?: string; dataUrl: string; coloredDataUrl?: string; route: string; }
 export interface CanonicalIcon { [key: string]: unknown; id: string; name: string; title: string; family: "icon" | "flag"; set: string; variant: string; geometry: CanonicalGeometry; artwork: { body: string }; generated?: GeneratedData; }
 export interface CanonicalIconSet extends LibraryMetadata { path: string; iconCount: number; }
 export interface CanonicalRegistry { version: 2; libraries: CanonicalIconSet[]; icons: CanonicalIcon[]; }
 export interface VeliconsRegistry { version: number; icons: CanonicalRegistry; flags: CanonicalRegistry; }
-export declare function getRegistry(): VeliconsRegistry;
-export declare function getIcons(): CanonicalIcon[];
-export declare function getFlags(): CanonicalIcon[];
-export declare function getIcon(idOrSlug: string, slug?: string): CanonicalIcon | undefined;
-export declare function getFlag(idOrSlug: string, slug?: string): CanonicalIcon | undefined;
-export declare function getIconById(id: string): CanonicalIcon | undefined;
-export declare function getFlagById(id: string): CanonicalIcon | undefined;
-export declare function getLibrary(id: string): CanonicalIconSet | undefined;
-export declare function getIconProp<K extends keyof CanonicalIcon>(iconOrId: CanonicalIcon | string, prop: K): CanonicalIcon[K] | undefined;
-export declare function getIconProp(iconOrId: CanonicalIcon | string, prop: string): unknown;
-export declare function getIconProps<K extends keyof CanonicalIcon>(iconOrId: CanonicalIcon | string, props?: readonly K[]): Pick<CanonicalIcon, K> | CanonicalIcon | undefined;
-export declare function getFlagProp<K extends keyof CanonicalIcon>(flagOrId: CanonicalIcon | string, prop: K): CanonicalIcon[K] | undefined;
-export declare function getFlagProps<K extends keyof CanonicalIcon>(flagOrId: CanonicalIcon | string, props?: readonly K[]): Pick<CanonicalIcon, K> | CanonicalIcon | undefined;
+export declare const iconsRegistry: CanonicalRegistry;
+export declare const flagsRegistry: CanonicalRegistry;
+export declare const getRegistry: () => VeliconsRegistry;
+export declare const getIcons: () => CanonicalIcon[];
+export declare const getFlags: () => CanonicalIcon[];
+export declare const getIcon: (idOrSlug: string, slug?: string) => CanonicalIcon | undefined;
+export declare const getFlag: (idOrSlug: string, slug?: string) => CanonicalIcon | undefined;
+export declare const getIconById: (id: string) => CanonicalIcon | undefined;
+export declare const getFlagById: (id: string) => CanonicalIcon | undefined;
+export declare const getLibrary: (id: string) => CanonicalIconSet | undefined;

package/dist/registry.js

@@ -1,61 +1,8 @@
 import iconsRegistry from "../jsons/icons/registry.json" with { type: "json" };
 import flagsRegistry from "../jsons/flags/registry.json" with { type: "json" };
-
-
-const icons = iconsRegistry.icons;
-const flags = flagsRegistry.icons;
-const registry = { version: 2, icons: iconsRegistry, flags: flagsRegistry };
+const icons = iconsRegistry.icons; const flags = flagsRegistry.icons;
+const decode = (value) => { try { return decodeURIComponent(value); } catch { return value; } }; const slugOf = (entity) => entity.generated?.slug ?? entity.name;
+const find = (items, a, b) => { const first = decode(a); if (b === undefined) return items.find((entity) => entity.id === first || slugOf(entity) === first || entity.name === first); const second = decode(b); return items.find((entity) => entity.set === first && (entity.id === second || slugOf(entity) === second || entity.name === second)); };
 export { iconsRegistry, flagsRegistry };
-
-export const getRegistry = () => registry;
-export const getIcons = () => icons;
-export const getFlags = () => flags;
-
-function decode(value) {
-  try { return decodeURIComponent(value); } catch { return value; }
-}
-
-function slugOf(entity) {
-  return entity.generated?.slug ?? entity.name;
-}
-
-function findEntity(collection, a, b) {
-  const first = decode(a);
-  if (b === undefined) {
-    return collection.find((entity) => entity.id === first || slugOf(entity) === first || entity.name === first);
-  }
-  const second = decode(b);
-  return collection.find((entity) => entity.set === first && (entity.id === second || slugOf(entity) === second || entity.name === second));
-}
-
-export function getIcon(idOrSlug, slug) { return findEntity(icons, idOrSlug, slug); }
-export function getFlag(idOrSlug, slug) { return findEntity(flags, idOrSlug, slug); }
-export function getIconById(id) { return icons.find((icon) => icon.id === id); }
-export function getFlagById(id) { return flags.find((flag) => flag.id === id); }
-export function getLibrary(id) {
-  return iconsRegistry.libraries.find((library) => library.id === id) ?? flagsRegistry.libraries.find((library) => library.id === id);
-}
-
-function resolveEntity(entityOrId, collection) {
-  if (entityOrId && typeof entityOrId === "object") return entityOrId;
-  return findEntity(collection, entityOrId);
-}
-
-function readPath(value, path) {
-  return path.split(".").reduce((current, key) => current == null ? undefined : current[key], value);
-}
-
-export function getIconProp(iconOrId, prop) { return readPath(resolveEntity(iconOrId, icons), prop); }
-export function getIconProps(iconOrId, props) {
-  const icon = resolveEntity(iconOrId, icons);
-  if (!icon) return undefined;
-  if (!props) return icon;
-  return Object.fromEntries(props.map((prop) => [prop, readPath(icon, prop)]));
-}
-export function getFlagProp(flagOrId, prop) { return readPath(resolveEntity(flagOrId, flags), prop); }
-export function getFlagProps(flagOrId, props) {
-  const flag = resolveEntity(flagOrId, flags);
-  if (!flag) return undefined;
-  if (!props) return flag;
-  return Object.fromEntries(props.map((prop) => [prop, readPath(flag, prop)]));
-}
+export const getRegistry = () => ({ version: 2, icons: iconsRegistry, flags: flagsRegistry });
+export const getIcons = () => icons; export const getFlags = () => flags; export const getIcon = (a,b) => find(icons,a,b); export const getFlag = (a,b) => find(flags,a,b); export const getIconById = (id) => icons.find((icon)=>icon.id===id); export const getFlagById = (id) => flags.find((flag)=>flag.id===id); export const getLibrary = (id) => [...iconsRegistry.libraries,...flagsRegistry.libraries].find((library)=>library.id===id);