docs: rework specs to comply with recent changes

Author: MathiasVDA

README.md

@@ -7,11 +7,14 @@ High-performance YASGUI plugin for rendering SPARQL SELECT results in an interac
 - 🚀 **Virtual Scrolling** - Efficiently handles 10,000+ rows
 - 🔍 **Search & Filter** - Real-time search with highlighting
 - 📊 **Interactive Columns** - Sort and resize columns
-- 🎨 **Theme Support** - Integrates with YASGUI themes
+- 🎨 **Dynamic Theme Support** - Automatically adapts to YASGUI light/dark theme changes
 - 📋 **Selection & Copy** - Select cells/rows and copy to clipboard
-- 💾 **Export** - Export to Markdown, CSV, or TSV formats
+- 💾 **Copy** - Copy to clipboard as Markdown, CSV, or TSV (tab-delimited) formats
+- 📥 **YASR Integration** - Integrated with YASR's download interface for CSV export
+- 💬 **Tooltips** - Hover over any cell to view full content
+- 🔔 **Notifications** - Visual feedback for copy operations
 - ♿ **Accessible** - WCAG AA compliant with keyboard navigation
-- 🎯 **SPARQL-Aware** - Proper rendering of URIs, literals, datatypes, and blank nodes
+- 🎯 **SPARQL-Aware** - Proper rendering of URIs, literals, datatypes, and blank nodes with prefix support from YASR
 
 ## Installation
 
@@ -87,15 +90,15 @@ tablePlugin.on('selectionChange', (data) => {
   console.log('Selection:', data.range);
 });
 
-// Listen for export events
-tablePlugin.on('export', (data) => {
-  console.log(`Exported as ${data.format}`);
+// Listen for copy events
+tablePlugin.on('copy', (data) => {
+  console.log(`Copied as ${data.format}`);
 });
 
 // Available events:
 // - ready, search, columnSort, columnResize, cellDoubleClick
 // - selectionChange, selectionCleared, clipboardCopy
-// - export, layoutChange, error, destroy
+// - copy, layoutChange, error, destroy
 ```
 
 ## Public Methods
@@ -139,7 +142,7 @@ npm install
 # Start development server with Vite (http://localhost:3000)
 npm run dev
 
-# Build for production
+# Build for production with esbuild
 npm run build
 
 # Run tests
@@ -162,6 +165,16 @@ The `npm run dev` command starts a Vite development server at `http://localhost:
 
 The demo automatically loads the plugin from source during development for live reload.
 
+### Build System
+
+The project uses **esbuild** for production builds with:
+- UMD and ESM module formats
+- PostCSS for CSS processing
+- TypeScript type declarations
+- Watch mode for development (`npm run dev:build`)
+
+Build outputs are generated in `dist/` with both `.umd.js` and `.esm.js` formats.
+
 ## License
 
 MIT

specs/001-advanced-table/contracts/config-schema.md

@@ -28,14 +28,16 @@ interface TabulatorPluginConfig {
   persistenceKey?: string;
   persistenceEnabled?: boolean;
 
-  // Export Configuration (FR-031, FR-032, FR-033)
+  // Export Configuration (FR-029, FR-030, FR-030a)
+  // Note: CSV download integrated with YASR's download interface (FR-031)
   exportFormat?: 'tsv' | 'csv' | 'markdown';
 
   // Theme Configuration
   themeIntegration?: boolean;
   customTheme?: string;
 
   // Prefix Configuration (for URI abbreviation)
+  // Fetched from YASR's getPrefixes() method and merged with common prefixes
   prefixMap?: PrefixMap;
 }
 ```
@@ -50,7 +52,7 @@ interface TabulatorPluginConfig {
   exportFormat: 'tsv',
   themeIntegration: true,
   customTheme: undefined,
-  prefixMap: {} // Populated from YASQE if available
+  prefixMap: {} // Populated from YASR's getPrefixes() merged with COMMON_PREFIXES
 }
 ```
 
@@ -318,14 +320,16 @@ if (sortState.direction && !['asc', 'desc'].includes(sortState.direction)) {
 ```javascript
 {
   layout: 'fitData',
-  height: '100%',
+  height: '100%',  // Not maxHeight to avoid resize loops
   renderVertical: 'virtual',
   virtualDomBuffer: 300,
   headerSort: true,
   pagination: false
 }
 ```
 
+**Note**: Using `maxHeight: '100%'` with virtual scrolling causes infinite resize loops. Always use `height: '100%'` instead.
+
 **Validation**: Delegated to Tabulator library (will throw if invalid)
 
 **Override Warning**: Setting `pagination: true` will disable virtual scrolling and may violate performance requirements (FR-004, FR-006).

specs/001-advanced-table/contracts/events.md

@@ -369,31 +369,36 @@ plugin.on('configChange', (e) => {
 
 ---
 
-## Export Events
+## Copy Events
 
-### `export`
+### `copy`
 
-**Fired**: When user exports table data (FR-031, FR-032, FR-033).
+**Fired**: When user copies table data to clipboard (FR-029, FR-030, FR-030a).
 
 **Event Object**:
 ```typescript
-interface ExportEvent extends BaseEvent {
-  type: 'export';
+interface CopyEvent extends BaseEvent {
+  type: 'copy';
   format: 'tsv' | 'csv' | 'markdown';
-  rowCount: number;       // Number of exported rows
-  columnCount: number;    // Number of exported columns
-  dataSize: number;       // Size of exported data (bytes)
+  rowCount: number;       // Number of copied rows
+  columnCount: number;    // Number of copied columns
+  dataSize: number;       // Size of copied data (bytes)
+  success: boolean;       // Whether copy succeeded
 }
 ```
 
 **Example**:
 ```javascript
-plugin.on('export', (e) => {
-  console.log(`Exported ${e.rowCount} rows as ${e.format} (${e.dataSize} bytes)`);
+plugin.on('copy', (e) => {
+  if (e.success) {
+    console.log(`Copied ${e.rowCount} rows as ${e.format} (${e.dataSize} bytes)`);
+  }
 });
 ```
 
-**Timing**: Fired after export data generated, before download initiated
+**Timing**: Fired after copy operation completes
+
+**Notifications**: Visual notification shown to user on success/failure
 
 ---
 
@@ -427,7 +432,9 @@ plugin.on('clipboard', (e) => {
 - Ctrl+C / Cmd+C with selection (FR-027)
 - Click "Copy" button (if implemented)
 
-**Browser Compatibility**: May fail in insecure contexts (non-HTTPS)
+**Browser Compatibility**: May fail in insecure contexts (non-HTTPS). Fallback to execCommand provided.
+
+**Notifications**: Visual notification shown to user on success/failure
 
 ---
 
@@ -549,10 +556,11 @@ plugin.on('search', (e) => {
   });
 });
 
-plugin.on('export', (e) => {
-  analytics.track('Table Export', {
+plugin.on('copy', (e) => {
+  analytics.track('Table Copy', {
     format: e.format,
-    rows: e.rowCount
+    rows: e.rowCount,
+    success: e.success
   });
 });
 ```
@@ -648,8 +656,8 @@ interface SearchHighlightEvent extends BaseEvent { searchTerm, highlightedCells
 // Configuration events
 interface ConfigChangeEvent extends BaseEvent { changes, config, previousConfig }
 
-// Export events
-interface ExportEvent extends BaseEvent { format, rowCount, columnCount, dataSize }
+// Copy/Export events
+interface CopyEvent extends BaseEvent { format, rowCount, columnCount, dataSize, success }
 interface ClipboardEvent extends BaseEvent { selection, format, dataSize, success }
 
 // Lifecycle events

specs/001-advanced-table/quickstart.md

@@ -14,7 +14,7 @@ This guide demonstrates how to integrate the advanced table plugin with YASGUI t
 
 - **YASGUI**: Version 4.x or higher
 - **Browser**: Chrome, Firefox, Safari, or Edge (latest 2 versions)
-- **Build Tool**: Webpack, Rollup, or module bundler with ES6 support
+- **Build Tool**: esbuild (used internally), or any module bundler with ES6 support
 - **Node.js**: 16+ (for development)
 
 ---
@@ -269,9 +269,11 @@ yasr.on('drawn', () => {
     console.log('Clicked:', e.value);
   });
 
-  // Monitor exports
-  tablePlugin.on('export', (e) => {
-    console.log(`Exported ${e.rowCount} rows as ${e.format}`);
+  // Monitor copy operations
+  tablePlugin.on('copy', (e) => {
+    if (e.success) {
+      console.log(`Copied ${e.rowCount} rows as ${e.format}`);
+    }
   });
 });
 ```
@@ -324,7 +326,9 @@ LIMIT 100`
 - Abbreviated URIs (dbr:London instead of http://dbpedia.org/resource/London)
 - Sortable columns (click "population" to sort)
 - Searchable (search for "London")
-- Exportable (download as CSV/TSV)
+- Copy to clipboard as Markdown, CSV, or TSV (tab-delimited)
+- Tooltips showing full cell content on hover
+- CSV download via YASR's download interface
 
 ---
 
@@ -405,8 +409,9 @@ const yasgui = new Yasgui(document.getElementById('yasgui'), {
 **Features**:
 - Custom authentication headers
 - Isolated localStorage (won't conflict with other instances)
-- Markdown export format
+- Markdown export format (also supports CSV and TSV)
 - Full URI display
+- Visual notifications for copy operations
 
 ---
 
@@ -487,11 +492,12 @@ yasr.on('drawn', () => {
     });
   });
 
-  // Track exports
-  tablePlugin.on('export', (e) => {
-    analytics.track('Table Export', {
+  // Track copy operations
+  tablePlugin.on('copy', (e) => {
+    analytics.track('Table Copy', {
       format: e.format,
-      rows: e.rowCount
+      rows: e.rowCount,
+      success: e.success
     });
   });
 });
@@ -595,11 +601,14 @@ console.log('Persistence enabled:', config.persistenceEnabled);
 // Check HTTPS context (Clipboard API requires secure context)
 console.log('Secure context:', window.isSecureContext);
 
-// Fallback to execCommand on HTTP
+// Automatic fallback to execCommand on HTTP or when Clipboard API fails
 if (!window.isSecureContext) {
-  console.warn('Clipboard API unavailable. Using legacy execCommand.');
+  console.warn('Clipboard API unavailable. Using legacy execCommand fallback.');
 }
 
+// Plugin automatically handles focus issues and fallbacks
+// Visual notifications will indicate success or failure
+
 // Check browser permissions
 navigator.permissions.query({ name: 'clipboard-write' })
   .then(result => {
@@ -631,9 +640,10 @@ navigator.permissions.query({ name: 'clipboard-write' })
 
 1. **Clone repository**: `git clone https://github.com/yasgui/table-plugin.git`
 2. **Install dependencies**: `npm install`
-3. **Run dev server**: `npm run dev` (opens demo at http://localhost:3000)
+3. **Run dev server**: `npm run dev` (opens demo at http://localhost:3000 with Vite)
 4. **Run tests**: `npm test`
-5. **Build**: `npm run build` (outputs to `dist/`)
+5. **Build**: `npm run build` (uses esbuild, outputs UMD and ESM to `dist/`)
+6. **Watch mode**: `npm run dev:build` (esbuild watch mode for incremental builds)
 
 ### Further Reading
 

specs/001-advanced-table/spec.md

@@ -11,6 +11,7 @@
 
 - Q: Search Highlight Color - Should search term highlighting use a hardcoded yellow color or adapt to themes? → A: Use theme-responsive highlight color (via CSS variable) that adapts to light/dark mode
 - Q: Ellipsized Cell Expansion Behavior - Should full content appear in overlay, inline expansion, or side panel? → A: Modal/tooltip overlay that appears above the table (preserves table layout)
+- Q: Theme Change Detection - How should plugin respond to YASGUI theme changes? → A: Use MutationObserver to watch data-theme attribute changes with 500ms polling fallback for dynamic theme adaptation
 - Q: Visual Guides During Column Resize - What type of visual guides should appear (column highlight, vertical line, measurements)? → A: Standard behavior of the library that we are going to use to implement the table
 - Q: Infinite Scroll Implementation Strategy - Should infinite scroll load all rows, use virtual scrolling, or batch loading? → A: Virtual scrolling (windowing) - render only visible rows plus buffer
 - Q: Row Number Column Behavior During Horizontal Scroll - Should row numbers be fixed/sticky, scroll with content, or use floating overlay? → A: Whatever is used by the library that we are going to implement
@@ -121,18 +122,19 @@ Users can select individual cells, ranges of cells, or entire rows, and copy sel
 
 ### User Story 7 - Export Functionality (Priority: P3)
 
-Users can export the complete table (or filtered results) to clipboard as Markdown or CSV, and download results as CSV file.
+Users can export the complete table (or filtered results) to clipboard as Markdown, CSV, or TSV (tab-delimited) formats, and download results as CSV file through YASR's download interface.
 
-**Why this priority**: While cell selection handles small data extraction, full table export is valuable for documentation (Markdown) and data analysis in external tools (CSV). Lower priority than core viewing and interaction features.
+**Why this priority**: While cell selection handles small data extraction, full table export is valuable for documentation (Markdown) and data analysis in external tools (CSV/TSV). Lower priority than core viewing and interaction features.
 
-**Independent Test**: Can be fully tested by clicking export controls and verifying that clipboard receives properly formatted Markdown or CSV, and that CSV download produces a valid file.
+**Independent Test**: Can be fully tested by clicking export controls and verifying that clipboard receives properly formatted Markdown, CSV, or TSV, and that CSV download through YASR produces a valid file.
 
 **Acceptance Scenarios**:
 
-1. **Given** a table with data is displayed, **When** user clicks "Copy as Markdown", **Then** clipboard contains properly formatted Markdown table with headers and alignment
-2. **Given** a table with data is displayed, **When** user clicks "Copy as CSV", **Then** clipboard contains CSV format with headers and quoted fields where necessary
-3. **Given** a table is displayed, **When** user clicks "Download CSV", **Then** browser downloads a `.csv` file with all visible data (respecting active filters)
-4. **Given** a search filter is active showing 50 of 500 rows, **When** user exports or downloads, **Then** only the 50 filtered rows are included
+1. **Given** a table with data is displayed, **When** user clicks "Copy as Markdown", **Then** clipboard contains properly formatted Markdown table with headers and alignment, and visual notification confirms success
+2. **Given** a table with data is displayed, **When** user clicks "Copy as CSV", **Then** clipboard contains CSV format with headers and quoted fields where necessary, and visual notification confirms success
+3. **Given** a table with data is displayed, **When** user clicks "Copy as TSV", **Then** clipboard contains tab-delimited format with headers, and visual notification confirms success
+4. **Given** a table is displayed, **When** user uses YASR's download interface, **Then** browser downloads a `.csv` file with all visible data (respecting active filters)
+5. **Given** a search filter is active showing 50 of 500 rows, **When** user exports or downloads, **Then** only the 50 filtered rows are included
 
 ---
 
@@ -168,6 +170,7 @@ Users can export the complete table (or filtered results) to clipboard as Markdo
 - **FR-010**: Plugin MUST provide a toggle control to show or hide datatype annotations on literals
 - **FR-011**: Plugin MUST provide an ellipsis mode control that truncates cell content with "..." when enabled
 - **FR-012**: Plugin MUST display full cell content in a modal or tooltip overlay when user clicks on an ellipsized cell, preserving table layout
+- **FR-012a**: Plugin MUST display full cell content as tooltip when user hovers over any cell
 
 #### Sorting
 - **FR-013**: Plugin MUST allow users to sort rows by clicking on column headers
@@ -194,13 +197,14 @@ Users can export the complete table (or filtered results) to clipboard as Markdo
 - **FR-028**: Plugin MUST format copied data as tab-separated values (rows separated by newlines)
 
 #### Export and Download
-- **FR-029**: Plugin MUST provide a control to copy entire table to clipboard as Markdown format
-- **FR-030**: Plugin MUST provide a control to copy entire table to clipboard as CSV format
-- **FR-031**: Plugin MUST provide a control to download table as CSV file
+- **FR-029**: Plugin MUST provide a control to copy entire table to clipboard as Markdown format with visual notification
+- **FR-030**: Plugin MUST provide a control to copy entire table to clipboard as CSV format with visual notification
+- **FR-030a**: Plugin MUST provide a control to copy entire table to clipboard as TSV (tab-delimited) format with visual notification
+- **FR-031**: Plugin MUST integrate with YASR's download interface to provide CSV download capability
 - **FR-032**: Plugin MUST respect active search filters when exporting or downloading
 
 #### Theming
-- **FR-033**: Plugin MUST respond to YASGUI theme changes (light/dark mode)
+- **FR-033**: Plugin MUST respond to YASGUI theme changes (light/dark mode) dynamically using MutationObserver with polling fallback
 - **FR-034**: Plugin MUST use YASGUI CSS variables for colors, borders, and backgrounds
 - **FR-035**: Plugin MUST ensure text contrast meets WCAG AA standards in both themes
 
@@ -238,8 +242,9 @@ Users can export the complete table (or filtered results) to clipboard as Markdo
 1. SPARQL results are provided in standard YASGUI result format (JSON bindings)
 2. Browser supports modern JavaScript features (ES2018) and CSS features required by YASGUI
 3. Users have basic familiarity with SPARQL query results and table interfaces
-4. Prefix definitions are available from YASQE or query context for URI abbreviation
+4. Prefix definitions are fetched from YASR's getPrefixes() method and merged with common prefixes for URI abbreviation
 5. LocalStorage is available for persisting user preferences
-6. Clipboard API is available for copy operations (with appropriate fallbacks)
+6. Clipboard API is available for copy operations (with execCommand fallback for older browsers)
 7. Result sets are finite (not streaming) and fit in browser memory
 8. The plugin is used within YASGUI/YASR environment with standard plugin lifecycle
+9. Build system uses esbuild for UMD and ESM module generation