Document URLPattern() constructor ignoreCase option (#22792)

Co-authored-by: Michael[tm] Smith <[email protected]>

files/en-us/web/api/url_pattern_api/index.md

@@ -353,6 +353,26 @@ there are some pattern representations that parse to the same underlying
 meaning, like `foo` and `{foo}`. Such cases are normalized to the simplest form.
 In this case `{foo}` gets changed to `foo`.
 
+## Case sensitivity
+
+The URL Pattern API treats many parts of the URL as case-sensitive by default when matching. In contrast, many client-side JavaScript frameworks use case-insensitive URL matching. An `ignoreCase` option is available on the {{domxref("URLPattern.URLPattern", "URLPattern()")}} constructor to enable case-insensitive matching if desired.
+
+```js
+// Case-sensitive matching by default
+const pattern = new URLPattern('https://events.com/2022/feb/*');
+console.log(pattern.test('https://events.com/2022/feb/xc44rsz')); // true
+console.log(pattern.test('https://events.com/2022/Feb/xc44rsz')); // false
+```
+
+Setting the `ignoreCase` option to `true` in the constructor switches all matching operations to case-insensitive for the given pattern:
+
+```js
+// Case-insensitive matching
+const pattern = new URLPattern('https://events.com/2022/feb/*', { ignoreCase : true });
+console.log(pattern.test('https://events.com/2022/feb/xc44rsz')); // true
+console.log(pattern.test('https://events.com/2022/Feb/xc44rsz')); // true
+```
+
 ## Examples
 
 ### Filter on a specific URL component

files/en-us/web/api/urlpattern/urlpattern/index.md

@@ -25,60 +25,81 @@ object representing the url pattern defined by the parameters.
 ```js-nolint
 new URLPattern(input)
 new URLPattern(input, baseURL)
+new URLPattern(input, options)
+new URLPattern(input, baseURL, options)
 ```
 
 ### Parameters
 
 - `input`
-  - : The pattern that will be used for matching. This can either be a
+  - : The input pattern that will be used for matching. This can either be a
     string, or an object providing patterns for each URL part
-    individually. The object members can be any of `protocol`, `username`,
-    `password`, `hostname`, `port`, `pathname`, `search`, `hash`, or `baseURL`.
-    Omitted parts in the object will be treated as wildcards (`*`).
+    individually. The object members can be any of:
+    - `protocol`
+    - `username`
+    - `password`
+    - `hostname`
+    - `port`
+    - `pathname`
+    - `search`
+    - `hash`
+    - `baseURL`
+    > **Note:** Omitted parts of the object will be treated as wildcards (`*`).
 - `baseURL` {{Optional_Inline}}
   - : A string representing the base URL to use in cases where
     `input` is a relative pattern. If not specified, it defaults to `undefined`.
+- `options` {{Optional_Inline}}
+  - : An object providing options for matching the given pattern. The possible object members are as follows:
+    - `ignoreCase`
+      - Enables case-insensitive matching if set to `true`. If omitted or set to `false`, matching will be case-sensitive.
 
 ### Exceptions
 
 - {{jsxref("TypeError")}}
   - : Indicates one of the following:
-    - The given pattern or base URL is not valid or syntactically correct.
+    - The given `input` or `baseURL` is not valid or syntactically correct.
+    - The given `input` is relative, but no `baseURL` is provided to form a complete absolute URL.
     - A `baseURL` is provided, and input is an absolute pattern or a structured object.
 
 ## Examples
 
+### Matching a pathname
+
 ```js
-// Matching a pathname
 let pattern1 = new URLPattern('https://example.com/books/:id')
+
 // same as
 let pattern2 = new URLPattern(
   '/books/:id',
   'https://example.com',
 );
+
 // or
 let pattern3 = new URLPattern({
   protocol: 'https',
   hostname: 'example.com',
   pathname: '/books/:id',
 });
+
 // or
 let pattern4 = new URLPattern({
   pathname: '/books/:id',
   baseURL: 'https://example.com',
 });
 ```
 
+### Match the protocol and hostname
+
 ```js
-// Match the protocol and hostname
 let pattern = new URLPattern({
   protocol: 'http{s}?',
   hostname: ':subdomain.example.com',
 });
 ```
 
+### Match all possible structured parts
+
 ```js
-// Match all possible structured parts
 let pattern = new URLPattern({
   protocol: 'http{s}?',
   username: ':username',
@@ -91,9 +112,27 @@ let pattern = new URLPattern({
 });
 ```
 
+### Case-insensitive matching
+
+```js
+// Case-sensitive matching by default
+const pattern = new URLPattern('https://events.com/2022/feb/*');
+console.log(pattern.test('https://events.com/2022/feb/xc44rsz')); // true
+console.log(pattern.test('https://events.com/2022/Feb/xc44rsz')); // false
+```
+
+Setting the `ignoreCase` option to `true` in the constructor switches all matching operations to case-insensitive for the given pattern:
+
+```js
+// Case-insensitive matching
+const pattern = new URLPattern('https://events.com/2022/feb/*', { ignoreCase : true });
+console.log(pattern.test('https://events.com/2022/feb/xc44rsz')); // true
+console.log(pattern.test('https://events.com/2022/Feb/xc44rsz')); // true
+```
+
 ## Usage notes
 
-The `URLPattern` constructor has two forms. The constructor either takes a
+The `URLPattern` constructor's input pattern can take two forms — a
 pattern object, or a pattern string and optional baseURL.
 
 ```js
@@ -102,19 +141,19 @@ new URLPattern(pattern);
 new URLPattern(pattern, baseURL);
 ```
 
-The first type of constructor (see above) takes an object that describes the
+The first type of constructor takes an object that describes the
 URLs that should be matched by specifying patterns for each individual URL part.
 Its members can be any of `protocol`, `username`, `password`, `hostname`,
-`port`, `pathname`, `search`, `hash`, or `baseURL`. If the baseURL property is
+`port`, `pathname`, `search`, `hash`, or `baseURL`. If the `baseURL` property is
 provided it will be parsed as a URL and used to populate any other properties
-that are missing. If the baseURL property is missing, then any other missing
+that are missing. If the `baseURL` property is missing, then any other missing
 properties default to the pattern `*` wildcard, accepting any input.
 
-The second type of constructor (see above) takes a URL string that contains
-patterns embedded in it. The URL string may be relative if a base URL is
-provided as the second argument. Note, it may be necessary to escape some
-characters in the URL string where its ambiguous whether the character is
-separating different URL components or if it's instead part of a pattern. For
+The second type of constructor takes a URL string that contains
+patterns embedded in it. The URL string may be relative if a `baseURL` is
+provided as the second argument. Note that it may be necessary to escape some
+characters in the URL string if it is ambiguous whether the character is
+separating different URL components or is part of a pattern. For
 example, you must write `about\\:blank` to indicate that the `:` is the protocol
 suffix and not the start of a `:blank` named group pattern.