@matdata/yasgui-utils 5.2.0 → 5.4.0

package/README.md

@@ -1,196 +1,180 @@
 # YASGUI
 
-YASGUI (Yet Another SPARQL GUI) is an advanced SPARQL client for querying and exploring RDF data. It provides a user-friendly interface for writing SPARQL queries, executing them against SPARQL endpoints, and visualizing the results in various formats.
-
-Go to https://yasgui.matdata.eu/ and use it freely in production. Or fork this repo and extend it yourself. Contributions are certainly welcome!
-
-## Table of Contents
-
-- [Useful Links](#useful-links)
-- [Features](#features)
-  - [Keyboard Shortcuts](#keyboard-shortcuts)
-    - [Query Editor (Yasqe)](#query-editor-yasqe)
-    - [Fullscreen Mode](#fullscreen-mode)
-    - [URI Explorer](#uri-explorer)
-  - [Prefix Management](#prefix-management)
-  - [Result Visualization Plugins (Yasr)](#result-visualization-plugins-yasr)
-- [Installation](#installation)
-  - [npm](#npm)
-  - [Yarn](#yarn)
-- [Local Development](#local-development)
-- [License](#license)
-
-## Useful Links
-
-- Production environment: https://yasgui.matdata.eu/
-- Dev environment: https://yasgui-dev.matdata.eu/ (GitHub Pages - automatically updated with every commit to main branch)
-- User documentation: https://docs.triply.cc/yasgui/
-- Developer documentation: https://docs.triply.cc/yasgui-api/
-- Docker Hub: https://hub.docker.com/r/mathiasvda/yasgui
+**Yet Another SPARQL GUI (YASGUI)** is a powerful, user-friendly web-based interface for querying and exploring RDF data using SPARQL. It combines a feature-rich query editor (YASQE) with a versatile results viewer (YASR) to provide a comprehensive SPARQL IDE.
 
-## Features
-
-### Themes
-
-Yasgui supports both **light** and **dark** themes with instant switching:
-
-- **Theme Toggle Button**: Quickly switch between light and dark modes using the button in the tab bar
-- **Persistent Preference**: Your theme choice is automatically saved
-- **System Detection**: Automatically matches your system's dark/light mode preference
-- **Full Coverage**: Consistent theming across all components (editor, results, modals)
-
-See the [Theme Guide](./docs/THEME_GUIDE.md) for detailed configuration options and usage examples.
-
-See the [Theme Implementation Guide](./docs/THEME_IMPLEMENTATION_GUIDE.md) for detailed instructions on how to implement theme support in your own Yasgui plugins.
-
-### Layout Orientation
-
-Yasgui supports two layout orientations to optimize screen space usage:
-
-- **Vertical Layout (Default)**: YASQE (query editor) positioned above YASR (results viewer)
-- **Horizontal Layout**: YASQE and YASR positioned side-by-side
-
-The horizontal layout is particularly useful for wide monitors, allowing you to dedicate the complete height to both the query editor and results viewer.
-
-#### Runtime Toggle
-
-Users can switch between vertical and horizontal layouts at any time using the **layout toggle button** in the control bar (next to the endpoint selector). This button shows:
-- **Side-by-side rectangles icon** when in vertical mode (click to switch to horizontal)
-- **Stacked rectangles icon** when in horizontal mode (click to switch to vertical)
-
-#### Initial Configuration
-
-You can also set the initial layout orientation when creating a Yasgui instance:
-
-```javascript
-new Yasgui(document.getElementById("yasgui"), {
-  orientation: "horizontal" // or "vertical" (default)
-});
-```
+🌐 **Try it now**: [https://yasgui.matdata.eu/](https://yasgui.matdata.eu/)
 
-#### CSS Customization
+[![npm version](https://img.shields.io/npm/v/@matdata/yasgui)](https://www.npmjs.com/package/@matdata/yasgui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Customize the header height used in the horizontal layout calculation by setting the CSS custom property:
+---
 
-```css
-.yasgui {
-  --yasgui-header-height: 120px; /* Adjust based on your header height */
-  --yasgui-min-height: 500px; /* Minimum height for horizontal layout panels */
-}
-```
-
-### Keyboard Shortcuts
-
-#### Query Editor (Yasqe)
-- **Ctrl+Enter** / **Cmd+Enter**: Execute the current query
-- **Ctrl+Space**: Trigger autocomplete
-- **Ctrl+S**: Save query to local storage
-- **Shift+Ctrl+F**: Auto-format the query
-- **Ctrl+/**: Comment/uncomment selected lines
-- **Shift+Ctrl+D**: Duplicate the current line
-- **Shift+Ctrl+K**: Delete the current line
-- **Esc**: Remove focus from the editor
-
-#### Fullscreen Mode
-- **F11**: Toggle fullscreen mode for the query editor (Yasqe)
-- **F10**: Toggle fullscreen mode for the results viewer (Yasr)
-- **Ctrl+Shift+F**: Switch between Yasqe and Yasr fullscreen modes
-
-#### URI Explorer
-- **Ctrl+Click** on any URI in the query editor: Automatically executes a CONSTRUCT query to explore the clicked URI's connections (incoming and outgoing triples). The query runs in the background without modifying your current query in the editor.
+## Quick Links
 
-### Prefix Management
-- **PREFIX Button**: Insert saved prefix declarations into your query (replaces existing PREFIX lines at the beginning)
-- **Settings Modal**: Access via the settings button (⚙) to manage:
-  - **Saved Prefixes**: Define reusable PREFIX declarations
-  - **Auto-capture**: Automatically captures new prefixes from your queries (enabled by default)
-  - **Request Configuration**: Configure HTTP request method, accept headers, arguments, headers, and named/default graphs
-- **Default Prefixes**: Automatically includes `rdf:` and `rdfs:` prefixes for new users
-- **Prefix Autocomplete**: When typing a prefix declaration (e.g., `PREFIX foaf:`), the editor automatically queries [prefix.cc](https://prefix.cc) to suggest and auto-complete the full URI commonly associated with that prefix. This helps you quickly add standard prefixes without needing to remember their full URIs.
+- 📖 **[User Guide](./docs/user-guide.md)** - Complete guide for end users
+- 🛠️ **[Developer Guide](./docs/developer-guide.md)** - API reference and integration guide
+- 🚀 **[Production Environment](https://yasgui.matdata.eu/)** - Live instance
+- 📦 **[npm Package](https://www.npmjs.com/package/@matdata/yasgui)**
+- 🐳 **[Docker Hub](https://hub.docker.com/r/mathiasvda/yasgui)**
+- 📝 **[Releases & Changelog](https://github.com/Matdata-eu/Yasgui/releases)**
+- 💻 **[GitHub Repository](https://github.com/Matdata-eu/Yasgui)**
 
-### Endpoint Quick Switch Buttons
+---
 
-Configure predefined SPARQL endpoint buttons for quick switching between different endpoints:
+## Documentation
 
-- **Predefined Buttons**: Configure a list of endpoint buttons during Yasgui initialization
-- **User-Defined Buttons**: Users can add their own custom endpoint buttons through the Settings modal
-- **One-Click Switching**: Instantly switch to a different SPARQL endpoint with a single button click
-- **Persistent Custom Buttons**: User-defined buttons are saved in local storage
-- **Fully Themed**: Buttons automatically adapt to light and dark themes
+The **documentation for YASGUI is hosted on GitHub Pages**:
 
-For detailed configuration options and examples, see the [Endpoint Buttons Guide](./docs/ENDPOINT_BUTTONS.md).
+- **📚 Documentation Website**: [https://yasgui-doc.matdata.eu/](https://matdata-eu.github.io/Yasgui/)
+  - User Guide, Developer Guide, API Reference
+  - Built with Docusaurus
+  - Version-tagged with the repository
 
-### Result Visualization Plugins (Yasr)
+- **🚀 Development Build**: [https://yasgui-doc.matdata.eu/dev/main/](https://matdata-eu.github.io/Yasgui/dev/main/)
+  - Live build from the main branch
+  - Updated automatically with every commit
+  - Test latest features before release
 
-Yasgui includes several built-in plugins to visualize SPARQL query results:
+The documentation is version-tagged with the repository, ensuring consistency between code and documentation across releases.
 
-- **Table**: Interactive table view with sorting, filtering, pagination, and column resizing. Ideal for SELECT query results.
-- **Boolean**: Displays boolean results (true/false) with visual indicators. Automatically used for ASK queries.
-- **Response**: Raw response viewer with syntax highlighting and code folding. Shows the original response from the endpoint in JSON, XML, Turtle, or other formats.
-- **Geo**: Geographic visualization plugin for displaying spatial data on interactive maps. Visualizes geospatial triples with coordinates. See [Yasgui Geo TG Plugin](https://github.com/Thib-G/yasgui-geo-tg) for more details.
-- **Graph**: Visual graph representation of RDF data using nodes and edges. Ideal for CONSTRUCT/DESCRIBE query results. See [Yasgui Graph Plugin](https://github.com/Matdata-eu/yasgui-graph-plugin) for more details.
-- **Error**: Displays error messages and diagnostics when queries fail, including CORS troubleshooting guidance.
+## Features
 
-Plugins are automatically selected based on the query type and response format. You can manually switch between available plugins using the view selector in the results pane.
+YASGUI provides a complete SPARQL development environment with powerful features:
+
+### ✏️ Advanced Query Editor
+- **[SPARQL Syntax Highlighting](./docs/user-guide.md#yasqe-query-editor)** - Color-coded SPARQL with error detection
+- **[Smart Autocomplete](./docs/user-guide.md#prefix-management)** - Context-aware suggestions for keywords, prefixes, and URIs
+- **[Query Formatting](./docs/user-guide.md#query-formatting)** - One-click query beautification with configurable formatters
+- **[Prefix Management](./docs/user-guide.md#prefix-management)** - Auto-capture and reuse PREFIX declarations
+- **[URI Explorer](./docs/user-guide.md#uri-explorer)** - Ctrl+Click URIs to explore connections
+- **[Keyboard Shortcuts](./docs/user-guide.md#keyboard-shortcuts)** - Efficient query development workflow
+
+### 📊 Powerful Visualizations
+- **[Table Plugin](./docs/user-guide.md#table-plugin)** - Sortable, filterable, paginated result tables
+- **[Graph Plugin](./docs/user-guide.md#graph-plugin)** - Interactive RDF graph visualization
+- **[Geo Plugin](./docs/user-guide.md#geo-plugin)** - Geographic data on interactive maps
+- **[Response Plugin](./docs/user-guide.md#response-plugin)** - Raw response viewer with syntax highlighting
+- **[Boolean Plugin](./docs/user-guide.md#boolean-plugin)** - Visual true/false indicators for ASK queries
+- **[Error Plugin](./docs/user-guide.md#error-plugin)** - Detailed error diagnostics
+
+### 🎨 Themes & Layouts
+- **[Light & Dark Themes](./docs/user-guide.md#themes)** - Seamless theme switching with persistent preferences
+- **[Flexible Layouts](./docs/user-guide.md#layout-orientation)** - Vertical or horizontal editor/results arrangement
+
+### 🔧 Expert Features
+- **[Multiple Tabs](./docs/user-guide.md#query-tabs)** - Work on multiple queries simultaneously
+- **[Endpoint Management](./docs/user-guide.md#endpoint-quick-switch)** - Quick-switch between SPARQL endpoints
+- **[Persistent Storage](./docs/user-guide.md#query-history-and-persistence)** - Auto-save queries and preferences
+- **[URL Sharing](./docs/user-guide.md#share-queries)** - Share queries via URL parameters
+- **[Fullscreen Mode](./docs/user-guide.md#fullscreen-mode)** - Maximize editor or results viewer
+- **[Export Results](./docs/developer-guide.md#yasr-class)** - Download results in various formats
+
+For detailed feature documentation, see the **[User Guide](./docs/user-guide.md)**.
 
 ## Installation
 
-Below are instructions on how to include Yasgui in your project.
-If you only want to install Yasr or Yasqe, replace yasgui in the commands below.
-
 ### npm
 
-```sh
-npm i @matdata/yasgui
+```bash
+npm install @matdata/yasgui
 ```
 
 ### Yarn
 
-```sh
+```bash
 yarn add @matdata/yasgui
 ```
 
-### Docker
+### CDN
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@matdata/yasgui/build/yasgui.min.css" />
+<script src="https://unpkg.com/@matdata/yasgui/build/yasgui.min.js"></script>
+```
 
-Yasgui is also available as a Docker image on Docker Hub. Images are built and published automatically when a new release is created.
+### Docker
 
-```sh
+```bash
 docker pull mathiasvda/yasgui:latest
 docker run -p 8080:8080 mathiasvda/yasgui:latest
 ```
 
-You can customize the default SPARQL endpoint by setting the `YASGUI_DEFAULT_ENDPOINT` environment variable:
-
-```sh
+**Custom endpoint:**
+```bash
 docker run -p 8080:8080 -e YASGUI_DEFAULT_ENDPOINT=https://your-endpoint.com/sparql mathiasvda/yasgui:latest
 ```
 
-The application will be available at `http://localhost:8080`.
+For detailed installation instructions and usage examples, see the **[Developer Guide](./docs/developer-guide.md#installation)**.
+
+## Quick Start
+
+### Basic HTML Usage
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://unpkg.com/@matdata/yasgui/build/yasgui.min.css" />
+</head>
+<body>
+  <div id="yasgui"></div>
+  
+  <script src="https://unpkg.com/@matdata/yasgui/build/yasgui.min.js"></script>
+  <script>
+    const yasgui = new Yasgui(document.getElementById("yasgui"), {
+      requestConfig: {
+        endpoint: "https://dbpedia.org/sparql"
+      }
+    });
+  </script>
+</body>
+</html>
+```
 
-## Local Development
+### ES Modules / React / Vue / Angular
 
-#### Installing dependencies
+```javascript
+import Yasgui from '@matdata/yasgui';
+import '@matdata/yasgui/build/yasgui.min.css';
+
+const yasgui = new Yasgui(document.getElementById('yasgui'), {
+  requestConfig: {
+    endpoint: 'https://query.wikidata.org/sparql'
+  },
+  theme: 'dark',
+  orientation: 'horizontal'
+});
+```
 
-Run `npm install`.
+For framework-specific examples and advanced usage, see the **[Developer Guide](./docs/developer-guide.md#usage-examples)**.
 
-#### Running Yasgui locally
+---
 
-To develop locally, run `npm run dev`
+## Contributing
 
-Go to `http://localhost:5173/demo` in your browser to see Yasgui in action.
+We welcome contributions! To get started:
 
-#### Compiling Yasgui
+1. Fork the repository
+2. Clone and install: `npm install`
+3. Run dev server: `npm run dev`
+4. Make your changes
+5. Run tests: `npm test`
+6. Submit a pull request
 
-Run `npm run build`. It'll store the transpiled js/css files in the `build` directory.
+For detailed contribution guidelines, see the **[Developer Guide](./docs/developer-guide.md#contributing)**.
+
+---
 
 ## License
 
+MIT License - see [LICENSE](./LICENSE) file for details.
+
 This is a fork from [Zazuko](https://github.com/zazuko/Yasgui) who forked it from [Triply](https://github.com/TriplyDB/Yasgui).
 
-This code is released under the MIT license.
+---
 
-## Release notes
+## Release Notes & Changelog
 
-Release notes can be found in the release section of the GitHub repository: [Yasgui Releases](https://github.com/Matdata-eu/yasgui/releases)
+Release notes and changelog are available in the [Releases](https://github.com/Matdata-eu/Yasgui/releases) section.
 
-Instructions on how to write release notes are found in 
+For instructions on writing release notes, see [release_notes_instructions.md](./docs/release_notes_instructions.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matdata/yasgui-utils",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Utils for YASGUI libs",
   "main": "build/utils.min.js",
   "types": "build/ts/src/index.d.ts",

package/src/store.d.ts

@@ -0,0 +1,13 @@
+declare module "store" {
+  interface StoreAPI {
+    enabled: boolean;
+    get(key: string): any;
+    set(key: string, value: any): void;
+    remove(key: string): void;
+    clearAll(): void;
+    each(callback: (value: any, key: string) => void): void;
+  }
+
+  const store: StoreAPI;
+  export default store;
+}