@panyam/tsappkit 0.0.3 → 0.0.4

package/src/docs/ActionCompiler.ts

@@ -0,0 +1,186 @@
+/**
+ * ActionCompiler - Shared action code compilation and execution
+ * Used by docs components like ExampleRunner and PlaygroundPage
+ */
+
+import ace from "ace-builds";
+
+export interface ActionCompileResult {
+  success: boolean;
+  fn: ((node: any) => any) | null;
+  error: string | null;
+  line: number | null; // 0-indexed line number for error
+}
+
+export interface ActionRunResult {
+  success: boolean;
+  result: any;
+  error: string | null;
+  line: number | null; // 0-indexed line number for runtime error
+}
+
+export class ActionCompiler {
+  private editor: ace.Ace.Editor | null = null;
+  private compiledFn: ((node: any) => any) | null = null;
+  private compileError: string | null = null;
+  private statusEl: HTMLElement | null = null;
+  private onCompile: ((result: ActionCompileResult) => void) | null = null;
+
+  constructor(
+    editor: ace.Ace.Editor,
+    statusEl: HTMLElement | null = null,
+    onCompile: ((result: ActionCompileResult) => void) | null = null,
+  ) {
+    this.editor = editor;
+    this.statusEl = statusEl;
+    this.onCompile = onCompile;
+
+    // Setup change listener with debounce
+    let compileTimeout: number | null = null;
+    this.editor.session.on("change", () => {
+      if (compileTimeout) clearTimeout(compileTimeout);
+      compileTimeout = window.setTimeout(() => this.compile(), 300);
+    });
+  }
+
+  /**
+   * Compile the current editor content
+   */
+  compile(): ActionCompileResult {
+    if (!this.editor) {
+      return { success: false, fn: null, error: "No editor", line: null };
+    }
+
+    const code = this.editor.getValue().trim();
+    const session = this.editor.session;
+
+    // Clear previous annotations
+    session.clearAnnotations();
+    this.compiledFn = null;
+    this.compileError = null;
+
+    if (!code) {
+      this.updateStatus("", "");
+      const result = { success: true, fn: null, error: null, line: null };
+      this.onCompile?.(result);
+      return result;
+    }
+
+    try {
+      // Compile using new Function
+      this.compiledFn = new Function("node", code) as (node: any) => any;
+      this.updateStatus("✓", "success");
+      const result = { success: true, fn: this.compiledFn, error: null, line: null };
+      this.onCompile?.(result);
+      return result;
+    } catch (e: any) {
+      this.compileError = e.message;
+      this.updateStatus("✗ Compile Error", "error");
+
+      // Try to extract line number from error message
+      // Common patterns: "at line 5", "line 5", ":5:", "(5:"
+      const lineMatch = e.message.match(/(?:at line |line |:|\()(\d+)(?::|,|\))/i);
+      const line = lineMatch ? parseInt(lineMatch[1], 10) - 1 : 0; // 0-indexed
+
+      session.setAnnotations([
+        {
+          row: line,
+          column: 0,
+          text: e.message,
+          type: "error",
+        },
+      ]);
+
+      const result = { success: false, fn: null, error: e.message, line };
+      this.onCompile?.(result);
+      return result;
+    }
+  }
+
+  /**
+   * Run the compiled action on a parse tree node
+   */
+  run(node: any): ActionRunResult {
+    if (!node) {
+      return { success: false, result: null, error: "No parse result available", line: null };
+    }
+
+    if (this.compileError) {
+      return { success: false, result: null, error: `Compile Error: ${this.compileError}`, line: null };
+    }
+
+    if (!this.compiledFn) {
+      return { success: true, result: null, error: null, line: null }; // No action code
+    }
+
+    try {
+      const result = this.compiledFn(node);
+      // Clear runtime error annotations
+      if (this.editor) {
+        this.editor.session.clearAnnotations();
+      }
+      this.updateStatus("✓", "success");
+      return { success: true, result, error: null, line: null };
+    } catch (e: any) {
+      // Try to extract line number from runtime error stack
+      const stack = e.stack || "";
+      const lineMatch = stack.match(/<anonymous>:(\d+):/);
+      const line = lineMatch ? parseInt(lineMatch[1], 10) - 1 : null; // 0-indexed
+
+      // Set runtime error annotation
+      if (this.editor && line !== null) {
+        this.editor.session.setAnnotations([
+          {
+            row: line,
+            column: 0,
+            text: e.message,
+            type: "error",
+          },
+        ]);
+      }
+
+      this.updateStatus("✗ Runtime Error", "error");
+      return { success: false, result: null, error: e.message, line };
+    }
+  }
+
+  /**
+   * Get the current compile error (if any)
+   */
+  getCompileError(): string | null {
+    return this.compileError;
+  }
+
+  /**
+   * Check if there's a compiled action function
+   */
+  hasCompiledAction(): boolean {
+    return this.compiledFn !== null;
+  }
+
+  /**
+   * Update status element
+   */
+  private updateStatus(text: string, statusClass: string): void {
+    if (this.statusEl) {
+      this.statusEl.textContent = text;
+      // Clear and set status classes without removing base class
+      this.statusEl.classList.remove("success", "error");
+      if (statusClass) {
+        this.statusEl.classList.add(statusClass);
+      }
+    }
+  }
+
+  /**
+   * Clear annotations and status
+   */
+  clear(): void {
+    if (this.editor) {
+      this.editor.session.clearAnnotations();
+    }
+    this.compiledFn = null;
+    this.compileError = null;
+    this.updateStatus("", "");
+  }
+}

package/src/docs/CodeBlock.ts

@@ -0,0 +1,103 @@
+/**
+ * CodeBlock.ts - Enhances pre/code blocks with copy functionality
+ * Automatically finds all pre>code elements and adds a copy button
+ */
+
+export class CodeBlock {
+  private container: HTMLElement;
+  private copyButton: HTMLButtonElement;
+  private codeElement: HTMLElement;
+
+  constructor(preElement: HTMLPreElement) {
+    this.codeElement = preElement.querySelector('code') || preElement;
+
+    // Wrap pre in a container for positioning
+    this.container = document.createElement('div');
+    this.container.className = 'code-block';
+    preElement.parentNode?.insertBefore(this.container, preElement);
+    this.container.appendChild(preElement);
+
+    // Create copy button
+    this.copyButton = document.createElement('button');
+    this.copyButton.className = 'code-block-copy';
+    this.copyButton.setAttribute('aria-label', 'Copy code');
+    this.copyButton.innerHTML = this.getCopyIcon();
+    this.copyButton.addEventListener('click', () => this.copyCode());
+
+    this.container.appendChild(this.copyButton);
+  }
+
+  private getCopyIcon(): string {
+    return `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+    </svg>`;
+  }
+
+  private getCheckIcon(): string {
+    return `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <polyline points="20 6 9 17 4 12"></polyline>
+    </svg>`;
+  }
+
+  private async copyCode(): Promise<void> {
+    const text = this.codeElement.textContent || '';
+
+    try {
+      await navigator.clipboard.writeText(text);
+      this.showSuccess();
+    } catch (err) {
+      // Fallback for older browsers
+      this.fallbackCopy(text);
+    }
+  }
+
+  private fallbackCopy(text: string): void {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+
+    try {
+      document.execCommand('copy');
+      this.showSuccess();
+    } catch (err) {
+      console.error('Failed to copy:', err);
+    }
+
+    document.body.removeChild(textarea);
+  }
+
+  private showSuccess(): void {
+    this.copyButton.innerHTML = this.getCheckIcon();
+    this.copyButton.classList.add('copied');
+
+    setTimeout(() => {
+      this.copyButton.innerHTML = this.getCopyIcon();
+      this.copyButton.classList.remove('copied');
+    }, 2000);
+  }
+}
+
+/**
+ * Initialize all code blocks on the page
+ * @param selector - CSS selector for finding pre elements (default: '.content-body pre')
+ */
+export function initCodeBlocks(selector: string = '.content-body pre'): void {
+  const preElements = document.querySelectorAll(selector);
+
+  preElements.forEach((pre) => {
+    // Skip if already initialized
+    if (pre.parentElement?.classList.contains('code-block')) {
+      return;
+    }
+    // Skip if this pre contains another pre (outer wrapper of double-wrapped code blocks)
+    // We only want to process the innermost pre that has the actual code
+    if (pre.querySelector('pre')) {
+      return;
+    }
+    new CodeBlock(pre as HTMLPreElement);
+  });
+}

package/src/docs/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Documentation site components and utilities
+ *
+ * This module provides reusable components for building documentation sites:
+ * - CodeBlock: Copy-to-clipboard for code blocks
+ * - pageSetup: Common page initialization (sidebar highlighting, etc.)
+ * - ActionCompiler: Compile and run user-provided action code
+ */
+
+export { CodeBlock, initCodeBlocks } from './CodeBlock';
+export { highlightActiveSidebarLink, initPageSetup } from './pageSetup';
+export { ActionCompiler } from './ActionCompiler';
+export type { ActionCompileResult, ActionRunResult } from './ActionCompiler';

package/src/docs/pageSetup.ts

@@ -0,0 +1,32 @@
+/**
+ * pageSetup.ts - Common page initialization shared across all doc pages
+ */
+
+/**
+ * Highlights the currently active link in the sidebar navigation
+ * @param sidebarSelector - CSS selector for sidebar links (default: '.sidebar .section-nav a')
+ */
+export function highlightActiveSidebarLink(sidebarSelector: string = '.sidebar .section-nav a'): void {
+  const currentPath = window.location.pathname;
+  const sidebarLinks = document.querySelectorAll(sidebarSelector);
+
+  sidebarLinks.forEach((link) => {
+    const href = link.getAttribute('href');
+    if (href && currentPath.endsWith(href.replace(/\/$/, '') + '/')) {
+      link.classList.add('active');
+    } else if (href && currentPath === href) {
+      link.classList.add('active');
+    }
+  });
+}
+
+/**
+ * Initialize common page features
+ * Call this on DOMContentLoaded for all doc pages
+ * @param options - Configuration options for page setup
+ */
+export function initPageSetup(options: {
+  sidebarSelector?: string;
+} = {}): void {
+  highlightActiveSidebarLink(options.sidebarSelector);
+}

package/styles/docs/DocsPage.scss

@@ -0,0 +1,22 @@
+// ============================================
+//   DocsPage - Main Documentation Styles
+//
+//   This is the main entry point for documentation site styling.
+//   Import this file in your project's main stylesheet:
+//
+//   @use '@panyam/tsappkit/styles/docs/DocsPage.scss';
+//
+//   Or import individual partials for customization:
+//
+//   @use '@panyam/tsappkit/styles/docs/variables';
+//   @use '@panyam/tsappkit/styles/docs/base';
+//   // ... add your customizations
+// ============================================
+
+@use 'variables';
+@use 'base';
+@use 'header';
+@use 'layout';
+@use 'content';
+@use 'footer';
+@use 'responsive';

package/styles/docs/_base.scss

@@ -0,0 +1,39 @@
+// ============================================
+//   Base Styles - Reset & Typography
+// ============================================
+
+// Reset
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--font-sans);
+  color: var(--color-text);
+  background: var(--color-bg);
+  line-height: 1.6;
+  min-height: 100vh;
+}
+
+a {
+  color: var(--color-primary);
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: underline;
+  }
+}
+
+code,
+pre {
+  font-family: var(--font-mono);
+}

package/styles/docs/_content.scss

@@ -0,0 +1,122 @@
+// ============================================
+//   Content Styles
+// ============================================
+
+.content-header {
+  margin-bottom: var(--spacing-xl);
+
+  h1 {
+    font-size: 2.5rem;
+    font-weight: 700;
+    line-height: 1.2;
+    margin-bottom: var(--spacing-sm);
+  }
+
+  .lead {
+    font-size: 1.25rem;
+    color: var(--color-text-muted);
+  }
+}
+
+.content-body {
+  font-size: 1rem;
+  line-height: 1.75;
+
+  h2 {
+    font-size: 1.75rem;
+    font-weight: 600;
+    margin-top: var(--spacing-xl);
+    margin-bottom: var(--spacing-md);
+  }
+
+  h3 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-top: var(--spacing-lg);
+    margin-bottom: var(--spacing-sm);
+  }
+
+  p {
+    margin-bottom: var(--spacing-md);
+  }
+
+  ul,
+  ol {
+    margin-bottom: var(--spacing-md);
+    padding-left: var(--spacing-lg);
+  }
+
+  li {
+    margin-bottom: var(--spacing-xs);
+  }
+
+  // Code blocks
+  pre {
+    background: var(--color-bg-code);
+    color: #e2e8f0;
+    padding: var(--spacing-md);
+    border-radius: var(--radius-md);
+    overflow-x: auto;
+    margin-bottom: var(--spacing-md);
+  }
+
+  // Inline code
+  code {
+    background: var(--color-bg-alt);
+    padding: 0.2em 0.4em;
+    border-radius: var(--radius-sm);
+    font-size: 0.9em;
+  }
+
+  pre code {
+    background: none;
+    padding: 0;
+  }
+}
+
+// Code block with copy button (used with CodeBlock.ts component)
+.code-block {
+  position: relative;
+  margin-bottom: var(--spacing-md);
+
+  pre {
+    margin-bottom: 0;
+  }
+}
+
+.code-block-copy {
+  position: absolute;
+  top: var(--spacing-sm);
+  right: var(--spacing-sm);
+  padding: 6px 8px;
+  background: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  border-radius: var(--radius-sm);
+  color: #94a3b8;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s, background 0.2s, color 0.2s;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  svg {
+    width: 16px;
+    height: 16px;
+  }
+}
+
+.code-block:hover .code-block-copy {
+  opacity: 1;
+}
+
+.code-block-copy:hover {
+  background: rgba(255, 255, 255, 0.2);
+  color: #e2e8f0;
+}
+
+.code-block-copy.copied {
+  color: #4ade80;
+  background: rgba(74, 222, 128, 0.2);
+  border-color: rgba(74, 222, 128, 0.3);
+}

package/styles/docs/_footer.scss

@@ -0,0 +1,56 @@
+// ============================================
+//   Footer Styles
+// ============================================
+
+.site-footer {
+  background: var(--color-bg-alt);
+  border-top: 1px solid var(--color-border);
+  padding: var(--spacing-xl) 0;
+  margin-top: var(--spacing-xl);
+}
+
+.footer-container {
+  max-width: var(--page-max-width);
+  margin: 0 auto;
+  padding: 0 var(--spacing-lg);
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: var(--spacing-xl);
+}
+
+.footer-section {
+  h4 {
+    font-weight: 600;
+    margin-bottom: var(--spacing-md);
+  }
+
+  ul {
+    list-style: none;
+  }
+
+  li {
+    margin-bottom: var(--spacing-xs);
+  }
+
+  a {
+    color: var(--color-text-muted);
+
+    &:hover {
+      color: var(--color-primary);
+    }
+  }
+
+  .version {
+    color: var(--color-text-light);
+    font-size: 0.875rem;
+  }
+}
+
+.footer-bottom {
+  text-align: center;
+  padding-top: var(--spacing-lg);
+  margin-top: var(--spacing-lg);
+  border-top: 1px solid var(--color-border);
+  color: var(--color-text-light);
+  font-size: 0.875rem;
+}