@portfoliablejs/valence 0.1.0

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

@@ -0,0 +1,227 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as CheckStories from './Check.stories';
+
+<Meta title="Atoms/Check [v1.0.0]/Architecture"/>
+
+# `ds-check`
+
+The `ds-check` component is a **controlled / presentational** Atom designed to render vector graphic selection indicators with optional surface background containers, built-in keyboard/click toggling, and accessibility synchronization.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component strictly adheres to the **State In / Events Out** pattern:
+* **State In (Attributes / Properties):** The host application or parent component binds primitive attributes (`selected`, `has-background`, `disabled`, `aria-label`) to control rendering state.
+* **User Interactions:** Click and keyboard events (`Space`, `Enter`) dynamically toggle state and update internal accessibility attributes (`aria-checked`, `aria-disabled`).
+* **Encapsulated State:** Visual presentation and SVG animation choreography are encapsulated within the Shadow DOM.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host Application / Parent Form"]
+          direction TB
+          State["State Manager / Component Host"]
+      end
+
+      subgraph WebComp["Valence Web Component"]
+          Component["ds-check"]
+      end
+
+      State -->|"1. State In: selected / disabled / has-background"| Component
+      Component -->|"2. Interaction Event: click / keydown"| 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-check` component is a self-contained visual primitive that encapsulates its vector graphics directly inside its Shadow DOM. It does not expose public slots, ensuring uniform geometric alignment, stroke thickness, and animation keyframes across all instances.
+
+### 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 vector graphics only; host text content is not rendered.</td>
+      <td>Renders internal SVG mark</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Data Model
+
+```typescript
+export interface DsCheckState {
+  selected: boolean;
+  hasBackground: boolean;
+  disabled: boolean;
+  ariaLabel?: string;
+}
+
+export interface DsCheckSubAtomicHooks {
+  '--ds-check-size'?: string;
+  '--ds-check-color'?: string;
+  '--ds-check-bg'?: string;
+  '--ds-check-border-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>`selected`</td>
+      <td>`selected`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Toggles active selection state and animated checkmark visibility.</td>
+    </tr>
+    <tr>
+      <td>`hasBackground`</td>
+      <td>`has-background`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Activates outer surface container background and structural border ring.</td>
+    </tr>
+    <tr>
+      <td>`disabled`</td>
+      <td>`disabled`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>Suppresses user interactions, removes tab focus, and applies opacity token.</td>
+    </tr>
+    <tr>
+      <td>`ariaLabel`</td>
+      <td>`aria-label`</td>
+      <td>`string`</td>
+      <td>`undefined`</td>
+      <td>Accessibility label delegated to component role contract.</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>`click`</td>
+      <td>`true` / `true`</td>
+      <td>`MouseEvent`</td>
+      <td>Native click interaction toggles selection state when not disabled.</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-check-size`</td>
+      <td>`var(--size-icon-sm)`</td>
+      <td>Overrides outer bounding box dimensions (`width` and `height`).</td>
+    </tr>
+    <tr>
+      <td>`--ds-check-color`</td>
+      <td>`var(--color-accent)`</td>
+      <td>Overrides checkmark SVG stroke vector color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-check-bg`</td>
+      <td>`var(--color-surface)`</td>
+      <td>Overrides background surface container fill when `has-background` is active.</td>
+    </tr>
+    <tr>
+      <td>`--ds-check-border-color`</td>
+      <td>`var(--color-gray-light)`</td>
+      <td>Overrides container border ring color when `has-background` is active.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **Role Delegation:** Automatically initializes `role="checkbox"` on the host custom element.
+* **ARIA Attribute Sync:** Real-time updates sync `aria-checked` and `aria-disabled` based on host attribute changes.
+* **Keyboard Interaction:** Supports full keyboard navigation with `Tab` focusing (`tabindex="0"`) and trigger handling via `Space`, `Spacebar`, or `Enter` keys.
+* **Global Accessibility Propagation:** Integrates `_observeRootAccessibility` using a `MutationObserver` on `document.documentElement` to synchronize global accessibility flags:
+  * `.a11y-dark-mode`: Adjusts surface boundary contrast.
+  * `.a11y-high-contrast`: Enforces strict binary contrast overrides.
+  * `.a11y-forced-colors`: Maps system active `Highlight` and `GrayText` palettes for Windows High Contrast Mode.
+  * `.a11y-reduce-motion`: Completely suppresses transition durations and delays for reduced motion preferences.
+
+---
+
+## Examples
+
+### Basic Integration Example
+
+```javascript
+import 'valence/ds-check';
+
+const check = document.createElement('ds-check');
+check.setAttribute('selected', '');
+check.setAttribute('has-background', '');
+check.setAttribute('aria-label', 'Accept terms and conditions');
+
+// Apply sub-atomic style overrides via CSS custom properties
+check.style.setProperty('--ds-check-color', 'var(--color-success)');
+check.style.setProperty('--ds-check-size', '24px');
+
+check.addEventListener('click', () => {
+  console.log('Check toggled. Is selected:', check.hasAttribute('selected'));
+});
+
+document.body.appendChild(check);
+```

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

@@ -0,0 +1,73 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Atoms/Check [v1.0.0]/Changelog"/>
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-16
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational selection indicator component (`ds-check`) featuring optional background container framing, smooth scale/opacity SVG transitions, and full keyboard navigation.
+
+<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-check`</td>
+      <td>Initial stable release of custom checkbox icon component with vector animation paths.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`ds-check`</td>
+      <td>Support for the `has-background` attribute to render framing border containers.</td>
+    </tr>
+    <tr>
+      <td>`Added`</td>
+      <td>`_observeRootAccessibility`</td>
+      <td>Integrates root class observer syncing dark mode, contrast, dyslexia, reduce-motion, and Windows Forced Colors.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`ds-check`</td>
+      <td>Compressed inner HTML template strings to completely eliminate whitespace text nodes inside Shadow DOM boundaries.</td>
+    </tr>
+    <tr>
+      <td>`Fixed`</td>
+      <td>`ds-check`</td>
+      <td>Disabled focus and keyboard click suppression logic to ignore all interaction event triggers when `disabled` is active.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Selection Indicator Atom:** Created `<ds-check>` serving as an animated vector completion checkmark.
+- **Surface Containers:** Smooth scale-opacity check transitions with optional background framing when `has-background` is active.
+- **Root Class Syncing:** MutationObserver on document roots reflects global setting cascades downstream as host element boolean flags.
+- **Thematic Overrides:** Bound outer dimensions, stroke vector color, background container fill, and border ring colors to the standard `--ds-check-*` naming layout.
+- **Storybook Workspace:** Configured complete interactive Controls and detailed CSF3 stories inside `Check.stories.js`.
+
+### Fixed
+- **Shadow DOM Layout Nodes:** Compressed inner Shadow DOM HTML templates on single lines to resolve ghost whitespace layout nodes.
+- **Keyboard & Disabled Focus Handling:** Suppressed keyboard spacebar/enter triggers and automatically assigned `tabindex="-1"` when the `disabled` attribute is present.
+
+---
+
+*This changelog is specific to the `<ds-check>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*

package/src/stories/atoms/Check/Check.js

@@ -0,0 +1,122 @@
+import css from './check.css?inline';
+
+export class DsCheck extends HTMLElement {
+  static get observedAttributes() {
+    return ['selected', 'disabled', 'has-background', 'aria-label'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    
+    // Compressed template string prevents ghost text nodes inside Shadow DOM layouts
+    this.shadowRoot.innerHTML = `<style>${css}</style><div class="check-root"><svg width="100%" height="100%" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg></div>`;
+
+    this._toggleSelected = this._toggleSelected.bind(this);
+    this._handleKeyDown = this._handleKeyDown.bind(this);
+  }
+
+  get disabled() {
+    return this.hasAttribute('disabled');
+  }
+
+  set disabled(value) {
+    this.toggleAttribute('disabled', Boolean(value));
+  }
+
+  get selected() {
+    return this.hasAttribute('selected');
+  }
+
+  set selected(value) {
+    this.toggleAttribute('selected', Boolean(value));
+  }
+
+  get hasBackground() {
+    return this.hasAttribute('has-background');
+  }
+
+  set hasBackground(value) {
+    this.toggleAttribute('has-background', Boolean(value));
+  }
+
+  connectedCallback() {
+    this.updateAttributes();
+    this._observeRootAccessibility();
+
+    this.addEventListener('click', this._toggleSelected);
+    this.addEventListener('keydown', this._handleKeyDown);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('click', this._toggleSelected);
+    this.removeEventListener('keydown', this._handleKeyDown);
+
+    if (this._themeObserver) {
+      this._themeObserver.disconnect();
+    }
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue !== newValue) {
+      if (name === 'selected') {
+        this.setAttribute('aria-checked', this.hasAttribute('selected').toString());
+      } else if (name === 'disabled') {
+        this.setAttribute('aria-disabled', this.hasAttribute('disabled').toString());
+        this.setAttribute('tabindex', this.hasAttribute('disabled') ? '-1' : '0');
+      } else if (name === 'aria-label') {
+        if (newValue) {
+          this.setAttribute('aria-label', newValue);
+        }
+      }
+    }
+  }
+
+  _handleKeyDown(e) {
+    if (this.disabled) return;
+
+    if (e.key === ' ' || e.key === 'Spacebar' || e.key === 'Enter') {
+      e.preventDefault();
+      this._toggleSelected();
+    }
+  }
+
+  _toggleSelected() {
+    if (this.disabled) return;
+
+    this.toggleAttribute('selected');
+    const isSelected = this.hasAttribute('selected');
+    this.setAttribute('aria-checked', isSelected.toString());
+  }
+
+  _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();
+    this._themeObserver = new MutationObserver(sync);
+    this._themeObserver.observe(root, {
+      attributes: true,
+      attributeFilter: ['class'],
+    });
+  }
+
+  updateAttributes() {
+    this.setAttribute('role', 'checkbox');
+    this.setAttribute('tabindex', this.disabled ? '-1' : '0');
+    this.setAttribute('aria-checked', this.hasAttribute('selected').toString());
+    this.setAttribute('aria-disabled', this.disabled.toString());
+  }
+}
+
+if (!customElements.get('ds-check')) {
+  customElements.define('ds-check', DsCheck);
+}

package/src/stories/atoms/Check/Check.stories.js

@@ -0,0 +1,196 @@
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { expect, userEvent, fireEvent } from 'storybook/test';
+
+import './Check';
+
+export default {
+  title: 'Atoms/Check [v1.0.0]',
+  component: 'ds-check',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A minimalist presentational vector graphic atom used to indicate selection or completion states. Features optional background container framing, smooth CSS animations, full keyboard/click toggling, disabled states, and sub-atomic style overrides.',
+      },
+    },
+  },
+  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 ---
+    selected: {
+      name: 'selected',
+      description: 'Toggles the active selection state and animated appearance of the checkmark.',
+      control: 'boolean',
+      table: { category: 'Component: Core', defaultValue: { summary: 'false' } },
+    },
+    hasBackground: {
+      name: 'hasBackground',
+      description: 'Activates an outer surface container background and structural border ring around the checkmark.',
+      control: 'boolean',
+      table: { category: 'Component: Core', defaultValue: { summary: 'false' } },
+    },
+    disabled: {
+      name: 'disabled',
+      description: 'Disables user interactions and applies muted visual opacity tokens.',
+      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 ---
+    color: {
+      name: 'color',
+      description: 'Sub-atomic modifier overriding default SVG stroke vector color (--ds-check-color).',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-accent)' } },
+    },
+    size: {
+      name: 'size',
+      description: 'Sub-atomic modifier overriding outer bounding box dimensions (--ds-check-size).',
+      control: 'text',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--size-icon-sm)' } },
+    },
+    bg: {
+      name: 'bg',
+      description: 'Sub-atomic modifier overriding surface container background color (--ds-check-bg).',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-surface)' } },
+    },
+    borderColor: {
+      name: 'borderColor',
+      description: 'Sub-atomic modifier overriding container border ring color (--ds-check-border-color).',
+      control: 'color',
+      table: { category: 'SUB-ATOMIC PROPS', defaultValue: { summary: 'var(--color-gray-light)' } },
+    },
+  },
+  render: (args) => {
+    const customStyles = [
+      args.color ? `--ds-check-color: ${args.color};` : '',
+      args.size ? `--ds-check-size: ${args.size};` : '',
+      args.bg ? `--ds-check-bg: ${args.bg};` : '',
+      args.borderColor ? `--ds-check-border-color: ${args.borderColor};` : '',
+    ].join(' ').trim();
+
+    return html`
+      <ds-check
+        ?selected=${args.selected}
+        ?has-background=${args.hasBackground}
+        ?disabled=${args.disabled}
+        aria-label=${ifDefined(args.ariaLabel)}
+        style=${ifDefined(customStyles || undefined)}>
+      </ds-check>
+    `;
+  },
+};
+
+/**
+ * Default isolated check icon state.
+ */
+export const Default = {
+  args: {
+    selected: true,
+    hasBackground: false,
+    disabled: false,
+    ariaLabel: 'Toggle task completion',
+  },
+  play: async ({ canvasElement, step }) => {
+    const component = canvasElement.querySelector('ds-check');
+
+    await step('Verify initial selected state and ARIA attributes', async () => {
+      expect(component.hasAttribute('selected')).toBe(true);
+      expect(component.getAttribute('aria-checked')).toBe('true');
+      expect(component.getAttribute('aria-disabled')).toBe('false');
+    });
+
+    await step('Simulate a mouse click to unselect the check', async () => {
+      await userEvent.click(component);
+      expect(component.hasAttribute('selected')).toBe(false);
+      expect(component.getAttribute('aria-checked')).toBe('false');
+    });
+
+    await step('Simulate another click to re-select it', async () => {
+      await userEvent.click(component);
+      expect(component.hasAttribute('selected')).toBe(true);
+      expect(component.getAttribute('aria-checked')).toBe('true');
+    });
+
+    await step('Simulate a keyboard spacebar press to unselect it again', async () => {
+      fireEvent.keyDown(component, { key: ' ', code: 'Space' });
+
+      expect(component.hasAttribute('selected')).toBe(false);
+      expect(component.getAttribute('aria-checked')).toBe('false');
+    });
+  },
+};
+
+/**
+ * Checkmark framed inside a surface container box with border outline.
+ */
+export const WithBackground = {
+  args: {
+    selected: true,
+    hasBackground: true,
+    disabled: false,
+    ariaLabel: 'Checkbox option with surface container',
+  },
+};
+
+/**
+ * Disabled state story validating disabled attributes and interaction suppression.
+ */
+export const Disabled = {
+  args: {
+    selected: true,
+    hasBackground: true,
+    disabled: true,
+    ariaLabel: 'Disabled completed item',
+  },
+  play: async ({ canvasElement, step }) => {
+    const component = canvasElement.querySelector('ds-check');
+
+    await step('Verify initial disabled ARIA attributes and focus prevention', async () => {
+      expect(component.hasAttribute('disabled')).toBe(true);
+      expect(component.getAttribute('aria-disabled')).toBe('true');
+      expect(component.getAttribute('tabindex')).toBe('-1');
+    });
+
+    await step('Verify click events are ignored when disabled', async () => {
+      await userEvent.click(component, { pointerEventsCheck: 0 });
+      expect(component.hasAttribute('selected')).toBe(true);
+    });
+  },
+};
+
+/**
+ * Sub-atomic style override configuration demonstrating all 4 custom hooks.
+ */
+export const CustomStyled = {
+  args: {
+    selected: true,
+    hasBackground: true,
+    disabled: false,
+    ariaLabel: 'Custom success indicator',
+    color: '#ffffff',
+    size: '2.5rem',
+    bg: '#10b981',
+    borderColor: '#059669',
+  },
+};