complete Studio core and JavaFX boundary migration
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 64.01% (20482/31999)
* Branch Coverage: 54.22% (8240/15196)
* Lines of Code: 31999
* Cyclomatic Complexity: 13164
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 64.01% (20482/31999)
* Branch Coverage: 54.22% (8240/15196)
* Lines of Code: 31999
* Cyclomatic Complexity: 13164
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
This commit is contained in:
@@ -1,169 +1,66 @@
|
||||
# Studio Components Module Specification
|
||||
# Studio JavaFX Components Boundary Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
|
||||
Purpose: Define the authoritative visual control layer for the Studio.
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio-ui-javafx`
|
||||
- shared Studio controls and workspace-framework primitives
|
||||
- JavaFX controls actively used by the Studio
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the visual component boundary inside the JavaFX adapter without creating a second application or domain layer.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio components module decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- `prometeu-studio-components`
|
||||
- Studio shell and workspace UI needs
|
||||
- JavaFX controls actively used by the Studio
|
||||
This specification is subordinate to [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. `prometeu-studio-components` is the official visual control module for Studio UI.
|
||||
2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
|
||||
3. A control enters the module when it is needed by the current Studio UI wave.
|
||||
4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
|
||||
5. Every admitted control must preserve theme and i18n compatibility.
|
||||
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.
|
||||
1. Reusable Studio visual controls belong to `prometeu-studio-ui-javafx`.
|
||||
2. The JavaFX adapter may organize reusable controls by shell, forms, banks, lifecycle, navigation, feedback, and inspection roles.
|
||||
3. A control is admitted when it has an immediate Studio consumer; speculative mirroring of JavaFX is forbidden.
|
||||
4. Shared controls must preserve theme, localization, and explicit visual-state behavior.
|
||||
5. Controls that observe UI events must expose predictable attach/detach or subscribe/unsubscribe lifecycle behavior.
|
||||
6. Visual controls must depend on neutral Studio API contracts, not core or provider implementations.
|
||||
7. Domain rules, application orchestration, filesystem workflows, compiler/Packer/LSP/runtime calls, and Spring composition do not belong in the visual component layer.
|
||||
|
||||
## Module Role
|
||||
## JavaFX Wrapping Boundary
|
||||
|
||||
`prometeu-studio-components` is:
|
||||
The Studio may use raw JavaFX for trivial local composition. A reusable control should expose the Studio-facing API actually needed instead of cloning the complete upstream JavaFX surface.
|
||||
|
||||
- the authoritative Studio control layer;
|
||||
- the home of the Studio visual dialect;
|
||||
- the place where Studio-facing controls are shaped for Studio use;
|
||||
- the preferred home for reusable lifecycle-aware workspace controls when those controls are part of the visible Studio UI dialect.
|
||||
Shared controls may include:
|
||||
|
||||
`prometeu-studio-components` is not:
|
||||
- shell and action controls;
|
||||
- workspace rails and hosts;
|
||||
- form sections and action bars;
|
||||
- list, tree, inspector, and dual-list surfaces;
|
||||
- activity, progress, badges, headers, and feedback controls;
|
||||
- lifecycle-managed visual primitives.
|
||||
|
||||
- a speculative generic framework;
|
||||
- a full reimplementation of JavaFX;
|
||||
- a dumping ground for unrelated non-visual infrastructure.
|
||||
## Construction and Lifecycle
|
||||
|
||||
## Admission Policy
|
||||
Controls, rows, dialogs, and views MUST NOT be Spring singletons by default. A Spring-managed JavaFX composition factory may create them with explicit constructor dependencies.
|
||||
|
||||
A control is admissible when it is needed by the current Studio UI work.
|
||||
Controls that attach event subscriptions MUST release them when detached. UI-local events may coordinate selection, navigation, editing scope, attach/detach, and presentation refresh. Request/response application behavior MUST use injected Studio API services directly.
|
||||
|
||||
Rules:
|
||||
## State Boundary
|
||||
|
||||
- immediate current Studio use is sufficient justification;
|
||||
- a second use is not required when the control is clearly part of the shell or the current workspace surface;
|
||||
- no control should be added without an immediate Studio consumer.
|
||||
- a control needed first by one workspace may still be admitted when it is clearly intended as a reusable Studio workspace primitive.
|
||||
Presentation-only view models, form drafts, selection state, and formatting helpers may live beside JavaFX controls when they do not determine domain outcomes.
|
||||
|
||||
## Studio Usage Rule
|
||||
|
||||
The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
|
||||
|
||||
Rules:
|
||||
|
||||
- a visual control used by Studio should normally come from `prometeu-studio-components`;
|
||||
- extremely trivial local composition may stay in `prometeu-studio`;
|
||||
- local exceptions must remain exceptional rather than becoming the default path.
|
||||
|
||||
## Wrapping Boundary
|
||||
|
||||
Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
|
||||
|
||||
Rules:
|
||||
|
||||
- the Studio-layer control should expose the Studio-facing API actually needed;
|
||||
- exhaustive mirroring of upstream JavaFX APIs is not required;
|
||||
- the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
|
||||
|
||||
## Control Lifecycle Hooks
|
||||
|
||||
Studio controls may need to observe event buses or other external state.
|
||||
|
||||
Rules:
|
||||
|
||||
- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed;
|
||||
- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks;
|
||||
- `onAttached()` should call `subscribe()`;
|
||||
- `onDetached()` should call `unsubscribe()`;
|
||||
- controls that attach subscriptions must also define how those subscriptions are released;
|
||||
- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring.
|
||||
|
||||
These hooks exist so event-driven controls remain predictable and safe to embed in shell and workspace UI.
|
||||
|
||||
## Reusable Workspace Primitives
|
||||
|
||||
Some reusable controls are not shell-only and are not domain-specific either.
|
||||
|
||||
They may still belong in `prometeu-studio-components` when they are part of the visible Studio workspace framework.
|
||||
|
||||
Illustrative admissible examples include:
|
||||
|
||||
- projection hosts for list/tree/detail surfaces;
|
||||
- lifecycle-managed row or item controls;
|
||||
- reusable section or inspector surfaces;
|
||||
- visible controls that encode local-patch versus structural-sync interaction patterns.
|
||||
|
||||
What does not belong here:
|
||||
|
||||
- workspace-specific orchestration logic;
|
||||
- domain-specific service calls;
|
||||
- hidden coordination code with no visible control responsibility.
|
||||
|
||||
## Typical Control Scope
|
||||
|
||||
Typical controls that belong in the module include:
|
||||
|
||||
- shell controls;
|
||||
- action controls and buttons;
|
||||
- tab systems;
|
||||
- tree and list controls;
|
||||
- inspector and panel surfaces;
|
||||
- activity and feedback surfaces;
|
||||
- badges, headers, and related Studio primitives.
|
||||
|
||||
What stays outside the module:
|
||||
|
||||
- workspace-specific composition logic;
|
||||
- non-visual domain behavior;
|
||||
- speculative controls with no immediate Studio consumer.
|
||||
|
||||
## Theme and i18n
|
||||
|
||||
Every admitted control must support:
|
||||
|
||||
- CSS-based theming;
|
||||
- safe locale-aware text behavior when text is exposed;
|
||||
- no hardcoded user-facing text;
|
||||
- explicit visual states where state matters.
|
||||
|
||||
## Organization Guidance
|
||||
|
||||
The module should be organized by Studio role rather than vague technical buckets.
|
||||
|
||||
Illustrative areas include:
|
||||
|
||||
- shell;
|
||||
- actions;
|
||||
- navigation;
|
||||
- feedback;
|
||||
- inspection;
|
||||
- trees.
|
||||
|
||||
## Anti-Bloat Rule
|
||||
|
||||
The module must remain:
|
||||
|
||||
- intentional;
|
||||
- Studio-driven;
|
||||
- small enough to reason about;
|
||||
- broad enough to prevent UI entropy in the application.
|
||||
Non-visual policies and workflows that determine asset validity, capacity, metadata, build, runtime, project, or semantic results MUST live behind `prometeu-studio-api` and be implemented by `prometeu-studio-core` or an explicit infrastructure adapter.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the first concrete component set in full detail
|
||||
- defining final package layout exhaustively
|
||||
- mirroring the entire JavaFX control hierarchy
|
||||
- storing domain-specific workspace orchestration code in the components module
|
||||
- creating a standalone `prometeu-studio-components` Gradle module;
|
||||
- wrapping the full JavaFX API;
|
||||
- storing workspace business logic in controls;
|
||||
- using Spring as a registry for each visual object;
|
||||
- defining components for a future web UI.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the module role is unambiguous;
|
||||
- admission rules are stable enough to guide implementation;
|
||||
- reusable workspace-control admission is clear enough to prevent local reimplementation drift;
|
||||
- the JavaFX wrapping boundary is clear enough to prevent drift.
|
||||
This specification is satisfied when reusable JavaFX controls have clear visual ownership, explicit lifecycle behavior, neutral injected dependencies, and no application or provider implementation responsibilities.
|
||||
|
||||
Reference in New Issue
Block a user