146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
# Studio Components Module Specification
|
|
|
|
Status: Draft
|
|
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
|
|
Purpose: Define the authoritative visual control layer for the Studio.
|
|
|
|
## 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
|
|
|
|
## 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.
|
|
|
|
## Module Role
|
|
|
|
`prometeu-studio-components` is:
|
|
|
|
- the authoritative Studio control layer;
|
|
- the home of the Studio visual dialect;
|
|
- the place where Studio-facing controls are shaped for Studio use.
|
|
|
|
`prometeu-studio-components` is not:
|
|
|
|
- a speculative generic framework;
|
|
- a full reimplementation of JavaFX;
|
|
- a dumping ground for unrelated non-visual infrastructure.
|
|
|
|
## Admission Policy
|
|
|
|
A control is admissible when it is needed by the current Studio UI work.
|
|
|
|
Rules:
|
|
|
|
- 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.
|
|
|
|
## 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.
|
|
|
|
## 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-Goals
|
|
|
|
- defining the first concrete component set in full detail
|
|
- defining final package layout exhaustively
|
|
- mirroring the entire JavaFX control hierarchy
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- the module role is unambiguous;
|
|
- admission rules are stable enough to guide implementation;
|
|
- the JavaFX wrapping boundary is clear enough to prevent drift.
|