Project: dorkbrain-led-panel (Grafana Panel Plugin)

Summary:
A custom Grafana panel plugin that renders LED-style text inside dashboards. Simulates physical LED/LCD segment displays using web fonts with configurable animations and effects.

Features:
- 14-segment and dot matrix fonts (6 fonts total)
- Color themes (Green, Amber, Red, Blue, Cyan, White, Yellow, LCD)
- Configurable colors, brightness, and glow effects
- "Off segments" display for authentic LED look
- Leading unlit segments for fixed-width display
- Blink, fade, and pulse animations (constant or threshold-triggered)
- Scrolling text animation (left/right)
- Count up/down animation with configurable easing
- Auto font size (fits text to panel dimensions)
- Grafana-native unit formatting
- Max digits counts all characters (excludes decimal point)
- Multi-line display for multiple values
- Dynamic data binding from Grafana queries
- Configurable calculation/reducer (Last, Min, Max, Mean, etc.)

Current Fonts (included):

14-Segment (DSEG):
1. DSEG14 Classic - Classic 14-segment alphanumeric display
2. DSEG14 Modern - Modern 14-segment display
   Source: https://github.com/keshikan/DSEG (SIL OFL)

Dot Matrix:
3. DotMatrix - 1980s dot matrix printer style
   Source: https://github.com/Gissio/font_DotMatrix (SIL OFL)
4. DotMatrix UK - Simple dot matrix typeface
   Source: https://github.com/DanielHartUK/Dot-Matrix-Typeface (SIL OFL)
5. Matrix Sans Screen - 5x7 LED display style
6. Matrix Sans Print - 5x7 dot matrix printer style
   Source: https://github.com/FriedOrange/MatrixSans (SIL OFL)

Technical Stack:
- Package manager: npm
- Build: Webpack + SWC
- Language: TypeScript + React
- Grafana SDK: @grafana/data, @grafana/ui, @grafana/runtime (v10.2+)

Project Structure:
dorkbrain-led-panel/
├── .config/webpack/          # Build configuration
├── checkpoints/              # Version archives (src + dist)
├── dist/                     # Built plugin (load into Grafana)
├── scripts/
│   └── create-checkpoint.sh  # Create version archives
├── src/
│   ├── components/
│   │   ├── LEDPanel.tsx      # Main panel component
│   │   └── fonts.css         # Font-face definitions
│   ├── fonts/                # LED font files (.woff, .woff2)
│   ├── img/                  # Plugin logo
│   ├── module.ts             # Plugin entry point + options
│   ├── plugin.json           # Plugin metadata
│   └── types.ts              # TypeScript types
├── package.json
└── tsconfig.json

Commands:
- npm install                            Install dependencies
- npm run dev                            Watch mode (hot reload)
- npm run build                          Production build
- npm run typecheck                      TypeScript checking
- ./scripts/create-checkpoint.sh <ver>   Bump versions, build, create archives + DEB
- ./scripts/create-deb.sh <ver>          Build Debian package installer (from existing dist/)

Panel Options (Current):

  Value:
  - Calculation: Last*, First*, Min, Max, Mean, Sum, Count, etc.
  - Prefix: text before value
  - Suffix: text after value
  - Decimals: number of decimal places
  - Min Digits: minimum digits (zero-pads)
  - Max Digits: maximum digit characters (excludes decimal point)

  Units:
  - Show Unit: toggle unit display
  - Unit: Grafana unit picker (bytes, percent, time, etc.)

  Font:
  - Font Family: DSEG14 Classic/Modern, DotMatrix, DotMatrixUK, MatrixSansScreen/Print
  - Auto Font Size: automatically fit text to panel
  - Font Size: 12-200px (when auto disabled)
  - Letter Spacing: -5 to 20px

  Colors:
  - Color Theme: preset (Green, Amber, Red, Blue, Cyan, White, Yellow, LCD, Custom)
  - Segment Color: lit segment color (custom only)
  - Background Color: panel background (custom only)
  - Show Off Segments: display unlit segments
  - Off Segment Color: unlit segment color (custom only)
  - Brightness: 10-100%

  Glow Effect:
  - Enable Glow: toggle glow effect
  - Glow Color: glow color
  - Glow Intensity: 1-30

  Animation:
  - Animation Effect: None | Blink | Fade | Pulse
  - Animation Speed: Slow | Medium | Fast (when effect != none)
  - Animation Trigger: Always | On Threshold (when effect != none)
  - Threshold Value: value trigger (threshold trigger only)
  - Trigger When Above: above/below threshold (threshold trigger only)
  - Scroll Mode: none/left/right
  - Scroll Speed: 10-200 px/s
  - Count Animation: enable smooth counting
  - Count Duration: 100-5000ms
  - Count Easing: linear/ease-in/ease-out/ease-in-out

  Display:
  - Display Mode: single/multi-line
  - Line Spacing: 0-32px
  - Max Lines: 1-10

Current Status:
- [x] Scaffolding complete
- [x] Build pipeline working (webpack + swc)
- [x] DSEG fonts integrated (7-seg and 14-seg)
- [x] Panel component with full options
- [x] Dynamic data binding
- [x] Brightness control
- [x] Off-segment display effect
- [x] Blink animation (timed + threshold)
- [x] Scroll animation (left/right)
- [x] Multi-line display support
- [x] Decimals as textbox (not slider)
- [x] Min/max digits with zero-padding
- [x] Grafana unit selector with toggle
- [x] Count up/down animation with configurable easing
- [x] Calculation/reducer selector (Last, Min, Max, etc.)
- [x] Easing options for count animation (linear, ease-in, ease-out, ease-in-out)
- [x] Leading unlit segments when maxDigits set (shows fixed digit positions)
- [x] Auto font size option (automatically sizes text to fit panel)
- [x] Fade and pulse animation effects
- [x] Restructured animation options (effect/speed/trigger)
- [x] Added 4 dot matrix fonts (DotMatrix, DotMatrixUK, MatrixSansScreen, MatrixSansPrint)
- [x] String/text field support (auto-detected, renders with all animations)

PENDING TASKS:
(none)

Roadmap (ordered by complexity):
1. [x] Color themes/presets - predefined color combinations
2. [x] More animation effects - fade, pulse with threshold support
3. [x] Additional fonts - Dot Matrix (4 new fonts added)

Development Notes:
- Restart Grafana after building: sudo systemctl restart grafana-server
- Clear browser cache after changes (Empty Cache and Hard Reload)
- Plugin ID: dorkbrain-led-panel
- Minimum Grafana version: 10.0.0
- Unsigned plugin - requires allow_loading_unsigned_plugins config

Key Files:
- src/types.ts - Type definitions and defaults
- src/module.ts - Plugin entry point and panel options
- src/components/LEDPanel.tsx - Main rendering logic

Last Completed Work (v1.3.x):
- Added string/text field support
  - Auto-detected via FieldType.string in raw data.series (NOT via getFieldDisplayValues)
  - getFieldDisplayValues skips string fields entirely and returns a "No data" sentinel
    (colIndex=undefined, hasView=false) — cannot be used to retrieve string values
  - Raw string values extracted directly from data.series field.values before calling
    getFieldDisplayValues; sentinel detected and replaced with string display values
  - Bypasses numeric formatting (decimals, min/max digits, units) for text fields
  - Prefix and suffix still applied to text values
  - All animations (blink, fade, pulse, scroll) work with text fields
  - Count animation naturally skipped for text (NaN values don't trigger it)
  - Mixed numeric+string queries supported (getFieldDisplayValues handles numeric,
    raw scan handles string)
- create-checkpoint.sh now bumps version files and rebuilds automatically
- create-deb.sh recovered and added to scripts/