@portfoliablejs/valence 0.1.0

package/src/stories/organisms/Gallery/Gallery.stories.js

@@ -0,0 +1,175 @@
+// src/stories/organisms/Gallery/Gallery.stories.js
+import { html } from 'lit';
+import { expect, fireEvent, fn } from 'storybook/test';
+import './Gallery';
+import '../../molecules/GalleryItem/GalleryItem';
+
+export default {
+  title: 'Organisms/Gallery [v1.0.0]',
+  component: 'ds-gallery',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'The `ds-gallery` organism renders a generated row of `ds-gallery-item` cards and lets the user drag the strip horizontally with a soft, Apple-like overscroll feel. Use `item-count` to control how many gallery items are rendered, with five items as the default.',
+      },
+    },
+  },
+  argTypes: {
+    engine: {
+      name: 'engine',
+      control: 'text',
+      description: 'Motion preset used for drag follow, overscroll, and edge-return timing.',
+      table: {
+        category: 'Component: Motion',
+        defaultValue: { summary: 'minimal' },
+      },
+    },
+    itemCount: {
+      name: 'item-count',
+      control: { type: 'range', min: 1, max: 8, step: 1 },
+      description: 'Controls how many GalleryItem cards are rendered by the gallery.',
+      table: {
+        category: 'Component: Core Controls',
+        defaultValue: { summary: '5' },
+      },
+    },
+    itemGap: {
+      name: 'item-gap',
+      control: 'text',
+      description: 'Horizontal gap between gallery items.',
+      table: {
+        category: 'Component: Layout',
+        defaultValue: { summary: '100px' },
+      },
+    },
+    onCaseSelect: {
+      action: 'ds-case-select',
+      description: 'Fires when a generated GalleryItem thumbnail is selected.',
+      table: { category: 'Events' },
+    },
+  },
+  args: {
+    engine: 'minimal',
+    itemCount: 5,
+    itemGap: '100px',
+    onCaseSelect: fn(),
+  },
+  render: (args) => html`
+    <div style="min-height: 100vh; width: 100%; padding: 0 50px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; background: transparent;">
+      <div style="width: 100%;">
+        <ds-gallery
+          style="width: 100%; --gallery-item-gap: ${args.itemGap};"
+          .engine=${args.engine}
+          .itemCount=${args.itemCount}
+          @ds-case-select=${args.onCaseSelect}
+        ></ds-gallery>
+      </div>
+    </div>
+  `,
+};
+
+export const Default = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'The default gallery renders five generated GalleryItem cards and keeps the strip flush without any outer padding.',
+      },
+    },
+  },
+  play: async ({ canvasElement, args, step }) => {
+    const gallery = canvasElement.querySelector('ds-gallery');
+
+    await step('Render the default five GalleryItem cards', async () => {
+      expect(gallery).toBeTruthy();
+      expect(gallery.shadowRoot.querySelectorAll('ds-gallery-item').length).toBe(5);
+    });
+
+    await step('Bubble a selection event from the first item', async () => {
+      const firstItem = gallery.shadowRoot.querySelector('ds-gallery-item');
+      const thumb = firstItem.shadowRoot.querySelector('.case-thumb-wrapper');
+      fireEvent.click(thumb);
+      expect(args.onCaseSelect).toHaveBeenCalled();
+    });
+
+    await step('Support arrow and enter navigation from the gallery viewport', async () => {
+      const viewport = gallery.shadowRoot.querySelector('.gallery-viewport');
+      viewport.focus();
+      fireEvent.keyDown(viewport, { key: 'ArrowRight' });
+      expect(gallery.shadowRoot.activeElement?.shadowRoot?.activeElement || gallery.shadowRoot.activeElement).toBeTruthy();
+      fireEvent.keyDown(viewport, { key: 'Enter' });
+    });
+  },
+};
+
+export const ThreeItems = {
+  args: {
+    itemCount: 3,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'A compact gallery variant that proves the item-count prop can reduce the row to three cards.',
+      },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    const gallery = canvasElement.querySelector('ds-gallery');
+
+    await step('Render only three generated items', async () => {
+      expect(gallery.shadowRoot.querySelectorAll('ds-gallery-item').length).toBe(3);
+    });
+  },
+};
+
+export const EightItems = {
+  args: {
+    itemCount: 8,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'An extended gallery that fills the track with the full internal item pool and confirms the generated cards scale cleanly.',
+      },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    const gallery = canvasElement.querySelector('ds-gallery');
+
+    await step('Render the full eight-item pool', async () => {
+      expect(gallery.shadowRoot.querySelectorAll('ds-gallery-item').length).toBe(8);
+    });
+  },
+};
+
+export const SoftEdgeDrag = {
+  args: {
+    itemCount: 5,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Exercises the drag physics by pulling past the leading edge and verifying the overscroll stays restrained before settling back into place.',
+      },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    const gallery = canvasElement.querySelector('ds-gallery');
+    const viewport = gallery.shadowRoot.querySelector('.gallery-viewport');
+    const track = gallery.shadowRoot.querySelector('.gallery-track');
+
+    await step('Pull the gallery beyond the left edge', async () => {
+      fireEvent.pointerDown(viewport, { button: 0, pointerId: 1, clientX: 120, clientY: 120 });
+      fireEvent.pointerMove(window, { pointerId: 1, clientX: 380, clientY: 120 });
+      expect(track.style.transform).not.toBe('translate3d(0px, 0, 0)');
+      expect(track.style.transform).toContain('px');
+      fireEvent.pointerUp(window, { pointerId: 1 });
+    });
+
+    await step('Snap the gallery back to the resting position', async () => {
+      expect(track.style.transform).toBe('translate3d(0px, 0, 0)');
+    });
+  },
+};

package/src/stories/organisms/Gallery/gallery.css

@@ -0,0 +1,59 @@
+/* src/stories/organisms/Gallery/gallery.css */
+:host {
+    display: block;
+    width: 100%;
+    height: auto;
+    overflow: visible;
+    box-sizing: border-box;
+    transform: scale(1);
+    transform-origin: center center;
+    transition: transform 280ms cubic-bezier(0.22, 1, 0.36, 1);
+    will-change: transform;
+}
+
+:host(.is-dragging) {
+    transform: scale(0.97);
+}
+
+:host([a11y-reduce-motion]) {
+    transition: none;
+}
+
+:host([a11y-reduce-motion].is-dragging) {
+    transform: scale(1);
+}
+
+.gallery-viewport {
+    width: 100%;
+    overflow-x: visible;
+    overflow-y: visible;
+    cursor: grab;
+    user-select: none;
+    -webkit-user-select: none;
+    touch-action: pan-y;
+    box-sizing: border-box;
+}
+
+.gallery-viewport.is-dragging {
+    cursor: grabbing;
+}
+
+.gallery-track {
+    display: flex;
+    align-items: flex-end;
+    gap: var(--gallery-item-gap, clamp(32px, 4vw, 72px));
+    width: max-content;
+    will-change: transform;
+    transform: translate3d(0, 0, 0);
+    box-sizing: border-box;
+}
+
+.gallery-track.is-dragging {
+    transition: none !important;
+}
+
+:host([a11y-reduce-motion]) .gallery-track,
+:host([a11y-reduce-motion]) .gallery-viewport,
+:host([a11y-reduce-motion]) .gallery-track.is-dragging {
+    transition: none !important;
+}

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

@@ -0,0 +1,195 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Header [v1.0.0]/Architecture" />
+
+# `ds-header`
+
+The `ds-header` component is a **stateless (presentational)** Organism designed to compose top-level application navigation chrome. It places a controlled `ds-breadcrumb` region on the far left and a `ds-navigation-menu` region on the far right while preserving a strict **State In / Events Out** contract for the host application.
+
+---
+
+## Principles
+
+### Dumb Composition Boundary
+The component strictly adheres to the **Unidirectional Data Flow** paradigm:
+* **State In (Attributes / Properties):** The host app binds breadcrumb arrays, visibility flags, and navigation-menu presentational attributes onto `<ds-header>`.
+* **Events Out (Child Events Forwarded):** The organism does not create domain state of its own. Instead, it allows child events such as `ds-breadcrumb-select` and `ds-navigation-menu-language-select` to bubble outward unchanged.
+* **No Smart App Logic:** Routing, locale changes, accessibility preference persistence, and profile actions remain fully external to the component.
+
+### Fixed Edge Alignment
+The visual contract is intentionally rigid:
+* **Left Anchor:** The breadcrumb region expands from the far left edge of the header content row.
+* **Right Anchor:** The navigation menu remains pinned to the far right edge through flex layout and auto margin separation.
+* **Viewport Shell:** The host element and internal shell stretch to the full viewport width, making the organism suitable for app-level framing rather than inline card use.
+
+<mermaid-diagram chart={`
+flowchart LR
+    Host["Host SPA / Smart App"] -->|bind props| Header["ds-header"]
+    Header --> Breadcrumb["ds-breadcrumb"]
+    Header --> Nav["ds-navigation-menu"]
+    Breadcrumb -->|bubble events| Host
+    Nav -->|bubble events| Host
+
+    style Host fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
+    style Header fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+    style Breadcrumb fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+    style Nav fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+`} />
+
+---
+
+## Internal Composition
+
+### Structural Regions
+
+<table>
+  <thead>
+    <tr>
+      <th>Region</th>
+      <th>Rendered Element</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`header-shell`</td>
+      <td>`<header>`</td>
+      <td>Full-width semantic landmark container delegating the host ARIA label.</td>
+    </tr>
+    <tr>
+      <td>`breadcrumb-region`</td>
+      <td>`<ds-breadcrumb>`</td>
+      <td>Flexible left-aligned region that can be hidden through `show-breadcrumb="false"`.</td>
+    </tr>
+    <tr>
+      <td>`navigation-region`</td>
+      <td>`<ds-navigation-menu>`</td>
+      <td>Right-aligned action group that remains mounted and receives pass-through attributes from the host element.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## API Contract
+
+### Properties & Attributes
+
+<table>
+  <thead>
+    <tr>
+      <th>Property / Attribute</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`breadcrumbItems`</td>
+      <td>`Array`</td>
+      <td>`null`</td>
+      <td>Controlled breadcrumb item stack forwarded to the composed `ds-breadcrumb` instance.</td>
+    </tr>
+    <tr>
+      <td>`breadcrumbMenuItems`</td>
+      <td>`Array`</td>
+      <td>`null`</td>
+      <td>Optional fallback menu options array forwarded to the breadcrumb molecule.</td>
+    </tr>
+    <tr>
+      <td>`show-breadcrumb`</td>
+      <td>`boolean`</td>
+      <td>`true`</td>
+      <td>Mounts or hides the left breadcrumb region without changing navigation behavior.</td>
+    </tr>
+    <tr>
+      <td>`show-language-menu`</td>
+      <td>`boolean`</td>
+      <td>`true`</td>
+      <td>Controls visibility of the language action inside the composed navigation menu.</td>
+    </tr>
+    <tr>
+      <td>`avatar-src`, `avatar-alt`, tooltip and aria-label props</td>
+      <td>`string` / `boolean`</td>
+      <td>Inherited from child molecule defaults</td>
+      <td>Presentational pass-through API forwarded directly to `ds-navigation-menu`.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Emitted Custom Events
+
+<table>
+  <thead>
+    <tr>
+      <th>Event Name</th>
+      <th>Source</th>
+      <th>Bubbles / Composed</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`ds-breadcrumb-home`</td>
+      <td>`ds-breadcrumb`</td>
+      <td>`true` / `true`</td>
+      <td>Signals that the root breadcrumb item was activated.</td>
+    </tr>
+    <tr>
+      <td>`ds-breadcrumb-return`</td>
+      <td>`ds-breadcrumb`</td>
+      <td>`true` / `true`</td>
+      <td>Signals a step-back breadcrumb action.</td>
+    </tr>
+    <tr>
+      <td>`ds-breadcrumb-select`</td>
+      <td>`ds-breadcrumb`</td>
+      <td>`true` / `true`</td>
+      <td>Signals selection of a breadcrumb item or contextual option.</td>
+    </tr>
+    <tr>
+      <td>`ds-navigation-menu-*`</td>
+      <td>`ds-navigation-menu`</td>
+      <td>`true` / `true`</td>
+      <td>Pass-through navigation events for language, accessibility, about, and option selection interactions.</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-header-gap`</td>
+      <td>`var(--space-lg, 16px)`</td>
+      <td>Overrides the spacing between the left and right header regions.</td>
+    </tr>
+    <tr>
+      <td>`--ds-header-min-height`</td>
+      <td>`var(--size-height-sm, 44px)`</td>
+      <td>Overrides the minimum height of the header row.</td>
+    </tr>
+    <tr>
+      <td>`--ds-header-padding`</td>
+      <td>`24px 28px`</td>
+      <td>Overrides the internal viewport-edge padding applied to the full-width header shell.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Semantics
+
+* **Semantic Landmark:** The organism renders an internal `<header>` element and delegates `aria-label` from the host for top-level navigation context.
+* **Child Accessibility Preservation:** Accessibility mechanics remain owned by `ds-breadcrumb` and `ds-navigation-menu`, allowing those molecules to preserve their own tooltip, keyboard, and contextual menu semantics.
+* **Visibility Without State Loss:** Optional regions are hidden through presentational toggles rather than destructive mutation of application state, keeping host control explicit and reversible.

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

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Organisms/Header [v1.0.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-23
+
+<br />
+
+### Initial Release
+
+The stable debut of the `ds-header` layout organism. This component establishes a full-width presentational header shell that composes `ds-breadcrumb` and `ds-navigation-menu` into a single app-level chrome surface while preserving a strict dumb-component contract.
+
+<br />
+
+### Added
+- **Viewport-Width Header Shell:** Created `<ds-header>` as a full-width organism that stretches across the viewport and maintains explicit left/right edge anchoring for its composed regions.
+- **Molecule Composition Contract:** Integrated `ds-breadcrumb` on the far left and `ds-navigation-menu` on the far right using a rigid flex layout intended for smart-app page framing.
+- **Presentational Visibility Toggles:** Added `show-breadcrumb` and `show-language-menu` booleans so the host application can suppress optional UI regions without introducing smart behavior into the component itself.
+- **Navigation Attribute Forwarding:** Implemented pass-through forwarding for avatar, tooltip, keyboard shortcut, aria-label, and disabled-state props into the child navigation menu.
+- **Storybook Coverage:** Added `Complete`, `NoBreadcrumb`, and `NoLanguageMenu` stories with explicit descriptions validating alignment and optional-region behavior.
+
+### Fixed
+- **Export Surface Completion:** Filled the missing `src/stories/organisms/Header/Header.js` module expected by the package entry export map.
+- **Contextual Menu Canvas Clipping:** Increased the Header story canvas height and bottom breathing room so the navigation menu popovers can open without being visually cut off in the preview.
+
+---
+
+*This changelog is specific to the `<ds-header>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/organisms/Header/Header.js

@@ -0,0 +1,151 @@
+import css from './header.css?inline';
+import '../../molecules/Breadcrumb/Breadcrumb.js';
+import '../../molecules/NavigationMenu/NavigationMenu.js';
+
+const NAVIGATION_MENU_ATTRIBUTES = [
+  'language-tooltip',
+  'language-kbd-label',
+  'language-kbd-key',
+  'language-kbd-show-plus',
+  'language-aria-label',
+  'accessibility-tooltip',
+  'accessibility-kbd-label',
+  'accessibility-kbd-key',
+  'accessibility-kbd-show-plus',
+  'accessibility-aria-label',
+  'about-tooltip',
+  'about-kbd-label',
+  'about-kbd-key',
+  'about-kbd-show-plus',
+  'about-aria-label',
+  'avatar-src',
+  'avatar-alt',
+  'disabled'
+];
+
+export class Header extends HTMLElement {
+  static get observedAttributes() {
+    return ['aria-label', 'show-breadcrumb', 'show-language-menu', ...NAVIGATION_MENU_ATTRIBUTES];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this._breadcrumbItems = null;
+    this._breadcrumbMenuItems = null;
+
+    this.shadowRoot.innerHTML = `
+      <style>${css}</style>
+      <header class="header-shell" aria-label="Header">
+        <div class="header-content">
+          <div class="breadcrumb-region">
+            <ds-breadcrumb></ds-breadcrumb>
+          </div>
+          <div class="navigation-region">
+            <ds-navigation-menu></ds-navigation-menu>
+          </div>
+        </div>
+      </header>
+    `;
+  }
+
+  connectedCallback() {
+    this.headerEl = this.shadowRoot.querySelector('.header-shell');
+    this.breadcrumbRegion = this.shadowRoot.querySelector('.breadcrumb-region');
+    this.navigationRegion = this.shadowRoot.querySelector('.navigation-region');
+    this.breadcrumbEl = this.shadowRoot.querySelector('ds-breadcrumb');
+    this.navigationEl = this.shadowRoot.querySelector('ds-navigation-menu');
+    this.render();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (this.headerEl) {
+      this.render();
+    }
+  }
+
+  get breadcrumbItems() {
+    return this._breadcrumbItems;
+  }
+
+  set breadcrumbItems(items) {
+    this._breadcrumbItems = Array.isArray(items) ? items : null;
+    this.render();
+  }
+
+  get breadcrumbMenuItems() {
+    return this._breadcrumbMenuItems;
+  }
+
+  set breadcrumbMenuItems(items) {
+    this._breadcrumbMenuItems = Array.isArray(items) ? items : null;
+    this.render();
+  }
+
+  get showBreadcrumb() {
+    return this.getAttribute('show-breadcrumb') !== 'false';
+  }
+
+  set showBreadcrumb(value) {
+    this.setAttribute('show-breadcrumb', value ? 'true' : 'false');
+  }
+
+  get showLanguageMenu() {
+    return this.getAttribute('show-language-menu') !== 'false';
+  }
+
+  set showLanguageMenu(value) {
+    this.setAttribute('show-language-menu', value ? 'true' : 'false');
+  }
+
+  _forwardNavigationAttributes() {
+    NAVIGATION_MENU_ATTRIBUTES.forEach((attributeName) => {
+      if (this.hasAttribute(attributeName)) {
+        this.navigationEl.setAttribute(attributeName, this.getAttribute(attributeName) || '');
+      } else {
+        this.navigationEl.removeAttribute(attributeName);
+      }
+    });
+  }
+
+  _syncLanguageVisibility() {
+    const showLanguageMenu = this.showLanguageMenu;
+    const navigationShadow = this.navigationEl.shadowRoot;
+
+    if (!navigationShadow) return;
+
+    const languageItem = navigationShadow.querySelector('.menu-item-language');
+    const languageMenu = navigationShadow.querySelector('.language-menu');
+
+    if (languageItem) {
+      languageItem.style.display = showLanguageMenu ? '' : 'none';
+    }
+
+    if (!showLanguageMenu && languageMenu) {
+      languageMenu.removeAttribute('open');
+    }
+  }
+
+  render() {
+    if (!this.headerEl) return;
+
+    this.headerEl.setAttribute('aria-label', this.getAttribute('aria-label') || 'Header');
+
+    this.breadcrumbRegion.hidden = !this.showBreadcrumb;
+    this.breadcrumbEl.visible = this.showBreadcrumb;
+
+    if (Array.isArray(this._breadcrumbItems)) {
+      this.breadcrumbEl.items = this._breadcrumbItems;
+    }
+
+    this.breadcrumbEl.menuItems = this._breadcrumbMenuItems;
+
+    this._forwardNavigationAttributes();
+    this._syncLanguageVisibility();
+  }
+}
+
+if (!customElements.get('ds-header')) {
+  customElements.define('ds-header', Header);
+}