@portfoliablejs/valence 0.1.0

package/src/stories/atoms/Tab/Tab.Architecture.mdx

@@ -0,0 +1,255 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Atoms/Tab [v1.0.0]/Architecture" />
+
+# `ds-tab`
+
+The `ds-tab` component is an interactive, presentational **controlled** Atom designed to render tab triggers inside tablist widgets. It includes native key event hooks, supports dual slot/attribute label configuration, handles disabled states, and implements 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 attributes (`label`, `active`, `disabled`, `aria-label`) to render label contents, toggle selection highlights, or block interaction events.
+* **Events Out (`ds-tab-click`):** Captures mouse clicks to dispatch unified cross-boundary events indicating which tab index has been focused and triggered.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host Application / App Shell"]
+          direction TB
+          State["State Manager / Component Host"]
+      end
+
+      subgraph WebComp["Valence Web Component"]
+          Component["ds-tab"]
+      end
+
+      State -->|"1. State In: label / active / disabled"| Component
+      Component -->|"2. Event Out: ds-tab-click"| 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
+`} />
+
+---
+
+## Slot Architecture
+
+The `ds-tab` component exposes its default slot to receive raw strings or HTML tags for visual layout labels. When a direct `label` attribute is defined on the host custom element, it completely overrides the projected slot contents.
+
+### 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>Text / HTML Subtree</td>
+      <td>Primary text or icon label projected inside the tab button wrapper.</td>
+      <td>Falls back to the `label` attribute or remains empty.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Data Model
+
+```typescript
+export interface DsTabState {
+  label?: string;
+  active: boolean;
+  disabled: boolean;
+  ariaLabel?: string;
+}
+
+export interface DsTabSubAtomicHooks {
+  '--ds-tab-bg'?: string;
+  '--ds-tab-color'?: string;
+  '--ds-tab-font'?: string;
+  '--ds-tab-padding'?: string;
+  '--ds-tab-radius'?: string;
+  '--ds-tab-hover-color'?: string;
+  '--ds-tab-hover-bg'?: string;
+  '--ds-tab-active-color'?: string;
+  '--ds-tab-active-bg'?: 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>`label`</td>
+      <td>`label`</td>
+      <td>`string`</td>
+      <td>`undefined`</td>
+      <td>Custom text string mapped to button content. Overrides slot projections.</td>
+    </tr>
+    <tr>
+      <td>`active`</td>
+      <td>`active`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Toggles active visualization. Sets `aria-selected` and forces `tabindex="0"`.</td>
+    </tr>
+    <tr>
+      <td>`disabled`</td>
+      <td>`disabled`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Disables clicks, strips focus maps, and sets `aria-disabled`.</td>
+    </tr>
+    <tr>
+      <td>`ariaLabel`</td>
+      <td>`aria-label`</td>
+      <td>`string`</td>
+      <td>`undefined`</td>
+      <td>Accessible tag description delegated down into internal buttons.</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-tab-click`</td>
+      <td>`true` / `true`</td>
+      <td>`{ active: boolean, label: string }`</td>
+      <td>Fires on user click interactions, passing current states 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-tab-bg`</td>
+      <td>`transparent`</td>
+      <td>Overrides baseline tab container background color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-color`</td>
+      <td>`var(--color-text-secondary)`</td>
+      <td>Overrides baseline label text color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-font`</td>
+      <td>`var(--font-family)`</td>
+      <td>Overrides label text font family.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-padding`</td>
+      <td>`var(--space-xs) var(--space-md)`</td>
+      <td>Overrides baseline container margins.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-radius`</td>
+      <td>`var(--radius-md)`</td>
+      <td>Overrides boundary corner radius curves.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-hover-color`</td>
+      <td>`var(--color-black)`</td>
+      <td>Overrides text color when hovered.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-hover-bg`</td>
+      <td>`var(--color-gray-xlight)`</td>
+      <td>Overrides background color when hovered.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-active-color`</td>
+      <td>`var(--color-white)`</td>
+      <td>Overrides active text foreground colors.</td>
+    </tr>
+    <tr>
+      <td>`--ds-tab-active-bg`</td>
+      <td>`var(--color-black)`</td>
+      <td>Overrides active backdrop background colors.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Semantics & Focusing:** Employs an internal `<button>` with `role="tab"` to handle focus paths correctly. Tab index is set to `0` (active) and `-1` (inactive) for standard keyboard focus flows.
+* **ARIA Host Scrubbing:** Automatically purges Light DOM `aria-label` tags and projects them cleanly onto the focusable button.
+* **Global Access Syncing:** Uses a `MutationObserver` on the HTML root to synchronize visual settings:
+  * `.a11y-dark-mode`: Swaps inactive font palettes and maps active containers to pure white.
+  * `.a11y-high-contrast`: Enforces clear AAA solid fills with inverted text.
+  * `.a11y-dyslexia`: Forces Comic Sans MS font overrides.
+  * `.a11y-reduce-motion`: Disables transitions.
+  * `.a11y-forced-colors`: Overrides backgrounds via system `Canvas` and selected fills via `Highlight`.
+
+---
+
+## Examples
+
+### Basic Integration Example
+
+```javascript
+import 'valence/ds-tab';
+
+const tab = document.createElement('ds-tab');
+tab.setAttribute('label', 'Analytics HUD');
+tab.setAttribute('active', 'true');
+tab.setAttribute('aria-label', 'View system statistics');
+
+// Clean sub-atomic overrides
+tab.style.setProperty('--ds-tab-radius', '4px');
+tab.style.setProperty('--ds-tab-active-bg', 'var(--color-success)');
+
+tab.addEventListener('ds-tab-click', (e) => {
+  console.log('Tab selected. Value:', e.detail.label);
+});
+
+document.body.appendChild(tab);
+```

package/src/stories/atoms/Tab/Tab.Changelog.mdx

@@ -0,0 +1,67 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Atoms/Tab [v1.0.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-20
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational navigation control trigger (`ds-tab`) featuring native button integration, high-contrast states, custom click events, and root class accessibility syncing.
+
+<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-tab`</td>
+      <td>Initial stable component registration with compressed shadow layouts and native button element integration.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-tab`</td>
+      <td>Fires standardized cross-boundary `ds-tab-click` event on click interactions.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`_observeRootAccessibility`</td>
+      <td>Integrates root class observer syncing dark mode, high contrast, dyslexia, reduce-motion, and Windows Forced Colors.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`Tab.stories.js`</td>
+      <td>Remapped custom style overrides in Storybook config to write precise `--ds-tab-*` tokens instead of generic `--custom-*` variables.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Interactive Tab Trigger Atom:** Created `<ds-tab>` as a stateless, controlled pagination button.
+- **Robust Accessibility:** Features keyboard tab paths, aria-selected and tabindex reflections, and proper light DOM aria-label scrubbing.
+- **Root Preference Synchronization:** MutationObserver on document roots reflects global setting cascades downstream as boolean host flags.
+- **Thematic Overrides:** Bound diameter dimensions, border-radius, background fill, active background, and hover background color tokens to the standardized `--ds-tab-*` naming layout.
+- **Storybook Workspace:** Authored interactive controls and CSF3 story parameters in `Tab.stories.js`.
+
+### Fixed
+- **Sub-Atomic Story Mapping:** Synchronized Storybook override controllers to output precise `--ds-tab-size`, `--ds-tab-bg`, and `--ds-tab-active-bg` custom styles.
+
+---
+
+*This changelog is specific to the `<ds-tab>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/atoms/Tab/Tab.js

@@ -0,0 +1,130 @@
+import css from './tab.css?inline';
+
+export class Tab extends HTMLElement {
+  static get observedAttributes() {
+    return ['label', 'active', 'aria-label', 'disabled'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    // CRITICAL: Single line compression to eliminate anonymous whitespace rendering text-nodes
+    this.shadowRoot.innerHTML = `<style>${css}</style><button class="combo-tab" role="tab" type="button"><slot></slot></button>`;
+  }
+
+  connectedCallback() {
+    this.btnEl = this.shadowRoot.querySelector('button');
+    this._handleClick = this._handleClick.bind(this);
+
+    if (this.btnEl) {
+      this.btnEl.addEventListener('click', this._handleClick);
+    }
+
+    this.updateAttributes();
+    this._observeRootAccessibility();
+  }
+
+  disconnectedCallback() {
+    if (this.btnEl) {
+      this.btnEl.removeEventListener('click', this._handleClick);
+    }
+    if (this._themeObserver) {
+      this._themeObserver.disconnect();
+    }
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    // GUARD: Prevents infinite loop reflection when internal scrubbing occurs
+    if (name === 'aria-label' && newValue === null) return;
+
+    if (this.btnEl && oldValue !== newValue) {
+      this.updateAttributes();
+    }
+  }
+
+  /**
+   * Dispatches unified cross-boundary event when tab button trigger fires
+   */
+  _handleClick(e) {
+    if (this.hasAttribute('disabled')) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+
+    this.dispatchEvent(new CustomEvent('ds-tab-click', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        active: this.hasAttribute('active') && this.getAttribute('active') !== 'false',
+        label: this.getAttribute('label') || ''
+      }
+    }));
+  }
+
+  /**
+   * Public method to programmatically set keyboard focus to the internal tab trigger
+   */
+  focusTab() {
+    if (this.btnEl) {
+      this.btnEl.focus();
+    }
+  }
+
+  /**
+   * Tracks root <html> modifications to circumvent cross-browser Safari :host-context() bugs
+   */
+  _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-dyslexia', root.classList.contains('a11y-dyslexia'));
+      this.toggleAttribute('a11y-large-text', root.classList.contains('a11y-large-text'));
+      this.toggleAttribute('a11y-reduce-motion', root.classList.contains('a11y-reduce-motion'));
+      this.toggleAttribute('a11y-forced-colors', root.classList.contains('a11y-forced-colors'));
+    };
+
+    sync(); // Initial execution
+    this._themeObserver = new MutationObserver(sync);
+    this._themeObserver.observe(root, {
+      attributes: true,
+      attributeFilter: ['class'],
+    });
+  }
+
+  updateAttributes() {
+    const isActive = this.hasAttribute('active') && this.getAttribute('active') !== 'false';
+    const label = this.getAttribute('label');
+    const disabled = this.hasAttribute('disabled');
+    const ariaLabel = this.getAttribute('aria-label');
+
+    // Structural class management & ARIA tab semantics
+    this.btnEl.className = `combo-tab${isActive ? ' active' : ''}`;
+    this.btnEl.setAttribute('aria-selected', isActive ? 'true' : 'false');
+    this.btnEl.setAttribute('tabindex', isActive ? '0' : '-1');
+
+    if (disabled) {
+      this.btnEl.setAttribute('disabled', '');
+      this.btnEl.setAttribute('aria-disabled', 'true');
+    } else {
+      this.btnEl.removeAttribute('disabled');
+      this.btnEl.removeAttribute('aria-disabled');
+    }
+
+    // Direct label attribute fallback if slotted light DOM content isn't passed
+    if (label) {
+      this.btnEl.textContent = label;
+    }
+
+    // --- ARIA DELEGATION & HOST MARKUP SCRUBBING ---
+    if (ariaLabel) {
+      this.btnEl.setAttribute('aria-label', ariaLabel);
+      this.removeAttribute('aria-label'); // Keeps outer light DOM tree validation compliant
+    }
+  }
+}
+
+if (!customElements.get('ds-tab')) {
+  customElements.define('ds-tab', Tab);
+}

package/src/stories/atoms/Tab/Tab.stories.js

@@ -0,0 +1,165 @@
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { expect, fn, userEvent } from 'storybook/test';
+import './Tab';
+
+/**
+ * Global component definition detail descriptions mapping clean architectural APIs down to layout layers.
+ */
+export default {
+  title: 'Atoms/Tab [v1.0.0]',
+  component: 'ds-tab',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'An interactive navigation tab control designed for switching views within a tablist widget. Fully accessible with dynamic `role="tab"`, `aria-selected`, and `tabindex` state tracking.',
+      },
+    },
+  },
+  // FIX: Added role="tablist" and aria-label to satisfy axe-core's aria-required-parent rule
+  decorators: [
+    (Story) => html`
+      <div 
+        class="canvas-buffer" 
+        role="tablist" 
+        aria-label="Tab Navigation Container" 
+        style="
+          display: flex; 
+          justify-content: center; 
+          align-items: center; 
+          box-sizing: border-box;
+        ">
+        ${Story()}
+      </div>
+    `
+  ],
+  argTypes: {
+    // --- COMPONENT: CORE ---
+    label: {
+      name: 'label',
+      description: 'Slotted template content or attribute label delivered cleanly to internal primitives.',
+      control: 'text',
+      table: { category: 'Component: Core' },
+    },
+    active: {
+      name: 'active',
+      description: 'Controls the selected visual state and aria-selected tracking parameter.',
+      control: 'boolean',
+      table: { category: 'Component: Core', defaultValue: { summary: 'false' } },
+    },
+    disabled: {
+      name: 'disabled',
+      description: 'Forces non-actionable interaction parameters across the tab button surface.',
+      control: 'boolean',
+      table: { category: 'Component: Core', defaultValue: { summary: 'false' } },
+    },
+    ariaLabel: {
+      name: 'ariaLabel',
+      description: 'Crucial accessibility label delegated directly to internal primitives to keep host clean.',
+      control: 'text',
+      table: { category: 'Component: Core' },
+    },
+
+    // --- SUB-ATOMIC PROPS ---
+    radius: {
+      name: 'radius',
+      description: 'Sub-atomic modifier overriding corner bounding geometry variables (--ds-tab-radius).',
+      control: 'text',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--radius-md)' } },
+    },
+    textColor: {
+      name: 'textColor',
+      description: 'Sub-atomic modifier overriding default baseline tab text color (--ds-tab-color).',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-text-secondary)' } },
+    },
+    activeColor: {
+      name: 'activeColor',
+      description: 'Sub-atomic modifier overriding active state background shading (--ds-tab-active-bg).',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-black)' } },
+    },
+  },
+  args: { 
+    onClick: fn() 
+  },
+  render: (args) => {
+    // Map Sub-Atomic Override Properties cleanly without polluting component markup structures
+    const customStyles = [
+      args.radius ? `--ds-tab-radius: ${args.radius};` : '',
+      args.textColor ? `--ds-tab-color: ${args.textColor};` : '',
+      args.activeColor ? `--ds-tab-active-bg: ${args.activeColor};` : ''
+    ].join(' ').trim();
+
+    return html`
+      <ds-tab
+        label=${ifDefined(args.label)}
+        ?active=${args.active}
+        ?disabled=${args.disabled}
+        aria-label=${ifDefined(args.ariaLabel)}
+        style=${ifDefined(customStyles || undefined)}
+        @ds-tab-click=${args.onClick}>
+      </ds-tab>
+    `;
+  },
+};
+
+/**
+ * Standard baseline story setup validating content passing, tracking variables, and operational interaction logic.
+ */
+export const Default = {
+  args: {
+    label: 'Project Dashboard',
+    active: false,
+    disabled: false,
+    ariaLabel: 'Project Dashboard View Tab',
+  },
+  play: async ({ canvasElement, step, args }) => {
+    const component = canvasElement.querySelector('ds-tab');
+
+    await step('Verify structural parameters pass cleanly and host scrubbing executes flawlessly', async () => {
+      expect(component.hasAttribute('active') && component.getAttribute('active') !== 'false').toBe(false);
+      expect(component.getAttribute('aria-label')).toBeNull(); // Confirms attribute host-purging worked
+    });
+
+    await step('Verify inner shadow layout primitives receive delegated ARIA attributes and tabindex', async () => {
+      const buttonEl = component.shadowRoot.querySelector('button');
+      expect(buttonEl.getAttribute('role')).toBe('tab');
+      expect(buttonEl.getAttribute('aria-selected')).toBe('false');
+      expect(buttonEl.getAttribute('tabindex')).toBe('-1');
+      expect(buttonEl.getAttribute('aria-label')).toBe('Project Dashboard View Tab');
+      expect(buttonEl.textContent).toBe('Project Dashboard');
+    });
+
+    await step('Verify click events dispatch the custom ds-tab-click event payload', async () => {
+      const buttonEl = component.shadowRoot.querySelector('button');
+      await userEvent.click(buttonEl);
+      expect(args.onClick).toHaveBeenCalled();
+    });
+  },
+};
+
+/**
+ * Active tab state configuration verifying active CSS classes, aria-selected="true", and tabindex="0".
+ */
+export const Active = {
+  args: {
+    label: 'Project History',
+    active: true,
+    disabled: false,
+    ariaLabel: 'Project History View Tab',
+  },
+  play: async ({ canvasElement, step }) => {
+    const component = canvasElement.querySelector('ds-tab');
+
+    await step('Verify active ARIA state and focusable tabindex on inner button primitive', async () => {
+      const buttonEl = component.shadowRoot.querySelector('button');
+      expect(buttonEl.classList.contains('active')).toBe(true);
+      expect(buttonEl.getAttribute('aria-selected')).toBe('true');
+      expect(buttonEl.getAttribute('tabindex')).toBe('0');
+      expect(buttonEl.getAttribute('aria-label')).toBe('Project History View Tab');
+    });
+  },
+};