prometeu-studio/docs/studio/specs/3. Studio Components Module Specification.md

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.