@pithyjs/ui-kit 0.1.0-beta.0

package/dist/atoms/forms/toggle/toggle.scss

@@ -0,0 +1,561 @@
+/// Toggle / switch component styles — premium edition.
+/// Native input is visually hidden; the .ui-toggle-track element renders the
+/// pill-shaped track in CSS, while .ui-toggle-thumb is the sliding circle knob.
+///
+/// @group atoms/forms
+
+@use 'sass:map';
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+@use '@pithyjs/design-system/borders/styles/tokens' as borders;
+@use '../../../shared/tokens' as shared;
+@use '../../../shared/form-animations' as form-anim;
+
+// -- Component-level tokens ---------------------------------------------------
+$_track-inset-shadow-opacity: 12%;
+
+// ============================================
+// Wrapper <label>
+// ============================================
+
+.ui-toggle {
+  // Single color family per state — declared on the wrapper so both the
+  // track and the label inherit it. Overridden by [data-success] / [data-error].
+  --_cmp-color: var(--color-primary);
+  --_cmp-color-hover: var(--color-primary-hover);
+  // Track border width — keep in sync with borders.border(control).
+  // Exposed as a custom property so the thumb can size itself relative to
+  // the padding-box (content area) rather than the border-box.
+  --_cmp-border-width: var(--border-width-thin);
+
+  @include a11y.touch-target-pseudo; // WCAG 2.5.5 — 44×44 invisible hit area
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-xs); // Lovers — track ↔ label
+  cursor: pointer;
+  position: relative;
+  user-select: none;
+  color: var(--color-text);
+
+  @include a11y.motion-safe {
+    transition: var(--motion-transition-color);
+  }
+}
+
+// Field wrapper (when helper/error is rendered)
+// No gap — child .ui-form-helper / .ui-form-error already carry
+// margin-block-start: var(--space-xs), consistent with other form atoms.
+.ui-toggle-field {
+  display: inline-flex;
+  flex-direction: column;
+}
+
+// ============================================
+// Native input — visually hidden but functional
+// ============================================
+
+.ui-toggle-input {
+  // sr-only — keeps the input in the layout (focusable, click-forwards via
+  // <label>), but visually hidden so the custom track renders the state.
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  padding: 0;
+  margin: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+// ============================================
+// Custom track (pill shape)
+// ============================================
+
+.ui-toggle-track {
+  --_cmp-shadow: 0 0 transparent;
+
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  position: relative;
+  inline-size: calc(var(--_cmp-track-height) * 2);
+  block-size: var(--_cmp-track-height);
+  background-color: var(--color-surface-variant);
+  border: borders.border(control);
+  // Strengthen the control border — the toggle track is a small pill
+  // with minimal inner content, so its border is the primary visual
+  // boundary. Blending with text color ensures ≥3:1 vs background
+  // in dark mode (global --color-border alone achieves only ~2.2:1).
+  border-color: color-mix(in oklch, var(--color-border) 80%, var(--color-text));
+  border-radius: var(--radius-pill);
+  box-shadow: var(--_cmp-shadow);
+  // No overflow:hidden — keep the thumb unclipped during interactive
+  // size/position transitions (for example pressed/stretch states), so the
+  // circle does not read as flattened or barrel-shaped at the track edge.
+
+  // Inset shadow on off-state — creates a recessed channel feel so the
+  // filled "on" state pops by contrast. Layered under the colored shadow.
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    box-shadow: inset 0 var(--border-width-hairline) var(--border-width-thin)
+      color-mix(
+        in oklch,
+        var(--color-on-surface) $_track-inset-shadow-opacity,
+        transparent
+      );
+    pointer-events: none;
+  }
+
+  @include a11y.motion-safe {
+    transition:
+      var(--motion-transition-background),
+      var(--motion-transition-border),
+      box-shadow var(--motion-duration-normal) var(--motion-easing-entrance);
+  }
+}
+
+// ============================================
+// Thumb (sliding circle)
+// ============================================
+
+.ui-toggle-thumb {
+  position: absolute;
+  // Gap between the thumb circle and the track's content edge.
+  // Equal on all sides so the thumb sits concentrically in the pill's end
+  // semicircle — no asymmetric "floating" effect.
+  --_thumb-gap: var(--border-width-hairline);
+  // Thumb size derived from the PADDING-BOX height (not border-box).
+  // padding-height = track-height - 2*border, then subtract 2*gap.
+  --_thumb-size: calc(
+    var(--_cmp-track-height) - var(--_cmp-border-width) *
+      2 - var(--_thumb-gap) * 2
+  );
+  // Thumb shape primitives — circle at rest, rounded-rect when stretched
+  // during the active-press animation. Component-scoped so the global
+  // border-radius allowlist stays limited to true primitives (0 / 50%).
+  --_thumb-radius: 50%;
+  --_thumb-radius-stretched: 40%;
+  inline-size: var(--_thumb-size);
+  block-size: var(--_thumb-size);
+  border-radius: var(--_thumb-radius);
+  background-color: var(--color-on-primary);
+  // Vertical: bulletproof centering via auto margins (not flex static position).
+  inset-block: 0;
+  margin-block: auto;
+  // Horizontal: equal gap from content edge = concentric in pill semicircle.
+  inset-inline-start: var(--_thumb-gap);
+  box-shadow: var(--shadow-sm);
+  // Off-state edge definition — hairline border ensures the thumb is
+  // distinguishable from the light track for WCAG 1.4.11 (non-text contrast).
+  // Disappears on checked — the colored track provides sufficient contrast.
+  box-sizing: border-box;
+  border: var(--border-width-hairline) solid
+    color-mix(in oklch, var(--color-on-surface) 55%, transparent);
+
+  @include a11y.motion-safe {
+    // Springy easing — thumb overshoots slightly and settles, feels physical.
+    transition:
+      inset-inline-start var(--motion-duration-slow)
+        var(--motion-easing-springy),
+      inline-size var(--motion-duration-normal) var(--motion-easing-entrance),
+      block-size var(--motion-duration-normal) var(--motion-easing-entrance),
+      border-radius var(--motion-duration-normal) var(--motion-easing-entrance),
+      box-shadow var(--motion-duration-normal) var(--motion-easing-entrance),
+      var(--motion-transition-border),
+      var(--motion-transition-background);
+  }
+}
+
+// ============================================
+// Visible label text
+// ============================================
+
+.ui-toggle-label {
+  font-size: var(--_cmp-font-size);
+  line-height: var(--leading-snug);
+  color: inherit;
+
+  // Branded selection — matches the active state color.
+  &::selection {
+    background-color: color-mix(
+      in oklch,
+      var(--_cmp-color) calc(var(--state-selected-opacity) * 100%),
+      transparent
+    );
+    color: inherit;
+  }
+}
+
+// ============================================
+// Sizes — set custom props per control size
+// ============================================
+
+@each $size in shared.$control-sizes {
+  .ui-toggle[data-size='#{$size}'] {
+    --_cmp-track-height: #{map.get(shared.$control-indicator-sizes, $size)};
+    --_cmp-font-size: #{map.get(shared.$control-font-sizes, $size)};
+  }
+}
+
+// ============================================
+// Checked state
+// ============================================
+
+.ui-toggle:has(.ui-toggle-input:checked) .ui-toggle-track {
+  background-color: var(--_cmp-color);
+  border-color: var(--_cmp-color);
+  --_cmp-shadow: 0 var(--shadow-base-offset-y) var(--shadow-base-blur)
+    calc(var(--shadow-base-offset-y) * -1)
+    color-mix(
+      in oklch,
+      var(--_cmp-color) #{shared.$checked-glow-opacity},
+      transparent
+    );
+
+  // Kill the recessed inset shadow — the filled track doesn't need it.
+  &::after {
+    box-shadow: none;
+  }
+}
+
+// Slide thumb to the end when checked.
+// Uses 100% (= actual rendered padding-box width) so the end gap exactly
+// mirrors the start gap, immune to DPI subpixel rounding of border-box tokens.
+.ui-toggle:has(.ui-toggle-input:checked) .ui-toggle-thumb {
+  inset-inline-start: calc(100% - var(--_thumb-size) - var(--_thumb-gap));
+  // Thumb lifts when checked — knob "rises" onto the active surface.
+  box-shadow: var(--shadow-md);
+  // Colored track provides ample contrast — border is no longer needed.
+  border-color: transparent;
+}
+
+// Pop animation on toggle
+@include form-anim.form-pop(
+  '.ui-toggle:has(.ui-toggle-input:checked) .ui-toggle-track'
+);
+
+// ============================================
+// Hover (not disabled / not readonly)
+// ============================================
+
+.ui-toggle:hover:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  )
+  .ui-toggle-track {
+  border-color: var(--_cmp-color);
+}
+
+.ui-toggle:hover:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  ):has(.ui-toggle-input:checked)
+  .ui-toggle-track {
+  background-color: var(--_cmp-color-hover);
+  border-color: var(--_cmp-color-hover);
+}
+
+// Hover: thumb grows to fill the full content area (padding-box height).
+// This is non-color feedback for WCAG (visible size change, not just shadow).
+// No overflow — the hover size exactly matches the padding-box height.
+.ui-toggle:hover:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  )
+  .ui-toggle-thumb {
+  --_thumb-hover-size: calc(
+    var(--_cmp-track-height) - var(--_cmp-border-width) * 2
+  );
+  inline-size: var(--_thumb-hover-size);
+  block-size: var(--_thumb-hover-size);
+  inset-inline-start: 0; // flush with content start edge
+  box-shadow: var(--shadow-md);
+}
+
+// Hover + checked: flush with content end edge.
+// Uses 100% to mirror the unchecked hover (inset-inline-start: 0).
+.ui-toggle:hover:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  ):has(.ui-toggle-input:checked)
+  .ui-toggle-thumb {
+  inset-inline-start: calc(100% - var(--_thumb-hover-size));
+}
+
+// ============================================
+// Focus — bridge native input focus to the track
+// ============================================
+
+.ui-toggle:has(.ui-toggle-input:focus-visible) .ui-toggle-track {
+  outline: none;
+  --ring-offset: #{shared.$focus-ring-offset};
+  box-shadow: borders.ring(), var(--_cmp-shadow);
+}
+
+// ============================================
+// Active / pressed feedback (iOS-style thumb stretch)
+// ============================================
+
+.ui-toggle:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  ):active
+  .ui-toggle-track {
+  @include a11y.state-background(pressed, var(--_cmp-color));
+}
+
+// iOS signature: thumb stretches ~30% wider on press, creating an elongated
+// pill shape that hints at the direction of travel. The border-radius shift
+// from 50% to 40% keeps it rounded-rect instead of an ellipse.
+//
+// Unchecked+active: thumb stretches RIGHT (toward checked position) — default
+// anchor is inset-inline-start so the width growth extends rightward.
+.ui-toggle:not([data-disabled]):not([data-readonly]):not(
+    :has(.ui-toggle-input:disabled)
+  ):active
+  .ui-toggle-thumb {
+  @include a11y.motion-safe {
+    inline-size: calc(var(--_thumb-size) * 1.3);
+    border-radius: var(--_thumb-radius-stretched);
+    transition:
+      inset-inline-start var(--motion-duration-slow)
+        var(--motion-easing-springy),
+      inline-size var(--motion-duration-fast) var(--motion-easing-standard),
+      border-radius var(--motion-duration-fast) var(--motion-easing-standard);
+  }
+}
+
+// Checked+active: thumb stretches LEFT (toward unchecked position).
+// Shift inset-inline-start to account for the wider thumb so the extra 30%
+// grows toward the start edge (direction of travel when unchecking).
+// Stretch width = thumb × 1.3. End gap = --_thumb-gap (mirrors unchecked start gap).
+// Uses 100% so the stretched thumb aligns flush with the rendered content end edge.
+.ui-toggle:has(.ui-toggle-input:checked):not([data-disabled]):not(
+    [data-readonly]
+  ):not(:has(.ui-toggle-input:disabled)):active
+  .ui-toggle-thumb {
+  @include a11y.motion-safe {
+    inset-inline-start: calc(
+      100% - var(--_thumb-size) * 1.3 - var(--_thumb-gap)
+    );
+  }
+}
+
+// ============================================
+// Success state
+// ============================================
+
+.ui-toggle[data-success] {
+  --_cmp-color: var(--color-success);
+  --_cmp-color-hover: var(--color-success-hover, var(--color-success));
+}
+
+.ui-toggle[data-success] .ui-toggle-track {
+  border-color: var(--_cmp-color);
+}
+
+.ui-toggle[data-success]:has(.ui-toggle-input:focus-visible) .ui-toggle-track {
+  --ring-color: var(--color-success);
+  box-shadow: borders.ring(), var(--_cmp-shadow);
+}
+
+// ============================================
+// Error state (after success — source order wins)
+// ============================================
+
+.ui-toggle[data-error] {
+  --_cmp-color: var(--color-danger);
+  --_cmp-color-hover: var(--color-danger-hover, var(--color-danger));
+}
+
+.ui-toggle[data-error] .ui-toggle-track {
+  border-color: var(--_cmp-color);
+}
+
+.ui-toggle[data-error]:has(.ui-toggle-input:focus-visible) .ui-toggle-track {
+  --ring-color: var(--color-danger);
+  box-shadow: borders.ring(), var(--_cmp-shadow);
+}
+
+.ui-toggle[data-error] .ui-toggle-label {
+  color: var(--color-danger);
+}
+
+// ============================================
+// Error shake animation
+// ============================================
+
+@include form-anim.form-shake('.ui-toggle-shake');
+
+// ============================================
+// Disabled state
+// ============================================
+
+.ui-toggle[data-disabled] {
+  opacity: var(--state-disabled-opacity);
+  filter: saturate(shared.$disabled-saturation);
+  cursor: not-allowed;
+
+  .ui-toggle-input {
+    cursor: not-allowed;
+  }
+}
+
+// Fieldset[disabled] cascade — when a toggle is disabled via a parent
+// <fieldset disabled>, the native input is :disabled but the wrapper has no
+// [data-disabled] attribute. Match the direct disabled visuals so individual
+// toggles look consistently deactivated across both disable paths.
+.ui-toggle:not([data-disabled]):has(.ui-toggle-input:disabled) {
+  opacity: var(--state-disabled-opacity);
+  filter: saturate(shared.$disabled-saturation);
+  cursor: not-allowed;
+
+  .ui-toggle-input {
+    cursor: not-allowed;
+  }
+}
+
+// ============================================
+// Readonly state — looks normal, blocks toggling
+// ============================================
+
+.ui-toggle[data-readonly] {
+  cursor: default;
+
+  .ui-toggle-input {
+    cursor: default;
+  }
+
+  // Unchecked track gets a slightly different surface to hint it's locked.
+  .ui-toggle-input:not(:checked) + .ui-toggle-track {
+    background-color: var(--color-surface-variant);
+  }
+}
+
+// ============================================
+// Required indicator on label text
+// ============================================
+
+.ui-toggle[data-required] .ui-toggle-label::after {
+  content: ' *';
+  color: var(--color-danger);
+  font-weight: var(--font-weight-medium);
+}
+
+// ============================================
+// Loading spinner — overlays the track
+// ============================================
+
+// Hide the thumb while loading — the spinner is the only signal.
+.ui-toggle.ui-toggle-loading .ui-toggle-thumb {
+  opacity: 0;
+}
+
+// Kill the inset shadow so it doesn't interfere with the spinner.
+.ui-toggle.ui-toggle-loading .ui-toggle-track::after {
+  box-shadow: none;
+}
+
+// Subtle border tint when not in error/success state.
+.ui-toggle.ui-toggle-loading:not([data-error]):not([data-success])
+  .ui-toggle-track {
+  border-color: var(--color-primary);
+}
+
+// Spinner color: primary on empty surface, on-primary when filled (checked).
+.ui-toggle.ui-toggle-loading .ui-toggle-track {
+  --_cmp-spinner-color: var(--color-primary);
+}
+
+.ui-toggle.ui-toggle-loading:has(.ui-toggle-input:checked) .ui-toggle-track {
+  --_cmp-spinner-color: var(--color-on-primary);
+}
+
+.ui-toggle[data-error].ui-toggle-loading .ui-toggle-track {
+  --_cmp-spinner-color: var(--color-danger);
+}
+
+.ui-toggle[data-success]:not([data-error]).ui-toggle-loading .ui-toggle-track {
+  --_cmp-spinner-color: var(--color-success);
+}
+
+// Spinner is a circle sized to the track height, centered in the track.
+// We can't use `inset: 15%` because the track is a wide pill — that would
+// create an oval. We can't use `transform: translate` for centering because
+// it conflicts with the spin animation's transform. Use margin auto instead.
+.ui-toggle.ui-toggle-loading .ui-toggle-track::before {
+  --_spinner-size: calc(var(--_cmp-track-height) * 0.5);
+  content: '';
+  position: absolute;
+  inset: 0;
+  // Explicit square dimensions + margin auto = centered circle in the pill
+  inline-size: var(--_spinner-size);
+  block-size: var(--_spinner-size);
+  margin: auto;
+  border: var(--border-width-medium) solid var(--_cmp-spinner-color);
+  border-inline-end-color: transparent;
+  border-radius: 50%;
+
+  @include a11y.motion-safe {
+    animation: var(--motion-animation-spin) var(--motion-duration-deliberate)
+      linear infinite;
+  }
+
+  @include a11y.motion-reduced {
+    border-inline-end-color: var(--_cmp-spinner-color);
+    opacity: shared.$spinner-reduced-opacity;
+  }
+}
+
+// Helper + error text use shared .ui-form-helper / .ui-form-error classes
+// from src/shared/_form-animations.scss — no per-component styles needed.
+
+// ============================================
+// Forced colors
+// ============================================
+
+@include a11y.forced-colors {
+  .ui-toggle-track {
+    border: var(--border-width-hairline) solid ButtonText;
+    background: Field;
+
+    // Suppress inset shadow — forced-colors surfaces must be flat.
+    &::after {
+      box-shadow: none;
+    }
+  }
+
+  .ui-toggle-thumb {
+    background: ButtonText;
+    border-color: ButtonText;
+    box-shadow: none;
+  }
+
+  .ui-toggle:has(.ui-toggle-input:checked) .ui-toggle-track {
+    background: Highlight;
+    border-color: Highlight;
+  }
+
+  .ui-toggle:has(.ui-toggle-input:checked) .ui-toggle-thumb {
+    background: HighlightText;
+    border-color: HighlightText;
+  }
+
+  .ui-toggle[data-disabled],
+  .ui-toggle:not([data-disabled]):has(.ui-toggle-input:disabled) {
+    color: GrayText;
+
+    .ui-toggle-track {
+      border-color: GrayText;
+    }
+
+    .ui-toggle-thumb {
+      background: GrayText;
+    }
+  }
+
+  .ui-toggle:has(.ui-toggle-input:focus-visible) .ui-toggle-track {
+    @include a11y.focus-outline(Highlight);
+  }
+}

package/dist/compiler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compiler-time metadata for @pithyjs/ui-kit components.
+ * Pass to htmlTransformPlugin({ componentScopes }) in vite.config.ts.
+ */
+import type { ComponentScopeConfig } from '@pithyjs/vite-plugin';
+export declare const componentScopes: Record<string, ComponentScopeConfig>;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAgBhE,CAAC"}

package/dist/compiler.js

@@ -0,0 +1,18 @@
+export const componentScopes = {
+    For: {
+        vars: ['item', 'index', 'count', 'first', 'last', 'even', 'odd'],
+        aliases: {
+            as: 'item',
+            indexAs: 'index',
+            countAs: 'count',
+            firstAs: 'first',
+            lastAs: 'last',
+            evenAs: 'even',
+            oddAs: 'odd',
+        },
+    },
+    ErrorBoundary: {
+        vars: ['error'],
+    },
+};
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,eAAe,GAAyC;IACnE,GAAG,EAAE;QACH,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;QAChE,OAAO,EAAE;YACP,EAAE,EAAE,MAAM;YACV,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,OAAO;YAChB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,MAAM;YACd,KAAK,EAAE,KAAK;SACb;KACF;IACD,aAAa,EAAE;QACb,IAAI,EAAE,CAAC,OAAO,CAAC;KAChB;CACF,CAAC"}

package/dist/icons/index.d.ts

@@ -0,0 +1,14 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icons",
+  "title": "Icon Sprite Registry Module",
+  "category": "runtime"
+}
+*/
+/**
+ * Icon sprite registry — tree-shakeable opt-in module.
+ *
+ * @module @pithyjs/ui-kit/icons
+ */
+export { registerIconSprite, lookupIcon, getRegisteredIcons, getIconMeta, hasIconSprite, getSpriteUrl, clearIconRegistry, type IconMeta, } from './registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/icons/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/icons/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC"}

package/dist/icons/index.js

@@ -0,0 +1,14 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icons",
+  "title": "Icon Sprite Registry Module",
+  "category": "runtime"
+}
+*/
+/**
+ * Icon sprite registry — tree-shakeable opt-in module.
+ *
+ * @module @pithyjs/ui-kit/icons
+ */
+export { registerIconSprite, lookupIcon, getRegisteredIcons, getIconMeta, hasIconSprite, getSpriteUrl, clearIconRegistry, } from './registry';
+//# sourceMappingURL=index.js.map

package/dist/icons/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/icons/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,iBAAiB,GAElB,MAAM,YAAY,CAAC"}