Files

undergroundwires bc91237d7c Refactor usage of tooltips for flexibility

This commit introduces a new Vue component to handle tooltips. It acts
as a wrapper for the `v-tooltip`. It enhances the maintainability,
readability and portability of tooltips by enabling the direct inclusion
of inline HTML in the tooltip components. It solves issues such as
absence of linting or editor support and cumbersome string
concatenation.

It also provides an abstraction layer that simplifies the switching
between different tooltip implementations, which would allow a smooth
migration to Vue 3 (see #230).

2023-08-12 16:53:58 +02:00

7.2 KiB

Raw Blame History

Presentation layer

The presentation layer handles UI concerns using Vue as JavaScript framework and Electron to provide desktop functionality.

It reflects the application state and allows user interactions to modify it. Components manage their own local UI state.

The presentation layer uses an event-driven architecture for bidirectional reactivity between the application state and UI. State change events flow bottom-up to trigger UI updates, while user events flow top-down through components, some ultimately modifying the application state.

📖 Refer to architecture.md (Layered Application) to read more about the layered architecture.

Structure

/src/ presentation/: Contains all presentation related code including Vue and Electron configurations
- bootstrapping/: Registers Vue global objects including components and plugins.
- components/: Contains all Vue components and their helper classes.
  - Shared/: Contains Vue components and component helpers that other components share.
    - hooks: Shared hooks for state access
- assets/: Contains assets that webpack will process.
  - fonts/: Contains fonts
  - styles/: Contains shared styles used throughout different components.
    - components/: Contains reusable styles coupled to a Vue/HTML component.
    - vendors-extensions/: Contains styles that override third-party components used.
    - main.scss: Primary Sass file, passes along all other styles, should be the single file used from other components.
- main.ts: Application entry point that mounts and starts Vue application.
- electron/: Electron configuration for the desktop application.
  - main.ts: Main process of Electron, started as first thing when app starts.
/public/: Contains static assets that are directly copied and do not go through webpack.
/vue.config.js: Global Vue CLI configurations loaded by @vue/cli-service.
/postcss.config.js: PostCSS configurations used by Vue CLI internally.
/babel.config.js: Babel configurations for polyfills used by @vue/cli-plugin-babel.

Visual design best-practices

Add visual clues for clickable items. It should be as clear as possible that they're interactable at first look without hovering. They should also have different visual state when hovering/touching on them that indicates that they are being clicked, which helps with accessibility.

Application data

Components (should) use UseApplication to reach the application domain to avoid parsing and compiling the application again.

Application.ts is an immutable domain model that represents application state. It includes:

available scripts, collections as defined in collection files,
package information as defined in package.json.

You can read more about how application layer provides application data to he presentation in application.md | Application data.

Application state

This project uses a singleton instance of the application state, making it available to all Vue components.

The decision to not use third-party state management libraries like vuex or pinia was made to promote code independence and enhance portability.

Stateful components can mutate and/or react to state changes (e.g., user selection, search queries) in the ApplicationContext. Vue components import CollectionState.ts to access both the application context and the state.

UseCollectionState.ts provides several functionalities including:

Singleton State Instance: It creates a singleton instance of the state, which is shared across the presentation layer. The singleton instance ensures that there's a single source of truth for the application's state.
State Change Callback and Lifecycle Management: It offers a mechanism to register callbacks, which will be invoked when the state initializes or mutates. It ensures that components unsubscribe from state events when they are no longer in use or when ApplicationContext switches the active collection.
State Access and Modification: It provides functions to read and mutate for accessing and modifying the state, encapsulating the details of these operations.
Event Subscription Lifecycle Management: Includes an events member that simplifies state subscription lifecycle events. This ensures that components unsubscribe from state events when they are no longer in use, or when ApplicationContext switches the active collection.

📖 Refer to architecture.md | Application State for an overview of event handling and application.md | Application State for an in-depth understanding of state management in the application layer.

Shared UI components

Shared UI components promote consistency and simplifies the creation of the front-end.

In order to maintain portability and easy maintainability, the preference is towards using homegrown components over third-party ones or comprehensive UI frameworks like Quasar.

Shared components include:

ModalDialog.vue is utilized for rendering modal windows.
TooltipWrapper.vue acts as a wrapper for rendering tooltips.

Sass naming convention

Use lowercase for variables/functions/mixins, e.g.:
- Variable: $variable: value;
- Function: @function function() {}
- Mixin: @mixin mixin() {}
Use - for a phrase/compound word, e.g.:
- Variable: $some-variable: value;
- Function: @function some-function() {}
- Mixin: @mixin some-mixin() {}
Grouping and name variables from generic to specific, e.g.:
- ✅ $border-blue, $border-blue-light, $border-blue-lightest, $border-red
- ❌ $blue-border, $light-blue-border, $lightest-blue-border, $red-border

7.2 KiB Raw Blame History