@umbra.ui/core 0.1.0

package/src/components/views/MarkdownViewer/README.md

@@ -0,0 +1,833 @@
+# MarkdownViewer
+
+A comprehensive markdown viewer component built with Vue 3 Composition API and TypeScript. The MarkdownViewer provides rich markdown rendering with syntax highlighting, copy-to-clipboard functionality for code blocks, and extensive theming support for both light and dark modes.
+
+## Installation/Import
+
+```typescript
+import { MarkdownViewer } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- marked (for markdown parsing)
+- prismjs (for syntax highlighting)
+- @umbra-ui/icons (for copy button icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+const markdownContent = ref(`
+# Hello World
+
+This is a **markdown** document with \`inline code\` and a code block:
+
+\`\`\`typescript
+const greeting = "Hello, World!";
+console.log(greeting);
+\`\`\`
+
+## Features
+
+- Syntax highlighting
+- Copy to clipboard
+- Responsive tables
+- Beautiful typography
+`);
+</script>
+
+<template>
+  <div class="app">
+    <MarkdownViewer :content="markdownContent" />
+  </div>
+</template>
+
+<style module>
+.app {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+</style>
+```
+
+## Props
+
+| Prop Name | Type     | Required | Default | Description                    |
+| --------- | -------- | -------- | ------- | ------------------------------ |
+| `content` | `string` | Yes      | `""`    | The markdown content to render |
+
+## Events
+
+This component does not emit any events.
+
+## Slots
+
+This component does not provide any slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## CSS Customization
+
+The MarkdownViewer component supports extensive theming through CSS custom properties:
+
+### Container and Typography
+
+```css
+:root {
+  /* Container colors */
+  --markdownviewer-container-color: var(--text-2);
+  --markdownviewer-container-font-family: -apple-system, BlinkMacSystemFont,
+    "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+    "Droid Sans", "Helvetica Neue", sans-serif;
+
+  /* Header colors */
+  --markdownviewer-header-color: var(--text-primary);
+  --markdownviewer-header-border: rgba(0, 0, 0, 0.1);
+
+  /* Paragraph colors */
+  --markdownviewer-paragraph-color: var(--text-secondary);
+
+  /* Link colors */
+  --markdownviewer-link-color: var(--link);
+  --markdownviewer-link-hover-color: var(--accent);
+}
+```
+
+### Code Blocks and Syntax Highlighting
+
+```css
+:root {
+  /* Inline code */
+  --markdownviewer-inline-code-bg: #f3f4f6;
+  --markdownviewer-inline-code-color: #1f2937;
+
+  /* Code blocks */
+  --markdownviewer-code-block-bg: #ffffff;
+  --markdownviewer-code-block-border: #e1e4e8;
+  --markdownviewer-code-block-color: #24292e;
+
+  /* Copy button */
+  --markdownviewer-copy-button-color: #24292e;
+  --markdownviewer-copy-button-bg: transparent;
+  --markdownviewer-copy-button-hover-bg: #f6f8fa;
+  --markdownviewer-copy-button-copied-color: #22863a;
+  --markdownviewer-copy-button-copied-border: #34d058;
+}
+```
+
+### Tables and Other Elements
+
+```css
+:root {
+  /* Tables */
+  --markdownviewer-table-border: rgba(0, 0, 0, 0.1);
+  --markdownviewer-table-th-bg: #f9fafb;
+  --markdownviewer-table-th-color: #1f2937;
+  --markdownviewer-table-tr-even-bg: #f3f4f6;
+  --markdownviewer-table-tr-hover-bg: #e5e7eb;
+
+  /* Horizontal rules */
+  --markdownviewer-hr-bg: rgba(0, 0, 0, 0.1);
+
+  /* Blockquotes */
+  --markdownviewer-blockquote-color: #6b7280;
+  --markdownviewer-blockquote-border: rgba(0, 0, 0, 0.1);
+
+  /* Strong text */
+  --markdownviewer-strong-color: #1f2937;
+}
+```
+
+### Syntax Highlighting Tokens
+
+```css
+:root {
+  /* Syntax highlighting colors */
+  --markdownviewer-token-comment: #6a737d;
+  --markdownviewer-token-punctuation: #24292e;
+  --markdownviewer-token-tag: #0550ae;
+  --markdownviewer-token-property: #116329;
+  --markdownviewer-token-boolean: #cf222e;
+  --markdownviewer-token-string: #0a3069;
+  --markdownviewer-token-operator: #24292e;
+  --markdownviewer-token-keyword: #cf222e;
+  --markdownviewer-token-function: #953800;
+  --markdownviewer-token-regex: #953800;
+}
+```
+
+## Examples
+
+### Documentation Viewer
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+const documentation = ref("");
+
+const loadDocumentation = async () => {
+  try {
+    const response = await fetch("/api/documentation");
+    documentation.value = await response.text();
+  } catch (error) {
+    console.error("Failed to load documentation:", error);
+  }
+};
+
+onMounted(() => {
+  loadDocumentation();
+});
+</script>
+
+<template>
+  <div class="documentation-viewer">
+    <div class="sidebar">
+      <h3>Table of Contents</h3>
+      <!-- Navigation items -->
+    </div>
+
+    <div class="content">
+      <MarkdownViewer :content="documentation" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.documentation-viewer {
+  display: flex;
+  height: 100vh;
+}
+
+.sidebar {
+  width: 300px;
+  background: var(--background-2);
+  padding: 1rem;
+  border-right: 1px solid var(--border-2);
+}
+
+.content {
+  flex: 1;
+  padding: 2rem;
+  overflow-y: auto;
+}
+</style>
+```
+
+### Blog Post Viewer
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+interface BlogPost {
+  id: string;
+  title: string;
+  content: string;
+  author: string;
+  publishedAt: string;
+}
+
+const currentPost = ref<BlogPost>({
+  id: "1",
+  title: "Getting Started with Vue 3",
+  content: `
+# Getting Started with Vue 3
+
+Vue 3 introduces the **Composition API** which provides a more flexible way to organize component logic.
+
+## Key Features
+
+- **Composition API**: Better logic reuse and organization
+- **Better TypeScript support**: Improved type inference
+- **Performance improvements**: Faster rendering and smaller bundle size
+- **Multiple root elements**: No more single root element requirement
+
+## Basic Example
+
+\`\`\`vue
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+
+const increment = () => {
+  count.value++
+}
+</script>
+
+<template>
+  <div>
+    <p>Count: {{ count }}</p>
+    <p>Doubled: {{ doubled }}</p>
+    <button @click="increment">Increment</button>
+  </div>
+</template>
+\`\`\`
+
+## Conclusion
+
+Vue 3 is a significant improvement over Vue 2, offering better developer experience and performance.
+`,
+  author: "John Doe",
+  publishedAt: "2024-01-15"
+});
+
+const formattedDate = computed(() => {
+  return new Date(currentPost.value.publishedAt).toLocaleDateString();
+});
+</script>
+
+<template>
+  <article class="blog-post">
+    <header class="post-header">
+      <h1>{{ currentPost.title }}</h1>
+      <div class="post-meta">
+        <span class="author">By {{ currentPost.author }}</span>
+        <span class="date">{{ formattedDate }}</span>
+      </div>
+    </header>
+
+    <div class="post-content">
+      <MarkdownViewer :content="currentPost.content" />
+    </div>
+  </article>
+</template>
+
+<style module>
+.blog-post {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+
+.post-header {
+  margin-bottom: 2rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--border-2);
+}
+
+.post-header h1 {
+  margin: 0 0 1rem 0;
+  color: var(--text-primary);
+}
+
+.post-meta {
+  display: flex;
+  gap: 1rem;
+  color: var(--text-secondary);
+  font-size: 0.9rem;
+}
+
+.post-content {
+  line-height: 1.6;
+}
+</style>
+```
+
+### Code Documentation with Custom Styling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+const apiDocumentation = ref(`
+# API Reference
+
+## Authentication
+
+All API requests require authentication using a Bearer token.
+
+\`\`\`bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \\
+     https://api.example.com/users
+\`\`\`
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | /users | List all users |
+| POST | /users | Create a new user |
+| GET | /users/:id | Get user by ID |
+| PUT | /users/:id | Update user |
+| DELETE | /users/:id | Delete user |
+
+## Response Format
+
+All responses follow this format:
+
+\`\`\`json
+{
+  "success": true,
+  "data": {
+    "id": "123",
+    "name": "John Doe",
+    "email": "john@example.com"
+  },
+  "message": "User retrieved successfully"
+}
+\`\`\`
+
+> **Note**: All timestamps are in ISO 8601 format (UTC).
+`);
+
+// Custom styling for API documentation
+const customStyles = `
+  .api-docs {
+    --markdownviewer-code-block-bg: #f8f9fa;
+    --markdownviewer-code-block-border: #e9ecef;
+    --markdownviewer-table-th-bg: #f1f3f4;
+    --markdownviewer-blockquote-border: #007bff;
+  }
+`;
+</script>
+
+<template>
+  <div class="api-documentation">
+    <style v-html="customStyles"></style>
+
+    <div class="api-docs">
+      <MarkdownViewer :content="apiDocumentation" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.api-documentation {
+  padding: 2rem;
+  background: var(--background-1);
+  min-height: 100vh;
+}
+
+.api-docs {
+  max-width: 1000px;
+  margin: 0 auto;
+  background: var(--background-2);
+  padding: 2rem;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+</style>
+```
+
+### Interactive Markdown Editor
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+const markdownInput = ref(`# Markdown Editor
+
+Type your markdown here and see it rendered in real-time!
+
+## Features
+
+- **Bold text**
+- *Italic text*
+- \`inline code\`
+- [Links](https://example.com)
+
+### Code Block
+
+\`\`\`javascript
+function greet(name) {
+  return \`Hello, \${name}!\`;
+}
+
+console.log(greet("World"));
+\`\`\`
+
+### List
+
+1. First item
+2. Second item
+3. Third item
+
+> This is a blockquote
+`);
+
+const wordCount = computed(() => {
+  return markdownInput.value.split(/\s+/).filter((word) => word.length > 0)
+    .length;
+});
+
+const characterCount = computed(() => {
+  return markdownInput.value.length;
+});
+
+const clearContent = () => {
+  markdownInput.value = "";
+};
+
+const insertTemplate = () => {
+  markdownInput.value = `# New Document
+
+## Introduction
+
+Write your content here...
+
+## Code Example
+
+\`\`\`typescript
+// Your code here
+\`\`\`
+
+## Conclusion
+
+Your conclusion here.
+`;
+};
+</script>
+
+<template>
+  <div class="markdown-editor">
+    <div class="editor-header">
+      <h2>Markdown Editor</h2>
+      <div class="stats">
+        <span>{{ wordCount }} words</span>
+        <span>{{ characterCount }} characters</span>
+      </div>
+      <div class="actions">
+        <button @click="clearContent" class="btn btn-secondary">Clear</button>
+        <button @click="insertTemplate" class="btn btn-primary">
+          Template
+        </button>
+      </div>
+    </div>
+
+    <div class="editor-layout">
+      <div class="input-panel">
+        <h3>Markdown Input</h3>
+        <textarea
+          v-model="markdownInput"
+          class="markdown-textarea"
+          placeholder="Type your markdown here..."
+        ></textarea>
+      </div>
+
+      <div class="preview-panel">
+        <h3>Preview</h3>
+        <div class="preview-content">
+          <MarkdownViewer :content="markdownInput" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.markdown-editor {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.editor-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 2rem;
+  background: var(--background-2);
+  border-bottom: 1px solid var(--border-2);
+}
+
+.stats {
+  display: flex;
+  gap: 1rem;
+  color: var(--text-secondary);
+  font-size: 0.9rem;
+}
+
+.actions {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.btn {
+  padding: 0.5rem 1rem;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.9rem;
+  transition: background-color 0.2s;
+}
+
+.btn-primary {
+  background: var(--accent);
+  color: white;
+}
+
+.btn-primary:hover {
+  background: var(--accent-hover);
+}
+
+.btn-secondary {
+  background: var(--control-2);
+  color: var(--text-1);
+}
+
+.btn-secondary:hover {
+  background: var(--control-3);
+}
+
+.editor-layout {
+  flex: 1;
+  display: flex;
+}
+
+.input-panel,
+.preview-panel {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+}
+
+.input-panel {
+  border-right: 1px solid var(--border-2);
+}
+
+.input-panel h3,
+.preview-panel h3 {
+  margin: 0;
+  padding: 1rem 2rem;
+  background: var(--background-3);
+  border-bottom: 1px solid var(--border-2);
+  font-size: 1rem;
+}
+
+.markdown-textarea {
+  flex: 1;
+  padding: 1rem 2rem;
+  border: none;
+  outline: none;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 14px;
+  line-height: 1.5;
+  background: var(--background-1);
+  color: var(--text-1);
+  resize: none;
+}
+
+.preview-content {
+  flex: 1;
+  padding: 1rem 2rem;
+  overflow-y: auto;
+  background: var(--background-1);
+}
+</style>
+```
+
+### Readme Viewer with Custom Theme
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { MarkdownViewer } from "@umbra-ui/core";
+
+const readmeContent = ref(`
+# My Awesome Project
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)
+
+A fantastic project that does amazing things!
+
+## 🚀 Features
+
+- ⚡ **Fast**: Built for performance
+- 🎨 **Beautiful**: Modern UI design
+- 🔧 **Configurable**: Highly customizable
+- 📱 **Responsive**: Works on all devices
+
+## 📦 Installation
+
+\`\`\`bash
+npm install my-awesome-project
+\`\`\`
+
+## 🎯 Quick Start
+
+\`\`\`typescript
+import { AwesomeProject } from 'my-awesome-project';
+
+const project = new AwesomeProject({
+  theme: 'dark',
+  animations: true
+});
+
+project.start();
+\`\`\`
+
+## 📖 API Reference
+
+### \`AwesomeProject(options)\`
+
+Creates a new instance of AwesomeProject.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| \`theme\` | \`string\` | \`'light'\` | Theme to use |
+| \`animations\` | \`boolean\` | \`true\` | Enable animations |
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (\`git checkout -b feature/amazing-feature\`)
+3. Commit your changes (\`git commit -m 'Add amazing feature'\`)
+4. Push to the branch (\`git push origin feature/amazing-feature\`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Thanks to all contributors
+- Inspired by the community
+- Built with ❤️
+`);
+
+// Custom theme for readme styling
+const readmeTheme = `
+  .readme-theme {
+    --markdownviewer-header-color: #2d3748;
+    --markdownviewer-link-color: #3182ce;
+    --markdownviewer-link-hover-color: #2c5282;
+    --markdownviewer-code-block-bg: #f7fafc;
+    --markdownviewer-code-block-border: #e2e8f0;
+    --markdownviewer-table-th-bg: #edf2f7;
+    --markdownviewer-blockquote-border: #3182ce;
+  }
+`;
+</script>
+
+<template>
+  <div class="readme-viewer">
+    <style v-html="readmeTheme"></style>
+
+    <div class="readme-theme">
+      <MarkdownViewer :content="readmeContent" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.readme-viewer {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 2rem;
+  background: var(--background-1);
+  min-height: 100vh;
+}
+
+.readme-theme {
+  background: var(--background-2);
+  padding: 2rem;
+  border-radius: 12px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+</style>
+```
+
+## Features
+
+### Syntax Highlighting
+
+The MarkdownViewer includes comprehensive syntax highlighting for:
+
+- **Languages**: TypeScript, JavaScript, Python, Java, C++, Go, Rust, and many more
+- **Language Aliases**: Automatic mapping (e.g., `ts` → `typescript`, `js` → `javascript`)
+- **Fallback**: Unsupported languages fall back to plain text
+- **VS Code Theme**: Colors match VS Code's default theme for familiarity
+
+### Copy to Clipboard
+
+- **Automatic Enhancement**: Code blocks are automatically enhanced with copy buttons
+- **Visual Feedback**: Copy button appears on hover with success animation
+- **Icon Integration**: Uses @umbra-ui/icons for consistent iconography
+- **Fallback Support**: Graceful fallback for browsers without clipboard API
+
+### Responsive Design
+
+- **Mobile Friendly**: Optimized for all screen sizes
+- **Table Scrolling**: Tables scroll horizontally on small screens
+- **Typography**: Responsive font sizes and spacing
+- **Touch Support**: Optimized for touch interactions
+
+### Accessibility
+
+- **Semantic HTML**: Proper heading hierarchy and semantic elements
+- **ARIA Labels**: Copy buttons include proper ARIA labels
+- **Keyboard Navigation**: Full keyboard accessibility
+- **Screen Reader Support**: Compatible with assistive technologies
+
+## Performance
+
+- **Lazy Rendering**: Content is rendered efficiently with Vue's reactivity
+- **Optimized Parsing**: Uses marked.js for fast markdown parsing
+- **Minimal Re-renders**: Only re-renders when content changes
+- **Memory Efficient**: Proper cleanup of event listeners and DOM elements
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Clipboard API**: Uses modern clipboard API with fallback
+- **CSS Grid/Flexbox**: Requires modern CSS support
+- **ES6+**: Requires modern JavaScript support
+
+## Migration Notes
+
+### From v1.x to v2.x
+
+- Updated to use marked v5+ with new token signature
+- Improved syntax highlighting with better language detection
+- Enhanced copy button functionality with better error handling
+- Updated CSS custom properties for better theming support
+
+### Breaking Changes
+
+- None in current version - fully backward compatible
+
+## Troubleshooting
+
+### Common Issues
+
+**Syntax highlighting not working:**
+
+- Ensure prismjs is properly installed and imported
+- Check that language names are supported by Prism.js
+- Verify that the language is correctly specified in code blocks
+
+**Copy button not appearing:**
+
+- Check browser console for JavaScript errors
+- Ensure @umbra-ui/icons is properly installed
+- Verify that the component is properly mounted
+
+**Styling issues:**
+
+- Check that theme.css is properly imported
+- Verify CSS custom properties are defined
+- Ensure proper CSS specificity for custom overrides
+
+### Performance Tips
+
+- Use `v-memo` for large markdown content that doesn't change often
+- Consider virtual scrolling for very long documents
+- Lazy load markdown content when possible
+- Use `shallowRef` for content that doesn't need deep reactivity