prometeu-studio/docs/specs/studio/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.
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.

## 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;
- the preferred home for reusable lifecycle-aware workspace controls when those controls are part of the visible Studio UI dialect.

`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.
- a control needed first by one workspace may still be admitted when it is clearly intended as a reusable Studio workspace primitive.

## 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-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

## 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.