comark 0.3.1 → 0.4.0

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

@@ -1,445 +0,0 @@
-# React Rendering Guide
-
-Complete guide for rendering Comark AST in React applications.
-
-## Table of Contents
-
-- [Basic Usage](#basic-usage)
-- [Custom Components](#custom-components)
-- [Dynamic Component Resolution](#dynamic-component-resolution)
-- [Props Conversion](#props-conversion)
-- [Streaming Mode](#streaming-mode)
-- [Prose Components](#prose-components)
-- [Custom Props Handling](#custom-props-handling)
-- [CSS Class Name](#css-class-name)
-
----
-
-## Basic Usage
-
-Use the `Comark` component to render markdown:
-
-```tsx
-import { Comark } from '@comark/react'
-
-const content = `
-# Hello World
-
-This is **markdown** content.
-
-::alert{type="info"}
-Important message
-::
-`
-
-export default function App() {
-  return <Comark>{content}</Comark>
-}
-```
-
----
-
-## Custom Components
-
-Map custom React components to Comark elements:
-
-```tsx
-import { Comark } from '@comark/react'
-import CustomHeading from './CustomHeading'
-import CustomAlert from './CustomAlert'
-import CustomCard from './CustomCard'
-
-const customComponents = {
-  h1: CustomHeading,
-  h2: CustomHeading,
-  alert: CustomAlert,
-  card: CustomCard,
-}
-
-export default function App({ content }) {
-  return (
-    <Comark
-      components={customComponents}
-    >{content}</Comark>
-  )
-}
-```
-
-### Custom Component Example
-
-```tsx
-// CustomHeading.tsx
-import React from 'react'
-
-interface Props {
-  __node: any  // Comark node
-  id?: string
-  children: React.ReactNode
-}
-
-export default function CustomHeading({ __node, id, children }: Props) {
-  const tag = __node[0]  // h1, h2, etc.
-  const Component = tag as keyof JSX.IntrinsicElements
-
-  return (
-    <Component id={id} className="custom-heading">
-      {children}
-    </Component>
-  )
-}
-```
-
-**Styled Component:**
-
-```tsx
-import styled from 'styled-components'
-
-const StyledHeading = styled.h1<{ level: number }>`
-  font-family: 'Inter', sans-serif;
-  font-weight: 700;
-  font-size: ${props => 3 - props.level * 0.25}rem;
-  margin-bottom: 1rem;
-  color: #1a202c;
-`
-
-export default function CustomHeading({ __node, children }: Props) {
-  const tag = __node[0]
-  const level = parseInt(tag[1])  // Extract level from 'h1', 'h2', etc.
-
-  return (
-    <StyledHeading as={tag} level={level}>
-      {children}
-    </StyledHeading>
-  )
-}
-```
-
-### Alert Component Example
-
-```tsx
-// CustomAlert.tsx
-import React from 'react'
-import './Alert.css'
-
-interface AlertProps {
-  type?: 'info' | 'warning' | 'error' | 'success'
-  children: React.ReactNode
-}
-
-export default function CustomAlert({ type = 'info', children }: AlertProps) {
-  const icons = {
-    info: 'ℹ️',
-    warning: '⚠️',
-    error: '❌',
-    success: '✅',
-  }
-
-  return (
-    <div className={`alert alert-${type}`} role="alert">
-      <div className="alert-icon">{icons[type]}</div>
-      <div className="alert-content">{children}</div>
-    </div>
-  )
-}
-```
-
----
-
-## Dynamic Component Resolution
-
-Load components dynamically using `componentsManifest`:
-
-```tsx
-import { Comark } from '@comark/react'
-
-const componentMap = {
-  'alert': () => import('./Alert'),
-  'card': () => import('./Card'),
-  'button': () => import('./Button'),
-}
-
-async function loadComponent(name: string) {
-  if (componentMap[name]) {
-    return componentMap[name]()
-  }
-  throw new Error(`Component ${name} not found`)
-}
-
-export default function App({ content }) {
-  return (
-    <Comark
-      componentsManifest={loadComponent}
-    >{content}</Comark>
-  )
-}
-```
-
----
-
-## Props Conversion
-
-React renderer handles HTML attribute conversion automatically:
-
-### Attribute Mapping
-
-```tsx
-// Markdown attribute → React prop
-{class="foo"}           → className="foo"
-{tabindex="0"}          → tabIndex={0}
-{style="..."}           → style={{...}}  (converted to object)
-{:bool="true"}          → bool={true}    (parsed from string)
-{:count="5"}            → count={5}      (parsed as number)
-{:data='{"key":"val"}'} → data={{key:"val"}} (parsed as object)
-```
-
-### Style Conversion
-
-```tsx
-// Input: style="color: red; font-size: 16px"
-// Output: style={{ color: 'red', fontSize: '16px' }}
-
-// Custom CSS properties preserved:
-// Input: style="--custom-color: blue"
-// Output: style={{ '--custom-color': 'blue' }}
-```
-
-### Boolean Props
-
-```tsx
-// Markdown: **text**{:disabled}
-// React prop: disabled={true}
-
-// Markdown: [link](url){:external}
-// React prop: external={true}
-```
-
-### Number Props
-
-```tsx
-// Markdown: ::component{:count="5"}
-// React prop: count={5}
-
-// Markdown: ::component{:max="100"}
-// React prop: max={100}
-```
-
-### Object/Array Props
-
-```tsx
-// Markdown: ::component{:config='{"theme":"dark"}'}
-// React prop: config={{theme:"dark"}}
-
-// Markdown: ::component{:items='["a","b","c"]'}
-// React prop: items={["a","b","c"]}
-```
-
----
-
-## Streaming Mode
-
-Use the `Comark` component with reactive state for streaming content:
-
-```tsx
-import { useState, useEffect } from 'react'
-import { Comark } from '@comark/react'
-
-export default function StreamingContent() {
-  const [content, setContent] = useState('')
-  const [isLoading, setIsLoading] = useState(true)
-
-  useEffect(() => {
-    async function loadContent() {
-      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
-        setContent(prev => prev + decoder.decode(value))
-      }
-
-      setIsLoading(false)
-    }
-
-    loadContent()
-  }, [])
-
-  return (
-    <>
-      {isLoading && <div>Loading...</div>}
-      <Comark>{content}</Comark>
-    </>
-  )
-}
-```
-
----
-
-## Prose Components
-
-The `Comark` component uses built-in prose styling automatically. You can override with custom components:
-
-```tsx
-import { Comark } from '@comark/react'
-import CustomAlert from './CustomAlert'
-
-const components = {
-  alert: CustomAlert,  // Override or add custom components
-}
-
-export default function App({ content }) {
-  return <Comark components={components}>{content}</Comark>
-}
-```
-
-### Tailwind CSS Prose
-
-```tsx
-import { Comark } from '@comark/react'
-
-export default function App({ content }) {
-  return (
-    <article className="prose prose-lg dark:prose-dark max-w-none">
-      <Comark>{content}</Comark>
-    </article>
-  )
-}
-```
-
----
-
-## Custom Props Handling
-
-Access props in custom components:
-
-```tsx
-// CustomAlert.tsx
-interface AlertProps {
-  type?: string        // From {type="info"}
-  bool?: boolean       // From {bool} → :bool="true"
-  count?: number       // From {:count="5"}
-  data?: object        // From {:data='{"key":"val"}'}
-  __node?: any         // Original Comark node
-  children: React.ReactNode
-}
-
-export default function CustomAlert({
-  type = 'info',
-  bool,
-  count,
-  data,
-  __node,
-  children
-}: AlertProps) {
-  return (
-    <div
-      className={`alert alert-${type}`}
-      data-bool={bool}
-      data-count={count}
-      data-info={JSON.stringify(data)}
-      role="alert"
-    >
-      {children}
-    </div>
-  )
-}
-```
-
-### Property Types
-
-- `:bool="true"` → `bool={true}` (boolean)
-- `:count="5"` → `count={5}` (number)
-- `:obj='{"key":"val"}'` → `obj={{key:"val"}}` (object)
-- `attr="value"` → `attr="value"` (string)
-
-### Accessing Node Structure
-
-```tsx
-interface Props {
-  __node?: any
-  children: React.ReactNode
-}
-
-export default function Component({ __node, children }: Props) {
-  // Node structure: [tag, props, ...children]
-  const tag = __node?.[0]
-  const nodeProps = __node?.[1] || {}
-  const nodeChildren = __node?.slice(2) || []
-
-  return (
-    <div data-tag={tag}>
-      {children}
-    </div>
-  )
-}
-```
-
-### Working with Complex Props
-
-```tsx
-// DataTable.tsx
-interface DataTableProps {
-  columns?: string[]   // From {:columns='["Name","Age"]'}
-  sortable?: boolean   // From {sortable}
-  striped?: boolean    // From {striped}
-  children: React.ReactNode
-}
-
-export default function DataTable({
-  columns = [],
-  sortable = false,
-  striped = false,
-  children
-}: DataTableProps) {
-  return (
-    <table className={striped ? 'table-striped' : ''}>
-      {columns.length > 0 && (
-        <thead>
-          <tr>
-            {columns.map((col, i) => (
-              <th key={i}>
-                {col}
-                {sortable && <button>↕</button>}
-              </th>
-            ))}
-          </tr>
-        </thead>
-      )}
-      <tbody>{children}</tbody>
-    </table>
-  )
-}
-```
-
-**Usage in Markdown:**
-
-```markdown
-::data-table{:columns='["Name", "Age", "Email"]' sortable striped}
-Table content here
-::
-```
-
----
-
-## CSS Class Name
-
-Add custom wrapper class:
-
-```tsx
-<Comark
-  className="prose dark:prose-dark"
->{content}</Comark>
-```
-
-### With Tailwind CSS
-
-```tsx
-<Comark
-  className="prose prose-slate lg:prose-xl dark:prose-invert max-w-none"
->{content}</Comark>
-```
-
----
-
-[← Back to Main Skills Guide](../SKILL.md)