codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/svelte5/references/component-patterns.md

@@ -0,0 +1,332 @@
+# Component Patterns — Deep Dive
+
+## 1. Props Patterns
+
+### Basic Destructuring with Defaults
+
+```svelte
+<script>
+  let { title, subtitle = 'Default subtitle', variant = 'primary' } = $props();
+</script>
+```
+
+Missing required props produce a compile-time warning when using TypeScript.
+
+### Rest Props
+
+Collect remaining props with rest syntax for forwarding to elements:
+
+```svelte
+<script>
+  let { class: className = '', children, ...rest } = $props();
+</script>
+<div class="wrapper {className}" {...rest}>
+  {@render children?.()}
+</div>
+```
+
+Note: `class` is a reserved word in JavaScript — rename it during destructuring.
+
+### TypeScript Props
+
+Define an interface for type safety and IDE autocompletion:
+
+```svelte
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    title: string;
+    count?: number;
+    variant?: 'primary' | 'secondary' | 'danger';
+    children?: Snippet;
+    header?: Snippet<[{ title: string }]>;
+    onclick?: (e: MouseEvent) => void;
+  }
+
+  let { title, count = 0, variant = 'primary', children, header, onclick }: Props = $props();
+</script>
+```
+
+Type snippets using `Snippet` from `svelte`. Parameterized snippets use `Snippet<[ParamType]>`.
+
+### $bindable Props
+
+Mark a prop as bindable to allow two-way binding from the parent:
+
+```svelte
+<!-- Input.svelte -->
+<script lang="ts">
+  interface Props {
+    value: string;
+    placeholder?: string;
+  }
+  let { value = $bindable(''), placeholder = '' }: Props = $props();
+</script>
+<input bind:value {placeholder} />
+```
+
+```svelte
+<!-- Parent -->
+<script>
+  import Input from './Input.svelte';
+  let name = $state('');
+</script>
+<Input bind:value={name} />
+<p>Typed: {name}</p>
+```
+
+Only mark props as `$bindable` when two-way data flow is the intended API. Prefer callback props for explicit data flow.
+
+## 2. Snippet Patterns
+
+### Basic Children
+
+The `children` snippet is the implicit content placed between component tags:
+
+```svelte
+<!-- Card.svelte -->
+<script>
+  let { children } = $props();
+</script>
+<div class="card">
+  {@render children?.()}
+</div>
+
+<!-- Usage -->
+<Card>
+  <h2>Title</h2>
+  <p>Content</p>
+</Card>
+```
+
+Use optional chaining (`children?.()`) when the children snippet is optional.
+
+### Named Snippets
+
+Named snippets replace named slots:
+
+```svelte
+<!-- Layout.svelte -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  interface Props {
+    header: Snippet;
+    footer?: Snippet;
+    children: Snippet;
+  }
+  let { header, footer, children }: Props = $props();
+</script>
+
+<header>{@render header()}</header>
+<main>{@render children()}</main>
+{#if footer}
+  <footer>{@render footer()}</footer>
+{/if}
+```
+
+```svelte
+<!-- Usage -->
+<Layout>
+  {#snippet header()}
+    <h1>Page Title</h1>
+  {/snippet}
+
+  <p>Main content as children</p>
+
+  {#snippet footer()}
+    <small>Footer text</small>
+  {/snippet}
+</Layout>
+```
+
+### Parameterized Snippets
+
+Pass data back to the parent through snippet parameters:
+
+```svelte
+<!-- DataTable.svelte -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props<T> {
+    items: T[];
+    row: Snippet<[T, number]>;
+    empty?: Snippet;
+  }
+
+  let { items, row, empty }: Props<any> = $props();
+</script>
+
+{#if items.length === 0}
+  {@render empty?.()}
+{:else}
+  {#each items as item, index}
+    {@render row(item, index)}
+  {/each}
+{/if}
+```
+
+```svelte
+<!-- Usage -->
+<DataTable {items}>
+  {#snippet row(item, index)}
+    <tr>
+      <td>{index + 1}</td>
+      <td>{item.name}</td>
+    </tr>
+  {/snippet}
+  {#snippet empty()}
+    <p>No items found</p>
+  {/snippet}
+</DataTable>
+```
+
+### Local Snippets for Reuse
+
+Define snippets locally within a component for repeated template blocks:
+
+```svelte
+{#snippet badge(text, color)}
+  <span class="badge" style:background={color}>{text}</span>
+{/snippet}
+
+{@render badge('New', 'green')}
+{@render badge('Sale', 'red')}
+{@render badge('Featured', 'blue')}
+```
+
+## 3. Event Patterns
+
+### DOM Events
+
+Svelte 5 uses standard HTML event attributes — no special directive syntax:
+
+```svelte
+<button onclick={handleClick}>Click</button>
+<input oninput={(e) => (query = e.currentTarget.value)} />
+<form onsubmit|preventDefault={handleSubmit}>
+```
+
+Note: Event modifiers use the pipe syntax inline. For complex modifier chains, handle in the callback instead:
+
+```js
+function handleSubmit(e) {
+  e.preventDefault();
+  e.stopPropagation();
+  // handle submission
+}
+```
+
+### Callback Props (Component Events)
+
+Replace `createEventDispatcher` with callback props:
+
+```svelte
+<!-- Dialog.svelte -->
+<script lang="ts">
+  interface Props {
+    title: string;
+    onclose?: () => void;
+    onconfirm?: (result: string) => void;
+  }
+  let { title, onclose, onconfirm }: Props = $props();
+</script>
+
+<dialog open>
+  <h2>{title}</h2>
+  <button onclick={() => onconfirm?.('yes')}>Confirm</button>
+  <button onclick={() => onclose?.()}>Cancel</button>
+</dialog>
+```
+
+```svelte
+<!-- Parent -->
+<Dialog
+  title="Confirm Action"
+  onclose={() => (showDialog = false)}
+  onconfirm={(result) => handleResult(result)}
+/>
+```
+
+### Event Forwarding
+
+Forward DOM events from inner elements to the component's consumer by accepting and spreading handler props:
+
+```svelte
+<!-- Button.svelte -->
+<script>
+  let { children, ...rest } = $props();
+</script>
+<button {...rest}>
+  {@render children?.()}
+</button>
+```
+
+All `on*` attributes passed to `<Button>` forward to the underlying `<button>` element.
+
+## 4. Composition Patterns
+
+### Wrapper Components
+
+Create components that enhance a base element while preserving its full API:
+
+```svelte
+<!-- Tooltip.svelte -->
+<script>
+  let { text, children, ...rest } = $props();
+</script>
+<div class="tooltip-wrapper" {...rest}>
+  {@render children?.()}
+  <div class="tooltip-text">{text}</div>
+</div>
+```
+
+### Dynamic Components
+
+Svelte 5 renders components directly from variables — `<svelte:component>` is no longer necessary:
+
+```svelte
+<script>
+  import Home from './Home.svelte';
+  import About from './About.svelte';
+
+  const routes = { home: Home, about: About };
+  let current = $state('home');
+</script>
+
+{@const Page = routes[current]}
+<Page />
+```
+
+### Generic Components with TypeScript
+
+Use generics for type-safe reusable components:
+
+```svelte
+<script lang="ts" generics="T">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    items: T[];
+    selected?: T;
+    row: Snippet<[T]>;
+    onselect?: (item: T) => void;
+  }
+
+  let { items, selected, row, onselect }: Props = $props();
+</script>
+
+<ul>
+  {#each items as item}
+    <li
+      class:selected={item === selected}
+      onclick={() => onselect?.(item)}
+    >
+      {@render row(item)}
+    </li>
+  {/each}
+</ul>
+```
+
+The `generics` attribute on `<script>` declares type parameters available throughout the component.

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/svelte5/references/layercake.md

@@ -0,0 +1,203 @@
+# LayerCake — Reference
+
+## Mental Model
+
+LayerCake is a headless graphics framework, not a chart library. It provides a coordinate system — reactive scales that map data values to pixel positions — and layout containers for SVG, HTML, Canvas, and WebGL. The developer authors individual layer components (axes, lines, points, labels) that read scale functions from context. This separation means LayerCake handles the math while the developer controls every visual detail.
+
+LayerCake does not ship pre-built chart types. Instead, it provides the plumbing: scale computation, responsive dimension tracking, data transformation helpers, and a layered rendering model that composites multiple technologies in a single chart area.
+
+> Official guide, API reference, and component gallery: <https://layercake.graphics>
+
+---
+
+## Core API
+
+### LayerCake Component
+
+The `<LayerCake>` component is the root container. It computes scales from data and exposes them to all descendant layer components through Svelte context.
+
+```svelte
+<script>
+  import { LayerCake, Svg } from 'layercake';
+  import Line from './Line.svelte';
+
+  let data = [
+    { x: 0, y: 10 },
+    { x: 1, y: 35 },
+    { x: 2, y: 20 }
+  ];
+</script>
+
+<div class="chart-container" style="width: 100%; height: 300px;">
+  <LayerCake
+    {data}
+    x="x"
+    y="y"
+  >
+    <Svg>
+      <Line />
+    </Svg>
+  </LayerCake>
+</div>
+```
+
+LayerCake requires a positioned container with explicit dimensions. The component measures this container and recomputes scales on resize.
+
+### Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | array | The dataset. Each element is one data point |
+| `x` | string / accessor | Key or function to extract the x value from each data point |
+| `y` | string / accessor | Key or function to extract the y value |
+| `z` | string / accessor | Optional third dimension (color, radius, category) |
+| `r` | string / accessor | Optional radius/size dimension |
+| `xScale` | d3 scale | Scale constructor for x axis (default: `scaleLinear`) |
+| `yScale` | d3 scale | Scale constructor for y axis (default: `scaleLinear`) |
+| `xDomain` | [min, max] | Override computed x domain |
+| `yDomain` | [min, max] | Override computed y domain |
+| `xRange` | [min, max] | Override x range (defaults to `[0, width]`) |
+| `yRange` | [min, max] | Override y range (defaults to `[height, 0]` for SVG convention) |
+| `padding` | object | `{ top, right, bottom, left }` in pixels |
+| `xNice` | boolean | Round domain extents to nice values |
+| `yNice` | boolean | Round domain extents to nice values |
+| `flatData` | array | Pre-flattened data for domain calculation on nested/grouped datasets |
+
+---
+
+## Layout Components
+
+Layout components create rendering contexts. Nest them inside `<LayerCake>` to composite multiple technologies:
+
+| Component | Renders Into | Use Case |
+|-----------|-------------|----------|
+| `<Svg>` | `<svg>` element | Lines, areas, axes, annotations |
+| `<Html>` | `<div>` overlay | Tooltips, labels, legends |
+| `<Canvas>` | `<canvas>` element | Large point clouds, heatmaps, performance-critical rendering |
+| `<WebGl>` | WebGL `<canvas>` | GPU-accelerated rendering for very large datasets |
+| `<ScaledSvg>` | `<svg>` with viewBox | Resolution-independent SVG (PDF export, fixed coordinate space) |
+
+Each layout component occupies the full chart area (respecting padding). Layers stack visually — SVG below, Canvas in the middle, HTML on top is a common arrangement.
+
+---
+
+## Context Values
+
+Layer components (axes, lines, points) access chart context using `getContext('LayerCake')`. The context is a Svelte store containing:
+
+### Dimensions
+- `width`, `height` — inner dimensions (after padding)
+- `containerWidth`, `containerHeight` — outer dimensions
+
+### Scales
+- `xScale`, `yScale`, `zScale`, `rScale` — configured d3 scale functions
+
+### Accessors
+- `x`, `y`, `z`, `r` — accessor functions that extract values from data points
+
+### Convenience Getters
+- `xGet(d)` — shorthand for `xScale(x(d))`, maps a data point to a pixel x position
+- `yGet(d)` — shorthand for `yScale(y(d))`, maps to pixel y position
+- `zGet(d)`, `rGet(d)` — same pattern for z and r dimensions
+
+### Data
+- `data` — the dataset passed to LayerCake
+- `flatData` — flattened version for domain calculation
+
+```svelte
+<!-- Line.svelte (layer component) -->
+<script>
+  import { getContext } from 'svelte';
+
+  const { data, xGet, yGet } = getContext('LayerCake');
+
+  // Build an SVG path from the data
+  $: path = 'M' + $data.map(d => `${$xGet(d)},${$yGet(d)}`).join('L');
+</script>
+
+<path d={path} fill="none" stroke="steelblue" stroke-width="2" />
+```
+
+> Context values are Svelte stores. Access them with `$` prefix in layer components: `$data`, `$xGet`, `$yGet`, `$width`, etc.
+
+---
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `calcExtents(data, keys)` | Calculate min/max extents for specified dimensions |
+| `stack(data, keys)` | D3-compatible stack layout for area/bar charts |
+| `groupLonger(data, keys)` | Pivot wide data to long format for multi-series charts |
+| `scaleCanvas(canvas, ctx)` | Apply device pixel ratio scaling to a canvas context |
+| `bin(data, accessor, options)` | Create histogram bins from continuous data |
+
+---
+
+## Runes Incompatibility
+
+**LayerCake uses `export let` and Svelte stores internally.** This makes the library incompatible with Svelte 5's global runes mode.
+
+### The Problem
+
+Enabling `runes: true` globally in `svelte.config.js` forces all components — including those inside `node_modules` — to use runes syntax. LayerCake's internal components use `export let` for props and `$:` reactive declarations, which are invalid in runes mode. The compiler will emit errors when processing LayerCake's source.
+
+### Workarounds
+
+**Option A (recommended):** Do not enable global runes mode. Svelte 5 components can use runes without any config flag — runes are auto-detected per file. Global `runes: true` is unnecessary for application code and breaks libraries that have not migrated.
+
+**Option B:** If the project requires global runes mode for other reasons, mark individual LayerCake wrapper components with per-component legacy mode:
+
+```svelte
+<svelte:options runes={false} />
+<!-- This component can use export let and $: safely -->
+```
+
+This workaround applies only to the wrapper component that imports LayerCake. Child layer components authored by the developer can still use runes for their own logic — they access context stores with the `$` prefix as shown above.
+
+### Migration Status
+
+LayerCake's runes migration is tracked in GitHub issue [#156](https://github.com/mhkeller/layercake/issues/156). Until the migration lands, treat LayerCake components as legacy-mode dependencies.
+
+### Layer Components and Runes
+
+User-authored layer components (the components nested inside `<Svg>`, `<Html>`, etc.) can use runes for their own local state and derived values. The constraint applies only to LayerCake's own components (`<LayerCake>`, `<Svg>`, `<Html>`, `<Canvas>`, etc.) which live in `node_modules`.
+
+However, context values from LayerCake are Svelte stores, not rune-based signals. Layer components must use the `$` store subscription syntax (`$data`, `$xGet`) regardless of whether they use runes for other state.
+
+---
+
+## Multi-Layer Composition
+
+A common pattern layers SVG (for axes and lines), Canvas (for dense point rendering), and HTML (for interactive tooltips):
+
+```svelte
+<script>
+  import { LayerCake, Svg, Canvas, Html } from 'layercake';
+  import AxisX from './AxisX.svelte';
+  import AxisY from './AxisY.svelte';
+  import Points from './Points.canvas.svelte';
+  import Tooltip from './Tooltip.svelte';
+
+  let data = [...];
+</script>
+
+<div class="chart-container" style="width: 100%; height: 400px;">
+  <LayerCake {data} x="date" y="value">
+    <Svg>
+      <AxisX />
+      <AxisY />
+    </Svg>
+    <Canvas>
+      <Points />
+    </Canvas>
+    <Html>
+      <Tooltip />
+    </Html>
+  </LayerCake>
+</div>
+```
+
+Each layout component creates its own rendering surface at the same dimensions. Layer components render independently — the SVG axes do not interfere with the Canvas points, and the HTML tooltip floats above both.
+
+Canvas layer components receive the canvas context through `getContext('canvas')` and render in the `onMount` or `$effect` lifecycle. Call `scaleCanvas` to handle high-DPI displays.