@damian-buho/support-ukraine 1.0.0 → 1.0.1

package/README.md

@@ -35,7 +35,7 @@ npm install @damian-buho/support-ukraine
 ```html
 
 <script type="module">
-  import {supportUkraineBlock} from 'https://cdn.jsdelivr.net/npm/@damian-buho/support-ukraine'
+  import {supportUkraineBlock} from 'https://cdn.jsdelivr.net/npm/@damian-buho/support-ukraine@1/+esm'
 
   await supportUkraineBlock()
 </script>

package/dist/i18n.d.ts

@@ -0,0 +1,38 @@
+import type { Charity, LocaleMessages } from './types.js';
+import { type SupportedLocale } from './locales/index.js';
+export type { SupportedLocale } from './locales/index.js';
+/**
+ * Detect the user's preferred locale from browser APIs.
+ *
+ * Resolution order:
+ * 1. Explicit `locale` option
+ * 2. First match from `navigator.languages[]` (user-ordered preference list)
+ * 3. `navigator.language` base tag (e.g. "es" from "es-MX")
+ * 4. Fallback: "en"
+ */
+export declare function detectLocale(preferred?: string): SupportedLocale;
+/**
+ * Load locale messages for the given language code.
+ * Returns cached result on repeat calls. Falls back to 'en' on error.
+ */
+export declare function loadLocale(lang: string): Promise<LocaleMessages>;
+/**
+ * Merge base charities with locale-specific translations.
+ *
+ * For each charity: use the locale tagline if available, otherwise keep
+ * the English default from the base data.
+ */
+export declare function mergeCharities(base: readonly Charity[], locale: LocaleMessages): Charity[];
+/** Returns true if the locale uses right-to-left script. */
+export declare function isRTL(lang: string): boolean;
+/**
+ * Build a translated banner text line for a charity.
+ *
+ * @returns The formatted string "UA_FLAG supportUkraine: name: tagline"
+ */
+export declare function formatBannerText(charity: Charity, messages: LocaleMessages): string;
+/**
+ * Eagerly pre-load the English locale so it is always available synchronously.
+ * Other locales are loaded on demand via `loadLocale()`.
+ */
+export declare function preloadDefault(): Promise<LocaleMessages>;

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { type Charity, type SupportUkraineBlockOptions } from './types.js';
+export type { Charity, CharityTag, SupportUkraineBlockOptions } from './types.js';
+export { charitySchema, charitiesSchema } from './types.js';
+export { detectLocale, loadLocale, mergeCharities, isRTL, formatBannerText } from './i18n.js';
+export { resolveLocale, RTL_LOCALES } from './locales/index.js';
+export type { SupportedLocale } from './locales/index.js';
+export declare const DEFAULT_CHARITIES: Charity[];
+/**
+ * Pick a random item from an array.
+ *
+ * @internal
+ */
+export declare function randomItem<T>(items: T[]): T;
+/**
+ * Create and mount the Ukraine-support charity banner.
+ *
+ * The banner is placed at the top of the page. It displays a randomly
+ * selected charity with the format "🇺🇦 Support Ukraine: Name: tagline" —
+ * the entire block is a clickable link. Text is translated to the user's
+ * detected locale (or the explicit `locale` option).
+ *
+ * @example
+ * ```ts
+ * import { supportUkraineBlock } from '@damian-buho/support-ukraine'
+ *
+ * // Auto-detect locale from navigator.language
+ * await supportUkraineBlock()
+ *
+ * // Force a specific locale
+ * await supportUkraineBlock({ locale: 'es' })
+ * ```
+ */
+export declare function supportUkraineBlock(options?: SupportUkraineBlockOptions): Promise<HTMLElement>;

package/dist/locales/index.d.ts

@@ -0,0 +1,11 @@
+import type { LocaleMessages } from '../types.js';
+/** Map of BCP 47 base language → dynamic import loader. */
+export declare const localeLoaders: Record<string, () => Promise<{
+    default: LocaleMessages;
+}>>;
+/** All supported locale codes. */
+export type SupportedLocale = keyof typeof localeLoaders;
+/** List of RTL locale codes. */
+export declare const RTL_LOCALES: readonly ["ar"];
+/** Resolve a raw BCP 47 tag to a supported locale code, or 'en'. */
+export declare function resolveLocale(tag: string): SupportedLocale;

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+/** Category tag for a charity. */
+export declare const charityTagSchema: z.ZodEnum<{
+    military: "military";
+    humanitarian: "humanitarian";
+    animals: "animals";
+}>;
+export type CharityTag = z.infer<typeof charityTagSchema>;
+/** A charity foundation that can appear in the banner. */
+export declare const charitySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagline: z.ZodString;
+    url: z.ZodString;
+    tags: z.ZodArray<z.ZodEnum<{
+        military: "military";
+        humanitarian: "humanitarian";
+        animals: "animals";
+    }>>;
+}, z.core.$strip>;
+export type Charity = z.infer<typeof charitySchema>;
+export declare const charitiesSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagline: z.ZodString;
+    url: z.ZodString;
+    tags: z.ZodArray<z.ZodEnum<{
+        military: "military";
+        humanitarian: "humanitarian";
+        animals: "animals";
+    }>>;
+}, z.core.$strip>>;
+/** Translated UI strings and charity taglines for a single locale. */
+export interface LocaleMessages {
+    /** Banner prefix, e.g. "Support Ukraine". */
+    supportUkraine: string;
+    /** "All charities" link text. */
+    allCharities: string;
+    /** Card donate button text, e.g. "Donate". */
+    donate: string;
+    /** Translated taglines keyed by charity id. Missing keys fall back to EN. */
+    charities: Record<string, {
+        tagline: string;
+    }>;
+}
+export interface SupportUkraineBlockOptions {
+    /** Target mount element. If omitted the banner is prepended to document.body. */
+    element?: HTMLElement;
+    /** Positioning mode: 'shift' pushes content down, 'overlap' floats on top. */
+    mode?: 'shift' | 'overlap';
+    /** Font size (default '0.875rem'). */
+    fontSize?: string;
+    /** Category tags to filter by. If omitted all charities are shown. */
+    tags?: CharityTag[];
+    /** Avoid repeating charities across page loads using localStorage. */
+    dontRepeat?: boolean;
+    /** Log a message to the dev console. */
+    isInConsole?: boolean;
+    /**
+     * Override the auto-detected locale (BCP 47 language tag).
+     * If omitted the locale is detected from `navigator.language`.
+     */
+    locale?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damian-buho/support-ukraine",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Browser library that adds a Ukraine-support charity banner to any website.",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsup",
+    "build": "npm run clean && tsup && tsc --emitDeclarationOnly --noCheck",
     "prepublishOnly": "npm run build",
     "test": "npm run build && node --test 'dist/test/index.test.js'",
     "test:verbose": "npm run build && node --test --test-reporter spec 'dist/test/index.test.js'",
@@ -46,7 +46,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com:damian-buho/support-ukraine.git"
+    "url": "git+ssh://git@github.com/damian-buho/support-ukraine.git"
   },
   "bugs": {
     "url": "https://github.com/damian-buho/support-ukraine/issues"
@@ -56,7 +56,7 @@
     "@eslint/js": "10.0.1",
     "@types/eslint": "9.6.1",
     "@types/js-yaml": "4.0.9",
-    "@types/node": "26.1.0",
+    "@types/node": "26.1.1",
     "esbuild": "0.28.1",
     "eslint": "10.6.0",
     "eslint-config-prettier": "10.1.8",
@@ -88,6 +88,8 @@
     "zod": "4.4.3"
   },
   "overrides": {
-    "esbuild": "0.28.1"
+    "esbuild": "0.28.1",
+    "@typescript-eslint/utils": "8.63.0",
+    "globals": "$globals"
   }
 }