@neptune.fintech/icons 2.0.0 → 2.2.0

package/NOTICE-brand-marks.md

@@ -0,0 +1,35 @@
+# NOTICE — Brand marks (third-party trademarks)
+
+The payment-network and fintech **brand marks** shipped in this package
+(`src/brand-marks.ts` → `BRAND_MARKS`, `brandMarkSvg`, `<npt-brand-mark>`) —
+including but not limited to **Visa, Mastercard, American Express, Discover,
+UnionPay, Western Union, MoneyGram, Apple Pay, Google Pay, PayPal, SWIFT,
+mada, NUMO, Moamalat, LyPay, OnePay, Sadad, and Tadawul** — are
+**third-party trademarks of their respective owners**.
+
+They are provided here ONLY as **simplified, schematic identification marks /
+placeholders** so that a user interface can label a payment method. They are:
+
+- **original, clean geometric placeholders** authored for Neptune Odyssey —
+  **NOT traced or copied** from any official logo artwork;
+- **NOT** pixel-exact reproductions of any official logo;
+- **NOT** licensed under the Neptune Odyssey Community License v1.0 (which covers
+  only the original monochrome icon set in `src/icons.ts`);
+- kept **separate** from the `ICONS` / `IconName` set on purpose.
+
+Each mark renders in three variants — `color`, `mono`, and `outline` — but all
+three remain placeholders.
+
+The Libyan / local marks (**NUMO, Moamalat, LyPay, OnePay, Sadad, Tadawul**) and
+the generic **mada**-style mark are **neutral placeholders** (a simple badge plus
+initials) — this package does not ship those brands' real assets.
+
+## In production
+
+Replace each brand mark with that brand's **official asset** — the supported path
+is `registerBrandMark(name, svg)` (or a per-variant `{ color, mono, outline }`),
+after which `brandMarkSvg()` and `<npt-brand-mark>` return your approved artwork.
+Use it strictly in accordance with the relevant brand / trademark owner's brand
+and usage guidelines. Use of a brand mark does not imply any endorsement,
+sponsorship, or affiliation. Neptune.Fintech claims no rights in these
+third-party trademarks.

package/README.md

@@ -55,6 +55,98 @@ registerIcons(); // browser-only, idempotent
 Reactive attributes: `name`, `size` (px, default 24), `stroke` (default 1.8).
 Override colour with the `--npt-icon-color` custom property or plain `color`.
 
+## Brand marks (third-party trademarks)
+
+> **Trademark notice.** The payment-network & fintech brand marks
+> (Visa, Mastercard, Amex, Discover, UnionPay, Western Union, MoneyGram,
+> Apple Pay, Google Pay, PayPal, SWIFT, mada, NUMO, Moamalat, LyPay, OnePay,
+> Sadad, Tadawul, …) are **third-party trademarks of their respective owners**,
+> provided here as **simplified identification marks / placeholders only**. They
+> are original, clean geometric placeholders (**never traced** from official
+> artwork) and are **NOT** licensed under the Neptune Odyssey Community License.
+> In production, register each brand's **official asset** with
+> [`registerBrandMark()`](#use-your-own-official-logos) per that brand's brand
+> guidelines. The Libyan/local marks are neutral placeholders to be replaced with
+> official assets. See [`NOTICE-brand-marks.md`](./NOTICE-brand-marks.md).
+
+Brand marks live in a separate module — they return a **complete** `<svg>` (with
+their own `viewBox`), not inner markup, and are NOT in `ICONS` / `IconName`. The
+bundled marks are **original, simplified geometric placeholders** (never traced
+from official artwork).
+
+### Three variants
+
+Every mark renders in three variants via `brandMarkSvg(name, { variant })`:
+
+| Variant   | What it is                                                              |
+| --------- | ---------------------------------------------------------------------- |
+| `color`   | Multicolour brand colours. **The default.** Not themeable.             |
+| `mono`    | A single flat silhouette in `currentColor` — themeable like an icon.   |
+| `outline` | Line style: `stroke="currentColor"`, `fill="none"`, round joins — themeable. |
+
+```ts
+import { brandMarkSvg, BRAND_MARK_NAMES, register } from "@neptune.fintech/icons";
+
+// full <svg> string, sized to a height (width preserves aspect ratio)
+document.querySelector("#pm")!.innerHTML = brandMarkSvg("visa", { height: 24 });
+
+// mono / outline track `currentColor`, so they theme like the icon set
+brandMarkSvg("mastercard", { variant: "mono", height: 24 });
+brandMarkSvg("onepay", { variant: "outline", height: 24, class: "pm" });
+
+// custom element — register() wires up BOTH <npt-icon> and <npt-brand-mark>
+register();
+```
+
+```html
+<npt-brand-mark name="mastercard" height="24"></npt-brand-mark>
+<npt-brand-mark name="apple-pay" height="20" variant="mono"></npt-brand-mark>
+<npt-brand-mark name="lypay" height="24" variant="outline"></npt-brand-mark>
+```
+
+### Use your own official logos
+
+The bundled marks are **identification placeholders**. If you are licensed to use
+a brand's official logo, drop it in with `registerBrandMark()` — after that,
+`brandMarkSvg(name, { variant })` (and `<npt-brand-mark>`) return **your**
+approved artwork:
+
+```ts
+import { registerBrandMark, brandMarkSvg } from "@neptune.fintech/icons";
+
+// one SVG covers all three variants
+registerBrandMark("visa", officialVisaSvg);
+
+// …or supply a per-variant set (missing variants fall back across the others)
+registerBrandMark("mastercard", {
+  color: officialMastercardColorSvg,
+  mono: officialMastercardMonoSvg,
+  outline: officialMastercardOutlineSvg,
+});
+
+brandMarkSvg("visa", { height: 24 });            // → your official Visa SVG
+brandMarkSvg("mastercard", { variant: "mono" }); // → your mono Mastercard SVG
+```
+
+`registerBrandMark(name, svg)` also accepts an arbitrary `name` string, so you can
+register brands that aren't bundled (then render them with `brandMarkSvg(name)`).
+**Licensed users SHOULD register official assets** and follow each brand's usage
+guidelines; the bundled marks are placeholders only.
+
+| Export             | Description                                                       |
+| ------------------ | ---------------------------------------------------------------- |
+| `brandMarkSvg`     | `(name, { variant?, height?, class? }) => string` — full `<svg>`. Throws on unknown name with no override. |
+| `registerBrandMark`| `(name, svg \| { color?, mono?, outline? }) => void` — install an official/own override. |
+| `unregisterBrandMark` | `(name) => void` — remove a registered override.             |
+| `hasBrandMarkOverride` | `(name) => boolean` — true when an override is registered.   |
+| `isBrandMarkName`  | `(name) => boolean` type guard for `BrandMarkName`.              |
+| `BRAND_MARKS`      | `Record<BrandMarkName, string>` — complete `color`-variant `<svg>` per mark. |
+| `BRAND_MARK_NAMES` | `BrandMarkName[]` — the roster, in catalogue order.             |
+| `BrandMarkName`    | Union type of every brand-mark name.                            |
+| `BrandMarkVariant` | `"color" \| "mono" \| "outline"`.                              |
+| `NptBrandMark`     | The `<npt-brand-mark>` custom-element class.                    |
+| `registerBrandMarks` / `register` | Register `<npt-brand-mark>` (and `register()` both elements). |
+
 ## Theming
 
 There is nothing to configure. Because each glyph uses `currentColor`, it
@@ -73,7 +165,7 @@ for free.
 | `IconName`       | Union type of every icon name.                                    |
 | `NptIcon`        | The `<npt-icon>` custom-element class.                            |
 | `registerIcons`  | Registers `<npt-icon>` (browser-only, idempotent).               |
-| `ICONS_VERSION`  | `"2.0.0"`.                                                        |
+| `ICONS_VERSION`  | `"2.2.0"`.                                                        |
 
 ## Icon list
 
@@ -86,7 +178,9 @@ for free.
 `trending-up`, `trending-down`, `savings`, `calendar`, `clock`, `location`,
 `phone`, `mail`, `support`, `chevron-right`, `chevron-down`, `arrow-right`,
 `arrow-left`, `menu`, `more-horizontal`, `more-vertical`, `copy`, `share`,
-`logout`, `language`, `moon`, `sun`.
+`logout`, `language`, `moon`, `sun`, `atm`, `pos-terminal`, `coins`,
+`cash-stack`, `invoice`, `pie-budget`, `exchange-rate`, `crypto`, `loan`,
+`insurance`, `split-bill`, `tap-to-pay`.
 
 ## License
 

package/dist/brand-marks.d.ts

@@ -0,0 +1,59 @@
+/** Every payment / fintech brand mark shipped (identification placeholders). */
+export type BrandMarkName = "visa" | "mastercard" | "amex" | "discover" | "unionpay" | "western-union" | "moneygram" | "numo" | "moamalat" | "lypay" | "onepay" | "sadad" | "tadawul" | "apple-pay" | "google-pay" | "paypal" | "swift" | "mada" | "generic-card" | "contactless-pay" | "cash" | "bank-building";
+/** The three render variants every brand mark supports. */
+export type BrandMarkVariant = "color" | "mono" | "outline";
+/** All brand-mark names, in catalogue order. */
+export declare const BRAND_MARK_NAMES: BrandMarkName[];
+/** True when `name` is a known brand mark. Acts as a type guard. */
+export declare function isBrandMarkName(name: string): name is BrandMarkName;
+/** Per-variant override entry. A bare string fills all three variants. */
+interface OverrideEntry {
+    color?: string;
+    mono?: string;
+    outline?: string;
+}
+/**
+ * Register a brand's OFFICIAL, licensed SVG, overriding the bundled placeholder.
+ *
+ * Licensed users SHOULD call this to render approved official artwork:
+ *   registerBrandMark("visa", officialVisaSvg);              // all variants
+ *   registerBrandMark("visa", { color, mono, outline });     // per-variant
+ *
+ * After registration, brandMarkSvg(name, { variant }) returns the override,
+ * falling back across variants when only some are provided
+ * (color → mono → outline, whichever exists). <npt-brand-mark> uses it too.
+ *
+ * `name` is typed as BrandMarkName | string so you may also register your own
+ * additional brands (then render them via brandMarkSvg(yourName)).
+ */
+export declare function registerBrandMark(name: BrandMarkName | string, svg: string | OverrideEntry): void;
+/** Remove a previously registered override (mainly for tests/tooling). */
+export declare function unregisterBrandMark(name: BrandMarkName | string): void;
+/** True when an official-asset override has been registered for `name`. */
+export declare function hasBrandMarkOverride(name: string): boolean;
+export interface BrandMarkOptions {
+    /** Render variant. Default "color". */
+    variant?: BrandMarkVariant;
+    /** Rendered height in px; width scales to preserve the mark's aspect ratio. */
+    height?: number;
+    /** Optional class attribute placed on the root <svg>. */
+    class?: string;
+}
+/**
+ * Return the complete <svg> for `name`, in the requested variant, sized to a
+ * height. Aspect ratio is preserved from the mark's intrinsic viewBox.
+ *
+ * If an official asset was registered via registerBrandMark(), that override is
+ * returned (with width/height sized to `height`), falling back across variants.
+ *
+ * @throws RangeError when `name` is not a known BrandMarkName and has no override.
+ */
+export declare function brandMarkSvg(name: BrandMarkName, opts?: BrandMarkOptions): string;
+/**
+ * BRAND_MARKS — name → complete multicolour ("color" variant) <svg> string.
+ * Kept as a convenience map (back-compat). For mono/outline or overrides, use
+ * brandMarkSvg(name, { variant }).
+ */
+export declare const BRAND_MARKS: Record<BrandMarkName, string>;
+export {};
+//# sourceMappingURL=brand-marks.d.ts.map

package/dist/brand-marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-marks.d.ts","sourceRoot":"","sources":["../src/brand-marks.ts"],"names":[],"mappings":"AA+BA,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAErB,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,UAAU,GAEV,eAAe,GACf,WAAW,GAEX,MAAM,GACN,UAAU,GACV,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GAET,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,MAAM,GACN,cAAc,GACd,iBAAiB,GACjB,MAAM,GACN,eAAe,CAAC;AAEpB,2DAA2D;AAC3D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAqrB5D,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAuB3C,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAkLD,0EAA0E;AAC1E,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,GAAG,MAAM,EAC5B,GAAG,EAAE,MAAM,GAAG,aAAa,GAC1B,IAAI,CAGN;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAEtE;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAiBD,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAgBrF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAMrD,CAAC"}