197 lines
7.6 KiB
Markdown
197 lines
7.6 KiB
Markdown
# Studio UI Foundations Specification
|
|
|
|
Status: Draft
|
|
Scope: Naming, event publication model, and Studio UI foundations
|
|
Purpose: Define the shared infrastructure rules that all Studio UI work must follow.
|
|
|
|
## Authority and Precedence
|
|
|
|
This specification consolidates the accepted Studio UI foundations decision into normative form.
|
|
|
|
## Normative Inputs
|
|
|
|
- Studio shell structures
|
|
- workspace UI structures
|
|
- Studio-owned services
|
|
- shell and workspace event publication needs
|
|
- reusable Studio control infrastructure
|
|
|
|
## Core Rules
|
|
|
|
1. Studio UI naming must be explicit by role.
|
|
2. The Studio must define its own typed event system.
|
|
3. The Studio event system must include one global bus and one bus per workspace.
|
|
4. Every event published on a workspace bus must also be published on the global bus automatically.
|
|
5. Studio UI must preserve theme and i18n compatibility by construction.
|
|
6. Lifecycle-managed event subscription is the canonical way Studio controls observe external state.
|
|
7. The Studio must provide a reusable workspace framework for event-driven workspace composition.
|
|
8. Studio workspaces must consume that framework rather than invent refresh-heavy workspace-local patterns.
|
|
|
|
## Naming by Role
|
|
|
|
Studio naming must follow role-oriented conventions.
|
|
|
|
Baseline naming guidance:
|
|
|
|
- `StudioShell*` for shell-level structures;
|
|
- `*Workspace` for workspaces;
|
|
- `*Panel` for composed regions or panels;
|
|
- `*View` for focused visual views;
|
|
- `*Item` or `*Row` for list and cell-like elements;
|
|
- `StudioEvent*` for event types;
|
|
- `*Service` for operational services;
|
|
- `*Control` for reusable low-level visual controls.
|
|
|
|
Names must communicate responsibility directly.
|
|
Vague naming that hides shell, panel, workspace, or control roles is non-conforming.
|
|
|
|
## Studio Event System
|
|
|
|
The Studio must not rely on stringly-typed event routing as its primary contract.
|
|
|
|
Baseline event rules:
|
|
|
|
- event publication is local to the process;
|
|
- event publication is strongly typed;
|
|
- event payloads are DTOs and should be immutable where practical;
|
|
- event publication and subscription management must be thread-safe;
|
|
- the baseline model should remain intentionally small;
|
|
- a large reactive framework is not baseline behavior.
|
|
|
|
Thread safety is required because background work such as asset recognition, scanning, diagnostics refresh, or other asynchronous Studio activity may publish events that eventually affect visible UI state.
|
|
|
|
## Global and Workspace Buses
|
|
|
|
The baseline event topology includes:
|
|
|
|
- one global `StudioEventBus`;
|
|
- one workspace-local event bus per workspace.
|
|
|
|
Propagation rules:
|
|
|
|
- every event published on a workspace bus is automatically republished on the global bus;
|
|
- propagation is workspace to global;
|
|
- global-to-workspace rebroadcast is not baseline behavior.
|
|
|
|
The global Studio bus is backed by a typed event bus reference owned by the Studio application container.
|
|
|
|
Container rules:
|
|
|
|
- the Studio `Container` owns the global typed event bus reference used by `StudioEventBus`;
|
|
- host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
|
|
- the `Container` must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.
|
|
|
|
This topology exists so callers do not need to duplicate publication decisions manually.
|
|
|
|
## Event Categories
|
|
|
|
The exact event catalog may evolve incrementally.
|
|
|
|
Illustrative baseline categories include:
|
|
|
|
- project lifecycle events;
|
|
- project loading lifecycle events;
|
|
- workspace selection events;
|
|
- run and build intent events;
|
|
- activity publication events;
|
|
- progress update events;
|
|
- diagnostics update events;
|
|
- asset selection events.
|
|
|
|
For project bootstrap and splash/loading integration, the Studio event catalog should reserve typed events for:
|
|
|
|
- project loading started;
|
|
- project loading progress;
|
|
- project loading completed;
|
|
- project loading failed.
|
|
|
|
Project loading progress events should carry at least:
|
|
|
|
- the project identity,
|
|
- a typed loading phase,
|
|
- a user-facing status message,
|
|
- and either determinate progress or an explicit indeterminate marker.
|
|
|
|
## Theme and i18n Compatibility
|
|
|
|
Shared Studio UI foundations must preserve:
|
|
|
|
- CSS-based theming;
|
|
- locale-safe user-facing text behavior;
|
|
- safe runtime locale updates where text changes dynamically;
|
|
- no hardcoded user-facing text in reusable Studio controls.
|
|
|
|
Theme and i18n compatibility are admission requirements for shared UI infrastructure.
|
|
|
|
## Foundation Boundary
|
|
|
|
Shared Studio foundations include:
|
|
|
|
- shell-level UI conventions;
|
|
- event publication and observation infrastructure;
|
|
- reusable workspace framework primitives;
|
|
- reusable Studio control conventions.
|
|
|
|
Shared Studio foundations do not, by themselves, define workspace-local feature scope.
|
|
For example, read-only editor behavior, passive placeholder regions, manual-refresh-only navigator behavior, and similar local workspace rules must be closed by workspace-local specifications rather than inferred from this document alone.
|
|
|
|
## Subscription Lifecycle
|
|
|
|
Reusable Studio controls must have an explicit subscription lifecycle when they observe events or external state.
|
|
|
|
Baseline rule:
|
|
|
|
- Studio controls that need event observation should expose subscribe and unsubscribe lifecycle hooks that can be overridden when needed.
|
|
- Studio controls should also expose attach and detach lifecycle hooks for integration with the UI tree.
|
|
- `onAttached()` should trigger subscription setup.
|
|
- `onDetached()` should trigger subscription teardown.
|
|
|
|
This exists to make event wiring visible, testable, and safe under UI lifecycle changes.
|
|
|
|
The exact base class or interface shape is an implementation concern, but the lifecycle itself is normative.
|
|
|
|
## Canonical Workspace Framework
|
|
|
|
The Studio workspace model is not just a collection of unrelated screens.
|
|
|
|
Baseline workspace-framework rules are:
|
|
|
|
- a workspace should be built as a composition root plus lifecycle-managed child controls;
|
|
- child controls should subscribe only to the workspace events or external state they actually consume;
|
|
- local UI changes should be propagated through typed events and targeted patches where identity is preserved;
|
|
- structural synchronization should be explicit and separate from local patch propagation;
|
|
- whole-workspace refresh is a structural recovery path, not the default routine interaction path.
|
|
|
|
The baseline reusable workspace framework should cover at least:
|
|
|
|
- composition-root conventions;
|
|
- lifecycle-managed event-subscriber controls;
|
|
- projection-host patterns for list/tree/detail surfaces;
|
|
- local-patch versus structural-sync orchestration rules.
|
|
|
|
When a workspace first wave is intentionally passive or read-only, that workspace may still consume the framework without forcing a premature event or mutation contract.
|
|
|
|
The first concrete proving ground for this framework may be a single workspace, but the resulting framework is normative for future Studio workspace implementation.
|
|
|
|
Shared Studio foundations do not include:
|
|
|
|
- domain-specific workspace business logic;
|
|
- speculative control catalogs;
|
|
- unrelated non-visual infrastructure that does not directly serve Studio UI.
|
|
|
|
## Non-Goals
|
|
|
|
- defining the full event catalog in advance
|
|
- defining every future workspace interaction
|
|
- defining the first concrete control implementation wave in detail
|
|
- allowing each workspace to define its own incompatible event/lifecycle model
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- naming rules are stable enough to guide new Studio code;
|
|
- the event topology is explicit;
|
|
- the lifecycle and workspace-framework rules are explicit;
|
|
- theme and i18n constraints are unambiguous for shared Studio UI work.
|