From c815458f9fb41cb63401fbc826d00c94a76f1083 Mon Sep 17 00:00:00 2001
From: solomonkinard <solomon@kinard.com>
Date: Wed, 1 May 2024 10:36:09 -0700
Subject: [PATCH] Moved schema to examples, added a generic schema, and a comma

This incorporates the kernel of what Simeon discussed in WECG and
recommended in
https://github.com/w3c/webextensions/pull/585#issuecomment-2077956982.
It's not meant to replace that comment, but only to introduce it here
for clarity, while allowing Simeon to update it as needed once this PR
is merged.

Added a fuzzy matching section again even though someone suggested it
be removed earlier. It was introduced in 6e6af62a8503, but removed in a
subsequent "Commit suggestion" from somoene on GitHub. It's worth
calling out here at some point, so it might as well be in this PR,
which is already approved but still awaiting someone with the ability
to go ahead and merge it.

Some of these changes may foster discussion, which is completely
understandable.
---
 proposals/dark_mode_extension_icons.md | 53 +++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/proposals/dark_mode_extension_icons.md b/proposals/dark_mode_extension_icons.md
index 402e5029..27f1fbd1 100644
--- a/proposals/dark_mode_extension_icons.md
+++ b/proposals/dark_mode_extension_icons.md
@@ -10,7 +10,7 @@ Feature to enable developers to enhance extension icon visibility in dark mode.
 
 **Sponsoring Browser:** Chromium
 
-**Contributors:** oliverdunk, xeenon, carlosjeurissen, hanguokai
+**Contributors:** oliverdunk, xeenon, carlosjeurissen, hanguokai, dotproto
 
 **Created:** 2024-04-05
 
@@ -45,6 +45,44 @@ The Chromium bug has a significant amount of developer interest.
 
 ### Schema
 
+manifest.json
+```
+type ImagePath = string;
+type ColorScheme = "light" | "dark";
+
+interface IconVariantsBase {
+  color_scheme?: ColorScheme | ColorScheme[];
+}
+
+interface IconVariantsManifest extends IconVariantsBase {
+  any?: ImagePath;
+  [index: number]: ImagePath;
+}
+
+interface ManifestAction {
+  [icon_variants: string]: IconVariantsManifest;
+}
+
+interface ExtensionManifest {
+  icon_variants: IconVariantsManifest[];
+  action: Action;
+}
+```
+
+action.setIcon
+```
+interface SetIconVariantsApiDetails extends IconVariantsBase {
+  any?: ImagePath | ImageData;
+  [index: number]: ImagePath | ImageData;
+}
+
+interface SetIconVariantsApi {
+  [variants: string]: ActionIconVariants;
+}
+```
+
+### Examples
+
 manifest.json
 ```
 "icon_variants": [
@@ -65,7 +103,10 @@ manifest.json
     "32": "light32.png",
     "color_scheme": ["dark", "light"]
   }
-]
+],
+"action": {
+  "icon_variants": [...]
+}
 ```
   `icon_variants` requires an array with a set of icon groups objects. Each icon
 group consists of a set of icon paths and icon group matching criteria.
@@ -185,7 +226,9 @@ warning. For example, `color_scheme: ["unknown"]` will be treated as an empty
 array. An empty array means the browser should mark the icon group as invalid
 and ignore it.
 1. If only one icon object is defined with a specific color scheme, that icon
-object will be applied to all color schemes. It will be the icon used.
+object will be applied to all color schemes.
+1. **Fuzzy matching** Inexact size matches will return the icon closest in size,
+starting with smaller sizes if available, retreating to the nearest larger size.
 
 **Size**
 1. The `"16"` is a size in `{"16": "icon.png"}` and any number can be used as a
@@ -199,7 +242,7 @@ the next largest pixel size or `"any"` will be used.
 1. **Vector images**: Sizes are in points, ensuring device independence. If the
 exact point size is unavailable, an integer multiple (e.g. 32, 48, etc.) or
 `"any"` will be used.
-* If none of the specified icon groups have matching criteria, browsers should
+1.  If none of the specified icon groups have matching criteria, browsers should
 drop matching criteria in a specified order until it finds a group which results
 in a match. It will start by dropping any matching criteria which are
 unsupported/unknown. If still no match could be made, it will drop known
@@ -213,7 +256,7 @@ action. If not specified, it falls back to default_icon, then to the top-level
 `icon_variants` or icons.
 1. `action.setIcon({variants})` will not throw when giving it icon groups with
 properties it does not understand. Those icon groups will simply be ignored for
-making matches. If however none of the icon groups are supported, an exception
+making matches. If however, none of the icon groups are supported, an exception
 will be thrown allowing both feature detection and specifying fallbacks without
 requiring feature detection.