====== WvdS FPC RAD Studio - Developer Documentation ======

//Internal documentation for developers of the WvdS FPC RAD Suite//

<note warning>This documentation is for **internal developers** of the suite, not for end users. For user documentation see [[..:p:start|Public Documentation]].</note>

===== Overview =====

WvdS FPC RAD Studio is an extension suite for Visual Studio Code, written entirely in Pascal and transpiled to JavaScript using pas2js.

==== Core Principles ====

  * **No TypeScript** - All extensions are Pascal-based
  * **SSOT** - Single Source of Truth in ''sources/''
  * **Separation of Concerns** - Strict layered architecture
  * **KRITIS/NIS2 compliant** - Security as a fundamental requirement

===== Documentation Index =====

==== Architecture ====

^ Document ^ Content ^
| [[.:architektur|Architecture Overview]] | Monorepo structure, layers, dependencies |
| [[.:umgebung|Development Environment]] | Project structure, paths, SSOT rules |
| [[.:pxaml-pipeline|PXAML Pipeline]] | Markup to IR to Renderer |
| [[.:extension-architektur|Extension Architecture]] | Entry Points, Activation, Services |
| [[.:targets|Build Targets]] | GUI, TUI, Web - Differences and commonalities |

==== Development ====

^ Document ^ Content ^
| [[.:extension-entwicklung|Extension Development]] | Creating new extensions, Best Practices |
| [[.:control-entwicklung|Control Development]] | 7-Step workflow for UI controls |
| [[.:code-konventionen|Code Conventions]] | Naming, structure, documentation |
| [[.:sicherheit|Security Guidelines]] | OWASP, KRITIS, Audit |
| [[.:i18n|Internationalization]] | Resourcestrings, translations |
| [[.:debugging|Debugging]] | Debug logging, error analysis |

==== Build and Release ====

^ Document ^ Content ^
| [[.:build-pipeline|Build Pipeline]] | pas2js compilation, Toolchain CLI, artifacts |
| [[.:pack-struktur|Pack Structure]] | Third-party packs, manifests, distribution |
| [[.:testing|Testing]] | Unit tests, integration tests |
| [[.:release|Release Process]] | Versioning, VSIX creation, publishing |

==== TUI Development ====

^ Document ^ Content ^
| [[.:tui-entwicklung|TUI Overview]] | Architecture, quality requirements, when to use TUI |
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, flicker-free rendering |
| [[.:tui-controls|TUI Controls]] | Model+Renderer Pattern, states, input, focus |
| [[.:tui-layout|TUI Layout]] | Anchoring, responsive, breakpoints, containers |

==== Quality Assurance ====

^ Document ^ Content ^
| [[.:qualitaetssicherung|QA Overview]] | Workflow, profile matrix, audit processes |
| [[.:audit-core|Core Checklist]] | Production-ready, error handling, logging |
| [[.:audit-sicherheit|Security Checklist]] | KRITIS/NIS2, OWASP, Crypto |
| [[.:audit-codequalitaet|Code Quality Checklist]] | Naming, functions, DRY, SSOT |
| [[.:kommentierung|Documentation Standards]] | PasDoc, doc comments, review |
| [[.:audit-vscode|VSCode Checklist]] | Extension-specific, pas2js |

==== API Reference ====

^ Document ^ Content ^
| [[.:core-api|Core API]] | Shared services, toolchain access |
| [[.:meta-api|Meta API]] | Component registry, IntelliSense provider |
| [[.:vscode-wrapper|VSCode Wrapper]] | WvdS.VSCode.* Units |

==== Control Library ====

^ Document ^ Content ^
| [[.:control-bibliothek|Control Catalog]] | All 108 controls with DevExpress mapping |
| [[.:control-architektur|Control Architecture]] | Properties/ViewInfo/Control Pattern |
| [[.:control-vsix-erstellen|Creating VSIX]] | Manually creating control extension |
| [[.:control-generierung|Control Generation]] | Batch generation with PowerShell |

==== Control API Reference ====

^ Document ^ Content ^
| [[.:api-controls-basic|Basic Controls]] | Label, Button, CheckBox, etc. (12) |
| [[.:api-controls-editors|Editor Controls]] | TextEdit, SpinEdit, DateEdit, etc. (18) |
| [[.:api-controls-navigation|Navigation]] | TabControl, Wizard, NavBar, etc. (7) |
| [[.:api-controls-data|Data Controls]] | DataGrid, TreeList, PivotGrid, etc. (10) |
| [[.:api-controls-charts|Charts]] | LineSeries, PieSeries, Sparkline, etc. (16) |
| [[.:api-controls-gauges|Gauges]] | CircularGauge, LED, Thermometer, etc. (10) |
| [[.:api-controls-layout|Layout]] | LayoutControl, DockingManager, etc. (10) |
| [[.:api-controls-bars|Bars/Ribbon]] | RibbonControl, StatusBar, etc. (10) |
| [[.:api-controls-specialized|Specialized]] | Scheduler, Spreadsheet, Map, etc. (15) |

===== Quick Start for New Developers =====

==== 1. Set Up Development Environment ====

<code bash>
# Clone repository
git clone https://github.com/ArmandoFilho/WvdS.FPC.git
cd WvdS.FPC

# Open VS Code
code .
</code>

==== 2. Install Tools ====

Required:
  * Free Pascal Compiler 3.2.2+
  * pas2js 2.2.0+
  * Node.js 18+ (for vsce)
  * VS Code 1.85.0+

Optional:
  * lazbuild (for LCL projects)
  * Inno Setup (for Windows installers)

==== 3. First Compilation ====

<code bash>
cd sources/extensions/wvds.vscode.core
pas2js -Jc -Jirtl.js -Tbrowser -Fu../../common -FE./dist extension_main.pas
</code>

==== 4. Test Extension ====

  - Press ''F5'' in VS Code to start the Extension Development Host
  - A new VS Code window opens with loaded extensions
  - Command Palette: ''WVDS: Hello'' to test

===== Repository Structure =====

<code>
WvdS.FPC/
├── sources/                    # SSOT - Version controlled
│   ├── common/                 # Shared Units
│   │   ├── core/               # Base units
│   │   ├── ui/                 # UI Framework
│   │   └── web/                # Host Bridges (Node, VSCode)
│   ├── extensions/             # VSIX Extensions
│   │   ├── wvds.vscode.core/
│   │   ├── wvds.vscode.build/
│   │   ├── wvds.vscode.projects/
│   │   ├── wvds.vscode.packaging/
│   │   ├── wvds.vscode.ui.designer/
│   │   ├── wvds.vscode.ui.meta/
│   │   └── wvds.vscode.ui.preview/
│   ├── applications/           # Standalone applications
│   ├── tools/                  # CLI tools (wvds-build, etc.)
│   └── packages/               # IDE Packages
│
├── binaries/                   # Build output (not version controlled)
│   ├── out/                    # Compiled artifacts
│   ├── cache/                  # Compiler cache
│   ├── dist/                   # Release packages
│   └── logs/                   # Build logs
│
└── .claude/                    # Claude configuration
    └── CLAUDE.md               # Repository rules
</code>

===== Policy Rules =====

These rules are **non-negotiable** and are checked by wvds-lint:

==== P0: Single Source of Truth ====

<code>
ALLOWED:   sources/common/WvdS.System.pas
FORBIDDEN: sources/extensions/wvds.vscode.core/WvdS.System.pas (duplicate!)
</code>

==== P1: No TypeScript ====

<code>
ALLOWED:   *.pas -> pas2js -> *.js
FORBIDDEN: *.ts, handwritten *.js
</code>

==== P2: Wrappers Only in common ====

<code>
ALLOWED:   sources/common/web/vscode/VSCode.API.pas
FORBIDDEN: sources/extensions/wvds.vscode.build/VSCode.API.pas
</code>

==== P3: Self-contained Output ====

<code>
dist/extension_main.js must contain all required units
</code>

===== Contacts =====

  * **Repository:** [[https://github.com/ArmandoFilho/WvdS.FPC|github.com/ArmandoFilho/WvdS.FPC]]
  * **Issues:** [[https://github.com/ArmandoFilho/WvdS.FPC/issues|Bug Reports and Feature Requests]]
  * **Code Review:** Pull Requests via GitHub

===== Next Steps =====

  * [[.:architektur|Understand the Architecture in Detail]]
  * [[.:extension-entwicklung|Develop Your First Extension]]
  * [[.:code-konventionen|Internalize Code Conventions]]