diff --git a/README.md b/README.md index 7e92331..7466eb4 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,16 @@ All DOM classes support: - **Data Persistence**: Multiple storage backends (in-memory, JSON file-based) - **System Integration**: Logging, file operations, and privilege elevation +### Injected Libraries + +The FDO application automatically injects several popular libraries and helper functions into your plugin environment: + +- **CSS Frameworks**: Pure CSS, Notyf notifications, Highlight.js themes +- **JavaScript Libraries**: FontAwesome icons, Split Grid, Highlight.js, Notyf, ACE Editor, Goober (CSS-in-JS) +- **Helper Functions**: Backend communication, DOM utilities, event management + +For complete documentation on available libraries and usage examples, see [Injected Libraries Documentation](./docs/INJECTED_LIBRARIES.md). + ## Getting Started ### Installation diff --git a/docs/INJECTED_LIBRARIES.md b/docs/INJECTED_LIBRARIES.md new file mode 100644 index 0000000..8613bb1 --- /dev/null +++ b/docs/INJECTED_LIBRARIES.md @@ -0,0 +1,386 @@ +# Injected Libraries and Helpers + +This document describes all the libraries, CSS frameworks, and helper functions that are automatically available in your FDO plugins. These are injected by the FDO application host and can be used without any additional imports. + +## Table of Contents + +- [CSS Libraries](#css-libraries) +- [JavaScript Libraries](#javascript-libraries) +- [Window Helper Functions](#window-helper-functions) +- [Usage Examples](#usage-examples) + +## CSS Libraries + +The following CSS libraries are automatically loaded in your plugin environment: + +### Pure CSS (purecss.io) + +A set of small, responsive CSS modules that you can use in every web project. + +**Available Classes:** +- `.pure-g` - Grid container +- `.pure-u-*` - Grid units (e.g., `.pure-u-1-2` for 50% width) +- `.pure-button` - Button styles +- `.pure-form` - Form layouts +- `.pure-table` - Table styles +- `.pure-menu` - Menu/navigation styles + +**Example:** +```html +
+
Half width column
+
Half width column
+
+``` + +### Highlight.js + +Syntax highlighting for code blocks with the "VS" theme. + +**Usage:** +```html +

+const hello = "world";
+
+ +``` + +**Available via:** +- CSS: Pre-loaded VS theme +- JS: `window.hljs` object + +### Notyf + +Modern notification library for displaying toast messages. + +**Available via:** +- CSS: Pre-loaded styles +- JS: `window.Notyf` class + +**Example:** +```javascript +const notyf = new Notyf({ + duration: 3000, + position: { x: 'right', y: 'top' } +}); +notyf.success('Operation successful!'); +notyf.error('Something went wrong!'); +``` + +## JavaScript Libraries + +### FontAwesome + +Complete icon library with all icon sets (solid, regular, brands). + +**Available Sets:** +- FontAwesome Solid +- FontAwesome Regular +- FontAwesome Brands + +**Usage:** +```html + + + +``` + +### Split Grid + +Advanced grid splitter for creating resizable layouts. + +**Available via:** `window.Split` function + +**Example:** +```javascript +Split({ + columnGutters: [{ + track: 1, + element: document.querySelector('.gutter-col-1'), + }], + rowGutters: [{ + track: 1, + element: document.querySelector('.gutter-row-1'), + }] +}); +``` + +### Goober + +Lightweight CSS-in-JS library (already exposed via SDK's DOM classes). + +**Available via:** `window.goober` + +**Note:** While goober is loaded, the SDK's DOM classes provide a more convenient interface for styling. Refer to the SDK documentation for usage. + +### ACE Editor + +Powerful code editor component. + +**Available via:** `window.ace` + +**Example:** +```javascript +const editor = ace.edit("editor"); +editor.setTheme("ace/theme/monokai"); +editor.session.setMode("ace/mode/javascript"); +``` + +## Window Helper Functions + +These helper functions are automatically injected into the `window` object and are available for use in your plugins. + +### `createBackendReq(type, data)` + +Creates a request to your plugin's backend handler. + +**Parameters:** +- `type` (string): The function name to call on the backend +- `data` (any, optional): The data to send to the backend + +**Returns:** `Promise` - The response from the backend + +**Example:** +```javascript +const result = await window.createBackendReq('getUserData', { userId: 123 }); +console.log(result); +``` + +### `waitForElement(selector, callback, timeout)` + +Waits for an element to appear in the DOM. + +**Parameters:** +- `selector` (string): CSS selector for the element +- `callback` (function): Callback function called when element is found +- `timeout` (number, optional): Timeout in milliseconds (default: 5000) + +**Example:** +```javascript +window.waitForElement('#my-dynamic-element', (element) => { + console.log('Element found:', element); + element.style.color = 'red'; +}, 10000); +``` + +### `executeInjectedScript(scriptContent)` + +Executes a script in the plugin context. + +**Parameters:** +- `scriptContent` (string): The JavaScript code to execute + +**Example:** +```javascript +window.executeInjectedScript(` + console.log('This code runs in the plugin context'); + // Your dynamic script here +`); +``` + +### `addGlobalEventListener(eventType, callback)` + +Adds a global event listener to the window. + +**Parameters:** +- `eventType` (string): The event type (e.g., 'click', 'keydown') +- `callback` (function): The event handler function + +**Example:** +```javascript +window.addGlobalEventListener('resize', (event) => { + console.log('Window resized:', window.innerWidth, window.innerHeight); +}); +``` + +### `removeGlobalEventListener(eventType, callback)` + +Removes a global event listener from the window. + +**Parameters:** +- `eventType` (string): The event type +- `callback` (function): The event handler function to remove + +**Example:** +```javascript +const handleResize = (event) => { + console.log('Resize event'); +}; + +window.addGlobalEventListener('resize', handleResize); +// Later... +window.removeGlobalEventListener('resize', handleResize); +``` + +### `applyClassToSelector(className, selector)` + +Applies a CSS class to an element matching the selector. + +**Parameters:** +- `className` (string): The CSS class name to add +- `selector` (string): CSS selector for the target element + +**Example:** +```javascript +window.applyClassToSelector('highlight', '#my-element'); +``` + +## Usage Examples + +### Example 1: Creating a Notification System + +```javascript +export default class NotificationPlugin extends FDO_SDK { + render() { + return ` +
+ + +
+ + `; + } +} +``` + +### Example 2: Code Editor with Syntax Highlighting + +```javascript +export default class CodeEditorPlugin extends FDO_SDK { + render() { + return ` +
+ + `; + } +} +``` + +### Example 3: Responsive Grid Layout + +```javascript +export default class GridLayoutPlugin extends FDO_SDK { + render() { + return ` +
+
+
Column 1
+
+
+
Column 2
+
+
+
Column 3
+
+
+ `; + } +} +``` + +### Example 4: Backend Communication + +```javascript +export default class DataPlugin extends FDO_SDK { + async fetchData() { + const data = await window.createBackendReq('getData', { + filter: 'active' + }); + return data; + } + + render() { + return ` +
Loading...
+ + `; + } +} +``` + +### Example 5: Split Panel Layout + +```javascript +export default class SplitPanelPlugin extends FDO_SDK { + render() { + return ` + +
+
Left Panel
+
+
Right Panel
+
+ + `; + } +} +``` + +## Best Practices + +1. **Use TypeScript types:** The SDK provides TypeScript definitions for all window helper functions +2. **Error handling:** Always wrap backend requests in try-catch blocks +3. **Element waiting:** Use `waitForElement` instead of `setTimeout` for DOM-dependent code +4. **Cleanup:** Remove event listeners when they're no longer needed +5. **CSP Compliance:** Be aware of Content Security Policy restrictions in the plugin environment + +## Additional Resources + +- [Pure CSS Documentation](https://purecss.io/) +- [Highlight.js Documentation](https://highlightjs.org/) +- [Notyf Documentation](https://github.com/caroso1222/notyf) +- [FontAwesome Icons](https://fontawesome.com/icons) +- [Split Grid Documentation](https://github.com/nathancahill/split/tree/master/packages/splitjs) +- [ACE Editor Documentation](https://ace.c9.io/) diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md new file mode 100644 index 0000000..d1286c5 --- /dev/null +++ b/docs/QUICK_REFERENCE.md @@ -0,0 +1,73 @@ +# Quick Reference: Injected Libraries + +This is a quick reference for developers who want to quickly look up available libraries and their basic usage. + +## Window Helpers (Always Available) + +```typescript +// Backend Communication +const response = await window.createBackendReq('methodName', { data }); + +// DOM Utilities +window.waitForElement('#my-element', (el) => { /* ... */ }); +window.applyClassToSelector('my-class', '#target'); +window.executeInjectedScript('console.log("hello")'); + +// Event Management +window.addGlobalEventListener('click', handler); +window.removeGlobalEventListener('click', handler); +``` + +## CSS Libraries (Already Loaded) + +### Pure CSS +```html +
+
Column 1
+
Column 2
+
+ +``` + +## JavaScript Libraries + +### Notyf (Notifications) +```javascript +const notyf = new Notyf(); +notyf.success('Success!'); +notyf.error('Error!'); +``` + +### Highlight.js (Syntax Highlighting) +```html +

+const code = "example";
+
+ +``` + +### FontAwesome (Icons) +```html + + + +``` + +### ACE Editor (Code Editor) +```javascript +const editor = ace.edit("editor"); +editor.setTheme("ace/theme/monokai"); +editor.session.setMode("ace/mode/javascript"); +editor.setValue("const x = 1;"); +``` + +### Split Grid (Resizable Panels) +```javascript +Split({ + columnGutters: [{ track: 1, element: document.querySelector('.gutter') }] +}); +``` + +## Full Documentation + +For complete documentation with examples, see [INJECTED_LIBRARIES.md](./INJECTED_LIBRARIES.md) diff --git a/examples/07-injected-libraries-demo.ts b/examples/07-injected-libraries-demo.ts new file mode 100644 index 0000000..cbe0d9c --- /dev/null +++ b/examples/07-injected-libraries-demo.ts @@ -0,0 +1,372 @@ +/** + * Example plugin demonstrating the use of injected libraries and helper functions + * + * This example shows how to use: + * - Pure CSS for responsive layouts + * - Notyf for notifications + * - Highlight.js for code syntax highlighting + * - FontAwesome icons + * - ACE Editor for code editing + * - Split Grid for resizable panels + * - Window helper functions (createBackendReq, waitForElement, etc.) + */ + +import { FDO_SDK, FDOInterface, PluginMetadata } from "../src"; + +export default class InjectedLibrariesDemoPlugin extends FDO_SDK implements FDOInterface { + private readonly _metadata: PluginMetadata = { + name: "Injected Libraries Demo", + version: "1.0.0", + author: "FDO SDK", + description: "Demonstrates the use of automatically injected libraries and helper functions", + icon: "💡" + }; + + get metadata(): PluginMetadata { + return this._metadata; + } + + init(): void { + this.log("InjectedLibrariesDemoPlugin initialized!"); + } + + render(): string { + return ` + + +
+

Injected Libraries Demo

+ + +
+

1. Pure CSS Responsive Grid

+
+
+
+ Column 1
+ Full width on mobile, half on tablet, third on desktop +
+
+
+
+ Column 2
+ Responsive grid using Pure CSS +
+
+
+
+ Column 3
+ No extra CSS needed! +
+
+
+
+ + +
+

2. Notyf Notifications

+ + + +
+ + +
+

3. FontAwesome Icons

+
+ + + + + + + + +
+
+ + +
+

4. Syntax Highlighting with Highlight.js

+ 
// JavaScript code with syntax highlighting
+const message = "Hello, World!";
+
+function greet(name) {
+    return \`Hello, \${name}!\`;
+}
+
+class Plugin extends FDO_SDK {
+    init() {
+        this.log("Plugin initialized");
+    }
+}
+
+
+ + +
+

5. ACE Code Editor

+
+ +
+ + +
+

6. Resizable Panels with Split Grid

+
+
+

Left Panel

+

Drag the center gutter to resize panels.

+
    +
  • Draggable divider
    • +
  • Customizable min/max sizes
    • +
  • Snap to grid support
    • +
+
+
+
+

Right Panel

+

Perfect for creating split-view layouts!

+ 
Split({
+    columnGutters: [{
+        track: 1,
+        element: document.querySelector('.gutter-col-1')
+    }]
+});
+
+
+
+ + +
+

7. Window Helper Functions

+ + + +
+ Output will appear here... +
+
+
+ + + `; + } +} diff --git a/examples/README.md b/examples/README.md index b5b3fbc..bf058b4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -15,6 +15,24 @@ The examples are numbered to indicate learning progression: 3. **03-persistence-plugin.ts** - Data persistence with storage backends 4. **04-ui-extensions-plugin.ts** - Quick actions and side panel integration 5. **05-advanced-dom-plugin.ts** - Advanced DOM generation with styling +6. **06-error-handling-plugin.ts** - Error handling and debugging techniques +7. **07-injected-libraries-demo.ts** - Demonstrates all automatically injected libraries and helper functions + +## Additional Examples + +- **dom_elements_plugin.ts** - Comprehensive examples of DOM element creation +- **example_plugin.ts** - Legacy example plugin (deprecated, use numbered examples instead) +- **metadata-template.ts** - Template for plugin metadata structure + +## Injected Libraries + +The FDO application automatically injects several popular libraries that you can use without additional imports: + +- **CSS Frameworks**: Pure CSS, Notyf, Highlight.js +- **JavaScript Libraries**: FontAwesome, Split Grid, Highlight.js, Notyf, ACE Editor +- **Window Helpers**: `createBackendReq`, `waitForElement`, `executeInjectedScript`, and more + +For complete documentation, see [Injected Libraries Documentation](../docs/INJECTED_LIBRARIES.md). ## Usage diff --git a/src/index.ts b/src/index.ts index bccfd50..df37a8d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -134,6 +134,138 @@ declare global { } function Split(options: SplitOptions): SplitInstance; + + /** + * Notyf notification library types + * A simple, lightweight toast notification library + */ + interface NotyfNotification { + triggerDismiss: () => void; + } + + interface NotyfPosition { + x: 'left' | 'center' | 'right'; + y: 'top' | 'center' | 'bottom'; + } + + interface NotyfOptions { + duration?: number; + ripple?: boolean; + position?: NotyfPosition; + dismissible?: boolean; + } + + interface NotyfNotificationOptions extends NotyfOptions { + type?: string; + message?: string; + icon?: string | boolean; + background?: string; + className?: string; + } + + interface Notyf { + success(message: string | NotyfNotificationOptions): NotyfNotification; + error(message: string | NotyfNotificationOptions): NotyfNotification; + open(options: NotyfNotificationOptions): NotyfNotification; + dismissAll(): void; + } + + interface NotyfConstructor { + new(options?: NotyfOptions): Notyf; + } + + /** + * Highlight.js types + * Syntax highlighting library + */ + interface HighlightResult { + value: string; + language?: string; + relevance: number; + illegal: boolean; + errorRaised?: Error; + second_best?: Omit; + } + + interface HighlightJS { + highlight(code: string, options: { language: string; ignoreIllegals?: boolean }): HighlightResult; + highlightAuto(code: string, languageSubset?: string[]): HighlightResult; + highlightElement(element: HTMLElement): void; + highlightAll(): void; + registerLanguage(languageName: string, languageDefinition: any): void; + getLanguage(languageName: string): any; + listLanguages(): string[]; + } + + /** + * ACE Editor types + * Advanced code editor + */ + namespace AceAjax { + interface Editor { + setValue(value: string, cursorPos?: number): string; + getValue(): string; + setTheme(theme: string): void; + setShowPrintMargin(show: boolean): void; + setOption(name: string, value: any): void; + setOptions(options: Partial): void; + getSession(): EditSession; + resize(force?: boolean): void; + destroy(): void; + on(event: string, callback: Function): void; + off(event: string, callback: Function): void; + } + + interface EditSession { + setMode(mode: string): void; + setValue(text: string): void; + getValue(): string; + setUseWrapMode(useWrapMode: boolean): void; + setTabSize(tabSize: number): void; + setUseSoftTabs(useSoftTabs: boolean): void; + } + + interface EditorOptions { + selectionStyle?: string; + highlightActiveLine?: boolean; + highlightSelectedWord?: boolean; + readOnly?: boolean; + cursorStyle?: string; + mergeUndoDeltas?: boolean | string; + behavioursEnabled?: boolean; + wrapBehavioursEnabled?: boolean; + autoScrollEditorIntoView?: boolean; + copyWithEmptySelection?: boolean; + useSoftTabs?: boolean; + navigateWithinSoftTabs?: boolean; + enableMultiselect?: boolean; + } + + interface Ace { + edit(el: string | HTMLElement, options?: Partial): Editor; + createEditSession(text: string, mode: string): EditSession; + } + } + + interface Window { + /** + * Notyf - Toast notification library + * @see https://github.com/caroso1222/notyf + */ + Notyf: NotyfConstructor; + + /** + * Highlight.js - Syntax highlighting library + * @see https://highlightjs.org/ + */ + hljs: HighlightJS; + + /** + * ACE Editor - Code editor + * @see https://ace.c9.io/ + */ + ace: AceAjax.Ace; + } } export class FDO_SDK {