docs: Integrate renderContext documentation and toggling

.changeset/bumpy-breads-rhyme.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+fix(GeoPath): Do not register with hit canavs unless pointer events (onclick, onpointermove, etc) or tooltipContext are defined

.changeset/huge-boats-fix.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+docs: Document each component's context support (svg, canvas, html) with interactive toggle

.changeset/ninety-ghosts-taste.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+breaking(Blur): Remove children snippet props (not needed and easier to support canvas in the future)

.changeset/pink-flies-worry.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+fix(Calendar|MonthPath): Support canvas by using `Spline` instead of `path`

.changeset/tangy-lies-strive.md

@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+breaking(Spline): Rename `splineRef` to `pathRef`

packages/layerchart/src/app.d.ts

@@ -19,6 +19,7 @@ declare namespace App {
       hideUsage?: boolean;
       hideTableOfContents?: boolean;
       status?: string;
+      supportedContexts?: Array<'svg' | 'canvas' | 'html'>;
     };
   }
 

packages/layerchart/src/lib/components/Arc.svelte

@@ -401,13 +401,13 @@
   <Spline
     pathData={trackArc()}
     stroke="none"
-    bind:splineRef={trackRef}
+    bind:pathRef={trackRef}
     {...extractLayerProps(track, 'arc-track')}
   />
 {/if}
 
 <Spline
-  bind:splineRef={ref}
+  bind:pathRef={ref}
   pathData={arc()}
   transform="translate({xOffset}, {yOffset})"
   {fill}

packages/layerchart/src/lib/components/Blur.svelte

@@ -14,9 +14,9 @@
 
     /**
      * The default children snippet which provides
-     * the id and url for the filter.
+     * the id for the filter.
      */
-    children?: Snippet<[{ id: string; url: string }]>;
+    children?: Snippet;
   };
 </script>
 
@@ -42,7 +42,9 @@
 
   {#if children}
     <g filter="url(#{id})" class={layerClass('blur-g')}>
-      {@render children({ id, url: `url(#${id})` })}
+      {@render children()}
     </g>
   {/if}
+{:else if children}
+  {@render children()}
 {/if}

packages/layerchart/src/lib/components/Connector.svelte

@@ -82,7 +82,7 @@
     type = 'rounded',
     radius = 20,
     curve = curveLinear,
-    splineRef = $bindable(),
+    pathRef = $bindable(),
     pathData: pathDataProp,
     marker,
     markerStart,
@@ -137,7 +137,7 @@
 
 <Spline
   pathData={motionPath.current}
-  bind:splineRef
+  bind:pathRef
   marker-start={markerStartId ? `url(#${markerStartId})` : undefined}
   marker-mid={markerMidId ? `url(#${markerMidId})` : undefined}
   marker-end={markerEndId ? `url(#${markerEndId})` : undefined}

packages/layerchart/src/lib/components/GeoPath.svelte

@@ -157,10 +157,11 @@
       name: 'GeoPath',
       render,
       events: {
-        click: _onClick,
-        pointerenter: _onPointerEnter,
-        pointermove: _onPointerMove,
-        pointerleave: _onPointerLeave,
+        // Only register events if they are defined (so they are not registered with hit canvas unnecessarily)
+        click: onclick ? _onClick : undefined,
+        pointerenter: restProps.onpointerenter || tooltipContext ? _onPointerEnter : undefined,
+        pointermove: restProps.onpointermove || tooltipContext ? _onPointerMove : undefined,
+        pointerleave: restProps.onpointerleave || tooltipContext ? _onPointerLeave : undefined,
         pointerdown: restProps.onpointerdown,
         touchmove: restProps.ontouchmove,
       },

packages/layerchart/src/lib/components/GeoPoint.svelte

@@ -1,7 +1,6 @@
 <script lang="ts" module>
   import type { Snippet } from 'svelte';
-  import type { SVGAttributes } from 'svelte/elements';
-  import Circle, { type CircleProps, type CirclePropsWithoutHTML } from './Circle.svelte';
+  import Circle, { type CircleProps } from './Circle.svelte';
   import type { Without } from '$lib/utils/types.js';
 
   export type GeoPointPropsWithoutHTML = {

packages/layerchart/src/lib/components/GeoSpline.svelte

@@ -42,13 +42,13 @@
     link,
     loft = 1.0,
     curve = curveNatural,
-    splineRef: splineRefProp = $bindable(),
+    pathRef: pathRefProp = $bindable(),
     ...restProps
   }: GeoSplineProps = $props();
 
-  let splineRef = $state<SVGPathElement>();
+  let pathRef = $state<SVGPathElement>();
   $effect.pre(() => {
-    splineRefProp = splineRef;
+    pathRefProp = pathRef;
   });
 
   const geoCtx = getGeoContext();
@@ -76,7 +76,7 @@
 </script>
 
 <Spline
-  bind:splineRef
+  bind:pathRef
   data={[source, middle, target]}
   x={(d) => d[0]}
   y={(d) => d[1]}

packages/layerchart/src/lib/components/MonthPath.svelte

@@ -20,30 +20,33 @@
      *
      * @bindable
      */
-    ref?: SVGPathElement;
+    pathRef?: SVGPathElement;
   };
 
   export type MonthPathProps = MonthPathPropsWithoutHTML &
-    Without<SVGAttributes<SVGPathElement>, MonthPathPropsWithoutHTML>;
+    // we omit the spline props to avoid conflicts with attribute names since we are
+    // passing them through to `<Spline />`
+    Without<SVGAttributes<SVGPathElement>, MonthPathPropsWithoutHTML & SplinePropsWithoutHTML>;
 </script>
 
 <script lang="ts">
   import { timeWeek, timeYear } from 'd3-time';
   import { endOfMonth } from 'date-fns';
   import { cls } from '@layerstack/tailwind';
   import { layerClass } from '$lib/utils/attributes.js';
+  import Spline, { type SplinePropsWithoutHTML } from './Spline.svelte';
 
   let {
     date,
     cellSize: cellSizeProp,
-    ref: refProp = $bindable(),
+    pathRef: pathRefProp = $bindable(),
     class: className,
     ...restProps
   }: MonthPathProps = $props();
 
-  let ref = $state<SVGPathElement>();
+  let pathRef = $state<SVGPathElement>();
   $effect.pre(() => {
-    refProp = ref;
+    pathRefProp = pathRef;
   });
 
   const cellSize = $derived(
@@ -68,9 +71,9 @@
   `);
 </script>
 
-<path
-  bind:this={ref}
-  d={pathData}
+<Spline
+  bind:pathRef
+  {pathData}
   fill="none"
   class={cls(layerClass('month-path'), 'stroke-surface-content/20', className)}
   {...restProps}

packages/layerchart/src/lib/components/Spline.svelte

@@ -103,7 +103,7 @@
      *
      * @bindable
      */
-    splineRef?: SVGPathElement;
+    pathRef?: SVGPathElement;
 
     motion?: MotionProp;
   } & CommonStyleProps;
@@ -159,14 +159,14 @@
     startContent,
     endContent,
     opacity,
-    splineRef: splineRefProp = $bindable(),
+    pathRef: pathRefProp = $bindable(),
     ...restProps
   }: SplineProps = $props();
 
-  let splineRef = $state<SVGPathElement>();
+  let pathRef = $state<SVGPathElement>();
 
   $effect.pre(() => {
-    splineRefProp = splineRef;
+    pathRefProp = pathRef;
   });
 
   const markerStart = $derived(markerStartProp ?? marker);
@@ -331,8 +331,8 @@
           easing: typeof draw === 'object' && draw.easing ? draw.easing : cubicInOut,
           interpolate() {
             return (t: number) => {
-              const totalLength = splineRef?.getTotalLength() ?? 0;
-              const point = splineRef?.getPointAtLength(totalLength * t);
+              const totalLength = pathRef?.getTotalLength() ?? 0;
+              const point = pathRef?.getPointAtLength(totalLength * t);
               return point;
             };
           },
@@ -343,10 +343,10 @@
   $effect(() => {
     if (!startContent && !endContent) return;
     d;
-    if (!splineRef || !splineRef.getTotalLength()) return;
-    startPoint = splineRef.getPointAtLength(0);
-    const totalLength = splineRef.getTotalLength();
-    endPoint.target = splineRef.getPointAtLength(totalLength);
+    if (!pathRef || !pathRef.getTotalLength()) return;
+    startPoint = pathRef.getPointAtLength(0);
+    const totalLength = pathRef.getTotalLength();
+    endPoint.target = pathRef.getPointAtLength(totalLength);
   });
 
   $effect(() => {
@@ -377,7 +377,7 @@
       marker-mid={markerMidId ? `url(#${markerMidId})` : undefined}
       marker-end={markerEndId ? `url(#${markerEndId})` : undefined}
       in:drawTransition|global={typeof draw === 'object' ? draw : undefined}
-      bind:this={splineRef}
+      bind:this={pathRef}
     />
     <MarkerWrapper id={markerStartId} marker={markerStart} />
     <MarkerWrapper id={markerMidId} marker={markerMid} />

packages/layerchart/src/lib/components/layout/Layer.svelte

@@ -3,17 +3,19 @@
 
   export type CanvasLayerProps = {
     type: 'canvas';
-  } & Omit<ComponentProps<typeof Canvas>, 'type'>;
+  } & Omit<ComponentProps<typeof Canvas>, 'type' | 'onpointermove'>;
 
   export type HtmlLayerProps = {
     type: 'html';
-  } & Omit<ComponentProps<typeof Html>, 'type'>;
+  } & Omit<ComponentProps<typeof Html>, 'type' | 'onpointermove'>;
 
   export type SvgLayerProps = {
     type: 'svg';
-  } & Omit<ComponentProps<typeof Svg>, 'type'>;
+  } & Omit<ComponentProps<typeof Svg>, 'type' | 'onpointermove'>;
 
-  export type LayerProps = CanvasLayerProps | HtmlLayerProps | SvgLayerProps;
+  export type LayerProps = (CanvasLayerProps | HtmlLayerProps | SvgLayerProps) & {
+    onpointermove?: (e: PointerEvent) => void;
+  };
 </script>
 
 <script lang="ts">

packages/layerchart/src/lib/utils/canvas.ts

@@ -46,6 +46,8 @@ export function getComputedStyles(
     if (styles) {
       Object.assign(svg.style, styles);
     }
+    // Make sure `<svg>` is not visible
+    svg.style.display = 'none';
 
     if (classes) {
       svg.setAttribute(

packages/layerchart/src/routes/docs/+layout.svelte

@@ -15,7 +15,16 @@
     mdiLink,
   } from '@mdi/js';
 
-  import { ApiDocs, Button, Dialog, Icon, ListItem, TableOfContents } from 'svelte-ux';
+  import {
+    ApiDocs,
+    Button,
+    Dialog,
+    Icon,
+    ListItem,
+    TableOfContents,
+    ToggleGroup,
+    ToggleOption,
+  } from 'svelte-ux';
 
   import { MediaQueryPresets } from '@layerstack/svelte-state';
   import { cls } from '@layerstack/tailwind';
@@ -24,6 +33,7 @@
   import Code from '$lib/docs/Code.svelte';
   import ViewSourceButton from '$lib/docs/ViewSourceButton.svelte';
   import { page } from '$app/state';
+  import { shared } from './shared.svelte.js';
 
   const { children } = $props();
 
@@ -51,6 +61,7 @@
     pageSource,
     api,
     status,
+    supportedContexts,
   } = $derived(page.data.meta ?? {});
 
   const { xlScreen } = new MediaQueryPresets();
@@ -96,11 +107,28 @@
       </div>
     </div>
 
-    <div class="text-2xl font-bold">
-      {#if type === 'examples' || type === 'tools'}
-        {title.replace(/([a-z])([A-Z])/g, '$1 $2')}
-      {:else}
-        {title}
+    <div class="flex items-center gap-4">
+      <span class="text-2xl font-bold">
+        {#if type === 'examples' || type === 'tools'}
+          {title.replace(/([a-z])([A-Z])/g, '$1 $2')}
+        {:else}
+          {title}
+        {/if}
+      </span>
+
+      {#if supportedContexts}
+        <ToggleGroup
+          bind:value={shared.renderContext}
+          variant="fill"
+          color="primary"
+          inset
+          gap="px"
+          size="sm"
+        >
+          {#each supportedContexts as context}
+            <ToggleOption value={context}>{toTitleCase(context)}</ToggleOption>
+          {/each}
+        </ToggleGroup>
       {/if}
 
       {#if status}