@portfoliablejs/valence 0.1.0

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

@@ -0,0 +1,264 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/Gallery Item [v1.2.0]/Architecture" />
+
+# `ds-gallery-item`
+
+The `ds-gallery-item` component is a presentational Molecule that composes a clickable preview thumbnail (`ds-thumbnail`), metadata text, and optional action pills for portfolio and case study catalogs.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component follows the **State In / Events Out** pattern:
+* **State In (Attributes):** Host applications provide title, short description, read time, thumbnail source, thumbnail frame selectors (`thumb-category`, `thumb-brand`, `thumb-model`, `thumb-color`, optional `thumb-device-src`), frame ratio, and state flags (`is-protected`, `is-unlocked`, `has-video`, `has-repo`, `has-live`).
+* **Events Out (`ds-case-select`):** The thumbnail activation surface dispatches selection intent via a bubbling/composed CustomEvent.
+* **Derived Presentation State:** Lock/unlock visuals and pill visibility are derived from host-provided booleans only.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host Application / Router"]
+          State["Current Case State"]
+      end
+
+      subgraph WebComp["Valence Molecule"]
+          Card["ds-gallery-item"]
+      end
+
+      State -->|"1. State In\n title, short-desc, thumb-src, thumb-model, flags"| Card
+      Card -->|"2. Event Out\n ds-case-select"| State
+
+      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 Card fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+`} />
+
+---
+
+## Slot Architecture
+
+`ds-gallery-item` is a sealed Shadow DOM component. It does not expose slots and controls all child composition internally.
+
+### 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>Internal composition only (`ds-thumbnail`, title row, read-time, pills).</td>
+      <td>Renders an internal fallback title and empty metadata when attributes are omitted.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## 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>`title`</td>
+      <td>`title`</td>
+      <td>`string`</td>
+      <td>`'Case Title'`</td>
+      <td>Primary card heading for the case item.</td>
+    </tr>
+    <tr>
+      <td>`shortDesc`</td>
+      <td>`short-desc`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Secondary descriptive text beneath the heading.</td>
+    </tr>
+    <tr>
+      <td>`readTime`</td>
+      <td>`read-time`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Optional reading/viewing duration label.</td>
+    </tr>
+    <tr>
+      <td>`thumbSrc`</td>
+      <td>`thumb-src`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Image URL fed into child `ds-thumbnail` via `screen-image`.</td>
+    </tr>
+    <tr>
+      <td>`aspectRatio`</td>
+      <td>`aspect-ratio`</td>
+      <td>`string`</td>
+      <td>`'9:19.5'`</td>
+      <td>Frame ratio applied to the thumbnail wrapper (for example `1:1`, `16:9`).</td>
+    </tr>
+    <tr>
+      <td>`thumbCategory`</td>
+      <td>`thumb-category`</td>
+      <td>`string`</td>
+      <td>`'mobile'`</td>
+      <td>Category passed to child `ds-thumbnail` catalog selection.</td>
+    </tr>
+    <tr>
+      <td>`thumbBrand`</td>
+      <td>`thumb-brand`</td>
+      <td>`string`</td>
+      <td>`'apple'`</td>
+      <td>Brand passed to child `ds-thumbnail` catalog selection.</td>
+    </tr>
+    <tr>
+      <td>`thumbModel`</td>
+      <td>`thumb-model`</td>
+      <td>`string`</td>
+      <td>`'Apple iPhone 12'`</td>
+      <td>Model passed to child `ds-thumbnail` catalog selection.</td>
+    </tr>
+    <tr>
+      <td>`thumbColor`</td>
+      <td>`thumb-color`</td>
+      <td>`string`</td>
+      <td>`'Black'`</td>
+      <td>Color variant passed to child `ds-thumbnail` catalog selection.</td>
+    </tr>
+    <tr>
+      <td>`thumbDeviceSrc`</td>
+      <td>`thumb-device-src`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Optional direct frame URL override for `ds-thumbnail` (`device-src`).</td>
+    </tr>
+    <tr>
+      <td>`isProtected`</td>
+      <td>`is-protected`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Enables lock icon rendering and protected state behavior.</td>
+    </tr>
+    <tr>
+      <td>`isUnlocked`</td>
+      <td>`is-unlocked`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>When paired with `is-protected`, toggles lock-open state and normal text visibility.</td>
+    </tr>
+    <tr>
+      <td>`hasVideo`</td>
+      <td>`has-video`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Shows localized video/pitch pill when unlocked.</td>
+    </tr>
+    <tr>
+      <td>`hasRepo`</td>
+      <td>`has-repo`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Shows localized repository pill when unlocked.</td>
+    </tr>
+    <tr>
+      <td>`hasLive`</td>
+      <td>`has-live`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Shows localized live demo pill when unlocked.</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-case-select`</td>
+      <td>`true` / `true`</td>
+      <td>`{}`</td>
+      <td>Emitted when the user activates the thumbnail surface via click, Enter, or Space.</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>`--device-h-gallery`</td>
+      <td>`55vh`</td>
+      <td>Controls rendered thumbnail height.</td>
+    </tr>
+    <tr>
+      <td>`--ds-thumbnail-screen-radius`</td>
+      <td>`var(--radius-lg)`</td>
+      <td>Controls corner radius of the thumbnail image surface.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Interaction
+
+* **Keyboard Activation:** Selection surface supports `Enter` and `Space` key activation.
+* **Focusable Surface:** Thumbnail host is exposed with `tabindex="0"` and `role="button"`.
+* **Protected State Redaction:** Locked cards hide read time, blur the thumbnail surface, and replace title/description text.
+* **Semantic Indicator:** Protected cards display lock-open / lock-closed iconography to communicate current availability.
+
+---
+
+## Integration Example
+
+```javascript
+import 'valence/src/stories/molecules/GalleryItem/GalleryItem.js';
+
+const card = document.createElement('ds-gallery-item');
+card.setAttribute('title', 'Agentic AI Design');
+card.setAttribute('short-desc', 'Exploration of orchestration and UX.');
+card.setAttribute('thumb-src', '/holofante.avif');
+card.setAttribute('thumb-model', 'Apple iPhone 12');
+card.setAttribute('thumb-color', 'Black');
+card.setAttribute('read-time', '3 min');
+card.setAttribute('has-video', '');
+card.addEventListener('ds-case-select', () => {
+  console.log('Open case details');
+});
+
+document.body.appendChild(card);
+```

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

@@ -0,0 +1,142 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/Gallery Item [v1.2.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.2.0] - 2026-07-23
+
+<br />
+
+### Thumbnail Frame Controls & iPhone 12 Defaults
+
+This release removes the forced `custom-only` thumbnail mode in `ds-gallery-item`, exposes full frame-selector props, and organizes Storybook controls into clear categories with iPhone 12 defaults.
+
+<br />
+
+### Summary of Changes
+
+<table>
+  <thead>
+    <tr>
+      <th>Classification</th>
+      <th>Scope / Context</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`Changed`</td>
+      <td>`GalleryItem.js`</td>
+      <td>Removed forced `custom-only` from child `ds-thumbnail` and enabled full frame rendering mode by default.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`GalleryItem.js`</td>
+      <td>Added thumbnail passthrough attributes: `thumb-category`, `thumb-brand`, `thumb-model`, `thumb-color`, and optional `thumb-device-src`.</td>
+    </tr>
+    <tr>
+      <td>`Changed`</td>
+      <td>`GalleryItem.stories.js`</td>
+      <td>Exposed thumbnail frame controls in story args and grouped controls by category (Content, Thumbnail Frame, Layout, State, Pills).</td>
+    </tr>
+    <tr>
+      <td>`Changed`</td>
+      <td>`GalleryItem.stories.js`</td>
+      <td>Set default frame values to Apple iPhone 12 (mobile/apple/Apple iPhone 12/Black).</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Thumbnail Frame Props:** Story + component now expose device frame selection inputs for catalog-driven rendering.
+
+### Changed
+- **Default Device:** Updated default framed thumbnail presentation to Apple iPhone 12.
+- **Story Controls Taxonomy:** Reorganized controls into distinct contributor-friendly groups.
+
+---
+
+<br />
+
+## [1.1.0] - 2026-07-23
+
+<br />
+
+### Thumbnail Composition Update
+
+This release updates `ds-gallery-item` to compose the shared `ds-thumbnail` atom instead of rendering a local image wrapper, and adds dedicated architecture/changelog documentation for maintainers.
+
+<br />
+
+### Summary of Changes
+
+<table>
+  <thead>
+    <tr>
+      <th>Classification</th>
+      <th>Scope / Context</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`Changed`</td>
+      <td>`GalleryItem.js`</td>
+      <td>Replaced local thumbnail wrapper/image composition with `ds-thumbnail` (`custom-only`) as the render surface.</td>
+    </tr>
+    <tr>
+      <td>`Changed`</td>
+      <td>`gallery-item.css`</td>
+      <td>Updated thumbnail styles to target the `ds-thumbnail` host and preserve hover, focus, and active interaction feedback.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`locked visuals`</td>
+      <td>Locked-state blur is now applied to the shared thumbnail host consistently with protected-card behavior.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`component docs`</td>
+      <td>Added architecture and changelog MDX coverage for `ds-gallery-item` to align with Valence molecule documentation standards.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Architecture Documentation:** Introduced `GalleryItem.Architecture.mdx` covering API, event contract, interaction model, and CSS hooks.
+- **Changelog Coverage:** Added component-level release notes with scoped, classified updates.
+
+### Changed
+- **Thumbnail Surface:** Gallery cards now pass `thumb-src` into `ds-thumbnail` via `screen-image` and preserve ratio/height constraints.
+- **Interaction Layer:** Existing click/keyboard select behavior remains on the same gallery thumbnail surface semantics.
+
+### Fixed
+- **Shared Thumbnail Consistency:** Gallery items now rely on the design system's thumbnail atom for image rendering behavior rather than duplicating local image mechanics.
+
+---
+
+## [1.0.0] - 2026-07-21
+
+<br />
+
+### Initial Release
+
+Initial release of the `ds-gallery-item` molecule for case study card previews, lock-state redaction, and optional metadata pills.
+
+<br />
+
+### Added
+- **Gallery Item Molecule:** Added `<ds-gallery-item>` with title, short description, read-time, lock icon, and pills support.
+- **Selection Event:** Added `ds-case-select` custom event for host-level case navigation.
+- **Protected State Support:** Added `is-protected` and `is-unlocked` behavior for locked/unlocked rendering.
+
+---
+
+*This changelog is specific to the `<ds-gallery-item>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/molecules/GalleryItem/GalleryItem.js

@@ -0,0 +1,201 @@
+// src/stories/molecules/GalleryItem/GalleryItem.js
+import css from './gallery-item.css?inline';
+import '../../atoms/Pill/Pill.js';
+import '../../atoms/Thumbnail/Thumbnail.js';
+import '../../sub-atomic/Iconography/Iconography.js';
+
+export class GalleryItem extends HTMLElement {
+  static get observedAttributes() {
+    return [
+      'title',
+      'short-desc',
+      'read-time',
+      'thumb-src',
+      'aspect-ratio',
+      'thumb-category',
+      'thumb-brand',
+      'thumb-model',
+      'thumb-color',
+      'thumb-device-src',
+      'thumb-custom-only',
+      'show-title',
+      'show-short-desc',
+      'show-read-time',
+      'show-thumbnail',
+      'is-protected',
+      'is-unlocked',
+      'has-video',
+      'has-repo',
+      'has-live',
+    ];
+  }
+
+  getCategoryHeight(category) {
+    const map = {
+      wearable: '26vh',
+      mobile: '40vh',
+      tablet: '46vh',
+      desktop: '32vh',
+      television: '30vh',
+    };
+
+    const baseHeight = map[category] || '40vh';
+    return `calc(${baseHeight} * 1.25)`;
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.innerHTML = `
+      <style>${css}</style>
+      <ds-thumbnail class="case-thumb-wrapper" tabindex="0" role="button"></ds-thumbnail>
+      <div class="gallery-item-meta">
+        <div class="gallery-item-text">
+          <div class="gallery-item-title-wrapper">
+            <h4 class="gallery-item-title">
+              <ds-icon class="lock-icon" size="14" style="display: none;"></ds-icon>
+              <span class="title-text"></span>
+            </h4>
+            <span class="gallery-read-time">
+              <ds-icon name="play" size="10"></ds-icon>
+              <span class="read-time-text"></span>
+            </span>
+          </div>
+          <p class="gallery-item-shortdesc"></p>
+        </div>
+        <div class="gallery-item-pills"></div>
+      </div>
+    `;
+
+    this.thumbWrapper = this.shadowRoot.querySelector('.case-thumb-wrapper');
+    
+    this.thumbWrapper.addEventListener('click', () => this.dispatchSelect());
+    this.thumbWrapper.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        this.dispatchSelect();
+      }
+    });
+  }
+
+  dispatchSelect() {
+    this.dispatchEvent(new CustomEvent('ds-case-select', { bubbles: true, composed: true }));
+  }
+
+  connectedCallback() { this.render(); }
+  attributeChangedCallback() { this.render(); }
+
+  parseToggleAttr(name, defaultValue = true) {
+    const raw = this.getAttribute(name);
+    if (raw === null) return defaultValue;
+
+    const normalized = String(raw).trim().toLowerCase();
+    if (['false', '0', 'off', 'no'].includes(normalized)) return false;
+    if (['true', '1', 'on', 'yes', ''].includes(normalized)) return true;
+
+    return defaultValue;
+  }
+
+  render() {
+    const title = this.getAttribute('title') || 'Case Title';
+    const shortDesc = this.getAttribute('short-desc') || '';
+    const readTime = this.getAttribute('read-time') || '';
+    const thumbSrc = this.getAttribute('thumb-src') || '';
+    const thumbCategory = this.getAttribute('thumb-category') || 'mobile';
+    const thumbBrand = this.getAttribute('thumb-brand') || 'apple';
+    const thumbModel = this.getAttribute('thumb-model') || 'Apple iPhone 12';
+    const thumbColor = this.getAttribute('thumb-color') || 'Black';
+    const thumbDeviceSrc = this.getAttribute('thumb-device-src') || '';
+    const thumbCustomOnly = this.hasAttribute('thumb-custom-only');
+    const aspectRatio = this.getAttribute('aspect-ratio');
+    const showTitle = this.parseToggleAttr('show-title', true);
+    const showShortDesc = this.parseToggleAttr('show-short-desc', true);
+    const showReadTime = this.parseToggleAttr('show-read-time', true);
+    const showThumbnail = this.parseToggleAttr('show-thumbnail', true);
+
+    const isProtected = this.hasAttribute('is-protected');
+    const isUnlocked = this.hasAttribute('is-unlocked');
+    const hasVideo = this.hasAttribute('has-video');
+    const hasRepo = this.hasAttribute('has-repo');
+    const hasLive = this.hasAttribute('has-live');
+
+    const isLocked = isProtected && !isUnlocked;
+
+    // Frame Logic
+    if (thumbCustomOnly && aspectRatio) {
+      this.thumbWrapper.style.aspectRatio = aspectRatio.replace(':', ' / ');
+    } else {
+      this.thumbWrapper.style.removeProperty('aspect-ratio');
+    }
+
+    this.thumbWrapper.style.setProperty('--device-h-gallery', this.getCategoryHeight(thumbCategory));
+
+    // Thumbnail atom
+    this.thumbWrapper.setAttribute('screen-image', thumbSrc);
+    this.thumbWrapper.setAttribute('category', thumbCategory);
+    this.thumbWrapper.setAttribute('brand', thumbBrand);
+    this.thumbWrapper.setAttribute('model', thumbModel);
+    this.thumbWrapper.setAttribute('color', thumbColor);
+    if (thumbDeviceSrc) {
+      this.thumbWrapper.setAttribute('device-src', thumbDeviceSrc);
+    } else {
+      this.thumbWrapper.removeAttribute('device-src');
+    }
+    if (thumbCustomOnly) {
+      this.thumbWrapper.setAttribute('custom-only', '');
+    } else {
+      this.thumbWrapper.removeAttribute('custom-only');
+    }
+    this.thumbWrapper.setAttribute('max-height', 'var(--device-h-gallery, 55vh)');
+    this.thumbWrapper.setAttribute('aria-label', `Thumbnail for ${title}`);
+    this.thumbWrapper.classList.toggle('locked-thumb', isLocked);
+    this.thumbWrapper.style.display = showThumbnail ? 'inline-flex' : 'none';
+    if (showThumbnail) {
+      this.thumbWrapper.setAttribute('tabindex', '0');
+      this.thumbWrapper.setAttribute('role', 'button');
+      this.thumbWrapper.removeAttribute('aria-hidden');
+    } else {
+      this.thumbWrapper.removeAttribute('tabindex');
+      this.thumbWrapper.removeAttribute('role');
+      this.thumbWrapper.setAttribute('aria-hidden', 'true');
+    }
+
+    // Text
+    const titleEl = this.shadowRoot.querySelector('.gallery-item-title');
+    this.shadowRoot.querySelector('.title-text').textContent = isLocked ? 'Protected Case' : title;
+    titleEl.style.display = showTitle ? 'flex' : 'none';
+    
+    const descEl = this.shadowRoot.querySelector('.gallery-item-shortdesc');
+    descEl.textContent = isLocked ? 'Protected content placeholder.' : shortDesc;
+    descEl.classList.toggle('locked-shortdesc', isLocked);
+    descEl.style.display = showShortDesc ? 'block' : 'none';
+
+    // Read Time
+    const readTimeEl = this.shadowRoot.querySelector('.gallery-read-time');
+    this.shadowRoot.querySelector('.read-time-text').textContent = readTime;
+    readTimeEl.style.display = (!showReadTime || isLocked || !readTime) ? 'none' : 'flex';
+
+    // Lock Icon
+    const lockIcon = this.shadowRoot.querySelector('.lock-icon');
+    if (isProtected) {
+      lockIcon.setAttribute('name', isUnlocked ? 'lock-open' : 'lock-closed');
+      lockIcon.style.display = 'inline-flex';
+    } else {
+      lockIcon.style.display = 'none';
+    }
+
+    // Pills
+    const pillsContainer = this.shadowRoot.querySelector('.gallery-item-pills');
+    pillsContainer.innerHTML = '';
+    if (!isLocked) {
+      const t = typeof window.t === 'function' ? window.t : (k) => k;
+      if (hasVideo) pillsContainer.innerHTML += `<ds-pill label="${t('pitch')}"></ds-pill>`;
+      if (hasRepo) pillsContainer.innerHTML += `<ds-pill label="${t('repo')}"></ds-pill>`;
+      if (hasLive) pillsContainer.innerHTML += `<ds-pill label="${t('demo')}"></ds-pill>`;
+    }
+  }
+}
+
+if (!customElements.get('ds-gallery-item')) {
+  customElements.define('ds-gallery-item', GalleryItem);
+}