@portfoliablejs/valence 0.1.0

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

@@ -0,0 +1,214 @@
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { fn, userEvent, fireEvent, expect } from 'storybook/test';
+import './VideoControls';
+
+export default {
+  title: 'Molecules/Video Controls [v1.0.0]',
+  tags: ['autodocs'],
+  parameters: {
+    backgrounds: { default: 'dark' },
+    docs: {
+      description: {
+        component: 'The `ds-video-controls` component aggregates an overlay configuration layout block of circular buttons and tooltip notifications designed explicitly to handle playback coordination on compact canvas media surfaces.',
+      }
+    }
+  },
+  argTypes: {
+    // --- CORE & VARIANT CONTROLS ---
+    playing: { 
+      control: 'boolean',
+      description: 'Sets the play/pause visualization state downstream.',
+      table: { category: 'Core & Variant Controls' }
+    },
+    muted: { 
+      control: 'boolean',
+      description: 'Configures active volume mute visualization.',
+      table: { category: 'Core & Variant Controls' }
+    },
+    ccEnabled: { 
+      name: 'cc-enabled',
+      control: 'boolean',
+      description: 'Toggles active highlighting for text overlays.',
+      table: { category: 'Core & Variant Controls' }
+    },
+    speed: { 
+      control: 'text',
+      description: 'Sets the active speed rate gauge string.',
+      table: { category: 'Core & Variant Controls' }
+    },
+
+    // --- LOCALIZATION PIPELINE ---
+    labelPlay: {
+      name: 'label-play',
+      control: 'text',
+      description: 'Translation string allocated to the Play button trigger description.',
+      table: { category: 'Localization' },
+    },
+    labelPause: {
+      name: 'label-pause',
+      control: 'text',
+      description: 'Translation string allocated to the Pause button trigger description.',
+      table: { category: 'Localization' },
+    },
+    labelCcOn: {
+      name: 'label-cc-on',
+      control: 'text',
+      description: 'Translation string allocated to captions when active.',
+      table: { category: 'Localization' },
+    },
+    labelCcOff: {
+      name: 'label-cc-off',
+      control: 'text',
+      description: 'Translation string allocated to captions when resting.',
+      table: { category: 'Localization' },
+    },
+    labelMute: {
+      name: 'label-mute',
+      control: 'text',
+      description: 'Translation string applied to the active mute toggle.',
+      table: { category: 'Localization' },
+    },
+    labelUnmute: {
+      name: 'label-unmute',
+      control: 'text',
+      description: 'Translation string applied to the resting unmute toggle.',
+      table: { category: 'Localization' },
+    },
+    labelSpeed: {
+      name: 'label-speed',
+      control: 'text',
+      description: 'Translation string prefix applied to the speed gauge state tracker.',
+      table: { category: 'Localization' },
+    },
+    labelReturn: {
+      name: 'label-return',
+      control: 'text',
+      description: 'Translation string allocated to the navigation escape trigger.',
+      table: { category: 'Localization' },
+    },
+  },
+  args: { onAction: fn() }
+};
+
+// Reusable template for binding data updates inside the render stream
+const baseRenderTemplate = (args) => {
+  const handleAction = (e) => {
+    args.onAction(e.detail.action);
+    const controls = e.target;
+
+    if (e.detail.action === 'play-pause') {
+      const isPlaying = controls.getAttribute('playing') === 'true';
+      controls.setAttribute('playing', (!isPlaying).toString());
+    }
+    if (e.detail.action === 'mute') {
+      const isMuted = controls.getAttribute('muted') === 'true';
+      controls.setAttribute('muted', (!isMuted).toString());
+    }
+    if (e.detail.action === 'cc') {
+      const isCC = controls.getAttribute('cc-enabled') === 'true';
+      controls.setAttribute('cc-enabled', (!isCC).toString());
+    }
+    if (e.detail.action === 'speed') {
+      const currentSpeed = controls.getAttribute('speed') || '1X';
+      const nextSpeed = currentSpeed === '1X' ? '1.5X' : currentSpeed === '1.5X' ? '2X' : '1X';
+      controls.setAttribute('speed', nextSpeed);
+    }
+  };
+
+  return html`
+    <ds-video-controls 
+      playing="${args.playing}"
+      muted="${args.muted}"
+      cc-enabled="${args.ccEnabled}"
+      speed="${args.speed}"
+      label-play="${ifDefined(args.labelPlay)}"
+      label-pause="${ifDefined(args.labelPause)}"
+      label-cc-on="${ifDefined(args.labelCcOn)}"
+      label-cc-off="${ifDefined(args.labelCcOff)}"
+      label-mute="${ifDefined(args.labelMute)}"
+      label-unmute="${ifDefined(args.labelUnmute)}"
+      label-speed="${ifDefined(args.labelSpeed)}"
+      label-return="${ifDefined(args.labelReturn)}"
+      @ds-video-action="${handleAction}">
+    </ds-video-controls>
+  `;
+};
+
+export const Desktop = {
+  args: {
+    playing: false,
+    muted: false,
+    ccEnabled: true,
+    speed: '1X',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default implementation rendering the video toolbar as a vertical floating menu panel block suitable for large desktop application layouts.',
+      }
+    }
+  },
+  render: (args) => html`
+    <div style="display: flex; justify-content: center; align-items: center; height: 25vh;">
+      ${baseRenderTemplate(args)}
+    </div>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const controlsMolecule = canvasElement.querySelector('ds-video-controls');
+    const shadowBoundary = controlsMolecule.shadowRoot;
+    
+    const playBtn = shadowBoundary.getElementById('btn-play');
+    const speedBtn = shadowBoundary.getElementById('btn-speed');
+
+    await step('Verify control buttons use simplified ds-button props contract', async () => {
+      const controlIds = ['btn-cc', 'btn-mute', 'btn-speed', 'btn-play', 'btn-stop'];
+      controlIds.forEach((id) => {
+        const btn = shadowBoundary.getElementById(id);
+        expect(btn.getAttribute('variant')).toBe('floating');
+        expect(btn.getAttribute('has-text')).toBe('false');
+        expect(btn.hasAttribute('has-icon')).toBe(true);
+      });
+    });
+
+    await step('Confirm structural interaction feedback on pointer targets', async () => {
+      await userEvent.hover(playBtn);
+    });
+
+    await step('Verify keyboard tab sequence capture within nested control trees', async () => {
+      playBtn.focus();
+      expect(shadowBoundary.activeElement).toBe(playBtn);
+    });
+
+    await step('Verify standard state switching updates across control actions', async () => {
+      fireEvent.keyDown(playBtn, { key: ' ', code: 'Space', keyCode: 32 });
+      await userEvent.click(playBtn);
+      expect(controlsMolecule.getAttribute('playing')).toBe('true');
+
+      await userEvent.click(speedBtn);
+      expect(controlsMolecule.getAttribute('speed')).toBe('1.5X');
+    });
+  }
+};
+
+export const Mobile = {
+  args: {
+    ...Desktop.args,
+    ccEnabled: false,
+  },
+  parameters: {
+    viewport: {
+      defaultViewport: 'mobile1'
+    },
+    docs: {
+      description: {
+        story: 'Renders the component using Storybook\'s explicit mobile device emulation mode. This shrinks the parent viewport canvas to force trigger the responsive horizontal bar layouts and confirms that contextual tooltips are disabled.',
+      }
+    }
+  },
+  render: (args) => html`
+    <div style="display: flex; justify-content: center; align-items: center; height: 25vh; width: 100%;">
+      ${baseRenderTemplate(args)}
+    </div>
+  `
+};

package/src/stories/molecules/VideoControls/video-controls.css

@@ -0,0 +1,70 @@
+/* Baseline host configurations focus purely on the parent layout shell */
+:host {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-md);
+  border: var(--border-width-thin) var(--border-style-solid) transparent;
+}
+
+/* Responsive Mobile Layout Conformance Block */
+@media (max-width: 768px) {
+  :host {
+    flex-direction: row;
+    background-color: var(--ds-video-controls-bg, var(--color-player-bg));
+    border: var(--ds-video-controls-border-width, var(--border-width-thin)) 
+            var(--border-style-solid) 
+            var(--ds-video-controls-border-color, var(--color-white));
+    border-radius: var(--ds-video-controls-radius, var(--radius-pill));
+    padding: var(--space-sm) var(--space-xl);
+    box-shadow: var(--ds-video-controls-shadow, var(--shadow-lg));
+  }
+
+  /* Suppress tooltip presentation on small viewports to eliminate touch screen tap-to-hover stickiness */
+  ds-tooltip {
+    display: none !important;
+  }
+}
+
+.video-controls-container {
+  display: contents;
+}
+
+.tooltip-wrapper {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Base structural scaling dimensions override for circular child controls */
+ds-button {
+  --ds-button-size: 33px;
+  --ds-button-radius: var(--radius-circle);
+  display: inline-flex;
+}
+
+/* ==========================================================================
+   CONTAINER BAR ACCESSIBILITY (Child controls rely on internal atom CSS rules)
+   ========================================================================= */
+
+/* High Contrast Mode (Container-level AAA framing resets) */
+:host([a11y-high-contrast]) {
+  background-color: #000000 !important;
+  box-shadow: var(--shadow-none) !important;
+  border: var(--border-width-medium) var(--border-style-solid) #FFFFFF !important;
+}
+
+/* Forced Colors Mode (Container-level system keyword mappings) */
+:host([a11y-forced-colors]) {
+  forced-color-adjust: none !important;
+  background-color: Canvas !important;
+  border-color: CanvasText !important;
+}
+
+@media (forced-colors: active) {
+  :host {
+    forced-color-adjust: none !important;
+    background-color: Canvas !important;
+    border-color: CanvasText !important;
+  }
+}

package/src/stories/organisms/Article/Article.Architecture.mdx

@@ -0,0 +1,215 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as ArticleStories from './Article.stories';
+
+<Meta title="Organisms/Article/Architecture" />
+
+# `ds-article`
+
+The `ds-article` component is a **stateless (presentational)** Organism designed to orchestrate the layout logic for long-form reading experiences. It provides rigid bounds and toggleable structural zones for typography, metadata, action buttons, summaries, media players, and floating navigation docks.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow & Layout Management
+The component strictly adheres to the **Unidirectional Data Flow** paradigm:
+* **State In (Attributes & Slots):** The host application binds strings for the header/actions and projects complex Web Components (`ds-summary`, `ds-audio-player`, `ds-case-navigator`) through named `<slot>` channels.
+* **Events Out (`ds-article-*`):** Action buttons and social share icons emit standardized custom events up to the router/shell to handle link routing and native share API triggers.
+* **Typographic Inheritance:** Body copy passed into the default slot relies natively on Light DOM inheritance for `<p>`, `<h3>`, and `<code>` tags mapping directly to global sub-atomic typographic scale definitions.
+
+### Scroll Transition Engine (Thumbnail Retraction)
+The reading layout uses a **continuous progress-driven transition** instead of a binary threshold snap:
+* **Progress Source:** Scroll position is normalized and eased in JavaScript, then written as `--ds-article-thumbnail-progress`.
+* **Smooth Interpolation:** The grid thumbnail column width, inter-column gap, thumbnail opacity/offset, and content column offset are interpolated from that single progress variable.
+* **Bidirectional Consistency:** The same interpolation path is used for scroll-down and scroll-up, so expansion and retraction feel symmetrical.
+* **Body Stability:** Article body children no longer scale/fade during this transition, preventing perceived paragraph "bouncing" while preserving the thumbnail motion effect.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host SPA / App Shell"]
+          direction TB
+          Data["Markdown Parser / Article Data"]
+      end
+
+      subgraph WebComp["Layout Organism"]
+          Article["ds-article"]
+          Summary["slot='summary'"]
+          Body["slot='default'"]
+      end
+
+      Data -->|"1. Map Props & Inject HTML"| Article
+      Article -->|"2. Event Out<br/>ds-article-share"| Host
+
+      %% Styling
+      style Host fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
+      style WebComp fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+      style Data fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style Article fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+`} />
+
+---
+
+## Slot Architecture
+
+The `ds-article` encapsulates its header grid in the Shadow DOM while relying on four distinct slots to map the article body.
+
+### 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>`summary`</td>
+      <td>`ds-summary`</td>
+      <td>Designated projection zone for the case study KPI summary block.</td>
+      <td>Section height collapses if omitted.</td>
+    </tr>
+    <tr>
+      <td>`player`</td>
+      <td>`ds-audio-player`</td>
+      <td>Designated projection zone for the integrated audio reader.</td>
+      <td>Section height collapses if omitted.</td>
+    </tr>
+    <tr>
+      <td>`default`</td>
+      <td>HTML / Markdown Elements</td>
+      <td>Primary reading column for article body text (`<p>`, `<h3>`, `<blockquote>`, `<code>`, `<ul>`). Automatically styled by internal `::slotted()` rules.</td>
+      <td>Empty content zone.</td>
+    </tr>
+    <tr>
+      <td>`navigator`</td>
+      <td>`ds-case-navigator`</td>
+      <td>Projects into a fixed `z-index: 100` container floating at the bottom center of the viewport.</td>
+      <td>Leaves the fixed container empty and invisible.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## API Contract
+
+### Properties & Attributes
+
+<table>
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`kicker`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Super-title category or date stamp (e.g., `2026 • R&D LAB`).</td>
+    </tr>
+    <tr>
+      <td>`title-text`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Main article `H1` title text.</td>
+    </tr>
+    <tr>
+      <td>`primary-label`</td>
+      <td>`string`</td>
+      <td>`'Primary'`</td>
+      <td>Text label for the main action button.</td>
+    </tr>
+    <tr>
+      <td>`primary-icon`</td>
+      <td>`string`</td>
+      <td>`null`</td>
+      <td>Icon rendered inside the primary action button.</td>
+    </tr>
+    <tr>
+      <td>`secondary1-label`</td>
+      <td>`string`</td>
+      <td>`'Secondary'`</td>
+      <td>Text label for the first secondary action button.</td>
+    </tr>
+    <tr>
+      <td>`show-*` flags</td>
+      <td>`boolean`</td>
+      <td>`true`</td>
+      <td>Comprehensive toggles to mount/unmount layout blocks programmatically (`show-social-x`, `show-action-primary`, `show-navigator`, 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-article-action`</td>
+      <td>`true` / `true`</td>
+      <td>`{ action: 'primary' \| 'secondary1' \| 'secondary2' }`</td>
+      <td>Emitted when any of the core header actions are clicked.</td>
+    </tr>
+    <tr>
+      <td>`ds-article-share`</td>
+      <td>`true` / `true`</td>
+      <td>`{ platform: 'native' \| 'linkedin' \| 'x' \| 'facebook' }`</td>
+      <td>Emitted when a social media icon button is clicked next to the title.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sub-Atomic CSS Custom Property Hooks
+
+<table>
+  <thead>
+    <tr>
+      <th>CSS Custom Property</th>
+      <th>Fallback Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`--ds-article-max-width`</td>
+      <td>`var(--size-max-width-md, 768px)`</td>
+      <td>Overrides the centered reading column constraint boundary.</td>
+    </tr>
+    <tr>
+      <td>`--ds-article-title-color`</td>
+      <td>`var(--color-black, #000000)`</td>
+      <td>Overrides the `H1` article title ink color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-article-social-color`</td>
+      <td>`var(--color-gray-med, #777777)`</td>
+      <td>Overrides the default outline color for social sharing icons.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Tooltips & KBD:** Action buttons pair natively with `ds-tooltip` primitives. The primary action tooltip explicitly registers `kbd-label="Enter"` indicating its global keyboard shortcut.
+* **Global Accessibility Propagation:** Listens to class changes on `document.documentElement` via `MutationObserver` to sync accessibility modes:
+  * `.a11y-dark-mode`: Inverts title typography, mutes secondary labels, and adjusts all `::slotted()` Markdown elements (`<blockquote>`, `<pre>`) to dark backgrounds.
+  * `.a11y-high-contrast`: Enforces `#FFFFFF` solid fills and borders on all header text arrays and slotted content.
+  * `.a11y-large-text`: Scales the article title by a 1.25x multiplier.
+  * `.a11y-dyslexia`: Re-renders the entire article structure using the high-legibility font stack.

package/src/stories/organisms/Article/Article.Changelog.mdx

@@ -0,0 +1,45 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Article/Changelog" />
+
+# Changelog
+
+<br />
+
+## [Unreleased] - 2026-07-23
+
+<br />
+
+### Changed
+- **Scroll Transition Model:** Reworked the thumbnail retraction interaction from a binary threshold/class toggle into a smooth, progress-driven scroll transition. Thumbnail width, opacity, position, and layout gap now interpolate continuously for both scroll-down and scroll-up.
+- **Transition Feel:** Introduced eased progress updates to make the retraction/expansion motion read as a single fluid interaction rather than a snap between open/retracted states.
+
+### Fixed
+- **Body Content Bounce:** Removed scroll-linked transform/opacity effects from article body children so paragraph and content items no longer appear to bounce while the thumbnail retracts/returns.
+
+<br />
+
+## [1.0.0] - 2026-07-21
+
+<br />
+
+### Initial Release
+
+The stable debut of the `ds-article` layout organism. This component standardizes the presentation shell for long-form case studies, integrating headers, granular sharing mechanics, AI summaries, audio readers, bottom case navigators, and parsed markdown body content into a single unified DOM block.
+
+<br />
+
+### Added
+- **Layout Shell Engine:** Created `<ds-article>` to orchestrate complex reading layouts dynamically via slot projection (`summary`, `player`, `navigator`, `default`).
+- **Action & Social Tooltips:** Integrated pre-wired `ds-button` and `ds-tooltip` structures into the Shadow DOM header. Added bottom-aligned tooltips to social icons and a KBD-enabled tooltip for the primary action button.
+- **Comprehensive Visibility Toggles:** Implemented a granular suite of `show-*` boolean attributes allowing the host application to conditionally hide or display any specific social icon (`show-social-linkedin`), action button, or slot container block without altering the DOM tree.
+- **Root Class Syncing:** Configured passive `MutationObserver` on `document.documentElement` reflecting global setting cascades (`a11y-dark-mode`, `a11y-high-contrast`, `a11y-large-text`, etc.) downstream as host element boolean attributes.
+
+### Fixed
+- **Markdown Light DOM Resolution:** Engineered exhaustive `::slotted()` rules within `article.css` ensuring slotted `<ul>`, `<ol>`, `<blockquote>`, `<pre>`, `<code>`, and `<table>` elements gracefully inherit global typography resets and appropriate vertical rhythm geometry natively from the host app without requiring deep Shadow DOM CSS penetrations.
+- **Sub-Atomic Token Hooks:** Established strictly prefixed structural variables (`--ds-article-max-width`, `--ds-article-title-color`, `--ds-article-social-color`) conforming to architecture standards.
+- **Dumb Component Architecture:** Replaced hard-coded data dependencies with declarative properties. The component now accepts flat Markdown/HTML via the default slot, totally decoupling it from internal application payload parsers or `data.js`.
+
+---
+
+*This changelog is specific to the `<ds-article>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*