@portfoliablejs/valence 0.1.0

package/src/stories/organisms/ComboCard/ComboCard.js

@@ -0,0 +1,44 @@
+// src/stories/organisms/ComboCard/ComboCard.js
+import css from './combo-card.css?inline';
+import '../../molecules/ComboTabs/ComboTabs.js';
+
+export class ComboCard extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `
+      <style>${css}</style>
+      <div class="combo-asset-card">
+        <ds-combo-tabs></ds-combo-tabs>
+        <div class="content-container"> 
+          <slot></slot>
+        </div>
+      </div>
+    `;
+    this.tabsEl = this.shadowRoot.querySelector('ds-combo-tabs');
+    this.tabsEl.addEventListener('ds-tab-change', (e) => this.updateContent(e.detail.activeId));
+  }
+
+  connectedCallback() {
+    // Let the browser parse the initial slotted content
+    setTimeout(() => this.initializeTabs(), 0);
+  }
+
+  initializeTabs() {
+    const tabs = [];
+    this.querySelectorAll('[slot]').forEach(el => {
+      tabs.push({ id: el.slot, label: el.getAttribute('data-label') || el.slot });
+    });
+    this.tabsEl.tabs = tabs;
+    if (tabs.length > 0) {
+      this.updateContent(tabs[0].id);
+    }
+  }
+
+  updateContent(activeId) {
+    this.querySelectorAll('[slot]').forEach(el => {
+      el.classList.toggle('active', el.slot === activeId);
+    });
+  }
+}
+if (!customElements.get('ds-combo-card')) customElements.define('ds-combo-card', ComboCard);

package/src/stories/organisms/ComboCard/ComboCard.stories.js

@@ -0,0 +1,18 @@
+// src/stories/organisms/ComboCard/ComboCard.stories.js
+import { html } from 'lit';
+import './ComboCard';
+
+export default {
+  title: 'Organisms/ComboCard',
+  tags: ['autodocs'],
+};
+
+export const WithTabs = {
+  render: () => html`
+    <ds-combo-card>
+      <div slot="dashboard" data-label="Dashboard">Content for Dashboard</div>
+      <div slot="history" data-label="History">Content for History</div>
+      <div slot="download" data-label="Download">Content for Download</div>
+    </ds-combo-card>
+  `,
+};

package/src/stories/organisms/ComboCard/combo-card.css

@@ -0,0 +1,25 @@
+/* src/stories/organisms/ComboCard/combo-card.css */
+:host {
+    display: block;
+}
+
+.combo-asset-card {
+    background-color: var(--color-card-bg, #F2F2F7);
+    border: 1px solid var(--color-card-border, rgba(0, 0, 0, 0.05));
+    border-radius: var(--radius-lg, 16px);
+    padding: var(--space-xl, 24px);
+    margin: var(--space-xxxxl, 80px) 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg, 16px);
+}
+
+.combo-content {
+    display: none;
+    flex-direction: column;
+    gap: var(--space-lg, 16px);
+}
+
+.combo-content.active {
+    display: flex;
+}

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

@@ -0,0 +1,296 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Contextual Menu [v1.1.0]/Architecture" />
+
+# `ds-contextual-menu`
+
+The `ds-contextual-menu` component is an interactive, presentational **controlled** Organism designed to render floating action popovers, settings panels, or navigation menus. It dynamically instantiates, configures, and projects child `<ds-item-row>` Molecules, handling hierarchical category dividers, keyboard focus traps, and root class accessibility observer syncs.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component strictly adheres to the **State In / Events Out** pattern:
+* **State In (Attributes / Properties):** The host binds configuration properties (`open`, `header-text`, `hide-header`, `hide-close`, `show-subcategory`, `subcategory-title`, `aria-label`) and an array of `items` data objects downstream to build lists and toggle visibility states.
+* **Events Out:** User clicks on the close button trigger a `ds-close` event, while click interactions on any nested item rows emit a consolidated `ds-select` event with current state details.
+
+<mermaid-diagram chart={`
+  flowchart TD
+      subgraph Host["Host Application / App Shell"]
+          direction TB
+          State["State Manager / Component Host"]
+      end
+
+      subgraph WebComp["ds-contextual-menu (Shadow DOM Composition)"]
+          Component["ds-contextual-menu"]
+          CloseBtn["ds-button (Close)"]
+          ItemRow["ds-item-row (Repeated)"]
+          Divider["ds-divider (Horizontal)"]
+      end
+
+      State -->|"1. State In: open / items / show-subcategory / titles"| Component
+      Component -->|"2. Updates Visibility"| CloseBtn
+      Component -->|"3. Instantiates & Binds Items"| ItemRow
+      Component -->|"4. Appends Dividers"| Divider
+      
+      CloseBtn -->|"5. Event Out: ds-close"| State
+      ItemRow -->|"6. Propagates Action: ds-select"| 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 CloseBtn fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style ItemRow fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+      style Divider fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+`} />
+
+---
+
+## Slot Architecture
+
+The `ds-contextual-menu` component completely seals its Shadow DOM bounds. To prevent WebKit compositor bugs on macOS Safari, scrolling overflow is structurally isolated inside a block-level `.menu-scroll-viewport` container, while child item rows and dividers are rendered inside a nested `.menu-content` flexbox layout. No public slots are projected.
+
+## Data Model
+
+```typescript
+export interface DsContextualMenuItem {
+  id: string;
+  label: string;
+  icon?: string;
+  showIcon?: boolean;
+  iconVariant?: 'outline' | 'fill';
+  showKbd?: boolean;
+  kbd?: string;
+  kbdVariant?: 'default' | 'inverted';
+  kbdShowPlus?: boolean;
+  kbdKey?: string;
+  control?: 'toggle' | 'check' | 'radio' | 'none';
+  checkHasBackground?: boolean;
+  active?: boolean;
+  selected?: boolean;
+  disabled?: boolean;
+  toggleTextOn?: string;
+  toggleTextOff?: string;
+  category: 'main' | 'subcategory';
+}
+
+export interface DsContextualMenuState {
+  items: DsContextualMenuItem[];
+  open: boolean;
+  headerText?: string;
+  hideHeader: boolean;
+  hideClose: boolean;
+  showSubcategory: boolean;
+  subcategoryTitle: string;
+  ariaLabel?: string;
+}
+
+export interface DsContextualMenuSubAtomicHooks {
+  '--ds-contextual-menu-width'?: string;
+  '--ds-contextual-menu-min-width'?: string;
+  '--ds-contextual-menu-bg'?: string;
+  '--ds-contextual-menu-radius'?: string;
+  '--ds-contextual-menu-max-height'?: string;
+  '--ds-contextual-menu-scroll-max-height'?: string;
+  '--ds-contextual-menu-scrollbar-color'?: 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>`items`</td>
+      <td>N/A</td>
+      <td>`DsContextualMenuItem[]`</td>
+      <td>`[]`</td>
+      <td>Programmatic array of row items configuration data. Re-renders on update.</td>
+    </tr>
+    <tr>
+      <td>`open`</td>
+      <td>`open`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Toggles popover visible entry/exit translate and scale animation states.</td>
+    </tr>
+    <tr>
+      <td>`headerText`</td>
+      <td>`header-text`</td>
+      <td>`string`</td>
+      <td>`'ACTIONS'`</td>
+      <td>Title string displayed inside the top header text bar.</td>
+    </tr>
+    <tr>
+      <td>`hideHeader`</td>
+      <td>`hide-header`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Hides the top header text bar entirely.</td>
+    </tr>
+    <tr>
+      <td>`hideClose`</td>
+      <td>`hide-close`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Hides the top-right close icon button.</td>
+    </tr>
+    <tr>
+      <td>`showSubcategory`</td>
+      <td>`show-subcategory`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Toggles display of the secondary subcategory preferences section.</td>
+    </tr>
+    <tr>
+      <td>`subcategoryTitle`</td>
+      <td>`subcategory-title`</td>
+      <td>`string`</td>
+      <td>`'PREFERENCES'`</td>
+      <td>Title string displayed inside the secondary subcategory header.</td>
+    </tr>
+    <tr>
+      <td>`ariaLabel`</td>
+      <td>`aria-label`</td>
+      <td>`string`</td>
+      <td>`undefined`</td>
+      <td>Accessible tag description delegated down into the menu card.</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-close`</td>
+      <td>`true` / `true`</td>
+      <td>`None`</td>
+      <td>Dispatched when the top close icon button is clicked, signaling a popover dismissal.</td>
+    </tr>
+    <tr>
+      <td>`ds-select`</td>
+      <td>`true` / `true`</td>
+      <td>`{ id: string, control: string, active: boolean, selected: boolean, label: string }`</td>
+      <td>Dispatched when any item row option triggers, passing updated state values upstream.</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-contextual-menu-width`</td>
+      <td>`260px`</td>
+      <td>Overrides menu card width limits.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-min-width`</td>
+      <td>`220px`</td>
+      <td>Overrides menu card minimum width constraints.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-bg`</td>
+      <td>`var(--color-bg)` / `var(--color-card-bg)`</td>
+      <td>Overrides backdrop surface background colors.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-radius`</td>
+      <td>`var(--radius-lg)`</td>
+      <td>Overrides backdrop corner rounded boundaries.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-max-height`</td>
+      <td>`none`</td>
+      <td>Caps overall host custom element max height.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-scroll-max-height`</td>
+      <td>`320px`</td>
+      <td>Caps vertical scrolling height limit for item list viewports.</td>
+    </tr>
+    <tr>
+      <td>`--ds-contextual-menu-scrollbar-color`</td>
+      <td>`#D9D9D9`</td>
+      <td>Overrides custom scrollbar thumb fill colors.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Aria Role Contract:** Assigns `role="menu"` on the container card, and applies `role="presentation"` to intermediate dividers and headers. Each generated list row is assigned `role="menuitem"`, `role="menuitemcheckbox"`, or `role="menuitemradio"` based on its form control parameters to strictly comply with WCAG standards.
+* **ARIA Host Scrubbing:** Automatically purges Light DOM `aria-label` custom attributes on the host custom element and projects them down onto the container.
+* **Disable Highlighting:** Applies native `user-select: none` across header titles to prevent unwanted text selections during clicks.
+* **Global Access Syncing:** Uses a `MutationObserver` on the HTML root element to capture visual preferences:
+  * `.a11y-dark-mode`: Swaps container background to matching dark player HUD tokens and redefines `--color-surface` locally.
+  * `.a11y-high-contrast`: Enforces strict AAA monochrome borders and outlines.
+  * `.a11y-dyslexia`: Overrides tooltip typeface families.
+  * `.a11y-reduce-motion`: Disables entering translations and scale transitions.
+  * `.a11y-forced-colors`: Employs active Windows system color maps (`Canvas` and `CanvasText`).
+* **Scroll Engine & WebKit Layer Isolation:** Attaches `data-lenis-prevent` and an explicit `wheel` listener to `.menu-scroll-viewport` to isolate smooth-scroll libraries (such as Lenis) from popover scrolling. Listens to `visibilitychange` and `open` state transitions to execute `_forceScrollbarRebind()`, safely resetting `overflowY` (`hidden` -> reflow -> `auto`) to destroy native WebKit overlay scrollbars without creating GPU texture ghosts or frozen thumb snapshots.
+---
+
+## Examples
+
+### Basic Integration Example
+
+```javascript
+import 'valence/ds-contextual-menu';
+
+const menu = document.createElement('ds-contextual-menu');
+menu.setAttribute('header-text', 'ACCESSIBILITY');
+menu.setAttribute('show-subcategory', '');
+menu.setAttribute('open', '');
+
+menu.items = [
+  { id: 'text-size', label: 'Large Text', icon: 'text-size', control: 'none', category: 'main' },
+  { id: 'dark-mode', label: 'Dark Theme', icon: 'moon', control: 'toggle', active: true, category: 'subcategory' }
+];
+
+// Clean sub-atomic overrides
+menu.style.setProperty('--ds-contextual-menu-width', '320px');
+menu.style.setProperty('--ds-contextual-menu-radius', '8px');
+
+menu.addEventListener('ds-select', (e) => {
+  console.log('Option chosen:', e.detail.id, 'Active:', e.detail.active);
+});
+
+document.body.appendChild(menu);
+```

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

@@ -0,0 +1,98 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Contextual Menu [v1.1.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.1.0] - 2026-07-22
+
+<br />
+
+### WebKit Scroll Engine Isolation & Safari Tab Switch Fix
+
+Architecturally decoupled the scrolling engine from the flexbox layout container inside the Shadow DOM to resolve macOS Safari / WebKit composite layer bugs where native overlay scrollbars bled through and custom scroll thumbs froze upon switching browser tabs or hiding/showing popovers.
+
+<br />
+
+### Refactored
+- **Viewport Engine Decoupling:** Introduced a block-level `.menu-scroll-viewport` container inside the Shadow DOM to handle `overflow-y` and scrollbar rendering, completely isolating scroll mechanics from the inner `.menu-content` flexbox layout.
+- **Unconditional WebKit Styling:** Applied `::-webkit-scrollbar` pseudo-element rules unconditionally (without `@supports` feature queries) to force WebKit in Safari 17+ to opt out of native `NSScroller` overlay tracks completely.
+* **Documentation Refactor:** Updated `ContextualMenu.Architecture.mdx` to document the block-level viewport scroll isolation, WebKit overlay scrollbar re-binding strategy, and new sub-atomic CSS custom property hooks (`--ds-contextual-menu-max-height`, `--ds-contextual-menu-scroll-max-height`, `--ds-contextual-menu-scrollbar-color`).
+
+### Fixed
+- **Safari Tab-Switch & Reveal Scrollbar Freeze:** Added `_forceScrollbarRebind()`, executing a temporary `overflowY` reset (`hidden` $\rightarrow$ layout flush $\rightarrow$ `auto`) triggered on `visibilitychange` tab focus and `open` attribute changes. This cleanly destroys phantom native overlay tracks without destroying DOM trees or duplicating GPU VRAM layers.
+- **Lenis Smooth-Scroll Conflict:** Added `data-lenis-prevent` attributes and bound `wheel` event `stopPropagation()` to `.menu-scroll-viewport`, stopping parent smooth-scroll engines from hijacking internal menu scroll events.
+- **Box-Shadow Preservation:** Guaranteed host and card `box-shadow` values remain completely unclipped while constraining internal vertical scroll heights.
+
+### Added
+- **Max Height Sub-Atomic Token:** Bound `max-height` attribute to `--ds-contextual-menu-max-height` and `--ds-contextual-menu-scroll-max-height`, allowing parent components (such as `ds-toc`) to dynamically cap popover menu heights.
+- **Storybook Overflow Testing:** Added `ScrollableOverflowMenu` story with automated play steps testing vertical scroll mechanics and layer stability.
+
+---
+
+## [1.0.0] - 2026-07-20
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational settings contextual popover menu organism (`ds-contextual-menu`) featuring dynamic item generation, hierarchical category divider syncs, and comprehensive accessibility coverage.
+
+<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-contextual-menu`</td>
+      <td>Initial stable release of the popover menu card organism.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-contextual-menu`</td>
+      <td>Configured dynamic, programmatic `items` mapping with automated subcategory sections and divider insertions.</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>`contextual-menu.css`</td>
+      <td>Remapped custom style parameters to standardized `--ds-contextual-menu-*` design tokens instead of generic `--custom-*` variables.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`ContextualMenu.stories.js`</td>
+      <td>Suffix-aligned storybook title and updated sub-atomic controllers to bind to standard variables inside templates.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Interactive Popover Organism:** Created `<ds-contextual-menu>` aggregating nested setting rows and horizontal divider atoms.
+- **Robust Role Mapping:** Assigned spec-compliant `role="menu"` on cards, `role="presentation"` on layout headers, and `role="menuitem"` or `role="menuitemcheckbox"`/`role="menuitemradio"` on nested setting rows to meet strict WCAG standards.
+- **Root Context Syncing:** MutationObserver on document roots reflects global setting cascades downstream as host element boolean flags.
+- **Thematic Overrides:** Bound menu card width, min-width, background, and corner rounded radius variables to standard `--ds-contextual-menu-*` properties.
+- **Storybook Workspace:** Configured complete interactive Controls and detailed CSF3 stories inside `ContextualMenu.stories.js`.
+
+### Fixed
+- **Sub-Atomic Story Mapping:** Synchronized Storybook override controllers to output precise `--ds-contextual-menu-*` custom styles.
+
+---
+
+*This changelog is specific to the `<ds-contextual-menu>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*