discussion framework migration
This commit is contained in:
@@ -0,0 +1,191 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user