fix(docs): exposes svg api on playground

Author: justin-schroeder

docs/play/arrow-types.d.ts

@@ -114,6 +114,10 @@ declare module '@arrow-js/core' {
     strings: TemplateStringsArray | string[],
     ...expressions: unknown[]
   ): ArrowTemplate
+  export function svg(
+    strings: TemplateStringsArray | string[],
+    ...expressions: unknown[]
+  ): ArrowTemplate
   export { html as t }
 
   export function reactive<T extends ReactiveTarget>(data: T): Reactive<T>
@@ -406,6 +410,7 @@ type SsrRenderResult = import('@arrow-js/ssr').SsrRenderResult
 
 declare const html: typeof import('@arrow-js/core').html
 declare const reactive: typeof import('@arrow-js/core').reactive
+declare const svg: typeof import('@arrow-js/core').svg
 declare const watch: typeof import('@arrow-js/core').watch
 declare const nextTick: typeof import('@arrow-js/core').nextTick
 declare const component: typeof import('@arrow-js/core').component

docs/play/preview.js

@@ -18,6 +18,7 @@ export const pick = mod.pick
 export const props = mod.props
 export const r = mod.r
 export const reactive = mod.reactive
+export const svg = mod.svg
 export const t = mod.t
 export const w = mod.w
 export const watch = mod.watch

docs/src/pages/docs/content.ts

@@ -844,6 +844,20 @@ export function Routing() {
             render the same page shape.
           </li>
         </ul>
+        <p>
+          For browser-only routing, Arrow recommends the native
+          <a
+            href="https://developer.mozilla.org/en-US/docs/Web/API/Navigation"
+            target="_blank"
+            rel="noopener"
+            >Navigation API</a
+          >
+          via <code>window.navigation</code> when your support matrix allows it.
+          It gives you a single navigation event stream and more reliable
+          history traversal than wiring everything around the older
+          <code>history.pushState()</code> flow. Keep a History API fallback if
+          you still support older browsers.
+        </p>
 
         ${TsCodeBlock(`import { html } from '@arrow-js/core'
 

packages/sandbox/src/compiler/module.ts

@@ -7,13 +7,14 @@ import {
 } from './scope'
 import type { ESTreeNode } from './scope'
 import { compileTemplateDescriptor } from './template'
-import type { TemplateDescriptor } from '../shared/protocol'
+import type { ElementNamespace, TemplateDescriptor } from '../shared/protocol'
 import { SandboxCompileError } from '../host/errors'
 
 const supportedImports = new Set([
   'component',
   'c',
   'html',
+  'svg',
   't',
   'onCleanup',
   'pick',
@@ -70,24 +71,25 @@ function readImportBindings(program: ESTreeNode) {
   }
 }
 
-function isArrowTagIdentifier(
+function getArrowTagNamespace(
   node: ESTreeNode,
   coreLocals: Map<string, string>,
   missingImports: Set<string>,
   isBound: (name: string) => boolean
-) {
-  if (node.type !== 'Identifier') return false
+): ElementNamespace | 'html' | null {
+  if (node.type !== 'Identifier') return null
 
   const local = String(node.name)
   const imported = coreLocals.get(local)
-  if (imported === 'html' || imported === 't') return true
+  if (imported === 'svg') return 'svg'
+  if (imported === 'html' || imported === 't') return 'html'
 
-  if ((local === 'html' || local === 't') && !isBound(local)) {
+  if ((local === 'html' || local === 'svg' || local === 't') && !isBound(local)) {
     missingImports.add(local)
-    return true
+    return local === 'svg' ? 'svg' : 'html'
   }
 
-  return false
+  return null
 }
 
 export function preprocessModule(
@@ -103,7 +105,10 @@ export function preprocessModule(
   const { coreLocals, lastImportEnd } = readImportBindings(program)
   const missingImports = new Set<string>()
   const descriptors: TemplateDescriptor[] = []
-  const taggedTemplates: ESTreeNode[] = []
+  const taggedTemplates: Array<{
+    expression: ESTreeNode
+    namespace?: ElementNamespace
+  }> = []
 
   collectReferences(program, analysis, (node, scope, parent) => {
     if (
@@ -117,9 +122,15 @@ export function preprocessModule(
     if (node.type === 'TaggedTemplateExpression') {
       const tag = asNode(node.tag)
       const isBound = (name: string) => analysis.isNameBound(scope, name)
-
-      if (tag && isArrowTagIdentifier(tag, coreLocals, missingImports, isBound)) {
-        taggedTemplates.push(node)
+      const tagNamespace = tag
+        ? getArrowTagNamespace(tag, coreLocals, missingImports, isBound)
+        : null
+
+      if (tagNamespace) {
+        taggedTemplates.push({
+          expression: node,
+          namespace: tagNamespace === 'svg' ? 'svg' : undefined,
+        })
         return
       }
 
@@ -129,18 +140,21 @@ export function preprocessModule(
         coreLocals.has(String(asNode(tag.object)?.name))
       ) {
         throw new SandboxCompileError(
-          'Namespace-style Arrow html tags are not supported in @arrow-js/sandbox.'
+          'Namespace-style Arrow template tags are not supported in @arrow-js/sandbox.'
         )
       }
     }
   })
 
   const output = new MagicString(source)
 
-  taggedTemplates.sort((left, right) => (right.start || 0) - (left.start || 0))
+  taggedTemplates.sort(
+    (left, right) =>
+      (right.expression.start || 0) - (left.expression.start || 0)
+  )
   let templateIndex = 0
 
-  for (const expression of taggedTemplates) {
+  for (const { expression, namespace } of taggedTemplates) {
     const quasi = expression.quasi as ESTreeNode
     const strings = (quasi.quasis as ESTreeNode[]).map((part) =>
       String((part.value as any).cooked ?? (part.value as any).raw ?? '')
@@ -149,7 +163,9 @@ export function preprocessModule(
       output.slice(part.start || 0, part.end || 0)
     )
     const descriptorId = `${path}#template:${templateIndex++}`
-    descriptors.push(compileTemplateDescriptor(descriptorId, strings))
+    descriptors.push(
+      compileTemplateDescriptor(descriptorId, strings, namespace)
+    )
 
     output.overwrite(
       expression.start || 0,

packages/sandbox/src/compiler/template.ts

@@ -1,5 +1,6 @@
 import type {
   AttributeBindingDescriptor,
+  ElementNamespace,
   ElementDescriptor,
   TemplateDescriptor,
   TemplateNodeDescriptor,
@@ -10,6 +11,7 @@ import { SandboxCompileError } from '../host/errors'
 const expressionTokenPrefix = '__ARROW_SANDBOX_EXPR_'
 const expressionTokenSuffix = '__'
 const expressionPattern = /__ARROW_SANDBOX_EXPR_(\d+)__/g
+const svgNamespaceUri = 'http://www.w3.org/2000/svg'
 
 function getExpressionToken(index: number) {
   return `${expressionTokenPrefix}${index}${expressionTokenSuffix}`
@@ -162,6 +164,8 @@ function compileElementNode(element: Element): ElementDescriptor {
   return {
     kind: 'element',
     tag: element.tagName.toLowerCase(),
+    namespace:
+      element.namespaceURI === svgNamespaceUri ? 'svg' : undefined,
     staticAttributes,
     dynamicAttributes,
     eventBindings,
@@ -224,7 +228,8 @@ function collectExpressionIndexes(
 
 export function compileTemplateDescriptor(
   templateId: string,
-  strings: string[]
+  strings: string[],
+  namespace?: ElementNamespace
 ): TemplateDescriptor {
   if (typeof document === 'undefined') {
     throw new SandboxCompileError(
@@ -238,7 +243,17 @@ export function compileTemplateDescriptor(
   }, '')
 
   const template = document.createElement('template')
-  template.innerHTML = html
+  if (namespace === 'svg') {
+    template.innerHTML = `<svg xmlns="${svgNamespaceUri}">${html}</svg>`
+    const root = template.content.firstChild as SVGElement | null
+    if (root) {
+      const content = template.content
+      while (root.firstChild) content.appendChild(root.firstChild)
+      content.removeChild(root)
+    }
+  } else {
+    template.innerHTML = html
+  }
 
   const rootCandidates = Array.from(template.content.childNodes)
     .flatMap((node) => compileDomNode(node))

packages/sandbox/src/host/renderer.ts

@@ -5,6 +5,8 @@ import type {
   VmPatch,
 } from '../shared/protocol'
 
+const svgNamespaceUri = 'http://www.w3.org/2000/svg'
+
 interface RegionAnchor {
   start: Comment
   end: Comment
@@ -71,7 +73,10 @@ export class HostRenderer {
         return fragment
       }
       case 'element': {
-        const element = document.createElement(serialized.tag)
+        const element =
+          serialized.namespace === 'svg'
+            ? document.createElementNS(svgNamespaceUri, serialized.tag)
+            : document.createElement(serialized.tag)
         this.nodes.set(serialized.id, element)
         this.nodeIds.set(element, serialized.id)
 

packages/sandbox/src/index.spec.ts

@@ -549,6 +549,36 @@ describe('@arrow-js/sandbox', () => {
     instance.destroy()
   })
 
+  it('supports unbound svg tagged templates in sandbox modules', async () => {
+    const root = document.createElement('div')
+
+    const instance = await sandbox(
+      `
+        const data = reactive({ values: [40, 20] })
+
+        export default html\`<svg width="100" height="100" viewBox="0 0 100 100">
+          \${() =>
+            data.values.map(
+              (value, index) => svg\`<rect
+                x="\${index * 10}"
+                y="\${100 - value}"
+                width="9"
+                height="\${value}"
+                fill="red"
+              />\`
+            )}
+        </svg>\`
+      `,
+      root
+    )
+
+    const rects = Array.from(root.querySelectorAll('rect'))
+    expect(rects).toHaveLength(2)
+    expect(rects[0]?.namespaceURI).toBe('http://www.w3.org/2000/svg')
+    expect(rects[1]?.getAttribute('height')).toBe('20')
+    instance.destroy()
+  })
+
   it('rejects namespace-style @arrow-js/core imports', async () => {
     const root = document.createElement('div')
 

packages/sandbox/src/shared/protocol.ts

@@ -86,9 +86,12 @@ export interface RefBindingDescriptor {
   exprIndex: number
 }
 
+export type ElementNamespace = 'svg'
+
 export interface ElementDescriptor {
   kind: 'element'
   tag: string
+  namespace?: ElementNamespace
   staticAttributes: Record<string, string>
   dynamicAttributes: AttributeBindingDescriptor[]
   eventBindings: EventBindingDescriptor[]
@@ -132,6 +135,7 @@ export interface SerializedElementNode {
   kind: 'element'
   id: string
   tag: string
+  namespace?: ElementNamespace
   attrs: Record<string, string | boolean>
   events: Record<string, string>
   children: SerializedNode[]

packages/sandbox/src/vm/generated-modules.ts

@@ -9,6 +9,7 @@ export {
   pick as props,
   reactive,
   reactive as r,
+  svg,
   watch,
   watch as w,
 } from './runtime'