@portfoliablejs/valence 0.1.0

package/src/stories/molecules/VideoControls/VideoControls.Architecture.mdx

@@ -0,0 +1,260 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/Video Controls [v1.0.0]/Architecture" />
+
+# `ds-video-controls`
+
+The `ds-video-controls` component is an interactive **controlled** Molecule designed to render quality, highly accessible playback buttons for floating, compact overlay video systems. It aggregates custom `ds-button` Atoms (configured as `variant="floating"` and `icon-variant="fill"` switches) and nested `ds-tooltip` cues.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component strictly adheres to the **State In / Events Out** pattern:
+* **State In (Attributes / Properties):** The host binds attributes (`playing`, `muted`, `cc-enabled`, `speed`, `label-*`) downstream to swap control icons, toggle active highlighting, and configure translations.
+* **Events Out (`ds-video-action`):** Selecting any control switch fires a unified custom event payload indicating the selected action name (`'play-pause'`, `'mute'`, `'cc'`, `'speed'`, or `'stop'`) upstream for video state management.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host Application / App Shell"]
+          direction TB
+          State["State Manager / Component Host"]
+      end
+
+      subgraph WebComp["ds-video-controls (Shadow DOM Composition)"]
+          Component["ds-video-controls"]
+          CcBtn["ds-button (CC)"]
+          MuteBtn["ds-button (Mute)"]
+          SpeedBtn["ds-button (Speed)"]
+          PlayBtn["ds-button (Play)"]
+          StopBtn["ds-button (Stop)"]
+      end
+
+      State -->|"1. State In: playing / muted / cc-enabled / speed / labels"| Component
+      Component -->|"2. Render Icons"| CcBtn
+      Component -->|"2. Render Icons"| MuteBtn
+      Component -->|"2. Render Icons"| SpeedBtn
+      Component -->|"2. Render Icons"| PlayBtn
+      Component -->|"2. Render Icons"| StopBtn
+      
+      CcBtn -->|"3. Event Out: ds-video-action { action: 'cc' }"| State
+      MuteBtn -->|"3. Event Out: ds-video-action { action: 'mute' }"| State
+      SpeedBtn -->|"3. Event Out: ds-video-action { action: 'speed' }"| State
+      PlayBtn -->|"3. Event Out: ds-video-action { action: 'play-pause' }"| State
+      StopBtn -->|"3. Event Out: ds-video-action { action: 'stop' }"| State
+
+      %% Styling
+      style Host fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
+      style WebComp fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+      style State fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style Component fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+      style CcBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style MuteBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style SpeedBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style PlayBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style StopBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+`} />
+
+---
+
+## Slot Architecture
+
+The `ds-video-controls` component seals its internal layouts completely, nesting all button and tooltip structures directly within its Shadow DOM boundaries. No public slot targets are exposed.
+
+### Slot Hierarchy Table
+
+<table>
+  <thead>
+    <tr>
+      <th>Slot Name</th>
+      <th>Type / Allowed Children</th>
+      <th>Description</th>
+      <th>Fallback Behavior</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`default`</td>
+      <td>None</td>
+      <td>Projects no content. Control buttons are fully encapsulated.</td>
+      <td>Renders standard captions, mute, speed, play, and return buttons.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Data Model
+
+```typescript
+export interface DsVideoControlsState {
+  playing: boolean;
+  muted: boolean;
+  ccEnabled: boolean;
+  speed: '0.75X' | '1X' | '1.25X' | '1.5X' | '1.75X' | '2X';
+}
+
+export interface DsVideoControlsLabels {
+  'label-play'?: string;
+  'label-pause'?: string;
+  'label-cc-on'?: string;
+  'label-cc-off'?: string;
+  'label-mute'?: string;
+  'label-unmute'?: string;
+  'label-speed'?: string;
+  'label-return'?: string;
+}
+```
+
+---
+
+## API Contract
+
+### Properties & Attributes
+
+<table>
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Attribute</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`playing`</td>
+      <td>`playing`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Sets play/pause visualization state.</td>
+    </tr>
+    <tr>
+      <td>`muted`</td>
+      <td>`muted`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Sets active volume mute visualization state.</td>
+    </tr>
+    <tr>
+      <td>`ccEnabled`</td>
+      <td>`cc-enabled`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Sets active captions (CC) highlighting visualization state.</td>
+    </tr>
+    <tr>
+      <td>`speed`</td>
+      <td>`speed`</td>
+      <td>`string`</td>
+      <td>`'1X'`</td>
+      <td>Configures active speed rate gauge (`'0.75X'`, `'1X'`, etc.).</td>
+    </tr>
+  </tbody>
+</table>
+
+### Emitted Custom Events
+
+<table>
+  <thead>
+    <tr>
+      <th>Event Name</th>
+      <th>Bubbles / Composed</th>
+      <th>Detail Payload</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`ds-video-action`</td>
+      <td>`true` / `true`</td>
+      <td>`{ action: DsVideoControlsAction }`</td>
+      <td>Dispatched when users select any button trigger on the toolbar, passing action keywords upstream.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sub-Atomic CSS Custom Property Hooks
+
+This composite molecule overrides sub-atomic properties on child `ds-button` elements to ensure unified sizes:
+* `ds-button`: Overridden to use `variant="floating"` and `icon-variant="fill"` to guarantee round, compact clickable targets.
+
+Additional mobile-responsive layout custom overrides:
+
+<table>
+  <thead>
+    <tr>
+      <th>CSS Custom Property</th>
+      <th>Fallback Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`--ds-video-controls-bg`</td>
+      <td>`var(--color-player-bg)`</td>
+      <td>Overrides background color on mobile views.</td>
+    </tr>
+    <tr>
+      <td>`--ds-video-controls-border-width`</td>
+      <td>`var(--border-width-thin)`</td>
+      <td>Overrides container border thickness on mobile views.</td>
+    </tr>
+    <tr>
+      <td>`--ds-video-controls-border-color`</td>
+      <td>`var(--color-bg)`</td>
+      <td>Overrides container border line color on mobile views.</td>
+    </tr>
+    <tr>
+      <td>`--ds-video-controls-radius`</td>
+      <td>`50px`</td>
+      <td>Overrides container border corner rounding on mobile views.</td>
+    </tr>
+    <tr>
+      <td>`--ds-video-controls-shadow`</td>
+      <td>`0 10px 30px rgba(0,0,0,0.15)`</td>
+      <td>Overrides container drop shadows.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Button Delegation:** Replaces legacy markup with compliant `<ds-button>` wrappers, enabling native keyboard focus loops, hover scaling, and keyboard triggers.
+* **Screen Reader Isolation:** Employs nested tooltip descriptions with keyboard shortcuts (`show-kbd="true"` and `kbd-label`). Screen readers are instructed to ignore background decorative graphics.
+* **Zero i18n Localization:** Supports complete multi-language overrides by exposing custom `label-[control]` attributes (e.g., `label-play`, `label-cc-on`) directly.
+* **Global Access Syncing:** MutationObserver on document roots reflects global setting cascades downstream as host element boolean flags:
+  * `.a11y-dark-mode`: Swaps container background to matching dark player HUD tokens.
+  * `.a11y-high-contrast`: Enforces strict AAA monochrome borders and outlines.
+  * `.a11y-dyslexia`: Adjusts tooltip typeface families.
+  * `.a11y-reduce-motion`: Disables hovering scale transitions.
+  * `.a11y-forced-colors`: Employs active Windows system color maps.
+
+---
+
+## Examples
+
+### Basic Integration Example
+
+```javascript
+import 'valence/ds-video-controls';
+
+const controls = document.createElement('ds-video-controls');
+controls.setAttribute('playing', 'true');
+controls.setAttribute('cc-enabled', 'true');
+controls.setAttribute('speed', '1.5X');
+
+// Customized translations
+controls.setAttribute('label-play', 'Iniciar');
+controls.setAttribute('label-pause', 'Pausar');
+
+controls.addEventListener('ds-video-action', (e) => {
+  console.log('Action selected:', e.detail.action);
+});
+
+document.body.appendChild(controls);
+```

package/src/stories/molecules/VideoControls/VideoControls.Changelog.mdx

@@ -0,0 +1,72 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/Video Controls [v1.0.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-20
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational video player control bar molecule (`ds-video-controls`) featuring custom floating button integrations, customizable speed rates, and full localization support.
+
+<br />
+
+### Summary of Changes
+
+<table>
+  <thead>
+    <tr>
+      <th>Classification</th>
+      <th>Scope / Context</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-video-controls`</td>
+      <td>Initial stable release of the video player controls region molecule.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-video-controls`</td>
+      <td>Fully refactored the layout markup to consume standard `<ds-button variant="floating">` atoms instead of legacy raw buttons with custom inline SVGs.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-video-controls`</td>
+      <td>Exposed observable attributes `label-play`, `label-cc-on`, etc., to allow translations inside tooltips and aria tags, adhering to the "Zero i18n" standard.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`_observeRootAccessibility`</td>
+      <td>Configured passive root observer syncing dark mode, high contrast, dyslexia, reduce-motion, and Windows Forced Colors.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`video-controls.css`</td>
+      <td>Purged all legacy button, typography, and SVG CSS rules, delegating focus rings and hover scale parameters into child design system primitives.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Interactive Control Molecule:** Created `<ds-video-controls>` aggregating custom button and tooltip atoms.
+- **Dumb Component Conformance:** Released of localized attribute translations for play, mute, speed, captions, and stop options.
+- **Root Context Synchronization:** MutationObserver on document roots reflects global setting cascades downstream as host element boolean flags.
+- **Thematic Overrides:** Bound mobile backdrop backgrounds, outlines, and drop shadows to `--ds-video-controls-*` properties.
+- **Storybook Workspace:** Configured complete interactive Controls and detailed CSF3 stories inside `VideoControls.stories.js`.
+
+### Fixed
+- **Style Purging:** Deleted all legacy layout, SVG, and typography CSS, allowing children to inherit design variables effortlessly.
+
+---
+
+*This changelog is specific to the `<ds-video-controls>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/molecules/VideoControls/VideoControls.js

@@ -0,0 +1,157 @@
+import css from './video-controls.css?inline';
+import '../../molecules/Tooltip/Tooltip';
+import '../../atoms/Button/Button.js';
+import '../../atoms/Icon/Iconography.js';
+
+export class VideoControls extends HTMLElement {
+  static get observedAttributes() {
+    return [
+      'playing', 'muted', 'cc-enabled', 'speed',
+      'label-play', 'label-pause', 'label-cc-on', 'label-cc-off',
+      'label-mute', 'label-unmute', 'label-speed', 'label-return'
+    ];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    
+    // Tightly compressed single line structure completely purges ghost spacing nodes from layouts
+    this.shadowRoot.innerHTML = `<style>${css}</style><div class="video-controls-container"><div class="tooltip-wrapper"><ds-button variant="floating" has-text="false" has-icon icon-variant="fill" id="btn-cc" icon="subtitle-closed" aria-label="Toggle Captions"></ds-button><ds-tooltip class="cc-tooltip" text="Captions" kbd-label="C" show-kbd="true" position="right"></ds-tooltip></div><div class="tooltip-wrapper"><ds-button variant="floating" has-text="false" has-icon icon-variant="fill" id="btn-mute" icon="volume-on" aria-label="Toggle Mute"></ds-button><ds-tooltip class="mute-tooltip" text="Mute" kbd-label="M" show-kbd="true" position="right"></ds-tooltip></div><div class="tooltip-wrapper"><ds-button variant="floating" has-text="false" has-icon icon-variant="fill" id="btn-speed" icon="playback-1x" aria-label="Playback Speed"></ds-button><ds-tooltip class="speed-tooltip" text="Speed" kbd-label="S" show-kbd="true" position="right"></ds-tooltip></div><div class="tooltip-wrapper"><ds-button variant="floating" has-text="false" has-icon icon-variant="fill" id="btn-play" icon="play" aria-label="Play or Pause"></ds-button><ds-tooltip class="play-tooltip" text="Play" kbd-label="Space" show-kbd="true" position="right"></ds-tooltip></div><div class="tooltip-wrapper"><ds-button variant="floating" has-text="false" has-icon icon-variant="fill" id="btn-stop" icon="arrow-left" aria-label="Return to Case"></ds-button><ds-tooltip class="stop-tooltip" text="Return" kbd-label="Esc" show-kbd="true" position="right"></ds-tooltip></div></div>`;
+
+    this.bindEvents();
+  }
+
+  connectedCallback() {
+    this._observeRootAccessibility();
+    this.render();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue !== newValue) {
+      this.render();
+    }
+  }
+
+  disconnectedCallback() {
+    if (this._themeObserver) {
+      this._themeObserver.disconnect();
+    }
+  }
+
+  bindEvents() {
+    const dispatch = (action) => {
+      this.dispatchEvent(new CustomEvent('ds-video-action', { 
+        detail: { action }, 
+        bubbles: true, 
+        composed: true 
+      }));
+    };
+
+    this.shadowRoot.getElementById('btn-cc').addEventListener('click', () => dispatch('cc'));
+    this.shadowRoot.getElementById('btn-mute').addEventListener('click', () => dispatch('mute'));
+    this.shadowRoot.getElementById('btn-speed').addEventListener('click', () => dispatch('speed'));
+    this.shadowRoot.getElementById('btn-play').addEventListener('click', () => dispatch('play-pause'));
+    this.shadowRoot.getElementById('btn-stop').addEventListener('click', () => dispatch('stop'));
+  }
+
+  _getSpeedIcon(speed) {
+    const normalized = String(speed).toLowerCase().replace('x', '').replace('.', '-');
+    const iconName = `playback-${normalized}x`;
+    const validIcons = ['playback-0-75x', 'playback-1x', 'playback-1-25x', 'playback-1-5x', 'playback-1-75x', 'playback-2x'];
+    return validIcons.includes(iconName) ? iconName : 'playback-1x';
+  }
+
+  _observeRootAccessibility() {
+    const root = this.ownerDocument.documentElement;
+    const sync = () => {
+      this.toggleAttribute('a11y-dark-mode', root.classList.contains('a11y-dark-mode'));
+      this.toggleAttribute('a11y-high-contrast', root.classList.contains('a11y-high-contrast'));
+      this.toggleAttribute('a11y-large-text', root.classList.contains('a11y-large-text'));
+      this.toggleAttribute('a11y-dyslexia', root.classList.contains('a11y-dyslexia'));
+      this.toggleAttribute('a11y-reduce-motion', root.classList.contains('a11y-reduce-motion'));
+      this.toggleAttribute('a11y-focus-mode', root.classList.contains('a11y-focus-mode'));
+      this.toggleAttribute('a11y-forced-colors', root.classList.contains('a11y-forced-colors'));
+    };
+
+    sync();
+    this._themeObserver = new MutationObserver(sync);
+    this._themeObserver.observe(root, { attributes: true, attributeFilter: ['class'] });
+  }
+
+  render() {
+    const isPlaying = this.getAttribute('playing') === 'true';
+    const isMuted = this.getAttribute('muted') === 'true';
+    const isCC = this.getAttribute('cc-enabled') === 'true';
+    const speed = this.getAttribute('speed') || '1X';
+
+    // Ingest multi-locale translation bindings
+    const labelPlay = this.getAttribute('label-play') || 'Play';
+    const labelPause = this.getAttribute('label-pause') || 'Pause';
+    const labelCcOn = this.getAttribute('label-cc-on') || 'Captions On';
+    const labelCcOff = this.getAttribute('label-cc-off') || 'Captions';
+    const labelMute = this.getAttribute('label-mute') || 'Mute';
+    const labelUnmute = this.getAttribute('label-unmute') || 'Unmute';
+    const labelSpeed = this.getAttribute('label-speed') || 'Speed';
+    const labelReturn = this.getAttribute('label-return') || 'Return';
+
+    // Playback Toggle Element Allocation
+    const playBtn = this.shadowRoot.getElementById('btn-play');
+    const playTooltip = this.shadowRoot.querySelector('.play-tooltip');
+    if (playBtn) {
+      playBtn.setAttribute('icon', isPlaying ? 'pause' : 'play');
+      playBtn.setAttribute('aria-label', isPlaying ? labelPause : labelPlay);
+    }
+    if (playTooltip) {
+      playTooltip.setAttribute('text', isPlaying ? labelPause : labelPlay);
+    }
+
+    // Audio Control Element Allocation
+    const muteBtn = this.shadowRoot.getElementById('btn-mute');
+    const muteTooltip = this.shadowRoot.querySelector('.mute-tooltip');
+    if (muteBtn) {
+      muteBtn.setAttribute('icon', isMuted ? 'volume-mute' : 'volume-on');
+      muteBtn.setAttribute('aria-label', isMuted ? labelUnmute : labelMute);
+    }
+    if (muteTooltip) {
+      muteTooltip.setAttribute('text', isMuted ? labelUnmute : labelMute);
+    }
+
+    // Subtitle / Closed Caption Element Allocation
+    const ccBtn = this.shadowRoot.getElementById('btn-cc');
+    const ccTooltip = this.shadowRoot.querySelector('.cc-tooltip');
+    if (ccBtn) {
+      ccBtn.setAttribute('icon', isCC ? 'subtitle-on' : 'subtitle-closed');
+      ccBtn.setAttribute('aria-label', isCC ? labelCcOn : labelCcOff);
+    }
+    if (ccTooltip) {
+      ccTooltip.setAttribute('text', isCC ? labelCcOn : labelCcOff);
+    }
+
+    // Playback Rate Gauge Element Allocation
+    const speedBtn = this.shadowRoot.getElementById('btn-speed');
+    const speedTooltip = this.shadowRoot.querySelector('.speed-tooltip');
+    if (speedBtn) {
+      speedBtn.setAttribute('icon', this._getSpeedIcon(speed));
+      speedBtn.setAttribute('aria-label', `${labelSpeed} ${speed}`);
+    }
+    if (speedTooltip) {
+      speedTooltip.setAttribute('text', `${labelSpeed} (${speed})`);
+    }
+
+    // Termination / Return Navigation Element Allocation
+    const stopBtn = this.shadowRoot.getElementById('btn-stop');
+    const stopTooltip = this.shadowRoot.querySelector('.stop-tooltip');
+    if (stopBtn) {
+      stopBtn.setAttribute('icon', 'arrow-left');
+      stopBtn.setAttribute('aria-label', labelReturn);
+    }
+    if (stopTooltip) {
+      stopTooltip.setAttribute('text', labelReturn);
+    }
+  }
+}
+
+if (!customElements.get('ds-video-controls')) {
+  customElements.define('ds-video-controls', VideoControls);
+}