Change wrap property to namespace enum

Replace the `wrap` property with a `namespace` property that accepts
a type-safe enum ('html' | 'svg' | 'mathml') instead of an arbitrary
tag name. The namespace defaults to 'html', matching the current
default behavior.

tidy

Tweak the description in the ADR

omit word

remove unneeded `as const`

ADR: for clarity, use backticks rather than quotes when enumerating possible values for the namespace option

update the namespace validity check to a form that typescript can use for narrowing

remove link to namespaceURI docs since the namespace option does not directly allow specifying namespaces (the connection can be elucidated in the user-facing docs)

Author: yurivish

library/src/plugins/watchers/patchElements.ts

@@ -18,19 +18,27 @@ type PatchElementsMode =
   | 'before'
   | 'after'
 
+const namespaceToTag = {
+  'html': '',
+  'svg': 'svg',
+  'mathml': 'math'
+}
+
+type Namespace = keyof typeof namespaceToTag
+
 type PatchElementsArgs = {
   elements: string
   mode: PatchElementsMode
   selector: string
   useViewTransition: boolean
-  wrap: string
+  namespace: Namespace
 }
 
 watcher({
   name: 'datastar-patch-elements',
   apply(
     ctx,
-    { elements = '', selector = '', mode = 'outer', useViewTransition = '', wrap = '' },
+    { elements = '', selector = '', mode = 'outer', useViewTransition = '', namespace = 'html' },
   ) {
     switch (mode) {
       case 'remove':
@@ -50,12 +58,16 @@ watcher({
       throw ctx.error('PatchElementsExpectedSelector')
     }
 
+    if (!(namespace === 'html' || namespace === 'svg' || namespace === 'mathml')) {
+      throw ctx.error('PatchElementsInvalidNamespace', { namespace })
+    }
+
     const args2: PatchElementsArgs = {
       mode,
       selector,
       elements,
       useViewTransition: useViewTransition.trim() === 'true',
-      wrap,
+      namespace
     }
 
     if (supportsViewTransitions && useViewTransition) {
@@ -68,8 +80,10 @@ watcher({
 
 const onPatchElements = (
   { error }: WatcherContext,
-  { elements, selector, mode, wrap }: PatchElementsArgs,
+  { elements, selector, mode, namespace }: PatchElementsArgs,
 ) => {
+  const wrap = namespaceToTag[namespace]
+
   const elementsWithSvgsRemoved = elements.replace(
     /<svg(\s[^>]*>|>)([\s\S]*?)<\/svg>/gim,
     '',

sdk/ADR.md

@@ -109,7 +109,7 @@ ServerSentEventGenerator.PatchElements(
     selector?: string,
     mode?: ElementPatchMode,
     useViewTransition?: boolean,
-    wrap?: string,
+    namespace?: 'html' | 'svg' | 'mathml',
     eventId?: string,
     retryDuration?: durationInMilliseconds
   }
@@ -138,7 +138,7 @@ ServerSentEventGenerator.PatchElements(
   data: mode inner
   data: selector #feed
   data: useViewTransition true
-  data: wrap div
+  data: namespace html
   data: elements <div id="feed">
   data: elements     <span>1</span>
   data: elements </div>
@@ -184,7 +184,7 @@ ServerSentEventGenerator.PatchElements(
   event: datastar-patch-elements
   data: mode append
   data: selector #vis
-  data: wrap svg
+  data: namespace svg
   data: elements <circle id="c1" cx="10" r="5" fill="red"/>
   data: elements <circle id="c2" cx="20" r="5" fill="green"/>
   data: elements <circle id="c3" cx="30" r="5" fill="blue"/>
@@ -234,7 +234,7 @@ String enum defining how elements are patched into the DOM.
 | `selector` | string | Element ID | CSS selector for target element. If a selector is not specified, each element must have an ID specified. |
 | `mode` | ElementPatchMode | `outer` | How to patch the element |
 | `useViewTransition` | boolean | `false` | Enable view transitions API |
-| `wrap` | string | Tag name | Tag name used to control the [namespace](https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI) of any new elements. If a tag name is not specified, elements will be created in the HTML namespace. |
+| `namespace` | `html` \| `svg` \| `mathml` | `html` | Namespace in which to create new elements |
 
 ### Implementation
 
@@ -244,7 +244,7 @@ String enum defining how elements are patched into the DOM.
 - `selector SELECTOR\n` (if provided)
 - `mode PATCH_MODE\n` (if not `outer`)
 - `useViewTransition true\n` (if `true`)
-- `wrap TAG_NAME\n` (if provided)
+- `namespace NAMESPACE\n` (if not `html`)
 - `elements HTML_LINE\n` (for each line of HTML)
 
 ---