@portfoliablejs/valence 0.1.0

package/src/stories/atoms/KBD/kbd.css

@@ -0,0 +1,110 @@
+:host {
+  display: inline-flex;
+}
+
+kbd {
+  font-family: var(--font-family);
+  
+  /* Sub-atomic Property Overrides with Semantic Token Fallbacks */
+  background: var(--ds-kbd-bg, var(--color-surface));
+  border: var(--ds-kbd-border-width, var(--border-width-thin)) 
+          var(--border-style-solid) 
+          var(--ds-kbd-border-color, var(--color-kbd-border));
+  border-radius: var(--ds-kbd-radius, var(--radius-sm));
+  
+  /* Layout Constraints */
+  padding: 3px 6px;
+  font-weight: 600;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-xs);
+  line-height: 1;
+  box-sizing: border-box;
+
+  /* Font size scaling with system large-text multiplier */
+  font-size: calc(10px * var(--font-scale-multiplier, 1));
+  
+  /* Light Mode baseline contrast */
+  color: var(--color-text-secondary); 
+}
+
+.key {
+  text-transform: uppercase;
+}
+
+/* --- DARK MODE CONFIGURATION --- */
+:host([a11y-dark-mode]) kbd {
+  background: var(--ds-kbd-bg, var(--color-card-bg));
+  border-color: var(--ds-kbd-border-color, var(--color-kbd-border));
+  color: var(--color-text-primary) !important; /* Fixed: Resolves dark mode contrast failure */
+}
+
+/* Inverted variant for dark tooltips */
+:host([variant="inverted"]) kbd {
+  background: var(--ds-kbd-bg, var(--color-overlay-light));
+  border-color: var(--ds-kbd-border-color, var(--color-tooltip-kbd-border));
+  color: var(--color-white); 
+}
+
+/* --- LAYOUT CLEANUP --- */
+#combo-container:empty {
+  display: none;
+}
+
+/* ==========================================================================
+   ACCESSIBILITY OVERRIDES MATRIX (Universal Safari Shadow-Piercing)
+   ========================================================================== */
+
+/* --- HIGH CONTRAST CONFIGURATION (WCAG AAA Compliance) --- */
+:host([a11y-high-contrast]) kbd {
+  background: #000000 !important;
+  color: #FFFFFF !important;
+  border: var(--border-width-thin) var(--border-style-solid) #FFFFFF !important;
+}
+
+/* --- DYSLEXIA FONT OVERRIDE --- */
+:host([a11y-dyslexia]) kbd {
+  font-family: "Comic Sans MS", "Comic Sans", cursive, sans-serif !important;
+  letter-spacing: 0.05em !important;
+  word-spacing: 0.1em !important;
+}
+
+/* --- BULLETPROOF ZERO-DURATION REDUCED MOTION --- */
+@media (prefers-reduced-motion: reduce) {
+  kbd, * {
+    transition-duration: 0s !important;
+    transition-delay: 0s !important;
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+
+:host([a11y-reduce-motion]) kbd,
+:host([a11y-reduce-motion]) * {
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+}
+
+/* ==========================================================================
+   ACCESSIBILITY: FORCED COLORS / WINDOWS HIGH CONTRAST MODE
+   ========================================================================== */
+
+/* 1. Attribute Reflected State (Storybook / DOM Toggle) */
+:host([a11y-forced-colors]) kbd {
+  forced-color-adjust: none !important;
+  background: Canvas !important;
+  color: CanvasText !important;
+  border: var(--border-width-thin) var(--border-style-solid) CanvasText !important;
+}
+
+/* 2. Native OS Media Query */
+@media (forced-colors: active) {
+  kbd {
+    forced-color-adjust: none !important;
+    background: Canvas !important;
+    color: CanvasText !important;
+    border: var(--border-width-thin) var(--border-style-solid) CanvasText !important;
+  }
+}

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

@@ -0,0 +1,216 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Atoms/Loader [v1.0.0]/Architecture" />
+
+# `ds-loader`
+
+The `ds-loader` component is a **presentational** Atom designed to render a circular loading spinner with robust accessibility support, semantic layout overrides, and full synchronization with application state shells.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component strictly adheres to the **State In / Events Out** pattern:
+* **State In (Attributes / Properties):** The host application binds primitive attributes (`visible`, `aria-label`, `size`) to control rendering states and dimensions.
+* **Events Out:** As a presentational indicator, the component is completely stateless and passive, emitting no action-oriented custom events. It relies entirely on screen-reader polite announcers inside its Shadow DOM boundaries.
+
+<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-loader"]
+      end
+
+      State -->|"1. State In: visible / aria-label / size"| Component
+
+      %% 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-loader` component is a self-contained visual indicator that completely encapsulates its spinning graphics. It does not expose public slot targets to ensure strict uniformity across visual layout environments.
+
+### 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 circular vectors only; host content is not projected.</td>
+      <td>Renders standard loading spinner graphics inside the shadow root.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Data Model
+
+```typescript
+export interface DsLoaderState {
+  visible: boolean;
+  ariaLabel: string;
+  size?: string;
+}
+
+export interface DsLoaderSubAtomicHooks {
+  '--ds-loader-size'?: string;
+  '--ds-loader-bg'?: string;
+  '--ds-loader-radius'?: string;
+  '--ds-loader-color'?: string;
+  '--ds-loader-shadow'?: 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>`visible`</td>
+      <td>`visible`</td>
+      <td>`boolean`</td>
+      <td>`true`</td>
+      <td>Toggles the structural opacity, pointer-events, and visibility states.</td>
+    </tr>
+    <tr>
+      <td>`ariaLabel`</td>
+      <td>`aria-label`</td>
+      <td>`string`</td>
+      <td>`'Loading'`</td>
+      <td>The accessible text read aloud by screen readers. Automatically delegated down.</td>
+    </tr>
+    <tr>
+      <td>`size`</td>
+      <td>`size`</td>
+      <td>`string`</td>
+      <td>`undefined`</td>
+      <td>Optional layout size override. Maps directly to `--loader-size` token.</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>`None`</td>
+      <td>`None`</td>
+      <td>`None`</td>
+      <td>This component is strictly presentational and does not emit custom events.</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-loader-size`</td>
+      <td>`var(--size-height-lg)`</td>
+      <td>Overrides the outer bounding box dimensions of the spinner.</td>
+    </tr>
+    <tr>
+      <td>`--ds-loader-bg`</td>
+      <td>`var(--color-bg)` / `var(--color-card-bg)`</td>
+      <td>Overrides the circular backdrop surface background color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-loader-radius`</td>
+      <td>`var(--radius-circle)`</td>
+      <td>Overrides the outer container's boundary border-radius.</td>
+    </tr>
+    <tr>
+      <td>`--ds-loader-color`</td>
+      <td>`var(--color-text-primary)`</td>
+      <td>Overrides the active rotating vector stroke foreground color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-loader-shadow`</td>
+      <td>`var(--shadow-md)`</td>
+      <td>Overrides outer backdrop boundary box-shadow dimensions.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Polite Announcements:** Employs an internal `role="status"` and `aria-live="polite"` element wrapper so assistive screen-reader software cleanly triggers updates during buffering.
+* **ARIA Host Scrubbing:** Automatically scrubs the Light DOM host attribute `aria-label` and delegates it into the internal Shadow DOM node, eliminating light validation warnings.
+* **Global Accessibility Propagation:** Integrates `_observeRootAccessibility` to monitor class modifications on the document root element:
+  * `.a11y-dark-mode`: Swaps backdrop shadows and base contrast maps.
+  * `.a11y-high-contrast`: Installs forced binary boundaries and high-contrast borders.
+  * `.a11y-reduce-motion`: Instantly disables rotation keyframe transitions.
+  * `.a11y-forced-colors`: Overrides stroke vectors using active Windows system palette bindings (`CanvasText`).
+
+---
+
+## Examples
+
+### Basic Integration Example
+
+```javascript
+import 'valence/ds-loader';
+
+const loader = document.createElement('ds-loader');
+loader.setAttribute('visible', 'true');
+loader.setAttribute('aria-label', 'Video study resources are buffering...');
+
+// Clean custom property style overrides
+loader.style.setProperty('--ds-loader-bg', 'var(--color-surface-card)');
+loader.style.setProperty('--ds-loader-color', 'var(--color-accent-blue)');
+
+document.body.appendChild(loader);
+```

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

@@ -0,0 +1,66 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Atoms/Loader [v1.0.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-20
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational loading indicator spinner (`ds-loader`) featuring responsive CSS transitions, complete custom property hooks, and advanced aria-label scrubbing.
+
+<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-loader`</td>
+      <td>Initial stable implementation of the SVG buffering spinner.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-loader`</td>
+      <td>Flexible CSS Custom Property mapping for layout control, including sizing, background, border-radius, stroke color, and shadow overrides.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`_observeRootAccessibility`</td>
+      <td>Integrates passive root class observer syncing dark mode, high contrast, dyslexia, reduce-motion, and forced-colors states.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`Loader.stories.js`</td>
+      <td>Refactored Storybook sub-atomic property mappings to bind to standardized `--ds-loader-*` design token custom hooks instead of the generic `--custom-*` overrides.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Circular Loader Atom:** Introduced `<ds-loader>` as a stateless, presentational spinner built for buffering or resource loading transitions.
+- **Root Accessibility Syncing:** Built-in `MutationObserver` automatically synchronizes viewport visual preferences directly onto host attributes.
+- **Thematic Style Customizations:** Bound border-radius, background backdrop, rotating spinner stroke color, and box-shadow variables to the standardized `--ds-loader-*` naming layout.
+- **Storybook Integration:** Created interactive controls and CSF3 story parameters inside `Loader.stories.js`.
+
+### Fixed
+- **Sub-Atomic Story Mapping:** Resolved broken style mappings in the Storybook render pipeline by binding props to the exact `--ds-loader-radius`, `--ds-loader-bg`, `--ds-loader-color`, and `--ds-loader-shadow` custom hooks.
+
+---
+
+*This changelog is specific to the `<ds-loader>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/atoms/Loader/Loader.js

@@ -0,0 +1,88 @@
+import css from './loader.css?inline';
+
+export class Loader extends HTMLElement {
+  static get observedAttributes() {
+    return ['visible', 'aria-label', 'size'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    // Single line compression eliminates anonymous whitespace rendering text-nodes
+    this.shadowRoot.innerHTML = `<style>${css}</style><div class="video-loader" role="status" aria-live="polite"><svg viewBox="0 0 50 50" class="spinner" aria-hidden="true"><circle cx="25" cy="25" r="20" fill="none" stroke="currentColor" stroke-width="5" stroke-linecap="round"></circle></svg><span class="sr-only" style="position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); border: 0;"></span></div>`;
+  }
+
+  connectedCallback() {
+    this.loaderEl = this.shadowRoot.querySelector('.video-loader');
+    this.srOnlyEl = this.shadowRoot.querySelector('.sr-only');
+    this.updateAttributes();
+    this._observeRootAccessibility();
+  }
+
+  disconnectedCallback() {
+    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.loaderEl && oldValue !== newValue) {
+      this.updateAttributes();
+    }
+  }
+
+  /**
+   * 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-focus-mode', root.classList.contains('a11y-focus-mode'));
+      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 visible = this.getAttribute('visible') !== 'false';
+    const ariaLabel = this.getAttribute('aria-label') || 'Loading';
+    const size = this.getAttribute('size');
+
+    if (visible) {
+      this.loaderEl.removeAttribute('aria-hidden');
+    } else {
+      this.loaderEl.setAttribute('aria-hidden', 'true');
+    }
+
+    if (size) {
+      this.style.setProperty('--loader-size', size.endsWith('px') ? size : `${size}px`);
+    }
+
+    // --- ARIA DELEGATION & HOST MARKUP SCRUBBING ---
+    if (this.srOnlyEl) {
+      this.srOnlyEl.textContent = ariaLabel;
+    }
+    if (ariaLabel) {
+      this.loaderEl.setAttribute('aria-label', ariaLabel);
+      this.removeAttribute('aria-label'); // Keeps outer light DOM tree validation compliant
+    }
+  }
+}
+
+if (!customElements.get('ds-loader')) {
+  customElements.define('ds-loader', Loader);
+}

package/src/stories/atoms/Loader/Loader.stories.js

@@ -0,0 +1,130 @@
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { expect } from 'storybook/test';
+import './Loader';
+
+/**
+ * Global component definition detail descriptions mapping clean architectural APIs down to layout layers.
+ */
+export default {
+  title: 'Atoms/Loader [v1.0.0]',
+  component: 'ds-loader',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: '`ds-loader` is a circular SVG spinner used to indicate loading or buffering states. It includes `role="status"` and `aria-live="polite"` to ensure screen readers announce the loading state properly.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => html`
+      <div class="canvas-buffer" style="
+        display: flex; 
+        justify-content: center; 
+        align-items: center; 
+        box-sizing: border-box;
+      ">
+        ${Story()}
+      </div>
+    `
+  ],
+  argTypes: {
+    // --- COMPONENT: CORE ---
+    visible: {
+      name: 'visible',
+      description: 'Toggles the opacity and visibility of the loader.',
+      control: 'boolean',
+      table: { category: 'Component: Core', defaultValue: { summary: 'true' } },
+    },
+    ariaLabel: {
+      name: 'ariaLabel',
+      description: 'Crucial accessibility label delegated directly to internal primitives to keep host clean.',
+      control: 'text',
+      table: { category: 'Component: Core', defaultValue: { summary: 'Video is buffering...' } },
+    },
+    size: {
+      name: 'size',
+      description: 'Controls the outer bounding box dimensions of the spinner container.',
+      control: 'text',
+      table: { category: 'Component: Core', defaultValue: { summary: '48px' } },
+    },
+
+    // --- SUB-ATOMIC OVERRIDES ---
+    backgroundColor: {
+      name: 'backgroundColor',
+      description: 'Sub-atomic modifier overriding default backdrop pattern shading.',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-bg)' } },
+    },
+    iconColor: {
+      name: 'iconColor',
+      description: 'Sub-atomic modifier overriding default stroke icon foreground color.',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-text-primary)' } },
+    },
+  },
+  render: (args) => {
+    const customStyles = [
+      args.backgroundColor ? `--ds-loader-bg: ${args.backgroundColor};` : '',
+      args.iconColor ? `--ds-loader-color: ${args.iconColor};` : ''
+    ].join(' ').trim();
+
+    return html`
+      <ds-loader
+        visible=${args.visible ? 'true' : 'false'}
+        aria-label=${ifDefined(args.ariaLabel)}
+        size=${ifDefined(args.size)}
+        style=${ifDefined(customStyles || undefined)}>
+      </ds-loader>
+    `;
+  },
+};
+
+/**
+ * Standard baseline story setup validating content passing, tracking variables, and operational interaction logic.
+ */
+export const DefaultBaseline = {
+  args: {
+    visible: true,
+    ariaLabel: 'Video is buffering...',
+    size: '48px',
+  },
+  play: async ({ canvasElement, step }) => {
+    const component = canvasElement.querySelector('ds-loader');
+
+    await step('Verify structural attributes pass cleanly and host scrubbing executes flawlessly', async () => {
+      expect(component.getAttribute('visible')).toBe('true');
+      expect(component.getAttribute('aria-label')).toBeNull();
+    });
+
+    await step('Verify inner shadow layout primitives receive the delegated attribute and accessible text', async () => {
+      const loaderEl = component.shadowRoot.querySelector('.video-loader');
+      const srOnlyEl = component.shadowRoot.querySelector('.sr-only');
+      
+      expect(loaderEl.getAttribute('aria-label')).toBe('Video is buffering...');
+      expect(srOnlyEl.textContent).toBe('Video is buffering...');
+      expect(loaderEl.getAttribute('role')).toBe('status');
+    });
+  },
+};
+
+/**
+ * Validates state updates when the component enters a hidden configuration.
+ */
+export const HiddenState = {
+  args: {
+    ...DefaultBaseline.args,
+    visible: false,
+    ariaLabel: 'Content loaded',
+  },
+  play: async ({ canvasElement, step }) => {
+    const component = canvasElement.querySelector('ds-loader');
+
+    await step('Verify hidden aria state applied to internal shadow primitive', async () => {
+      const loaderEl = component.shadowRoot.querySelector('.video-loader');
+      expect(loaderEl.getAttribute('aria-hidden')).toBe('true');
+    });
+  },
+};