@pithyjs/ui-kit 0.1.0-beta.0

package/dist/sections/hero/HeroSection.js

@@ -0,0 +1,156 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.hero-section",
+  "title": "<HeroSection> Section Template",
+  "category": "feature"
+}
+*/
+import { captureChildren } from '@pithyjs/core';
+import { Heading } from '../../atoms/content/heading/Heading';
+import { Text } from '../../atoms/content/text/Text';
+import { Image } from '../../atoms/content/image/Image';
+import { PY_CLASS } from '../../shared/common';
+import { captureSlot } from '../../shared/slots';
+import { clampHeadingLevel, validateSpacing, applyContainment, generateSectionHeadingId, } from '../../shared/section';
+import { bindReactive, readReactive, hasReactive, } from '../../shared/clickable';
+import { observeEntrance } from '../entrance';
+const HERO_VARIANTS = ['centered', 'split'];
+/**
+ * Hero section with heading, subtext, and CTA area.
+ *
+ * Two variants: "centered" (stacked, text-centered) and "split"
+ * (image + text side by side). Children are projected into the
+ * actions area for CTA buttons.
+ *
+ * @example
+ * ```html
+ * <HeroSection heading="'Welcome'" subheading="'Build faster'">
+ *   <Button color="'primary'">Get Started</Button>
+ * </HeroSection>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.hero-section","name":"HeroSection","stability":"stable","signature":"(props: HeroSectionProps) => { el: HTMLElement; destroy: () => void }"} */
+export function HeroSection({ variant: rawVariant = 'centered', eyebrow, heading, headingLevel: rawLevel = 1, subheading, imageSrc, imageAlt, imageWidth, imageHeight, spacing: rawSpacing = 'xl', id, }) {
+    const validVariant = HERO_VARIANTS.includes(rawVariant);
+    const resolvedImageSrc = readReactive(imageSrc);
+    const resolvedImageAlt = readReactive(imageAlt);
+    if (import.meta.env?.DEV) {
+        if (!validVariant) {
+            console.warn(`[<HeroSection>] Invalid variant: "${rawVariant}". Expected "centered" or "split". Falling back to "centered".`);
+        }
+        if (resolvedImageSrc && !resolvedImageAlt) {
+            console.warn(`[<HeroSection>] imageSrc provided without imageAlt. Images must have alt text for accessibility.`);
+        }
+        if (resolvedImageSrc && rawVariant !== 'split') {
+            console.warn(`[<HeroSection>] imageSrc is only rendered in the "split" variant. Current variant: "${rawVariant}".`);
+        }
+    }
+    const variant = validVariant ? rawVariant : 'centered';
+    const spacing = validateSpacing('HeroSection', rawSpacing, 'xl');
+    const level = clampHeadingLevel(rawLevel);
+    const disposers = [];
+    // Capture projected children FIRST and clear context so inner component
+    // calls (Heading, Text, Image) don't consume our children.
+    const { el: childFragment, destroy: destroyChildren } = captureChildren();
+    disposers.push(destroyChildren);
+    // Root section element
+    const section = document.createElement('section');
+    section.classList.add('ui-section', 'ui-hero', PY_CLASS[spacing]);
+    if (id)
+        section.id = id;
+    // Inner container with containment
+    const container = document.createElement('div');
+    applyContainment(container);
+    section.appendChild(container);
+    // Create heading via Heading() component — link to section via aria-labelledby
+    const headingId = generateSectionHeadingId('hero', id);
+    const headingComp = Heading({
+        level,
+        align: variant === 'centered' ? 'center' : undefined,
+        text: heading,
+    });
+    const headingEl = headingComp.el;
+    headingEl.id = headingId;
+    section.setAttribute('aria-labelledby', headingId);
+    disposers.push(headingComp.destroy);
+    // Create subheading via Text() component
+    let subheadingComp;
+    if (subheading) {
+        subheadingComp = Text({
+            size: 'xl',
+            color: 'text-muted',
+            align: variant === 'centered' ? 'center' : undefined,
+            text: subheading,
+        });
+        disposers.push(subheadingComp.destroy);
+    }
+    // Text block groups eyebrow + heading + subheading (Close Friends spacing via SCSS)
+    const textBlock = document.createElement('div');
+    textBlock.classList.add('ui-hero-text-block');
+    // Eyebrow label
+    // Optional reactive fields are live-patched, not re-rendered: clearing one to ""
+    // empties the text but leaves the element (and its ~12px flex-gap slot) in place.
+    // Accepted over hide-on-empty — studio edits are transient and the slot is negligible.
+    if (eyebrow) {
+        const eyebrowEl = document.createElement('span');
+        eyebrowEl.classList.add('ui-section-eyebrow');
+        const eyebrowText = eyebrowEl.appendChild(document.createTextNode(''));
+        disposers.push(bindReactive(hasReactive(eyebrow), () => {
+            eyebrowText.nodeValue = readReactive(eyebrow) ?? '';
+        }));
+        textBlock.appendChild(eyebrowEl);
+    }
+    textBlock.appendChild(headingComp.el);
+    if (subheadingComp)
+        textBlock.appendChild(subheadingComp.el);
+    // Actions area
+    const actionsArea = document.createElement('div');
+    actionsArea.classList.add('ui-hero-actions');
+    captureSlot(actionsArea, 'actions');
+    actionsArea.appendChild(childFragment);
+    if (variant === 'split') {
+        // Split layout: content + image side by side
+        container.classList.add('ui-hero-content');
+        container.setAttribute('data-variant', 'split');
+        // Content side
+        const contentSide = document.createElement('div');
+        contentSide.classList.add('ui-hero-text-side');
+        contentSide.appendChild(textBlock);
+        contentSide.appendChild(actionsArea);
+        container.appendChild(contentSide);
+        // Image side
+        if (imageSrc && (typeof imageSrc === 'function' || resolvedImageSrc)) {
+            const imageComp = Image({
+                src: imageSrc,
+                alt: imageAlt,
+                width: imageWidth,
+                height: imageHeight,
+                loading: 'eager',
+                rounded: 'md',
+            });
+            disposers.push(imageComp.destroy);
+            const imageSide = document.createElement('div');
+            imageSide.classList.add('ui-hero-image-side');
+            imageSide.appendChild(imageComp.el);
+            container.appendChild(imageSide);
+        }
+    }
+    else {
+        // Centered variant (default)
+        container.classList.add('ui-hero-content');
+        container.setAttribute('data-variant', 'centered');
+        container.appendChild(textBlock);
+        container.appendChild(actionsArea);
+    }
+    // Entrance animation
+    disposers.push(observeEntrance(section));
+    return {
+        el: section,
+        destroy: () => {
+            for (const dispose of disposers)
+                dispose();
+            section.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=HeroSection.js.map

package/dist/sections/hero/HeroSection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeroSection.js","sourceRoot":"","sources":["../../../src/sections/hero/HeroSection.ts"],"names":[],"mappings":"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"}

package/dist/sections/hero/hero-section.scss

@@ -0,0 +1,211 @@
+/// HeroSection styles
+/// Provides the design layer for centered and split hero layouts.
+/// Friendship spacing: heading↔subheading = Close Friends (sm),
+/// text-block↔CTA = Acquaintances (lg).
+///
+/// @group sections
+
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+@use '../../shared/tokens' as shared;
+@use '../../shared/mixins' as shared-mix;
+
+// ============================================
+// Base
+// ============================================
+
+.ui-hero {
+  // Subtle depth — radial glow behind content
+  position: relative;
+  overflow-inline: clip;
+
+  &::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 50%;
+    // NOTE: translate is physical but the glow is centered symmetrically — RTL is visually identical.
+    translate: -50% -30%;
+    inline-size: 60%;
+    block-size: 60%;
+    border-radius: 50%;
+    background: radial-gradient(
+      ellipse at center,
+      color-mix(in oklch, var(--color-primary) 8%, transparent) 0%,
+      transparent 70%
+    );
+    pointer-events: none;
+    z-index: 0;
+  }
+}
+
+// ============================================
+// Centered variant
+// ============================================
+
+.ui-hero-content[data-variant='centered'] {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  position: relative;
+  z-index: 1;
+}
+
+// Heading → subheading: Close Friends (sm)
+.ui-hero-text-block {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+}
+
+// Constrain centered text for readability
+.ui-hero-content[data-variant='centered'] .ui-hero-text-block {
+  max-inline-size: shared.$measure-content;
+}
+
+// Text-block → actions: Acquaintances (lg)
+.ui-hero-content[data-variant='centered']
+  .ui-hero-text-block
+  + .ui-hero-actions {
+  margin-block-start: var(--space-lg);
+}
+
+// Subheading: lighter weight + constrained width for readability
+.ui-hero-text-block .ui-text {
+  max-inline-size: shared.$measure-text;
+  font-weight: var(--font-weight-regular);
+}
+
+// Hero headings: larger, tighter line-height, tight tracking for impact
+.ui-hero .ui-heading {
+  font-size: var(--font-size-3xl);
+  line-height: var(--line-height-3xl);
+  letter-spacing: var(--heading-letter-spacing);
+}
+
+// Balance centered headings
+.ui-hero-content[data-variant='centered'] .ui-heading {
+  text-wrap: balance;
+}
+
+// ============================================
+// Split variant
+// ============================================
+
+.ui-hero-content[data-variant='split'] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-xl);
+  position: relative;
+  z-index: 1;
+
+  // Centre wrapped children whose width is capped by fluid-center-child
+  @include shared-mix.fluid-center-parent;
+}
+
+.ui-hero-text-side {
+  flex: 1 1 shared.$min-column;
+  display: flex;
+  flex-direction: column;
+
+  // Cap width so parent's justify-content: center kicks in when wrapped
+  @include shared-mix.fluid-center-child;
+}
+
+// Heading → subheading: Close Friends (sm)
+.ui-hero-text-side .ui-hero-text-block {
+  gap: var(--space-sm);
+}
+
+// Text-block → actions: Acquaintances (lg)
+.ui-hero-text-side .ui-hero-actions {
+  margin-block-start: var(--space-lg);
+}
+
+.ui-hero-image-side {
+  flex: 1 1 shared.$min-column;
+
+  // Image depth — shadow + radius for lifted appearance
+  .ui-image {
+    box-shadow: var(--shadow-lg);
+    border-radius: var(--radius-lg);
+
+    @include a11y.motion-safe {
+      transition: var(--motion-transition-shadow);
+    }
+
+    &:hover {
+      box-shadow: var(--shadow-xl);
+    }
+  }
+}
+
+// ============================================
+// Actions (button pair)
+// ============================================
+
+.ui-hero-actions {
+  display: flex;
+  flex-direction: row;
+  gap: var(--space-sm);
+  flex-wrap: wrap;
+
+  // Centre buttons only when parent stacks (inherits container from fluid-center-parent)
+  @container (max-width: #{shared.$min-column * 2 + 4rem}) {
+    justify-content: center;
+  }
+}
+
+// ============================================
+// Motion
+// ============================================
+
+@include a11y.motion-safe {
+  .ui-hero {
+    &::before {
+      transition: opacity var(--motion-duration-slow)
+        var(--motion-easing-standard);
+    }
+  }
+
+  // Expressive preset: split hero image slides in from the inline-end side
+  [data-entrance='expressive'] .ui-hero-image-side {
+    opacity: 0;
+    translate: var(--motion-distance-big) 0;
+    transition:
+      opacity var(--motion-duration-deliberate) var(--motion-easing-entrance),
+      translate var(--motion-duration-deliberate)
+        var(--motion-easing-emphasized);
+  }
+
+  [data-entrance='expressive'] .ui-section-visible .ui-hero-image-side {
+    opacity: 1;
+    translate: 0 0;
+  }
+
+  // Expressive: text side fades up with slight delay
+  [data-entrance='expressive'] .ui-hero-text-side {
+    opacity: 0;
+    translate: 0 var(--motion-distance-medium);
+    transition:
+      opacity var(--motion-duration-deliberate) var(--motion-easing-entrance),
+      translate var(--motion-duration-deliberate) var(--motion-easing-entrance);
+    transition-delay: 100ms;
+  }
+
+  [data-entrance='expressive'] .ui-section-visible .ui-hero-text-side {
+    opacity: 1;
+    translate: 0 0;
+  }
+}
+
+// ============================================
+// Forced colors
+// ============================================
+
+@include a11y.forced-colors {
+  .ui-hero::before {
+    display: none;
+  }
+}

package/dist/shared/_form-animations.scss

@@ -0,0 +1,283 @@
+/// Shared form control styles and animations
+/// Keyframes and text styles used by multiple form atoms (Input, Select, Textarea).
+///
+/// @group atoms/forms
+
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+
+// ============================================
+// Error shake animation
+// ============================================
+
+@keyframes ui-form-shake {
+  0%,
+  100% {
+    translate: 0;
+  }
+  20% {
+    translate: calc(-1 * var(--motion-distance-subtle));
+  }
+  40% {
+    translate: var(--motion-distance-subtle);
+  }
+  60% {
+    translate: calc(-1 * var(--motion-distance-subtle) / 2);
+  }
+  80% {
+    translate: calc(var(--motion-distance-subtle) / 2);
+  }
+}
+
+/// Mixin to apply shake animation class on a given selector.
+/// Usage: @include form-shake('.ui-input-shake');
+/// @param {String} $selector - The class selector that triggers the shake
+@mixin form-shake($selector) {
+  @include a11y.motion-safe {
+    #{$selector} {
+      animation: ui-form-shake var(--motion-duration-normal)
+        var(--motion-easing-standard);
+    }
+  }
+}
+
+// ============================================
+// State-engage pop animation (for Checkbox, Radio, Toggle)
+// 1 → var(--motion-scale-big) → 1 with springy easing — gives a tactile
+// "this state just turned on" feel without altering the layout box.
+// ============================================
+
+@keyframes ui-form-pop {
+  0% {
+    transform: scale(1);
+  }
+  35% {
+    transform: scale(var(--motion-scale-big));
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+
+/// Mixin to apply the pop animation to a target. Wrap your selector and
+/// pass it in. The mixin handles motion-safe gating.
+/// Usage: @include form-pop('.ui-checkbox-box');
+/// @param {String} $selector - The element to animate
+@mixin form-pop($selector) {
+  @include a11y.motion-safe {
+    #{$selector} {
+      animation: ui-form-pop var(--motion-duration-slow)
+        var(--motion-easing-springy) both;
+    }
+  }
+}
+
+// ============================================
+// Shared field polish
+// Caret color, error background wash, adaptive selection color.
+// ============================================
+
+/// Mixin for polished text-input field styles (caret, selection, error wash).
+/// Apply inside the wrapper selector (e.g., .ui-input, .ui-textarea).
+/// @param {String} $field-selector - Inner field element class (e.g., '.ui-input-field')
+@mixin form-field-polish($field-selector) {
+  // Caret synced to primary — subtle but noticeable on focus
+  #{$field-selector} {
+    caret-color: var(--color-primary);
+  }
+
+  // Error state — danger caret + faint background wash for scanability
+  &[data-error] {
+    --_scroll-bg: color-mix(
+      in oklch,
+      var(--color-danger) 3%,
+      var(--color-surface)
+    );
+    background-color: var(--_scroll-bg);
+
+    #{$field-selector} {
+      caret-color: var(--color-danger);
+    }
+
+    #{$field-selector}::selection {
+      background-color: color-mix(
+        in oklch,
+        var(--color-danger) calc(var(--state-selected-opacity) * 100%),
+        transparent
+      );
+    }
+  }
+
+  // Success state — success caret + selection tint
+  &[data-success]:not([data-error]) {
+    #{$field-selector} {
+      caret-color: var(--color-success);
+    }
+
+    #{$field-selector}::selection {
+      background-color: color-mix(
+        in oklch,
+        var(--color-success) calc(var(--state-selected-opacity) * 100%),
+        transparent
+      );
+    }
+  }
+}
+
+/// Mixin for spinner color that inherits error/success state.
+/// Apply inside the wrapper selector that holds the ::after spinner.
+/// @param {String} $loading-selector - Full selector from wrapper to ::after host
+///   e.g., '.ui-input-loading' (spinner on wrapper::after)
+///   e.g., '.ui-select-loading .ui-select-trigger' (spinner on child::after)
+@mixin form-spinner-adaptive($loading-selector) {
+  &[data-error]#{$loading-selector}::after {
+    border-color: var(--color-danger);
+    border-inline-end-color: transparent;
+  }
+
+  &[data-success]:not([data-error])#{$loading-selector}::after {
+    border-color: var(--color-success);
+    border-inline-end-color: transparent;
+  }
+}
+
+/// Mixin for scroll overflow shadows (top + bottom fade).
+/// Uses background-attachment: local trick — pure CSS, no JS needed.
+/// Requires --_scroll-bg set on the element or an ancestor (defaults via wrapper).
+@mixin scroll-shadows {
+  background:
+    // Top shadow — scrolls with content (disappears at top)
+    linear-gradient(var(--_scroll-bg) 30%, transparent) center top,
+    // Bottom shadow — scrolls with content (disappears at bottom)
+    linear-gradient(transparent, var(--_scroll-bg) 70%) center bottom,
+    // Top fade indicator — fixed
+    radial-gradient(
+        farthest-side at 50% 0,
+        color-mix(
+          in oklch,
+          var(--color-text) calc(var(--state-hover-opacity) * 100%),
+          transparent
+        ),
+        transparent
+      )
+      center top,
+    // Bottom fade indicator — fixed
+    radial-gradient(
+        farthest-side at 50% 100%,
+        color-mix(
+          in oklch,
+          var(--color-text) calc(var(--state-hover-opacity) * 100%),
+          transparent
+        ),
+        transparent
+      )
+      center bottom;
+  background-repeat: no-repeat;
+  background-size:
+    100% var(--space-lg),
+    100% var(--space-lg),
+    100% var(--space-sm),
+    100% var(--space-sm);
+  background-attachment: local, local, scroll, scroll;
+}
+
+/// Mixin for required asterisk on floating labels.
+/// Shows red asterisk after label text when wrapper has [data-required][data-floating-label].
+/// @param {String} $label-selector - Label element class (e.g., '.ui-input-label')
+@mixin form-required-indicator($label-selector) {
+  &[data-required][data-floating-label] #{$label-selector}::after {
+    content: ' *';
+    color: var(--color-danger);
+    font-weight: var(--font-weight-medium);
+  }
+}
+
+// ============================================
+// Shared inline button inside form controls (clear ×, password toggle)
+// Provides consistent styling, focus ring, hover state, and a 44×44
+// invisible touch target for WCAG 2.2 SC 2.5.8 AAA compliance.
+// ============================================
+
+/// @param {Color} $hover-color - The color used for hover/active state backgrounds
+@mixin form-inline-button($hover-color: var(--color-text)) {
+  appearance: none;
+  border: none;
+  background: none;
+  padding: 0;
+  margin: 0;
+  cursor: pointer;
+  color: var(--color-text-muted);
+  line-height: 1;
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  position: relative;
+  inline-size: var(--_form-btn-size, var(--icon-size-md));
+  block-size: var(--_form-btn-size, var(--icon-size-md));
+  // Scale text glyph (×) to match button container size
+  font-size: var(--_form-btn-size, var(--icon-size-md));
+
+  // 44×44 invisible touch target (WCAG 2.2 SC 2.5.8 AAA)
+  &::after {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    translate: -50% -50%;
+    min-inline-size: 44px;
+    min-block-size: 44px;
+  }
+
+  &:hover {
+    color: $hover-color;
+    @include a11y.state-background(hover, $hover-color);
+  }
+
+  @include a11y.focus-ring-visible;
+
+  @include a11y.motion-safe {
+    transition:
+      var(--motion-transition-opacity), var(--motion-transition-color),
+      var(--motion-transition-background);
+  }
+
+  // Keeps layout space when hidden to prevent input width shift.
+  // Uses [data-hidden] (not [hidden]) so the global display:none!important reset doesn't apply.
+  &[data-hidden] {
+    display: inline-flex;
+    visibility: hidden;
+    opacity: 0;
+    pointer-events: none;
+  }
+}
+
+// ============================================
+// Shared helper / error text below form controls
+// ============================================
+
+.ui-form-helper {
+  display: block;
+  margin-block-start: var(--space-xs);
+  font-size: var(--font-size-xs);
+  color: var(--color-text-muted);
+  line-height: var(--leading-tight);
+
+  @include a11y.motion-safe {
+    animation: var(--motion-animation-fade-in) var(--motion-duration-fast)
+      var(--motion-easing-entrance);
+  }
+}
+
+.ui-form-error {
+  display: block;
+  margin-block-start: var(--space-xs);
+  font-size: var(--font-size-xs);
+  color: var(--color-danger);
+  line-height: var(--leading-tight);
+
+  @include a11y.motion-safe {
+    animation: var(--motion-animation-fade-in) var(--motion-duration-fast)
+      var(--motion-easing-entrance);
+  }
+}