emoji-styles 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 emoji-styles contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# emoji-styles
+
+Framework-independent emoji resolution with typed providers, explicit fallback
+chains, semantic themes, Unicode metadata, and deterministic asset policies.
+
+## Install
+
+```bash
+npm install emoji-styles
+```
+
+## Usage
+
+```ts
+import {
+  defineEmojiTheme,
+  publicProviders,
+  resolveEmoji,
+  resolveEmojiToken,
+} from "emoji-styles";
+
+const theme = defineEmojiTheme({
+  "action.deploy": {
+    emoji: "🚀",
+    label: "Deploy application",
+  },
+});
+
+const resolved = await resolveEmoji("🚀", {
+  provider: publicProviders.fluent3d,
+  fallbacks: [publicProviders.twemoji],
+  nativeFallback: false,
+});
+
+const deploy = await resolveEmojiToken("action.deploy", theme);
+```
+
+Use this package directly in any JavaScript framework, or pair it with
+[`react-emoji-styles`](https://www.npmjs.com/package/react-emoji-styles) or
+[`emoji-styles-web`](https://www.npmjs.com/package/emoji-styles-web).
+
+Documentation and the interactive provider explorer are available at
+[emoji-styles.space](https://emoji-styles.space).
+
+## License
+
+Source code is MIT licensed. Artwork returned by external providers retains its
+own license and delivery terms; see the repository's
+[license policy](https://github.com/Blancochuy/emoji-styles/blob/master/docs/LICENSE_POLICY.md).

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+import * as emoji_styles_data from 'emoji-styles-data';
+export { EmojiDatasetInfo, EmojiMetadata, EmojiQualification, emojiData, emojiDatasetInfo, isRGIEmoji, normalizeEmoji, toEmojiCodepointSequence } from 'emoji-styles-data';
+
+type EmojiStyle = "fluent-animated" | "fluent-3d" | "fluent-color" | "fluent-flat" | "noto" | "serenityos" | "twemoji" | "native";
+type EmojiSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | number;
+type ProviderVisibility = "public" | "custom";
+type EmojiAssetFormat = "png" | "svg" | "webp" | "avif";
+interface ProviderLicense {
+    name: string;
+    url?: string;
+    attribution?: string;
+    ownership?: string;
+}
+interface EmojiData {
+    /** Stable CLDR-derived identifier used by provider URL formatters. */
+    name: string;
+    /** Human-readable alt text. */
+    alt: string;
+    /** Canonical lowercase, hyphen-separated Unicode sequence. */
+    codepoint: string;
+    /** Enriched fields are present for catalog entries and optional for custom providers. */
+    codepoints?: readonly string[];
+    sequence?: string;
+    unicodeVersion?: string;
+    emojiVersion?: string;
+    group?: string;
+    subgroup?: string;
+    qualification?: "fully-qualified" | "component";
+    /** Styles that DON'T have this emoji (blacklist) */
+    unsupported?: EmojiStyle[];
+}
+interface ProviderConfig {
+    name: EmojiStyle;
+    baseUrl: string;
+    extension: string;
+    label: string;
+}
+/** A source of emoji artwork. Custom providers keep asset hosting outside the core. */
+interface EmojiAssetProvider {
+    id: string;
+    label: string;
+    visibility: ProviderVisibility;
+    /** Required for v2 providers; optional only while adapting legacy providers. */
+    version?: string;
+    formats?: readonly EmojiAssetFormat[];
+    local?: boolean;
+    source?: string;
+    license?: ProviderLicense;
+    /** Whether the provider can resolve emoji absent from the bundled catalog. */
+    supportsUnknownEmoji?: boolean;
+    /** @deprecated Implement `resolve` for v2 providers. Retained for synchronous compatibility. */
+    getUrl?(data: EmojiData, emoji?: string): string | null;
+    resolve?(emoji: NormalizedEmoji): ProviderResolution;
+    getCoverage?(): ProviderCoverage | Promise<ProviderCoverage>;
+}
+type EmojiProviderRef = EmojiStyle | EmojiAssetProvider;
+interface NormalizedEmojiMetadata {
+    label: string;
+    codepoints: readonly string[];
+    sequence: string;
+    unicodeVersion?: string;
+    emojiVersion?: string;
+    category?: string;
+    subgroup?: string;
+}
+interface NormalizedEmoji {
+    input: string;
+    normalized: string;
+    metadata: NormalizedEmojiMetadata;
+    data: EmojiData;
+}
+interface ResolvedEmojiAsset {
+    providerId: string;
+    providerVersion: string;
+    url: string;
+    format: EmojiAssetFormat;
+    local: boolean;
+    width?: number;
+    height?: number;
+    checksum?: string;
+    license?: ProviderLicense;
+}
+type ProviderResolution = ResolvedEmojiAsset | null | Promise<ResolvedEmojiAsset | null>;
+interface EmojiResolutionAttempt {
+    providerId: string;
+    status: "resolved" | "unsupported" | "native" | "error";
+    asset: ResolvedEmojiAsset | null;
+    error?: string;
+}
+interface EmojiResolution {
+    input: string;
+    normalized: string;
+    metadata: NormalizedEmojiMetadata;
+    selected: ResolvedEmojiAsset | null;
+    attempts: EmojiResolutionAttempt[];
+    fallbackUsed: boolean;
+    nativeFallback: boolean;
+}
+interface ProviderCoverage {
+    providerId: string;
+    providerVersion: string;
+    datasetVersion: string;
+    total: number;
+    supported: number;
+    percentage: number;
+    verified: boolean;
+    source?: string;
+    missing?: readonly string[];
+}
+interface ProviderValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+
+interface CdnProviderOptions {
+    id: string;
+    label: string;
+    baseUrl: string;
+    extension: string;
+    visibility: ProviderVisibility;
+    license?: ProviderLicense;
+    filename?: (data: EmojiData) => string;
+    version?: string;
+    format?: EmojiAssetFormat;
+    local?: boolean;
+    source?: string;
+    supports?: (data: EmojiData, emoji?: string) => boolean;
+    coverage?: () => ProviderCoverage | Promise<ProviderCoverage>;
+}
+declare function createCdnProvider(options: CdnProviderOptions): EmojiAssetProvider;
+/** Match Twemoji's asset convention: keep VS16 inside ZWJ sequences, omit it otherwise. */
+declare function getTwemojiAssetId(data: Pick<EmojiData, "codepoint">): string;
+/** Providers whose artwork has an explicit redistribution license. */
+declare const publicProviders: {
+    readonly fluentAnimated: EmojiAssetProvider;
+    readonly fluent3d: EmojiAssetProvider;
+    readonly fluentColor: EmojiAssetProvider;
+    readonly fluentFlat: EmojiAssetProvider;
+    readonly noto: EmojiAssetProvider;
+    readonly serenityOS: EmojiAssetProvider;
+    readonly twemoji: EmojiAssetProvider;
+    readonly native: {
+        id: string;
+        label: string;
+        visibility: "public";
+        version: string;
+        formats: never[];
+        local: true;
+        source: string;
+        getUrl: () => null;
+        resolve: () => null;
+    };
+};
+/**
+ * Licensed providers whose upstream delivery is intentionally rolling.
+ * Keep these separate from `publicProviders` so production consumers can opt in.
+ */
+declare const experimentalProviders: {
+    readonly notoAnimated: EmojiAssetProvider;
+};
+/** Built-in providers with documented redistribution terms. */
+declare const providers: Record<EmojiStyle, EmojiAssetProvider>;
+declare const SIZE_MAP: Record<string, number>;
+
+type EmojiAssetMap = Readonly<Record<string, string>>;
+interface MappedProviderOptions {
+    id?: string;
+    label?: string;
+    /** Exact Unicode emoji mapped to an application-owned asset URL. */
+    assets: EmojiAssetMap;
+    /** Used whenever an emoji has no custom asset. */
+    fallback?: EmojiAssetProvider;
+    license?: ProviderLicense;
+    version?: string;
+    source?: string;
+    format?: EmojiAssetFormat;
+    local?: boolean;
+}
+/**
+ * Create a partial custom provider without requiring a filename convention.
+ * Invalid or empty mappings fail immediately so configuration errors surface
+ * during application startup instead of as broken images in production.
+ */
+declare function createMappedProvider(options: MappedProviderOptions): EmojiAssetProvider;
+
+interface ResolveEmojiOptions {
+    provider: EmojiProviderRef;
+    fallbacks?: readonly EmojiProviderRef[];
+}
+interface ProviderCoverageOptions {
+    includeMissing?: boolean;
+}
+declare function createNormalizedEmoji(input: string): NormalizedEmoji | null;
+declare function getEmojiMetadata(input: string): NormalizedEmojiMetadata | null;
+declare function isEmoji(input: string): boolean;
+declare function resolveEmoji(input: string, options: ResolveEmojiOptions): Promise<EmojiResolution>;
+declare function getProviderCoverage(providerRef: EmojiProviderRef, options?: ProviderCoverageOptions): Promise<ProviderCoverage>;
+
+interface LegacyEmojiAssetProvider {
+    id: string;
+    label: string;
+    visibility: ProviderVisibility;
+    license?: EmojiAssetProvider["license"];
+    supportsUnknownEmoji?: boolean;
+    getUrl: NonNullable<EmojiAssetProvider["getUrl"]>;
+}
+interface LegacyProviderAdapterOptions {
+    version?: string;
+    format?: EmojiAssetFormat;
+    local?: boolean;
+    source?: string;
+}
+declare function isV2Provider(provider: EmojiAssetProvider): boolean;
+declare function adaptLegacyProvider(legacy: LegacyEmojiAssetProvider, options?: LegacyProviderAdapterOptions): EmojiAssetProvider;
+
+interface EmojiProviderManifestAsset {
+    file: string;
+    sha256?: string;
+    width?: number;
+    height?: number;
+}
+interface EmojiProviderGenerator {
+    type: string;
+    model: string;
+    createdAt: string;
+}
+interface EmojiProviderManifest {
+    $schema?: string;
+    id: string;
+    label: string;
+    version: string;
+    format: EmojiAssetFormat;
+    basePath: string;
+    generated?: boolean;
+    generator?: EmojiProviderGenerator;
+    license?: ProviderLicense;
+    source?: string;
+    assets: Record<string, EmojiProviderManifestAsset>;
+}
+interface ManifestProviderOptions {
+    baseUrl?: string;
+    visibility?: "public" | "custom";
+    local?: boolean;
+}
+declare function validateProviderManifest(manifest: EmojiProviderManifest): ProviderValidationResult;
+declare function createManifestProvider(manifest: EmojiProviderManifest, options?: ManifestProviderOptions): EmojiAssetProvider;
+declare function createGeneratedProvider(manifest: EmojiProviderManifest, options?: ManifestProviderOptions): EmojiAssetProvider;
+
+interface CompositeProviderOptions {
+    id: string;
+    label: string;
+    version: string;
+    providers: readonly EmojiAssetProvider[];
+    visibility?: ProviderVisibility;
+    license?: ProviderLicense;
+}
+declare function createCompositeProvider(options: CompositeProviderOptions): EmojiAssetProvider;
+
+type EmojiConfigProviderRef = EmojiProviderRef | string;
+/** Runtime subset shared by project config files and framework adapters. */
+interface EmojiStylesConfig {
+    provider?: EmojiConfigProviderRef;
+    fallbacks?: readonly EmojiConfigProviderRef[];
+    nativeFallback?: boolean;
+}
+/**
+ * Validate and freeze the runtime policy exported by `emoji-styles.config.ts`.
+ * Extra CLI-only fields remain structurally compatible when a JSON config is imported.
+ */
+declare function defineEmojiConfig<T extends EmojiStylesConfig>(config: T): Readonly<T>;
+
+interface EmojiTextToken {
+    type: "emoji" | "text";
+    value: string;
+}
+/** Split text into supported emoji graphemes and ordinary text. */
+declare function tokenizeEmojiText(text: string): EmojiTextToken[];
+
+declare const EMOJI_THEME_SCHEMA_VERSION: 1;
+declare const EMOJI_TOKEN_NAME_PATTERN: RegExp;
+type EmojiThemeProviderRef = EmojiProviderRef | string;
+interface EmojiTokenAsset {
+    url: string;
+    format: EmojiAssetFormat;
+    local?: boolean;
+    providerId?: string;
+    providerVersion?: string;
+    width?: number;
+    height?: number;
+    checksum?: string;
+    license?: ProviderLicense;
+}
+interface EmojiTokenDefinitionInput {
+    emoji: string;
+    label: string;
+    decorative?: boolean;
+    labels?: Readonly<Record<string, string>>;
+    provider?: EmojiThemeProviderRef;
+    /** Stable semantic asset id resolved by a SemanticTokenProvider, or an exact asset. */
+    asset?: string | EmojiTokenAsset;
+}
+interface EmojiTokenDefinition extends EmojiTokenDefinitionInput {
+    decorative: boolean;
+}
+type EmojiTokenMapInput = Readonly<Record<string, EmojiTokenDefinitionInput>>;
+type EmojiTokenMap = Readonly<Record<string, EmojiTokenDefinition>>;
+interface EmojiTheme {
+    schemaVersion: typeof EMOJI_THEME_SCHEMA_VERSION;
+    id: string;
+    version: string;
+    tokens: EmojiTokenMap;
+    defaultProvider?: EmojiThemeProviderRef;
+    fallbacks?: readonly EmojiThemeProviderRef[];
+    /** Whether native OS emoji is appended as the terminal fallback. Defaults to true. */
+    nativeFallback?: boolean;
+    inherits: readonly string[];
+}
+interface DefineEmojiThemeOptions {
+    id?: string;
+    version?: string;
+    defaultProvider?: EmojiThemeProviderRef;
+    fallbacks?: readonly EmojiThemeProviderRef[];
+    nativeFallback?: boolean;
+    extends?: EmojiTheme | readonly EmojiTheme[];
+    /** Preserved ancestry metadata when parsing a flattened serialized theme. */
+    inherits?: readonly string[];
+}
+interface EmojiThemeValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+interface EmojiThemeValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    issues: EmojiThemeValidationIssue[];
+}
+interface ResolveEmojiTokenOptions {
+    provider?: EmojiThemeProviderRef;
+    fallbacks?: readonly EmojiThemeProviderRef[];
+    nativeFallback?: boolean;
+    locale?: string;
+    providers?: Readonly<Record<string, EmojiAssetProvider>>;
+}
+interface ResolvedEmojiToken {
+    token: string;
+    themeId: string;
+    themeVersion: string;
+    emoji: string;
+    label: string;
+    decorative: boolean;
+    locale?: string;
+    asset: ResolvedEmojiAsset | null;
+    emojiResolution: EmojiResolution | null;
+    source: "custom-asset" | "semantic-provider" | "emoji-provider" | "native" | "unresolved";
+}
+interface SemanticTokenResolveContext {
+    token: string;
+    definition: EmojiTokenDefinition;
+    theme: EmojiTheme;
+}
+interface SemanticTokenProvider extends EmojiAssetProvider {
+    resolveToken(assetId: string, context: SemanticTokenResolveContext): ProviderResolution;
+}
+interface SemanticTokenProviderOptions {
+    id: string;
+    label: string;
+    version: string;
+    assets: Readonly<Record<string, string | EmojiTokenAsset>>;
+    fallback?: EmojiAssetProvider;
+    format?: EmojiAssetFormat;
+    local?: boolean;
+    source?: string;
+    license?: ProviderLicense;
+    visibility?: "public" | "custom";
+}
+interface SerializeEmojiThemeOptions {
+    format?: "json" | "typescript";
+    space?: number;
+    variableName?: string;
+}
+declare function validateEmojiTheme(theme: unknown): EmojiThemeValidationResult;
+declare function defineEmojiTheme(tokens: EmojiTokenMapInput, options?: DefineEmojiThemeOptions): EmojiTheme;
+declare function mergeEmojiThemes(...themes: readonly EmojiTheme[]): EmojiTheme;
+declare function getEmojiTokenDefinition(theme: EmojiTheme, token: string): EmojiTokenDefinition | null;
+declare function getEmojiTokenLabel(definition: EmojiTokenDefinition, locale?: string): string;
+declare function resolveEmojiToken(token: string, theme: EmojiTheme, options?: ResolveEmojiTokenOptions): Promise<ResolvedEmojiToken>;
+declare function createSemanticTokenProvider(options: SemanticTokenProviderOptions): SemanticTokenProvider;
+declare function serializeEmojiTheme(theme: EmojiTheme, options?: SerializeEmojiThemeOptions): string;
+/** Migrate a schema-less v0 theme or parse a current serialized theme. */
+declare function migrateEmojiTheme(input: unknown): EmojiTheme;
+declare const parseEmojiTheme: typeof migrateEmojiTheme;
+
+declare function validateProvider(provider: EmojiAssetProvider): ProviderValidationResult;
+
+declare function resolveProvider(provider: EmojiProviderRef): EmojiAssetProvider | null;
+/** Resolve an emoji through a built-in style or a custom asset provider. */
+declare function getEmojiUrl(emoji: string, providerRef: EmojiProviderRef): string | null;
+/**
+ * Build a fallback chain. The default fallback is the publicly licensed Twemoji
+ * provider; callers can supply their own ordered provider list.
+ */
+declare function getFallbackChain(emoji: string, primary: EmojiProviderRef, fallbacks?: readonly EmojiProviderRef[]): string[];
+declare function hasEmoji(emoji: string): boolean;
+declare function getAvailableEmojis(): string[];
+/** @deprecated Use getEmojiMetadata for the normalized v2 metadata contract. */
+declare function getEmojiData(emoji: string): emoji_styles_data.EmojiMetadata | null;
+
+export { type CdnProviderOptions, type CompositeProviderOptions, type DefineEmojiThemeOptions, EMOJI_THEME_SCHEMA_VERSION, EMOJI_TOKEN_NAME_PATTERN, type EmojiAssetFormat, type EmojiAssetMap, type EmojiAssetProvider, type EmojiConfigProviderRef, type EmojiData, type EmojiProviderGenerator, type EmojiProviderManifest, type EmojiProviderManifestAsset, type EmojiProviderRef, type EmojiResolution, type EmojiResolutionAttempt, type EmojiSize, type EmojiStyle, type EmojiStylesConfig, type EmojiTextToken, type EmojiTheme, type EmojiThemeProviderRef, type EmojiThemeValidationIssue, type EmojiThemeValidationResult, type EmojiTokenAsset, type EmojiTokenDefinition, type EmojiTokenDefinitionInput, type EmojiTokenMap, type EmojiTokenMapInput, type LegacyEmojiAssetProvider, type LegacyProviderAdapterOptions, type ManifestProviderOptions, type MappedProviderOptions, type NormalizedEmoji, type NormalizedEmojiMetadata, type ProviderConfig, type ProviderCoverage, type ProviderCoverageOptions, type ProviderLicense, type ProviderValidationResult, type ProviderVisibility, type ResolveEmojiOptions, type ResolveEmojiTokenOptions, type ResolvedEmojiAsset, type ResolvedEmojiToken, SIZE_MAP, type SemanticTokenProvider, type SemanticTokenProviderOptions, type SemanticTokenResolveContext, type SerializeEmojiThemeOptions, adaptLegacyProvider, createCdnProvider, createCompositeProvider, createGeneratedProvider, createManifestProvider, createMappedProvider, createNormalizedEmoji, createSemanticTokenProvider, defineEmojiConfig, defineEmojiTheme, experimentalProviders, getAvailableEmojis, getEmojiData, getEmojiMetadata, getEmojiTokenDefinition, getEmojiTokenLabel, getEmojiUrl, getFallbackChain, getProviderCoverage, getTwemojiAssetId, hasEmoji, isEmoji, isV2Provider, mergeEmojiThemes, migrateEmojiTheme, parseEmojiTheme, providers, publicProviders, resolveEmoji, resolveEmojiToken, resolveProvider, serializeEmojiTheme, tokenizeEmojiText, validateEmojiTheme, validateProvider, validateProviderManifest };