diff --git a/README.md b/README.md new file mode 100644 index 0000000..96cfdec --- /dev/null +++ b/README.md @@ -0,0 +1,230 @@ +# TDX-Enhanced + +A Chrome extension that enhances the TeamDynamix (TDX) interface with improved styling, functionality, and user experience features. Originally developed as a userscript, this extension has been converted to a Chrome extension to simplify development and distribution. + +## Features + +### Visual Enhancements +- **Dark/Light Mode**: Automatic color scheme detection based on system preferences, with manual override options +- **Queue Color Coding**: Automatic color highlighting for different support queues with predefined color schemes +- **Custom Themes**: Multiple theme options (Gold, Blue, Green) with custom color support +- **Custom Highlighting**: Support for inline text highlighting using special markers (e.g., `!! text !!`, `~~ text ~~`) +- **Responsive Layout Options**: Sticky columns and customizable dashboard layouts + +### Functional Improvements +- **Relative Date Display**: Converts absolute dates to relative time (e.g., "2 hours ago", "3 days ago") +- **Calendar Enhancements**: Improved date picker with quick shortcuts for common date operations (+1 day, +1 week, +1 month, 12PM, 5PM) +- **Link Behavior Customization**: Options to open links in new tabs or windows +- **Ticket Age Highlighting**: Visual indicators for ticket age with color-coded backgrounds +- **User Reply Detection**: Highlights tickets with recent user replies +- **Modified By Indicators**: Visual indicators for tickets modified by internal staff + +### UI Components +- **Status Monitor**: Integration with IT status page showing current system status +- **Settings Panel**: Comprehensive settings interface accessible from the toolbar +- **TDX Tools Integration**: Quick access link to TDX tools +- **Custom Toolbar**: Enhanced toolbar with status indicators and settings + +## Installation + +### For Development + +1. Clone this repository: + ```bash + git clone + cd TDX-Enhanced + ``` + +2. Open Chrome and navigate to `chrome://extensions/` + +3. Enable "Developer mode" (toggle in the top right) + +4. Click "Load unpacked" and select the repository directory + +5. The extension will be loaded and active on TDX pages + +## Configuration + +### Settings Panel + +Access the settings panel by clicking the wrench icon in the TDX toolbar. Available settings include: + +- **Color Mode**: Light, Dark, or Auto (follows system preference) +- **Theme**: Gold, Blue, Green, or Custom +- **Custom Colors**: Define custom accent and background colors +- **Custom Highlights**: Configure custom highlighting rules +- **Link Behavior**: Choose how links open (tabs or default windows) +- **Highlight Behavior**: Block or text highlighting style +- **Sticky Columns**: Enable sticky positioning for dashboard columns + +### Queue Colors + +Queue colors are predefined in `content/modules/config.js`. Each queue has a background and text color defined. Supported queues include: +- AAE, ABE, BIDC, Biology, BME, CE, CHE, Chem, COEA, COEP +- Computer Science, DP, DOE, ECE, ECN Accounts, EAPS, EEE +- ENE, EPICS, FLEX, Helpdesk, IE, IMI, Apple, Mailman, Math +- ME, MSE, NE, PARI, Physics, President, Site Managers, Stat +- SWT, Polytechnic, CNIT, UDS, Web, Windows, ZSite +- And more... + +### Custom Highlighting + +#### Inline Highlighting +Use special markers in ticket titles or descriptions: +- `!! highlighted text !!` - Highlights with primary highlight color +- `~~ highlighted text ~~` - Highlights with secondary highlight color + +#### Custom Highlight Rules +Configure custom highlighting rules through the settings panel or color editor: +- **Highlight**: Custom inline highlighting with user-defined markers +- **Reply**: Highlight tickets with user replies +- **Date Modified**: Highlight based on ticket age +- **User Modified**: Highlight tickets modified by internal users +- **Report**: Highlight specific report types +- **Person**: Highlight specific users + +## Project Structure + +``` +TDX-Enhanced/ +├── manifest.json # Chrome extension manifest +├── userscript.js # Legacy userscript file (not used in extension) +├── content/ +│ ├── content.js # Main content script entry point +│ ├── styles.css # All CSS styles and theme definitions +│ └── modules/ +│ ├── config.js # Configuration constants (queue colors, URLs) +│ ├── color.js # Color manipulation and CSS filter generation +│ ├── utils.js # Utility functions (color mode, CSS variables) +│ ├── settings.js # Settings management and localStorage +│ ├── highlighting.js # Highlighting logic and bubble creation +│ ├── links.js # Link handling and behavior +│ ├── parsing.js # Ticket and table parsing functions +│ ├── ui.js # UI components (toolbar, status, styles injection) +│ └── observer.js # MutationObserver for dynamic content +└── lib/ + ├── moment.min.js # Moment.js for date manipulation + └── tinycolor.min.js # TinyColor for color operations +``` + +## Architecture + +### Entry Point +`content/content.js` is the main entry point that: +- Applies color mode early to prevent flash of unstyled content +- Initializes all modules in the correct order +- Sets up event listeners for storage changes and messages + +### Module System + +The extension is organized into focused modules: + +1. **config.js**: Central configuration including queue colors, status markers, and URLs +2. **color.js**: Advanced color manipulation using CSS filters to match target colors +3. **utils.js**: Helper functions for color mode management and CSS variable setting +4. **settings.js**: Settings persistence and retrieval from localStorage +5. **highlighting.js**: Applies highlighting rules to elements based on configuration +6. **links.js**: Modifies link behavior (new tabs/windows) based on user preferences +7. **parsing.js**: Parses tickets, tables, and other TDX elements to extract and format data +8. **ui.js**: Creates and manages UI components (toolbar, status monitor, settings panel) +9. **observer.js**: Watches for DOM changes and applies enhancements to new content + +### MutationObserver + +A MutationObserver watches for DOM changes and automatically applies enhancements to: +- New tables (reports, ticket lists) +- Feed updates (ticket activity feeds) +- Dashboard widgets +- Side panels +- IFrames and shadow DOM elements + +### Style Injection + +The extension injects styles into: +- Main document +- Shadow DOM elements (TDX search bar, etc.) +- IFrames (embedded content) +- Dynamically loaded content + +Styles use CSS custom properties (variables) that change based on the selected theme and color mode. + +## Development + +### Making Changes + +1. **Modify Code**: Edit files in the `content/` directory +2. **Reload Extension**: Go to `chrome://extensions/` and click the reload icon +3. **Test**: Navigate to a TDX page and verify changes +4. **Debug**: Use Chrome DevTools Console to view logs and errors + +### Key Functions + +#### Color Mode Management +```javascript +setColorMode(mode) // Sets color mode: "lightMode", "darkMode", or "auto" +getColorMode() // Returns current system color mode preference +``` + +#### Settings Management +```javascript +settings('get', 'settingName') // Get a setting value +settings('apply') // Apply all settings from storage +settings('update') // Update settings from form +settings('toggle') // Toggle settings menu visibility +``` + +#### Highlighting +```javascript +handleHighlight(type, txt, element) // Apply highlighting to an element +createHighlightBubble(element, bgColor, txtColor) // Create highlight bubble +``` + +#### Link Handling +```javascript +handleLink(source, link) // Modify link behavior based on settings +``` + +### CSS Custom Properties + +The extension uses CSS custom properties for theming. Key variables: +- `--dark-col-primary` / `--light-col-primary`: Primary accent color +- `--dark-bg-primary` / `--light-bg-primary`: Primary background color +- `--dark-col-reply` / `--light-col-reply`: Color for user replies +- `--dark-col-modified` / `--light-col-modified`: Color for modified tickets +- `--filter-*`: CSS filter values for color manipulation + +## Browser Compatibility + +- **Chrome**: Fully supported (Manifest V3) +- **Other Chromium browsers**: Should work, may need minor modifications +- **Firefox-based Browsers**: not working at the moment :( + +## Permissions + +The extension requires: +- **storage**: For saving user settings +- **host_permissions**: For accessing TDX domains and status API +- **web_accessible_resources**: For injecting CSS styles + +## Dependencies + +- **Moment.js**: Date parsing and formatting +- **TinyColor**: Color manipulation and brightness calculations + +Both are included as minified files in the `lib/` directory. + +## Known Limitations + +1. **Shadow DOM**: Some TDX elements use shadow DOM, which requires special style injection +2. **Dynamic Content**: Content loaded via AJAX requires MutationObserver handling +3. **IFrames**: Embedded content may not always receive styles immediately +4. **Queue Colors**: Queue names must match exactly (case-insensitive) for color coding + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test thoroughly on TDX pages +5. Submit a pull request +