@siladev/qalam 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,135 @@
+# @siladev/qalam
+
+Islamic content editor with Quran verse references, hadith, poetry, and inline quotes. Built on Tiptap/React, RTL-first.
+
+## Install
+
+```bash
+bun add @siladev/qalam
+```
+
+## Editor
+
+```tsx
+import { QalamEditor } from "@siladev/qalam";
+import "@siladev/qalam/styles.css";
+
+// Load quran data first
+import { loadQuranData } from "@siladev/qalam";
+const data = await fetch("/quran-data.json").then(r => r.json());
+loadQuranData(data);
+
+function App() {
+  const [doc, setDoc] = useState(initialContent);
+  return (
+    <QalamEditor
+      content={doc}        // initial content (remount with key to replace)
+      onChange={setDoc}
+      repeat={true}         // enable repeat controls
+      dir="rtl"
+    />
+  );
+}
+```
+
+## Renderer
+
+```tsx
+import { QalamRenderer, resolveAST } from "@siladev/qalam";
+
+const resolved = resolveAST(doc); // needs quran data loaded
+<QalamRenderer doc={resolved} dir="rtl" />
+```
+
+## Markdown
+
+Bidirectional JSON <-> Markdown conversion.
+
+```typescript
+import { docToMarkdown, markdownToDoc, resolvedDocToMarkdown, markdownToResolvedDoc } from "@siladev/qalam";
+
+// Source markdown (for editing, LLM pipelines)
+const md = docToMarkdown(doc);
+const doc = markdownToDoc(md);
+
+// Resolved markdown (for rendering without quran data)
+const compiledMd = resolvedDocToMarkdown(resolvedDoc);
+const resolvedDoc = markdownToResolvedDoc(compiledMd);
+```
+
+### Markdown Syntax
+
+#### Inline nodes
+
+```markdown
+:quran[2:البَقَرَة:255]
+:quran[2:البَقَرَة:255]{basmalah nocite}
+:quran[2:البَقَرَة:255:3-7x3,256]{basmalah}
+
+:hadith[narration ^^prophetic speech^^ text]{cite="البخاري" grade="صحيح"}
+
+:quote[quoted text]{cite="المصدر"}
+```
+
+#### Marks
+
+```markdown
+**bold**  *italic*  [link](url)
+^^prophetic speech^^
+{x3:repeated text}
+```
+
+#### Blocks
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+
+Paragraph text {x3}
+
+> Blockquote text
+> {cite="المصدر" x=2}
+
+- Bullet list
+1. Ordered list
+أ. Abjad list
+
+:::poem{cite="الشاعر"}
+صدر | عجز
+صدر | عجز {x3}
+***
+صدر | شطر ثاني | شطر ثالث
+:::
+```
+
+### Escaping
+
+- `\]` inside `:name[content]` — literal `]`
+- `\"` inside `{key="value"}` — literal `"`
+- `\{` at start of blockquote line — literal, not metadata
+
+### Known Limitations
+
+- `^^` inside propheticSpeech mark content is not safe
+- `}` inside inline-repeat mark content is not safe
+- `\]` in directive content loses the backslash
+- Blockquote line exactly matching `{key="value"}` is consumed as metadata
+
+These do not affect Arabic Islamic content.
+
+## Schema Types
+
+```typescript
+import type { QalamDoc, QalamDocResolved, QalamBlock, QalamInline } from "@siladev/qalam";
+```
+
+## Standalone Markdown Manager
+
+```typescript
+import { createMarkdownManager } from "@siladev/qalam";
+
+const manager = createMarkdownManager();
+const json = manager.parse(markdown);
+const md = manager.serialize(json);
+```