codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/svelte5/references/spa-and-routing.md

@@ -0,0 +1,262 @@
+# SPA and Routing — Deep Dive
+
+## 1. SPA Configuration
+
+### Core Setup
+
+Three changes convert a SvelteKit project to a single-page application:
+
+**1. Install adapter-static:**
+
+```bash
+npm install -D @sveltejs/adapter-static
+```
+
+**2. Configure svelte.config.js:**
+
+```js
+import adapter from '@sveltejs/adapter-static';
+
+export default {
+  kit: {
+    adapter: adapter({
+      fallback: '200.html'   // Serves the SPA shell for all unmatched routes
+    }),
+    prerender: {
+      entries: []             // Disable automatic prerendering
+    }
+  }
+};
+```
+
+**3. Disable SSR globally:**
+
+```js
+// src/routes/+layout.js
+export const ssr = false;
+```
+
+The `fallback` page name depends on the hosting platform:
+- `200.html` — Surge, many static hosts
+- `index.html` — GitHub Pages, Netlify (with `_redirects` file)
+- `404.html` — GitHub Pages alternative (handles as custom 404)
+
+### Why ssr = false in +layout.js
+
+Setting `ssr = false` at the root layout propagates to all routes. Every page renders exclusively on the client. This means:
+
+- No server-side rendering step
+- No `+page.server.js` or `+layout.server.js` files (server load functions are unavailable)
+- All data fetching occurs in `+page.js` load functions or in component effects
+- `$app/environment` reports `browser` as always `true`
+
+## 2. File-Based Routing
+
+SvelteKit uses the filesystem for routing. Each directory under `src/routes/` maps to a URL path:
+
+```
+src/routes/
+├── +layout.svelte          → root layout (wraps all pages)
+├── +page.svelte            → /
+├── about/
+│   └── +page.svelte        → /about
+├── blog/
+│   ├── +page.svelte        → /blog
+│   └── [slug]/
+│       └── +page.svelte    → /blog/:slug
+└── (app)/
+    ├── +layout.svelte      → shared layout for grouped routes
+    ├── dashboard/
+    │   └── +page.svelte    → /dashboard
+    └── settings/
+        └── +page.svelte    → /settings
+```
+
+### Dynamic Parameters
+
+Square brackets define dynamic route segments:
+
+```
+[slug]        → single parameter (required)
+[...rest]     → catch-all (zero or more segments)
+[[optional]]  → optional parameter
+```
+
+Access parameters in load functions or via the `$page` store:
+
+```js
+// src/routes/blog/[slug]/+page.js
+export function load({ params }) {
+  return { slug: params.slug };
+}
+```
+
+### Route Groups
+
+Parenthesized directories like `(app)` create layout groups without affecting the URL. Routes inside `(app)/` share a layout but the URL does not include `(app)`.
+
+Use route groups to:
+- Apply different layouts to different sections
+- Separate authenticated and public routes
+- Share a sidebar or navigation across a subset of pages
+
+## 3. Load Functions in SPA Mode
+
+In SPA mode, only `+page.js` and `+layout.js` load functions are available (no `.server.js` variants).
+
+### Client-Only Load Function
+
+```js
+// src/routes/dashboard/+page.js
+export async function load({ fetch, params, url }) {
+  const res = await fetch('/api/dashboard');
+  const data = await res.json();
+  return { dashboard: data };
+}
+```
+
+The `fetch` provided by SvelteKit adds relative URL resolution and cookie forwarding. Prefer it over the global `fetch`.
+
+### Accessing Load Data
+
+Load function return values are available as `data` in the corresponding `+page.svelte`:
+
+```svelte
+<!-- src/routes/dashboard/+page.svelte -->
+<script>
+  let { data } = $props();
+</script>
+<h1>Dashboard</h1>
+<pre>{JSON.stringify(data.dashboard, null, 2)}</pre>
+```
+
+### Invalidation and Re-running Loads
+
+Force a load function to re-run using `invalidate` or `invalidateAll`:
+
+```js
+import { invalidate, invalidateAll } from '$app/navigation';
+
+// Re-run load functions that depend on a specific URL
+invalidate('/api/dashboard');
+
+// Re-run all active load functions
+invalidateAll();
+```
+
+Load functions re-run when their dependencies change (URL parameters, `fetch` URLs, or `depends` keys).
+
+Register custom dependency keys with `depends`:
+
+```js
+export async function load({ fetch, depends }) {
+  depends('app:dashboard');
+  const res = await fetch('/api/dashboard');
+  return { dashboard: await res.json() };
+}
+
+// Later: invalidate('app:dashboard');
+```
+
+## 4. Prerendering in SPA Mode
+
+Even with `ssr = false`, specific routes can be prerendered as static HTML:
+
+```js
+// src/routes/about/+page.js
+export const prerender = true;
+```
+
+This generates a static `about/index.html` at build time. Useful for:
+- Marketing pages that benefit from instant load
+- SEO-critical pages (search engines see full HTML)
+- Pages with no dynamic data
+
+The rest of the application still uses the SPA fallback for client-side routing.
+
+### Prerender Configuration
+
+Control prerender behavior in `svelte.config.js`:
+
+```js
+export default {
+  kit: {
+    prerender: {
+      entries: ['/about', '/pricing'], // Explicitly list pages to prerender
+      handleHttpError: 'warn'          // Warn instead of fail on broken links
+    }
+  }
+};
+```
+
+## 5. Navigation
+
+### Programmatic Navigation
+
+```js
+import { goto } from '$app/navigation';
+
+// Navigate to a route
+goto('/dashboard');
+
+// Replace history entry (no back button)
+goto('/login', { replaceState: true });
+
+// Keep current scroll position
+goto('/page', { noScroll: true });
+```
+
+### Navigation Lifecycle
+
+```js
+import { beforeNavigate, afterNavigate, onNavigate } from '$app/navigation';
+
+// Runs before leaving current page — can cancel navigation
+beforeNavigate(({ cancel, to }) => {
+  if (hasUnsavedChanges && !confirm('Leave without saving?')) {
+    cancel();
+  }
+});
+
+// Runs after navigation completes — useful for analytics
+afterNavigate(({ from, to }) => {
+  trackPageView(to?.url.pathname);
+});
+
+// Runs when navigation starts — returns a promise for view transitions
+onNavigate((navigation) => {
+  // Optionally return a promise to delay navigation
+});
+```
+
+### Page Store
+
+Access the current URL, params, and route info via the `$page` store:
+
+```svelte
+<script>
+  import { page } from '$app/stores';
+</script>
+<nav>
+  <a href="/" class:active={$page.url.pathname === '/'}>Home</a>
+  <a href="/about" class:active={$page.url.pathname === '/about'}>About</a>
+</nav>
+```
+
+### Link Options
+
+Control SvelteKit link behavior with `data-sveltekit-*` attributes:
+
+```html
+<!-- Preload on hover (default behavior) -->
+<a href="/about">About</a>
+
+<!-- Preload immediately when link enters viewport -->
+<a href="/about" data-sveltekit-preload-data="eager">About</a>
+
+<!-- Disable SvelteKit handling (full page navigation) -->
+<a href="/external" data-sveltekit-reload>External</a>
+
+<!-- Replace history entry -->
+<a href="/step2" data-sveltekit-replacestate>Next Step</a>
+```

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/svelte5/references/svelte-dnd-action.md

@@ -0,0 +1,181 @@
+# svelte-dnd-action — Reference
+
+## Mental Model
+
+`svelte-dnd-action` is an action-based drag-and-drop library. The `use:dndzone` action transforms any container element into a drag-and-drop zone. Items are plain arrays managed with `$state`; the library emits events when the user drags (consider) and drops (finalize), and the component reassigns its items array in response. There is no separate state store or provider — the action reads items from its options and communicates changes through DOM events.
+
+> Official documentation and examples: <https://github.com/isaacHagworthy/svelte-dnd-action>
+
+---
+
+## Core API
+
+### The dndzone Action
+
+Apply `use:dndzone` to a container element. The action accepts an options object and emits two events:
+
+```svelte
+<script>
+  import { dndzone } from 'svelte-dnd-action';
+
+  let items = $state([
+    { id: 1, name: 'Item A' },
+    { id: 2, name: 'Item B' },
+    { id: 3, name: 'Item C' }
+  ]);
+
+  function handleSort(e) {
+    items = e.detail.items;
+  }
+</script>
+
+<div
+  use:dndzone={{ items }}
+  onconsider={handleSort}
+  onfinalize={handleSort}
+>
+  {#each items as item (item.id)}
+    <div>{item.name}</div>
+  {/each}
+</div>
+```
+
+### Events
+
+| Event | When | Purpose |
+|-------|------|---------|
+| `consider` | During drag (hover, reorder) | Preview the tentative new order; update items for visual feedback |
+| `finalize` | On drop | Commit the final order; update items to persist the result |
+
+Both events provide `e.detail.items` (the reordered array) and `e.detail.info` (metadata about the drag operation including `trigger` and `source`).
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `items` | array | required | The array of items. Each must have a unique `id` property |
+| `type` | string | internal ID | Zone type identifier. Only zones with matching types accept drops |
+| `flipDurationMs` | number | 0 | Animation duration in ms for reorder transitions. Set to ~200 for smooth animations |
+| `dragDisabled` | boolean | false | Disable dragging from this zone |
+| `morphDisabled` | boolean | false | Disable morph animation when items move between zones |
+| `dropFromOthersDisabled` | boolean | false | Prevent items from being dropped into this zone from other zones |
+| `dropTargetStyle` | object | `{outline: ...}` | CSS styles applied to the zone when a dragged item hovers over it |
+| `dropTargetClasses` | array | `[]` | CSS classes applied to the zone during hover |
+| `transformDraggedElement` | function | undefined | Callback to modify the dragged element's appearance |
+| `autoAriaDisabled` | boolean | false | Disable automatic ARIA attribute management |
+| `centreDraggedOnCursor` | boolean | false | Center the dragged element on the cursor |
+| `zoneTabIndex` | number | 0 | Tab index for the zone container |
+| `minItems` | number | undefined | Minimum items the zone must retain |
+| `maxItems` | number | undefined | Maximum items the zone accepts |
+| `itemsOrientation` | string | inferred | `"vertical"`, `"horizontal"`, or `"grid"`. Usually auto-detected |
+| `multiDrag` | boolean | false | Enable selecting and dragging multiple items |
+
+---
+
+## Drag Handle Pattern
+
+Use `dragHandleZone` and `dragHandle` when only a specific element within each item should initiate dragging:
+
+```svelte
+<script>
+  import { dragHandleZone, dragHandle } from 'svelte-dnd-action';
+
+  let items = $state([
+    { id: 1, name: 'Task A' },
+    { id: 2, name: 'Task B' }
+  ]);
+
+  function handleSort(e) {
+    items = e.detail.items;
+  }
+</script>
+
+<div
+  use:dragHandleZone={{ items }}
+  onconsider={handleSort}
+  onfinalize={handleSort}
+>
+  {#each items as item (item.id)}
+    <div>
+      <span use:dragHandle aria-label="drag handle">☰</span>
+      <span>{item.name}</span>
+    </div>
+  {/each}
+</div>
+```
+
+`dragHandleZone` replaces `dndzone` on the container. `dragHandle` marks the grip element inside each item. All options and events remain the same.
+
+---
+
+## Svelte 5 Integration
+
+### Event Syntax
+
+Svelte 5 uses `onconsider` and `onfinalize` (no colon). The Svelte 4 syntax `on:consider` and `on:finalize` does not work in runes mode:
+
+```svelte
+<!-- Correct (Svelte 5) -->
+<div use:dndzone={{ items }} onconsider={handleSort} onfinalize={handleSort}>
+
+<!-- Wrong (Svelte 4 syntax) -->
+<div use:dndzone={{ items }} on:consider={handleSort} on:finalize={handleSort}>
+```
+
+### State Management
+
+Store items with `$state()` and reassign in event handlers. The library checks reference equality, so always reassign the entire array — never use `splice` or other in-place mutations in the handler:
+
+```js
+let items = $state([...]);
+
+function handleSort(e) {
+  items = e.detail.items;  // full reassignment
+}
+```
+
+### Version Requirement
+
+Version **0.9.59+** is required for `$state` compatibility. Earlier versions do not correctly detect Svelte 5's reactive proxies and may fail silently or throw during drag operations.
+
+---
+
+## Shadow Item Handling
+
+During a drag operation, the library inserts a shadow placeholder item into the items array to represent the drop position. This shadow item is visible to `$derived` computations over the items array.
+
+Filter shadow items when computing derived values to avoid counting or displaying the placeholder:
+
+```js
+import { SHADOW_ITEM_MARKER_PROPERTY_NAME } from 'svelte-dnd-action';
+
+let items = $state([...]);
+let realCount = $derived(
+  items.filter(i => !i[SHADOW_ITEM_MARKER_PROPERTY_NAME]).length
+);
+```
+
+The shadow item carries the `SHADOW_ITEM_MARKER_PROPERTY_NAME` property set to `true`. The companion constant `SHADOW_PLACEHOLDER_ITEM_ID` holds the shadow's `id` value for identity-based filtering.
+
+---
+
+## Exported Constants
+
+| Constant | Purpose |
+|----------|---------|
+| `TRIGGERS` | Enum of drag trigger types (e.g., `DRAG_STARTED`, `DROPPED_INTO_ZONE`) |
+| `SOURCES` | Enum of event sources (e.g., `POINTER`, `KEYBOARD`) |
+| `SHADOW_ITEM_MARKER_PROPERTY_NAME` | Property name on shadow placeholder items |
+| `SHADOW_PLACEHOLDER_ITEM_ID` | The `id` value assigned to shadow items |
+
+Access trigger and source info from `e.detail.info`:
+
+```js
+import { TRIGGERS, SOURCES } from 'svelte-dnd-action';
+
+function handleFinalize(e) {
+  if (e.detail.info.trigger === TRIGGERS.DROPPED_INTO_ZONE) {
+    saveOrder(e.detail.items);
+  }
+}
+```