From: Jérôme Benoit <jerome.benoit@sap.com>
Date: Thu, 30 Apr 2026 09:23:57 +0000 (+0200)
Subject: docs(ui-web): fix 6 stale comments after refactoring
X-Git-Url: https://git.piment-noir.org/?a=commitdiff_plain;h=b67eb66c74fd75939a372e2b1994c55a1e1a1123;p=e-mobility-charging-stations-simulator.git

docs(ui-web): fix 6 stale comments after refactoring
---

diff --git a/ui/web/src/shared/composables/useAsyncAction.ts b/ui/web/src/shared/composables/useAsyncAction.ts
index 1b40bb1b..12398a49 100644
--- a/ui/web/src/shared/composables/useAsyncAction.ts
+++ b/ui/web/src/shared/composables/useAsyncAction.ts
@@ -9,7 +9,7 @@ import { useToast } from 'vue-toast-notification'
  * Creates a reactive pending-state map and a run() helper for async actions with toast notifications.
  *
  * Encapsulates the pending-key guard, toast feedback, and error logging pattern
- * shared by modern skin components.
+ * shared across layout composables.
  * @param initialPending - Object defining the pending keys (e.g. `{ connection: false, startStop: false }`)
  * @param onRefresh - Called after each successful action (e.g. `() => emit('need-refresh')`)
  * @returns `{ pending, run }` — reactive pending map and action executor
diff --git a/ui/web/src/shared/composables/useConnectorActions.ts b/ui/web/src/shared/composables/useConnectorActions.ts
index ccf8ffce..64570b93 100644
--- a/ui/web/src/shared/composables/useConnectorActions.ts
+++ b/ui/web/src/shared/composables/useConnectorActions.ts
@@ -62,6 +62,7 @@ export function useConnectorActions (deps: ConnectorActionsDeps): {
   }
 
   const lockConnector = (): void => {
+    // 'lock' key is shared by lockConnector and unlockConnector
     run('lock', {
       action: () => $uiClient.lockConnector(hashId.value, connectorId.value),
       errorMsg: 'Error locking connector',
diff --git a/ui/web/src/shared/composables/useLayoutData.ts b/ui/web/src/shared/composables/useLayoutData.ts
index f2df9c70..dca3b8a7 100644
--- a/ui/web/src/shared/composables/useLayoutData.ts
+++ b/ui/web/src/shared/composables/useLayoutData.ts
@@ -40,7 +40,8 @@ export interface LayoutData {
 /**
  * Extracts the common data-fetching and WebSocket lifecycle logic shared by layout components.
  *
- * Registers `onMounted` / `onUnmounted` hooks internally so consumers do not need to.
+ * Registers `onMounted` / `onUnmounted` hooks internally. Also exposes
+ * `registerWSEventListeners` / `unregisterWSEventListeners` for manual lifecycle management.
  * @returns Layout data state and control functions
  */
 export function useLayoutData (): LayoutData {
diff --git a/ui/web/src/shared/composables/useSkin.ts b/ui/web/src/shared/composables/useSkin.ts
index 000ecad3..0d8a9f0d 100644
--- a/ui/web/src/shared/composables/useSkin.ts
+++ b/ui/web/src/shared/composables/useSkin.ts
@@ -30,7 +30,7 @@ const activeSkinId: Ref<SkinName> = ref(
     return isValidSkin(stored) ? stored : DEFAULT_SKIN
   })()
 )
-// JS/testing hook — no CSS uses [data-skin]; skin isolation is via component class scoping.
+// Sets data-skin on document root for CSS scoping (used by modern skin) and JS/testing hooks.
 if (typeof document !== 'undefined') {
   document.documentElement.setAttribute('data-skin', activeSkinId.value)
 }
diff --git a/ui/web/src/shared/tokens/contract.ts b/ui/web/src/shared/tokens/contract.ts
index 822e4561..b0f5f426 100644
--- a/ui/web/src/shared/tokens/contract.ts
+++ b/ui/web/src/shared/tokens/contract.ts
@@ -1,8 +1,8 @@
 /**
  * CSS token contract.
  *
- * Typography and spacing tokens are provided by `base.css` (shared across all themes).
- * Color tokens (`color-*`) and `color-scheme` must be defined per theme file.
+ * Typography and spacing tokens have defaults in `base.css` and may be overridden per theme.
+ * Color tokens (`color-*`) have no defaults and MUST be defined per theme file.
  * When adding a new theme, ensure all `color-*` tokens below are defined in your theme CSS.
  *
  * Every theme file MUST define a value for each token (as `--{token-name}`).
diff --git a/ui/web/src/skins/modern/modern.css b/ui/web/src/skins/modern/modern.css
index 7fa6eb6f..0e548d7e 100644
--- a/ui/web/src/skins/modern/modern.css
+++ b/ui/web/src/skins/modern/modern.css
@@ -1,7 +1,7 @@
 /* Modern skin styles.
  *
  * Flat, modern design with Material-inspired structural patterns.
- * - Teal primary (Material 500/400) + Green / Amber / Red state colours
+ * - Primary and state colours driven by the active theme contract
  * - Onest across the UI; mono only for the supervision URL itself
  * - Elevation tiers: base < card body < raised (header/modal) + sunken inserts
  * - Hovers only touch colour / shadow, never layout
diff --git a/ui/web/src/skins/registry.ts b/ui/web/src/skins/registry.ts
index ee36d433..032a6f83 100644
--- a/ui/web/src/skins/registry.ts
+++ b/ui/web/src/skins/registry.ts
@@ -4,8 +4,8 @@
  * Single source of truth for available skins.
  * Each skin carries metadata and a lazy CSS loader for code splitting.
  *
- * Convention: All skin CSS MUST scope rules to `html[data-skin='<id>']` to prevent
- * style bleeding when multiple skin stylesheets are loaded in the DOM simultaneously.
+ * Convention: Skin CSS should scope structural rules to `html[data-skin='<id>']` or use
+ * component-scoped class prefixes (e.g. `.classic-*`, `.modern-*`) to prevent style bleeding.
  */
 
 import type { Component } from 'vue'