@johnmorrisdotca/kuni 1.2.0 → 1.4.0

package/dist/element.d.cts

@@ -0,0 +1,114 @@
+declare const ElementBase: typeof HTMLElement;
+/**
+ * The fields a card can show, in any order; facts retain their recorded year.
+ * @example
+ * ```ts
+ * import { KUNI_CARD_FIELDS } from "@johnmorrisdotca/kuni/element";
+ * console.log(KUNI_CARD_FIELDS.includes("population")); // true
+ * ```
+ */
+declare const KUNI_CARD_FIELDS: readonly ["name", "codes", "flag", "map", "capital", "population", "area", "continent", "subregion", "currency", "languages", "calling-code", "tld", "zones", "ioc"];
+/** Host SVG loaders and native map appearance; attributes override drawing defaults.
+ * @example
+ * ```ts
+ * import { type KuniCardOptions, KUNI_CARD_OPTION_KEYS } from "@johnmorrisdotca/kuni/element";
+ * const options: KuniCardOptions = {};
+ * console.log(Object.keys(options).length); // 0
+ * console.log(KUNI_CARD_OPTION_KEYS.length); // 4
+ * ```
+ */
+interface KuniCardOptions {
+    /** Load a Hata flag or an equivalent SVG for the ISO code; null means unavailable. */
+    flag?: (code: string) => Promise<string | null>;
+    /** Load trusted SVG for the ISO code/language, honouring optional drawing settings; null means unavailable. */
+    map?: (code: string, language: "en" | "ja", drawing?: Pick<KuniCardOptions, "colors" | "capital">) => Promise<string | null>;
+    /** Per-region CSS colours for the native drawing; code:hex-colour attribute pairs override this map. */
+    colors?: Readonly<Record<string, string>>;
+    /** Show the capital markers on the map, true by default. This does not remove the capital text field. */
+    capital?: boolean;
+}
+/**
+ * Host option keys, kept complete by TypeScript and checked by the builder.
+ * @example
+ * ```ts
+ * import { KUNI_CARD_OPTION_KEYS } from "@johnmorrisdotca/kuni/element";
+ * console.log(KUNI_CARD_OPTION_KEYS.length); // 4
+ * ```
+ */
+declare const KUNI_CARD_OPTION_KEYS: string[];
+/** Read the card's bounded code:hex-colour attribute without accepting CSS or markup fragments.
+ * @param text - Comma-separated pairs; null or empty means the theme colour.
+ * @returns Validated colour pairs, or null when any pair is malformed.
+ * @example
+ * ```ts
+ * import { readCardColors } from "@johnmorrisdotca/kuni/element";
+ * console.log(readCardColors("JP:#2f6b4f")?.JP); // "#2f6b4f"
+ * console.log(readCardColors("JP:url(evil)")); // null
+ * ```
+ */
+declare function readCardColors(text: string | null): Record<string, string> | null;
+/**
+ * `<kuni-card code="JP" fields="name flag map capital population">`, a country or ISO subdivision without stored state.
+ * @example
+ * ```ts
+ * import { KuniCard, defineCard } from "@johnmorrisdotca/kuni/element";
+ * console.log(typeof KuniCard); // "function"
+ * if (typeof document !== "undefined") {
+ *   defineCard();
+ *   const card = document.createElement("kuni-card");
+ *   card.setAttribute("code", "JP");
+ *   card.setAttribute("colors", "JP:#2f6b4f");
+ *   card.setAttribute("capital", "off");
+ *   document.body.append(card);
+ * }
+ * ```
+ */
+declare class KuniCard extends ElementBase {
+    #private;
+    static get observedAttributes(): readonly string[];
+    /** The country or subdivision code. */
+    get code(): string;
+    set code(value: string | null | undefined);
+    /** The field names, reflected as their space-separated attribute. */
+    get fields(): string;
+    set fields(value: string | readonly string[] | null | undefined);
+    /** Light, dark or auto. */
+    get theme(): string;
+    set theme(value: string | null | undefined);
+    /** Small, medium or large. */
+    get size(): string;
+    set size(value: string | null | undefined);
+    /** Width in pixels, fitting the parent. */
+    get width(): string | null;
+    set width(value: string | number | null | undefined);
+    /** Optional spoken label. */
+    get label(): string | null;
+    set label(value: string | null | undefined);
+    /** Per-region hex colours, reflected as comma-separated code:colour pairs. */
+    get colors(): string | null;
+    set colors(value: string | null | undefined);
+    /** Show map capital markers; false aliases turn them off. The capital text field is separate. */
+    get capital(): boolean;
+    set capital(value: boolean | string | null | undefined);
+    /** Optional host SVG loaders; assigning them redraws the card. */
+    get options(): KuniCardOptions;
+    set options(value: KuniCardOptions);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Redraw the card, coalescing attribute updates into one load. */
+    refresh(): void;
+}
+/**
+ * Register `<kuni-card>` or a host's own tag, preserving an existing definition. Safe without a browser.
+ * @param tag - The tag to register; kuni-card by default.
+ * @returns Nothing; the element is registered once when a browser is present.
+ * @example
+ * ```ts
+ * import { defineCard } from "@johnmorrisdotca/kuni/element";
+ * console.log(defineCard());
+ * ```
+ */
+declare function defineCard(tag?: string): void;
+
+export { KUNI_CARD_FIELDS, KUNI_CARD_OPTION_KEYS, KuniCard, type KuniCardOptions, defineCard, readCardColors };

package/dist/element.d.ts

@@ -0,0 +1,114 @@
+declare const ElementBase: typeof HTMLElement;
+/**
+ * The fields a card can show, in any order; facts retain their recorded year.
+ * @example
+ * ```ts
+ * import { KUNI_CARD_FIELDS } from "@johnmorrisdotca/kuni/element";
+ * console.log(KUNI_CARD_FIELDS.includes("population")); // true
+ * ```
+ */
+declare const KUNI_CARD_FIELDS: readonly ["name", "codes", "flag", "map", "capital", "population", "area", "continent", "subregion", "currency", "languages", "calling-code", "tld", "zones", "ioc"];
+/** Host SVG loaders and native map appearance; attributes override drawing defaults.
+ * @example
+ * ```ts
+ * import { type KuniCardOptions, KUNI_CARD_OPTION_KEYS } from "@johnmorrisdotca/kuni/element";
+ * const options: KuniCardOptions = {};
+ * console.log(Object.keys(options).length); // 0
+ * console.log(KUNI_CARD_OPTION_KEYS.length); // 4
+ * ```
+ */
+interface KuniCardOptions {
+    /** Load a Hata flag or an equivalent SVG for the ISO code; null means unavailable. */
+    flag?: (code: string) => Promise<string | null>;
+    /** Load trusted SVG for the ISO code/language, honouring optional drawing settings; null means unavailable. */
+    map?: (code: string, language: "en" | "ja", drawing?: Pick<KuniCardOptions, "colors" | "capital">) => Promise<string | null>;
+    /** Per-region CSS colours for the native drawing; code:hex-colour attribute pairs override this map. */
+    colors?: Readonly<Record<string, string>>;
+    /** Show the capital markers on the map, true by default. This does not remove the capital text field. */
+    capital?: boolean;
+}
+/**
+ * Host option keys, kept complete by TypeScript and checked by the builder.
+ * @example
+ * ```ts
+ * import { KUNI_CARD_OPTION_KEYS } from "@johnmorrisdotca/kuni/element";
+ * console.log(KUNI_CARD_OPTION_KEYS.length); // 4
+ * ```
+ */
+declare const KUNI_CARD_OPTION_KEYS: string[];
+/** Read the card's bounded code:hex-colour attribute without accepting CSS or markup fragments.
+ * @param text - Comma-separated pairs; null or empty means the theme colour.
+ * @returns Validated colour pairs, or null when any pair is malformed.
+ * @example
+ * ```ts
+ * import { readCardColors } from "@johnmorrisdotca/kuni/element";
+ * console.log(readCardColors("JP:#2f6b4f")?.JP); // "#2f6b4f"
+ * console.log(readCardColors("JP:url(evil)")); // null
+ * ```
+ */
+declare function readCardColors(text: string | null): Record<string, string> | null;
+/**
+ * `<kuni-card code="JP" fields="name flag map capital population">`, a country or ISO subdivision without stored state.
+ * @example
+ * ```ts
+ * import { KuniCard, defineCard } from "@johnmorrisdotca/kuni/element";
+ * console.log(typeof KuniCard); // "function"
+ * if (typeof document !== "undefined") {
+ *   defineCard();
+ *   const card = document.createElement("kuni-card");
+ *   card.setAttribute("code", "JP");
+ *   card.setAttribute("colors", "JP:#2f6b4f");
+ *   card.setAttribute("capital", "off");
+ *   document.body.append(card);
+ * }
+ * ```
+ */
+declare class KuniCard extends ElementBase {
+    #private;
+    static get observedAttributes(): readonly string[];
+    /** The country or subdivision code. */
+    get code(): string;
+    set code(value: string | null | undefined);
+    /** The field names, reflected as their space-separated attribute. */
+    get fields(): string;
+    set fields(value: string | readonly string[] | null | undefined);
+    /** Light, dark or auto. */
+    get theme(): string;
+    set theme(value: string | null | undefined);
+    /** Small, medium or large. */
+    get size(): string;
+    set size(value: string | null | undefined);
+    /** Width in pixels, fitting the parent. */
+    get width(): string | null;
+    set width(value: string | number | null | undefined);
+    /** Optional spoken label. */
+    get label(): string | null;
+    set label(value: string | null | undefined);
+    /** Per-region hex colours, reflected as comma-separated code:colour pairs. */
+    get colors(): string | null;
+    set colors(value: string | null | undefined);
+    /** Show map capital markers; false aliases turn them off. The capital text field is separate. */
+    get capital(): boolean;
+    set capital(value: boolean | string | null | undefined);
+    /** Optional host SVG loaders; assigning them redraws the card. */
+    get options(): KuniCardOptions;
+    set options(value: KuniCardOptions);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Redraw the card, coalescing attribute updates into one load. */
+    refresh(): void;
+}
+/**
+ * Register `<kuni-card>` or a host's own tag, preserving an existing definition. Safe without a browser.
+ * @param tag - The tag to register; kuni-card by default.
+ * @returns Nothing; the element is registered once when a browser is present.
+ * @example
+ * ```ts
+ * import { defineCard } from "@johnmorrisdotca/kuni/element";
+ * console.log(defineCard());
+ * ```
+ */
+declare function defineCard(tag?: string): void;
+
+export { KUNI_CARD_FIELDS, KUNI_CARD_OPTION_KEYS, KuniCard, type KuniCardOptions, defineCard, readCardColors };