@fsegurai/marked-extended-tabs 15.1.0 → 17.0.0-beta.0

package/README.custom.md

@@ -0,0 +1,462 @@
+<!-- SECTION:CUSTOM_INTRO -->
+---
+
+This extension enables you to create interactive tabbed content sections with support for custom icons, animations, and
+nested Markdown content. All tabs are implemented using CSS-only interactions, providing excellent performance and
+accessibility.
+
+<!-- SECTION:CUSTOM_TOC_USAGE -->
+
+	- [Aliases](#aliases)
+	- [Configuration Options](#configuration-options)
+	- [Animation Types](#animation-types)
+	- [Advanced Examples](#advanced-examples)
+
+<!-- SECTION:CUSTOM_BASIC_USAGE -->
+**`tabs` is the identifier for the extended tabs block, and `tab` for individual tab items.**
+
+<!-- SECTION:CUSTOM_USAGE_EXAMPLE -->
+const exampleMarkdown = `
+::::tabs
+:::tab{label="JavaScript" active="true"}
+\`\`\`javascript
+console.log("Hello from JavaScript!");
+\`\`\`
+:::tabend
+
+:::tab{label="Python" icon="🐍"}
+\`\`\`python
+print("Hello from Python!")
+\`\`\`
+:::tabend
+
+:::tab{label="HTML" icon="🌐"}
+\`\`\`html
+<h1>Hello from HTML!</h1>
+\`\`\`
+:::tabend
+::::tabsend
+`;
+
+marked.parse(exampleMarkdown);
+
+<!-- SECTION:CUSTOM_USAGE_NOTES -->
+The extension supports **nested Markdown content** within tabs, including code blocks, tables, lists, and even other
+marked extensions. Tabs use a CSS-only implementation for optimal performance and can be styled to match your design
+system.
+
+### Styling Your Tabs
+
+This extension injects minimal structural CSS for functionality. Visual styling is completely separated for maximum
+flexibility.
+
+#### Generated HTML Structure
+
+```html
+
+<div class="marked-extended-tabs-container" id="tabs-{id}">
+    <nav class="marked-extended-tabs-nav" role="tablist">
+        <input type="radio" name="tabs-{id}" id="tab-{id}-0" class="marked-extended-tabs-input" checked>
+        <label for="tab-{id}-0" class="marked-extended-tabs-label" role="tab">
+            <span class="marked-extended-tabs-icon">🔧</span>
+            <span class="marked-extended-tabs-label-text">JavaScript</span>
+        </label>
+        <!-- More tabs... -->
+    </nav>
+    <div class="marked-extended-tabs-content">
+        <div class="marked-extended-tabs-content-pane" role="tabpanel">
+            <!-- Tab 1 content -->
+        </div>
+        <div class="marked-extended-tabs-content-pane" role="tabpanel">
+            <!-- Tab 2 content -->
+        </div>
+    </div>
+</div>
+```
+
+#### CSS Classes Reference
+
+| Class                                               | Purpose              | Element        |
+|-----------------------------------------------------|----------------------|----------------|
+| `.marked-extended-tabs-container`                   | Main wrapper         | Container      |
+| `.marked-extended-tabs-nav`                         | Tab navigation bar   | Nav            |
+| `.marked-extended-tabs-input`                       | Hidden radio input   | Input (hidden) |
+| `.marked-extended-tabs-label`                       | Tab button/label     | Label          |
+| `.marked-extended-tabs-label[aria-selected="true"]` | Active tab           | Active Label   |
+| `.marked-extended-tabs-icon`                        | Tab icon             | Span           |
+| `.marked-extended-tabs-label-text`                  | Tab text             | Span           |
+| `.marked-extended-tabs-content`                     | Content area wrapper | Div            |
+| `.marked-extended-tabs-content-pane`                | Individual tab pane  | Div            |
+
+#### Complete Styling Example
+
+```css
+/* Container */
+.marked-extended-tabs-container {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    background: #fff;
+    overflow: hidden;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+}
+
+/* Navigation Bar */
+.marked-extended-tabs-nav {
+    display: flex;
+    background: #f5f5f5;
+    border-bottom: 1px solid #ddd;
+    overflow-x: auto;
+    scrollbar-width: thin;
+}
+
+/* Hide radio inputs */
+.marked-extended-tabs-input {
+    position: absolute;
+    opacity: 0;
+    pointer-events: none;
+}
+
+/* Tab Labels (Buttons) */
+.marked-extended-tabs-label {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.75rem 1.5rem;
+    cursor: pointer;
+    border-bottom: 2px solid transparent;
+    background: transparent;
+    transition: all 0.2s ease;
+    font-weight: 500;
+    color: #666;
+    white-space: nowrap;
+}
+
+.marked-extended-tabs-label:hover {
+    background: #e8e8e8;
+    color: #333;
+}
+
+/* Active Tab */
+.marked-extended-tabs-label[aria-selected="true"] {
+    background: #fff;
+    border-bottom-color: #0066cc;
+    color: #0066cc;
+    font-weight: 600;
+}
+
+/* Tab Icon */
+.marked-extended-tabs-icon {
+    font-size: 1.2rem;
+    opacity: 0.8;
+}
+
+/* Content Area */
+.marked-extended-tabs-content {
+    padding: 1.5rem;
+    background: #fff;
+}
+
+.marked-extended-tabs-content-pane {
+    display: none;
+}
+
+/* Show active pane (controlled by radio input) */
+.marked-extended-tabs-input:checked + .marked-extended-tabs-label + * .marked-extended-tabs-content-pane:nth-of-type(1),
+#tab-id-0:checked ~ .marked-extended-tabs-content .marked-extended-tabs-content-pane:nth-of-type(1) {
+    display: block;
+    animation: tab-fade-in 0.3s ease;
+}
+
+/* Fade animation */
+@keyframes tab-fade-in {
+    from {
+        opacity: 0;
+        transform: translateY(10px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+```
+
+#### Variant: Compact Tabs
+
+```css
+.marked-extended-tabs-container.tabs-compact .marked-extended-tabs-label {
+    padding: 0.5rem 0.75rem;
+    font-size: 0.875rem;
+}
+
+.marked-extended-tabs-container.tabs-compact .marked-extended-tabs-content {
+    padding: 0.75rem;
+}
+```
+
+#### Variant: Vertical Tabs
+
+```css
+.marked-extended-tabs-container.tabs-vertical {
+    display: flex;
+}
+
+.marked-extended-tabs-container.tabs-vertical .marked-extended-tabs-nav {
+    flex-direction: column;
+    min-width: 200px;
+    border-right: 1px solid #ddd;
+    border-bottom: none;
+}
+
+.marked-extended-tabs-container.tabs-vertical .marked-extended-tabs-label {
+    border-bottom: none;
+    border-right: 2px solid transparent;
+    justify-content: flex-start;
+}
+
+.marked-extended-tabs-container.tabs-vertical .marked-extended-tabs-label[aria-selected="true"] {
+    border-right-color: #0066cc;
+    border-bottom: none;
+}
+
+.marked-extended-tabs-container.tabs-vertical .marked-extended-tabs-content {
+    flex: 1;
+}
+```
+
+#### Variant: Pills Style
+
+```css
+.marked-extended-tabs-container.tabs-pills .marked-extended-tabs-nav {
+    gap: 0.5rem;
+    padding: 0.5rem;
+    background: #f8f9fa;
+    border-bottom: none;
+}
+
+.marked-extended-tabs-container.tabs-pills .marked-extended-tabs-label {
+    border-radius: 20px;
+    border: none;
+    padding: 0.5rem 1rem;
+}
+
+.marked-extended-tabs-container.tabs-pills .marked-extended-tabs-label:hover {
+    background: #e9ecef;
+}
+
+.marked-extended-tabs-container.tabs-pills .marked-extended-tabs-label[aria-selected="true"] {
+    background: #0066cc;
+    color: white;
+    border: none;
+}
+```
+
+#### Dark Mode Support
+
+```css
+/* Light theme */
+body.light .marked-extended-tabs-container {
+    background: #ffffff;
+    border-color: #ddd;
+}
+
+body.light .marked-extended-tabs-nav {
+    background: #f5f5f5;
+    border-bottom-color: #ddd;
+}
+
+body.light .marked-extended-tabs-label {
+    color: #333;
+}
+
+body.light .marked-extended-tabs-label:hover {
+    background: #e8e8e8;
+}
+
+body.light .marked-extended-tabs-content {
+    background: #ffffff;
+}
+
+/* Dark theme */
+body.dark .marked-extended-tabs-container {
+    background: #22272e;
+    border-color: #444c56;
+}
+
+body.dark .marked-extended-tabs-nav {
+    background: #2d333b;
+    border-bottom-color: #444c56;
+}
+
+body.dark .marked-extended-tabs-label {
+    color: #d1d5da;
+}
+
+body.dark .marked-extended-tabs-label:hover {
+    background: #444c56;
+}
+
+body.dark .marked-extended-tabs-label[aria-selected="true"] {
+    background: #3b4551;
+    color: #58a6ff;
+}
+
+body.dark .marked-extended-tabs-content {
+    background: #22272e;
+    color: #d1d5da;
+}
+```
+
+#### Accessibility Enhancements
+
+```css
+/* Focus styles for keyboard navigation */
+.marked-extended-tabs-input:focus + .marked-extended-tabs-label {
+    outline: 2px solid #0066cc;
+    outline-offset: 2px;
+}
+
+/* Remove outline for mouse users */
+.marked-extended-tabs-input:focus:not(:focus-visible) + .marked-extended-tabs-label {
+    outline: none;
+}
+```
+
+#### Copy Demo Theme
+
+For complete styling with all
+variants: [tabs-theme.css](https://github.com/fsegurai/marked-extensions/blob/main/demo/styles/extensions/tabs-theme.css)
+
+Check the [demo](https://fsegurai.github.io/marked-extensions) to see all tab variants in action.
+
+<!-- SECTION:CUSTOM_SECTIONS -->
+
+### Aliases
+
+The `tabs` block can be rendered using alternative aliases for start and end blocks:
+
+* Start Aliases
+    - `:tbs`
+    - `:tabs`
+* End Aliases
+    - `:tbsend`
+    - `:tabsend`
+
+Individual tabs can use these aliases:
+
+* Tab Start Aliases
+    - `:tab`
+* Tab End Aliases
+    - `:tabend`
+
+### Configuration Options
+
+The marked-extended-tabs extension accepts the following configuration options:
+
+- `className`: The base CSS class name for tabs container. Defaults to 'marked-extended-tabs-container'.
+- `persistSelection`: Whether to remember tab selection across page reloads. Defaults to false.
+- `animation`: Animation type for tab transitions. Defaults to 'fade'. See [Animation Types](#animation-types).
+- `autoActivate`: Automatically activate the first tab if none is explicitly active. Defaults to true.
+- `template`: A custom HTML template for the tabs structure. Defaults to the built-in template.
+- `customizeToken`: A function that allows you to customize the token object before rendering. Defaults to null.
+- `injectStyles`: Whether to inject default CSS styles. Defaults to true.
+
+Tab syntax parameters:
+
+- `label`: The display text for the tab header. Defaults to 'Tab N' where N is the tab number.
+- `active`: Whether this tab is active by default ("true" or "false"). Defaults to "false".
+- `icon`: An optional icon (emoji or Unicode) to display in the tab header. No default.
+
+### Animation Types
+
+The extension supports three animation types:
+
+- `'fade'`: Smooth fade in/out transition between tabs (default)
+- `'slide'`: Horizontal sliding animation between tab contents
+- `'none'`: No animation, instant tab switching
+
+Example with custom animation:
+
+```javascript
+marked.use(markedExtendedTabs({
+    animation: 'slide',
+    autoActivate: true
+}));
+```
+
+### Advanced Examples
+
+#### Tabs with Icons and Mixed Content
+
+```markdown
+::::tabs
+:::tab{label="Overview" icon="📋" active="true"}
+
+## Project Overview
+
+This project demonstrates the power of **nested Markdown** within tabs.
+
+- ✅ Code highlighting
+- ✅ Tables and lists
+- ✅ Images and links
+- ✅ Other extensions
+
+[Learn more →](https://example.com)
+:::tabend
+
+:::tab{label="API Reference" icon="⚙️"}
+
+### REST API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET    | `/api/users` | List all users |
+| POST   | `/api/users` | Create user |
+| PUT    | `/api/users/{id}` | Update user |
+
+> **Note**: All endpoints require authentication.
+:::tabend
+
+:::tab{label="Examples" icon="💻"}
+
+### Code Examples
+
+JavaScript implementation:
+\`\`\`javascript
+const api = new APIClient({
+baseUrl: 'https://api.example.com',
+apiKey: 'your-key-here'
+});
+
+const users = await api.get('/users');
+console.log(users);
+\`\`\`
+
+Python implementation:
+\`\`\`python
+import requests
+
+response = requests.get('https://api.example.com/users')
+users = response.json()
+print(users)
+\`\`\`
+:::tabend
+::::tabsend
+```
+
+#### Configuration Example
+
+```javascript
+import {marked} from "marked";
+import markedExtendedTabs from "@fsegurai/marked-extended-tabs";
+
+marked.use(markedExtendedTabs({
+    className: 'my-custom-tabs',
+    animation: 'slide',
+    persistSelection: true,
+    autoActivate: true,
+    customizeToken: (token) => {
+        // Add custom logic here
+        console.log('Processing tabs token:', token);
+    }
+}));
+```