comark 0.3.1 → 0.4.0

package/skills/skills/comark/references/rendering-svelte.md

@@ -1,453 +0,0 @@
-# Svelte Rendering Guide
-
-Complete guide for rendering Comark AST in Svelte 5 applications.
-
-## Table of Contents
-
-- [Basic Usage](#basic-usage)
-- [Custom Components](#custom-components)
-- [Dynamic Component Resolution](#dynamic-component-resolution)
-- [Slots Support](#slots-support)
-- [Props Mapping](#props-mapping)
-- [Streaming Mode](#streaming-mode)
-- [Prose Components](#prose-components)
-- [Experimental Async](#experimental-async)
-- [Custom Props Handling](#custom-props-handling)
-- [CSS Class](#css-class)
-
----
-
-## Basic Usage
-
-Use the `Comark` component to render markdown:
-
-```svelte
-<script lang="ts">
-  import { Comark } from '@comark/svelte'
-
-  const content = `
-# Hello World
-
-This is **markdown** content.
-
-::alert{type="info"}
-Important message
-::
-`
-</script>
-
-<Comark markdown={content} />
-```
-
----
-
-## Custom Components
-
-Map custom Svelte components to Comark elements:
-
-```svelte
-<script lang="ts">
-  import { Comark } from '@comark/svelte'
-  import CustomHeading from './CustomHeading.svelte'
-  import CustomAlert from './CustomAlert.svelte'
-  import CustomCard from './CustomCard.svelte'
-
-  const customComponents = {
-    h1: CustomHeading,
-    h2: CustomHeading,
-    alert: CustomAlert,
-    card: CustomCard,
-  }
-</script>
-
-<Comark markdown={content} components={customComponents} />
-```
-
-### Component Resolution Order
-
-Components are resolved by checking these keys in order:
-1. `Prose{PascalTag}` — e.g., `ProseH1` for `<h1>` tags
-2. `PascalTag` — e.g., `Alert` for `::alert` components
-3. `tag` — e.g., `alert` for `::alert` components
-
-### Custom Component Example
-
-Custom components receive AST node attributes as props and children as a Svelte `children` snippet:
-
-```svelte
-<!-- CustomHeading.svelte -->
-<script lang="ts">
-  import type { Snippet } from 'svelte'
-
-  let { id, children }: { id?: string, children?: Snippet } = $props()
-</script>
-
-<h1 {id} class="custom-heading">
-  {@render children?.()}
-</h1>
-```
-
-### Alert Component Example
-
-```svelte
-<!-- CustomAlert.svelte -->
-<script lang="ts">
-  import type { Snippet } from 'svelte'
-
-  let {
-    type = 'info',
-    children,
-  }: {
-    type?: 'info' | 'warning' | 'error' | 'success'
-    children?: Snippet
-  } = $props()
-
-  const icons = {
-    info: '\u2139\uFE0F',
-    warning: '\u26A0\uFE0F',
-    error: '\u274C',
-    success: '\u2705',
-  }
-</script>
-
-<div class="alert alert-{type}" role="alert">
-  <div class="alert-icon">{icons[type]}</div>
-  <div class="alert-content">{@render children?.()}</div>
-</div>
-```
-
----
-
-## Dynamic Component Resolution
-
-Load components dynamically using `componentsManifest`:
-
-```svelte
-<script lang="ts">
-  import { Comark } from '@comark/svelte'
-
-  const componentMap: Record<string, () => Promise<any>> = {
-    'alert': () => import('./Alert.svelte'),
-    'card': () => import('./Card.svelte'),
-    'button': () => import('./Button.svelte'),
-  }
-
-  async function loadComponent(name: string) {
-    if (componentMap[name]) {
-      const mod = await componentMap[name]()
-      return mod.default
-    }
-    throw new Error(`Component ${name} not found`)
-  }
-</script>
-
-<Comark markdown={content} componentsManifest={loadComponent} />
-```
-
----
-
-## Slots Support
-
-Comark components with named slots work in Svelte using the `children` snippet pattern:
-
-### Markdown with Slots
-
-```markdown
-::card
-#header
-## Card Title
-
-#default
-Main content here with **markdown** support
-
-#footer
-Footer text
-::
-```
-
-### Custom Component with Slots
-
-In Svelte 5, children are passed as implicit slot content and received as a `Snippet`:
-
-```svelte
-<!-- Card.svelte -->
-<script lang="ts">
-  import type { Snippet } from 'svelte'
-
-  let {
-    children,
-  }: {
-    children?: Snippet
-  } = $props()
-</script>
-
-<div class="card">
-  {@render children?.()}
-</div>
-
-<style>
-  .card {
-    border: 1px solid #e5e7eb;
-    border-radius: 0.5rem;
-    overflow: hidden;
-    padding: 1rem;
-  }
-</style>
-```
-
-Note: Named slots from Comark (`#header`, `#content`, `#footer`) are rendered as `template` elements in the AST. The Svelte renderer passes all children (including named slot templates) as a single `children` snippet. To handle named slots individually, access the `__node` prop and filter children by template name.
-
----
-
-## Props Mapping
-
-The Svelte renderer maps AST attributes to component props:
-
-### Attribute Mapping
-
-```
-// Markdown attribute → Svelte prop
-{class="foo"}           → class="foo"    (pass-through)
-{className="foo"}       → class="foo"    (mapped)
-{style="color: red"}    → style="color: red"  (pass-through as string)
-{tabindex="0"}          → tabindex="0"   (pass-through)
-{:bool="true"}          → bool={true}    (parsed from string)
-{:count="5"}            → count={5}      (parsed as number)
-{:data='{"key":"val"}'} → data={{key:"val"}} (parsed as object)
-```
-
-Svelte is closer to HTML than React, so most attributes pass through unchanged. The only mapping is `className` → `class`. Colon-prefixed attributes (`:prop="value"`) are parsed as typed values (boolean, number, JSON).
-
-### Boolean Props
-
-```
-// Markdown: ::component{:disabled="true"}
-// Svelte prop: disabled={true}
-
-// Markdown: ::component{:visible="false"}
-// Svelte prop: visible={false}
-```
-
-### Number Props
-
-```
-// Markdown: ::component{:count="5"}
-// Svelte prop: count={5}
-
-// Markdown: ::component{:max="100"}
-// Svelte prop: max={100}
-```
-
-### Object/Array Props
-
-```
-// Markdown: ::component{:config='{"theme":"dark"}'}
-// Svelte prop: config={{theme:"dark"}}
-
-// Markdown: ::component{:items='["a","b","c"]'}
-// Svelte prop: items={["a","b","c"]}
-```
-
----
-
-## Streaming Mode
-
-Use the `Comark` component with `$state` for streaming content:
-
-```svelte
-<script lang="ts">
-  import { Comark } from '@comark/svelte'
-
-  let content = $state('')
-  let isStreaming = $state(false)
-
-  async function streamContent() {
-    isStreaming = true
-    const response = await fetch('/api/content.md')
-    const reader = response.body!.getReader()
-    const decoder = new TextDecoder()
-
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      content += decoder.decode(value, { stream: true })
-    }
-
-    isStreaming = false
-  }
-</script>
-
-<Comark markdown={content} streaming={isStreaming} caret />
-```
-
-The `caret` prop appends a blinking cursor indicator to the last text node during streaming. Customize with a CSS class:
-
-```svelte
-<Comark markdown={content} streaming={isStreaming} caret={{ class: 'my-caret' }} />
-```
-
-`autoClose` is enabled by default — incomplete syntax like `**bold text` is automatically closed on every parse.
-
----
-
-## Prose Components
-
-Override native HTML elements using the `Prose` prefix:
-
-```svelte
-<script lang="ts">
-  import { Comark } from '@comark/svelte'
-  import ProseH1 from './ProseH1.svelte'
-  import ProseA from './ProseA.svelte'
-  import ProsePre from './ProsePre.svelte'
-
-  const components = { ProseH1, ProseA, ProsePre }
-</script>
-
-<Comark markdown={content} {components} />
-```
-
-### Tailwind CSS Prose
-
-```svelte
-<article class="prose prose-lg dark:prose-dark max-w-none">
-  <Comark markdown={content} />
-</article>
-```
-
----
-
-## Experimental Async
-
-The `ComarkAsync` component uses Svelte's experimental `await` in `$derived` for a declarative approach. Requires `experimental.async` in your Svelte config:
-
-```js
-// svelte.config.js
-const config = {
-  compilerOptions: {
-    experimental: { async: true },
-  },
-}
-export default config
-```
-
-Usage with `<svelte:boundary>`:
-
-```svelte
-<script lang="ts">
-  import { ComarkAsync } from '@comark/svelte/async'
-</script>
-
-<svelte:boundary>
-  <ComarkAsync markdown={content} />
-  {#snippet pending()}
-    <p>Loading...</p>
-  {/snippet}
-  {#snippet failed(error, reset)}
-    <p>Error: {error.message}</p>
-    <button onclick={reset}>Retry</button>
-  {/snippet}
-</svelte:boundary>
-```
-
----
-
-## Custom Props Handling
-
-Access props in custom components:
-
-```svelte
-<!-- CustomAlert.svelte -->
-<script lang="ts">
-  import type { Snippet } from 'svelte'
-
-  let {
-    type = 'info',
-    count,
-    data,
-    children,
-  }: {
-    type?: string       // From {type="info"}
-    count?: number      // From {:count="5"}
-    data?: object       // From {:data='{"key":"val"}'}
-    children?: Snippet
-  } = $props()
-</script>
-
-<div
-  class="alert alert-{type}"
-  data-count={count}
-  data-info={JSON.stringify(data)}
-  role="alert"
->
-  {@render children?.()}
-</div>
-```
-
-### Working with Complex Props
-
-```svelte
-<!-- DataTable.svelte -->
-<script lang="ts">
-  import type { Snippet } from 'svelte'
-
-  let {
-    columns = [],
-    sortable = false,
-    striped = false,
-    children,
-  }: {
-    columns?: string[]   // From {:columns='["Name","Age"]'}
-    sortable?: boolean   // From {:sortable="true"}
-    striped?: boolean    // From {:striped="true"}
-    children?: Snippet
-  } = $props()
-</script>
-
-<table class:table-striped={striped}>
-  {#if columns.length > 0}
-    <thead>
-      <tr>
-        {#each columns as col (col)}
-          <th>
-            {col}
-            {#if sortable}<button>↕</button>{/if}
-          </th>
-        {/each}
-      </tr>
-    </thead>
-  {/if}
-  <tbody>{@render children?.()}</tbody>
-</table>
-```
-
-**Usage in Markdown:**
-
-```markdown
-::data-table{:columns='["Name", "Age", "Email"]' :sortable="true" :striped="true"}
-Table content here
-::
-```
-
----
-
-## CSS Class
-
-Add a custom wrapper class:
-
-```svelte
-<Comark markdown={content} class="prose dark:prose-dark" />
-```
-
-### With Tailwind CSS
-
-```svelte
-<Comark
-  markdown={content}
-  class="prose prose-slate lg:prose-xl dark:prose-invert max-w-none"
-/>
-```
-
----
-
-[← Back to Main Skills Guide](../SKILL.md)