papiflyfx-docking

A multi-module Java/JavaFX framework for IDE-style docking layouts — drag-and-drop panels, floating windows, minimize/maximize, tab groups, and JSON session persistence.

Overview

PapiflyFX Docking provides composable UI building blocks for desktop applications that need flexible, resizable, dockable panel layouts (similar to IntelliJ IDEA, VS Code, or Eclipse). The project is organized as a Maven multi-module build targeting Java 25 with JavaFX 25.0.2.

Requirements

Tool	Version
Java	25 (Zulu FX recommended)
Maven	≥ 3.9 (wrapper included — ./mvnw)
JavaFX	25.0.2 (managed via Maven, auto-resolved per platform)

Java setup (SDKMAN)

sdk use java 25.0.1.fx-zulu

Build & Run

# compile all modules
./mvnw compile

# full build (compile + test + package)
./mvnw clean package

Run demos

# docks demo
./mvnw javafx:run -pl papiflyfx-docking-docks

# samples demo
./mvnw javafx:run -pl papiflyfx-docking-samples

Tests

The project uses JUnit Jupiter 5 and TestFX for UI tests.

# run all tests
./mvnw test

# run tests for a single module
./mvnw test -pl papiflyfx-docking-docks

# headless UI tests (CI / no display)
./mvnw -Dtestfx.headless=true test

# headless for a single module
./mvnw -Dtestfx.headless=true test -pl papiflyfx-docking-docks

UI Standards

PapiflyFX Docking uses a single runtime styling source: Theme. Cross-module UI standards are projected from that API through shared helpers in papiflyfx-docking-api rather than through separate per-module theme systems.

Shared UI standards are implemented in:

• org.metalib.papifly.fx.ui.UiMetrics for the shared 4px spacing grid and standard heights/radii
• org.metalib.papifly.fx.ui.UiStyleSupport and UiCommonStyles for Theme -> CSS variable projection and stylesheet loading
• org.metalib.papifly.fx.ui.ui-common.css for shared popup, field, chip, pill, icon-button, and status-slot styling
• org.metalib.papifly.fx.ui.UiPillButton, UiChip, UiChipToggle, UiChipLabel, and UiStatusSlot for lightweight reusable JavaFX primitives

Current shared metrics:

• Spacing scale: 4 / 8 / 12 / 16 / 20 / 24
• Radii: 4 / 8 / 12 / 999
• Standard heights: compact controls 24, regular controls 28, toolbar minimum 44

Shared CSS variables use the -pf-ui-* prefix. Examples include:

• Surface tokens such as -pf-ui-surface-overlay and -pf-ui-surface-control
• Text tokens such as -pf-ui-text-primary and -pf-ui-text-muted
• Border/status tokens such as -pf-ui-border-focus, -pf-ui-accent, -pf-ui-success, -pf-ui-warning, and -pf-ui-danger
• Metric tokens such as -pf-ui-space-*, -pf-ui-radius-*, and -pf-ui-control-height-*

Module guidance:

• Bind dock content to ObjectProperty<Theme> and keep that property as the only runtime theme source.
• Prefer shared Ui* controls and ui-common.css surface classes before introducing module-local styling.
• Keep canvas layout metrics aligned to UiMetrics or theme-derived dimensions instead of local ad hoc numbers.

The rollout plan and token reference live in spec/ui-standards/research.md and spec/ui-standards/plan.md.

Environment Variables

No special environment variables are required for building or running. SDKMAN is used to manage the Java version (see Requirements).

Project Structure

papiflyfx-docking/
├── pom.xml                        # root aggregator POM
├── mvnw / mvnw.cmd                # Maven wrapper
├── papiflyfx-docking-api/         # shared API & interfaces
├── papiflyfx-docking-settings-api/ # settings and secret-management SPI
├── papiflyfx-docking-docks/       # core docking framework (drag-drop, tabs, floating, persistence)
├── papiflyfx-docking-settings/    # settings runtime and persistence
├── papiflyfx-docking-login-idapi/ # login provider SPI
├── papiflyfx-docking-login-session-api/ # auth session SPI
├── papiflyfx-docking-login/       # login runtime and UI
├── papiflyfx-docking-code/        # code-editor docking panel
├── papiflyfx-docking-tree/        # tree-view docking panel
├── papiflyfx-docking-media/       # media (audio/video) viewer panels
├── papiflyfx-docking-hugo/        # Hugo preview panel
├── papiflyfx-docking-github/      # GitHub toolbar/content integration
├── papiflyfx-docking-samples/     # demo applications
├── papiflyfx-docking-bom/         # Bill of Materials for dependency alignment
├── papiflyfx-docking-archetype/   # Maven archetype for new applications
└── spec/                          # architecture specs & design docs
    ├── papiflyfx-docking-api/
    ├── papiflyfx-docking-code/
    ├── papiflyfx-docking-docks/
    ├── papiflyfx-docking-github/
    ├── papiflyfx-docking-hugo/
    ├── papiflyfx-docking-media/
    ├── papiflyfx-docking-settings/
    ├── papiflyfx-docking-samples/
    └── papiflyfx-docking-tree/

Module summary

Module	Description
papiflyfx-docking-api	Shared docking API plus Theme, shared UI metrics, CSS token helpers, and lightweight reusable UI primitives
papiflyfx-docking-settings-api	Settings and secret-management SPI
papiflyfx-docking-docks	Core docking/layout UI — drag-and-drop, floating windows, minimize/maximize, JSON session persistence
papiflyfx-docking-settings	Composable settings runtime, event-driven UI, tokenized styling, and secure secret storage
papiflyfx-docking-login-idapi	Identity-provider SPI and built-in provider contracts
papiflyfx-docking-login-session-api	Authentication session lifecycle and storage SPI
papiflyfx-docking-login	Login runtime and UI integration
papiflyfx-docking-code	Canvas-based code editor with search/go-to-line overlays and runtime theme binding
papiflyfx-docking-tree	Canvas-based virtualized tree with search, inline info, and runtime theme binding
papiflyfx-docking-media	Image, SVG, audio, video, and embedded viewers with theme-aware host controls
papiflyfx-docking-hugo	Hugo preview content with theme-aware host chrome and embedded WebView rendering
papiflyfx-docking-github	GitHub workflow toolbar using shared pills, chips, popup surfaces, and status slots
papiflyfx-docking-samples	Demo/sample applications showcasing the framework
papiflyfx-docking-bom	Bill of Materials — import to align all framework dependency versions
papiflyfx-docking-archetype	Maven archetype for bootstrapping a new PapiflyFX application

Using PapiflyFX in Your Project

BOM (Bill of Materials)

Import the BOM to align all framework dependency versions:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.metalib.papifly.docking</groupId>
            <artifactId>papiflyfx-docking-bom</artifactId>
            <version>0.0.18-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- Then add modules without version tags: -->
<dependencies>
    <dependency>
        <groupId>org.metalib.papifly.docking</groupId>
        <artifactId>papiflyfx-docking-docks</artifactId>
    </dependency>
</dependencies>

Archetype (Project Generator)

Bootstrap a new PapiflyFX application with a single command:

mvn archetype:generate \
  -DarchetypeGroupId=org.metalib.papifly.docking \
  -DarchetypeArtifactId=papiflyfx-docking-archetype \
  -DarchetypeVersion=0.0.19-SNAPSHOT \
  -DgroupId=com.example \
  -DartifactId=my-app \
  -Dversion=0.1.0-SNAPSHOT \
  -Dpackage=com.example.myapp \
  -DinteractiveMode=false

cd my-app
mvn wrapper:wrapper -Dmaven=3.9.12
./mvnw clean package

The generated project includes a multi-module structure with DockManager starter, headless TestFX tests, CI workflow, and agent documentation. See papiflyfx-docking-archetype/README.md for details.

Documentation

• Module specs and design docs: spec/ directory
• UI standards research and rollout plan: spec/ui-standards/research.md, spec/ui-standards/plan.md
• Agent operating model, playbook, prompt pack, and cheat sheet: spec/agents/README.md, spec/agents/playbook.md, spec/agents/prompts.md, and spec/agents/cheatsheet.md

Similar Projects

• Drombler FX — modular application framework for JavaFX
• BentoFX — a docking system for JavaFX
• DockFX — docking framework for JavaFX
• FxDock — simple docking framework with multi-monitor support

License

Apache License, Version 2.0