Core UI Components

Core UI Components in the RoundingWell frontend are encapsulated, terminal objects designed to handle specific state logic, views, and templates. These components are primarily built using Marionette.Toolkit, which provides a Component class for creating generic widgets such as datepickers, picklists, and tooltips.

Components are designed to be highly configurable rather than extensible. They often serve as wrappers for third-party widgets or jQuery plugins, providing a consistent API by controlling a region, a view, and an attached state model. This architecture ensures that complex UI elements remain isolated from the broader application logic while maintaining internal state consistency.

Sources: src/js/components/README.md, README.md:104-106

Component Architecture and Lifecycle

The project utilizes Marionette.Toolkit to manage component lifecycles. A component typically manages a specific DOM region and synchronizes its view with a state model. For more complex application logic, the project uses Toolkit.App, which follows a specific pattern for rendering and attaching views.

Application Initialization Flow

The standard pattern for initializing views within an application context involves three distinct steps: setView (preparing the layout), showChildView (populating regions), and showView (final rendering).

The diagram above illustrates the sequence of preparing and displaying views within a Marionette Toolkit application.
Sources: README.md:92-102, src/js/README.md:46-47

Implementation Guidelines

• UI Hash: Views must utilize the ui hash to reference DOM elements rather than querying the global jQuery selector.
• State Management: State should be stored on a dedicated state model rather than appending properties directly to view instances.
• DOM Scoping: Views are restricted to managing the DOM inside their own templates; they must not reach into external DOM structures.
• Event Naming: Triggers and events follow a verb:subject or context:verb:subject convention (e.g., click:button2, state:change:foo).

Sources: src/js/README.md:46-55, README.md:189-216

UI Component Types

UI elements are categorized based on their complexity and reuse across the application.

Sidebar Component Structure

Sidebars are sophisticated components that utilize Marionette Regions to nest multiple sub-views. For example, the FlowSidebar manages separate regions for names, details, state, and activity logs.

The diagram represents the hierarchical structure of a standard entity sidebar, where a parent SidebarView manages multiple specialized child views via regions.
Sources: src/js/views/patients/sidebar/flow/flow-sidebar_views.js:90-101, src/js/views/programs/sidebar/flow/flow-sidebar_views.js:161-172

Design and Styling Standards

The project follows the BEM (Block, Element, Modifier) format for SASS to ensure style isolation.

CSS Selector Conventions

• JavaScript Hooks: Selectors intended for JS logic must use the .js- prefix (e.g., .js-submit). These should never be styled directly.
• State Selectors: Selectors like .is-active or .has-error are shared between SASS and JS/Handlebars.
• Component Styling: SASS files are imported directly into the JS module that uses the corresponding view or template to build a clear dependency tree.

Sources: src/scss/README.md:7-40, src/js/views/README.md:20-25

HTML Attribute Ordering

To maintain readability, HTML attributes in templates follow a strict order:

1. class
2. id, name
3. src, for, type, href, value
4. title, alt
5. role, aria-*
6. boolean values

Sources: src/js/views/README.md:65-75

Internationalization (i18n)

Components utilize formatjs and handlebars-intl for localized strings. Translation keys follow a hierarchical naming strategy: view.directory.fileViews.viewName.stringContextName.

i18n Data Flow

This diagram shows how localized strings are retrieved from the YAML definitions and injected into the Marionette View's rendering context.
Sources: src/js/i18n/README.md:6-15, src/js/i18n/en-US.yml

Technical Summary

Core UI Components provide the building blocks for the RoundingWell frontend by enforcing strict separation between DOM manipulation, state management, and styling. By utilizing Marionette Toolkit's component architecture, the system ensures that complex widgets remain terminal and predictable, while the standardized use of i18n and BEM SASS maintains consistency across the platform.

Sources: README.md:104-110, src/js/components/README.md