@neptune.fintech/icons 2.1.0 → 2.3.0

package/NOTICE-brand-marks.md

@@ -10,19 +10,26 @@ mada, NUMO, Moamalat, LyPay, OnePay, Sadad, and Tadawul** — are
 They are provided here ONLY as **simplified, schematic identification marks /
 placeholders** so that a user interface can label a payment method. They are:
 
-- **NOT** original Neptune Odyssey artwork;
+- **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** and 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.
+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

@@ -62,15 +62,27 @@ Override colour with the `--npt-icon-color` custom property or plain `color`.
 > 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 **NOT** original Neptune Odyssey artwork and are **NOT** licensed under the
-> Neptune Odyssey Community License. In production use each brand's **official
-> assets 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).
+> 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 are **multicolour** and live in a separate module — they return a
-**complete** `<svg>` (with their own `viewBox`), not inner markup, and are NOT in
-`ICONS` / `IconName`.
+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";
@@ -78,22 +90,60 @@ 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"></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, { height? }) => string` — full `<svg>`. Throws on bad name. |
+| `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 `<svg>` per mark.     |
+| `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). |
 
@@ -115,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.1.0"`.                                                        |
+| `ICONS_VERSION`  | `"2.2.0"`.                                                        |
 
 ## Icon list
 

package/dist/brand-marks.d.ts

@@ -1,25 +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";
-/**
- * name → complete multicolour <svg> string.
- *
- * Card-ratio canvas (viewBox 0 0 48 32) for wide marks; 32×32 for square
- * badges. A neutral card body (#F4F5F7 fill, #E1E3E8 hairline) frames most
- * marks so they sit well on any surface.
- */
-export declare const BRAND_MARKS: Record<BrandMarkName, string>;
+/** 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 multicolour <svg> for `name`, sized to a given height.
- * Aspect ratio is preserved from the mark's intrinsic viewBox.
- * @throws RangeError when `name` is not a known BrandMarkName.
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"brand-marks.d.ts","sourceRoot":"","sources":["../src/brand-marks.ts"],"names":[],"mappings":"AAwBA,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;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAkJrD,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAuB3C,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAkBrF"}
+{"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;AAslB5D,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"}