@thiennq/docs-viewer - npm Package Compare versions

Comparing version 1.6.0 to 1.6.1

AGENTS.md

@@ -11,3 +11,3 @@ # Integration & Configuration Guide (`@thiennq/docs-viewer`)
 * **Backend**: Pure Node.js server (zero external dependencies) to scan files, serve JSON file trees, manage inline comments, and serve static assets.
-* **Frontend**: Vanilla HTML/JS/CSS, rendering Markdown documents smoothly using CDN libraries (`marked.js`, `mermaid.js` for diagrams, `KaTeX` for math formulas, `highlight.js` for code syntax highlighting, `DOMPurify` for HTML, Babel & React for MDX).
+* **Frontend**: Vanilla HTML/JS/CSS, rendering Markdown & MDX documents smoothly using CDN libraries (`marked.js`, `mermaid.js` for diagrams, `KaTeX` for math formulas, `highlight.js` for code syntax highlighting, `DOMPurify` for HTML, `Chart.js` for data visualization, `styled-components`, Babel Standalone & React 18 for client-side MDX & no-build modular JSX components).
 
@@ -28,3 +28,14 @@ ---
 │   ├── app.js
-│   └── style.css
+│   ├── mdx.js              ← Modular MDX transpilation engine
+│   ├── loader.js           ← Dynamic No-build JSX component loader
+│   ├── style.css
+│   └── components/         ← Built-in React/JSX component library
+│       ├── Badge.jsx
+│       ├── Button.jsx
+│       ├── Callout.jsx
+│       ├── Card.jsx
+│       ├── StatCard.jsx
+│       ├── StatGrid.jsx
+│       ├── StyledCard.jsx
+│       └── ThresholdViewer.jsx
 │
@@ -113,2 +124,6 @@ ├── [your-docs-folder-1]/   ← Your documentation directory (e.g., docs, v1, wiki,...)
    * When changing accent colors, modify `--accent` and `--accent-dim` in `:root`. Avoid writing inline CSS styles in JavaScript.
+5. **No-Build Modular JSX Components (`public/components/`)**:
+   * MDX documents can utilize built-in or custom JSX components. Components are located in `public/components/` as modular `.jsx` files.
+   * `public/loader.js` dynamically fetches and transpiles `.jsx` files at runtime via Babel Standalone without requiring any bundler or build step.
+   * When adding new UI components, place them in `public/components/` and register them in `public/mdx.js` scope if they are to be globally available in MDX files.
 
@@ -133,1 +148,86 @@ ---
 4. **Resolving Threads**: Click **✓ Resolve** to mark threads as resolved.
+
+---
+
+## 7. MDX Writing Guidelines & Component Examples
+
+Docs Viewer supports writing documents using **MDX** (`.mdx` files) which combines standard Markdown syntax with interactive React/JSX components, transpiled entirely client-side without any bundler or build step.
+
+### 7.1. General Guidelines for Writing MDX
+1. **File Extension**: Save MDX documents with `.mdx` extension (e.g., `getting-started.mdx`).
+2. **Valid JSX Syntax**: All JSX elements must be properly closed (e.g., `<br />`, `<hr />`, `<img src="..." />`).
+3. **Mixing Markdown & Components**: Leave an empty line before and after JSX block tags so Markdown headers, lists, and paragraphs parse cleanly.
+4. **No Import Statements Needed**: All built-in components inside `public/components/` are automatically available globally in MDX files without needing `import ... from ...` statements.
+
+### 7.2. Available Built-in Components & Examples
+
+#### 1. `<Callout>` — Highlighted Notification Banners
+Displays notice, alert, warning, or success boxes.
+- **Props**: `type` (`"info" | "warning" | "success" | "error"`), `title` (optional string).
+
+```jsx
+<Callout type="info" title="Architecture Note">
+This section outlines the backend communication protocol.
+</Callout>
+
+<Callout type="warning" title="Important Warning">
+Ensure path traversal validation is never disabled.
+</Callout>
+```
+
+#### 2. `<Card>` — Content Cards
+Encloses content within a styled card container.
+- **Props**: `title` (optional string), `icon` (optional emoji or icon text, default `'📁'`).
+
+```jsx
+<Card title="Quick Start Guide" icon="🚀">
+Follow the steps below to integrate Docs Viewer into your project package.json.
+</Card>
+```
+
+#### 3. `<Badge>` — Status & Difficulty Badges
+Displays inline status tags or difficulty badges.
+- **Props**: `type` (`"default" | "primary" | "success" | "warning" | "danger"`). Preset text (`Easy`, `Medium`, `Hard`, `Nightmare`) automatically applies tailored color themes.
+
+```jsx
+Difficulty: <Badge>Easy</Badge> | Status: <Badge type="success">Active</Badge>
+```
+
+#### 4. `<Button>` — Styled Action Buttons
+Renders styled interactive buttons.
+- **Props**: `variant` (`"primary" | "secondary"`), `onClick` (optional handler function).
+
+```jsx
+<Button variant="primary">Download Specs</Button>
+```
+
+#### 5. `<StatGrid>` & `<StatCard>` — Metric Dashboard Cards
+Renders grid layouts of key metrics and statistics.
+- **`<StatGrid>` Props**: `children`
+- **`<StatCard>` Props**: `label`, `value`, `sub` (optional subtext), `color` (optional accent color hex/rgb).
+
+```jsx
+<StatGrid>
+  <StatCard label="Total Requests" value="1,248" sub="+12% from last week" color="#6366f1" />
+  <StatCard label="Avg Response Time" value="14ms" sub="Optimal performance" color="#10b981" />
+</StatGrid>
+```
+
+#### 6. `<StyledCard>` — CSS-in-JS Styled Components
+Demonstrates custom component styling using `styled-components`.
+- **Props**: `title` (optional string).
+
+```jsx
+<StyledCard title="Custom CSS-in-JS Component">
+This card is styled dynamically using styled-components without external CSS files.
+</StyledCard>
+```
+
+#### 7. `<ThresholdViewer>` — Chart.js Data Visualizations
+Renders interactive statistical charts powered by Chart.js.
+- **Props**: `data` (optional custom dataset object).
+
+```jsx
+<ThresholdViewer />
+```
+

CHANGELOG.md

@@ -5,2 +5,12 @@ # Docs Viewer CHANGELOG
 
+## [1.6.1] - 2026-07-26
+
+### Added / Documentation
+* **Comprehensive MDX & JSX Component Documentation (`AGENTS.md`)**:
+  * Added Section 7 with complete MDX writing guidelines and JSX syntax rules.
+  * Added detailed API documentation and usage code examples for all 7 built-in components (`<Callout>`, `<Card>`, `<Badge>`, `<Button>`, `<StatGrid>`, `<StatCard>`, `<StyledCard>`, `<ThresholdViewer>`).
+  * Updated `AGENTS.md` project directory structure and core technology overview.
+
+---
+
 ## [1.6.0] - 2026-07-26
@@ -7,0 +17,0 @@

package.json

 {
   "name": "@thiennq/docs-viewer",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Standalone Docs Viewer CLI — static HTTP server & browser reader for Markdown, MDX, HTML and Mermaid diagrams",
@@ -5,0 +5,0 @@ "main": "server.js",

No alert changes

Improved metrics

Total package byte prevSize

192022

2.63%

No dependency changes