@stacksjs/components 0.2.154 → 0.2.156

package/dist/Form-bpnpbymb.stx

@@ -0,0 +1,163 @@
+<script server>
+export const action = $props.action || ''
+export const method = $props.method || 'POST'
+export const validationSchema = $props.validationSchema || {}
+export const className = $props.className || ''
+// These three were declared in FormProps and read by nothing, so passing them
+// did exactly nothing. See #1874.
+export const initialValues = $props.initialValues || {}
+export const validateOnChange = $props.validateOnChange === true
+export const validateOnBlur = $props.validateOnBlur === true
+
+export const formClasses = `space-y-6 ${className}`.trim()
+export const errorClasses = `mt-1 text-sm text-red-600 dark:text-red-400`.trim()
+</script>
+
+<script client>
+const emit = defineEmits()
+const validationSchema = {{ validationSchema }}
+const initialValues = {{ initialValues }}
+const validateOnChange = {{ validateOnChange }}
+const validateOnBlur = {{ validateOnBlur }}
+
+const errors = state({})
+const isSubmitting = state(false)
+const submitCount = state(0)
+// Seeded from initialValues so the prop has an effect before the first submit,
+// and so resetForm() has something to restore to.
+const values = state({ ...initialValues })
+
+function validateField(name, value, allValues) {
+  const schema = validationSchema[name]
+  if (!schema) return null
+  if (schema.required && !value) {
+    return schema.requiredMessage || `${name} is required`
+  }
+  if (schema.minLength && String(value).length < schema.minLength) {
+    return schema.minLengthMessage || `${name} must be at least ${schema.minLength} characters`
+  }
+  if (schema.maxLength && String(value).length > schema.maxLength) {
+    return schema.maxLengthMessage || `${name} must be at most ${schema.maxLength} characters`
+  }
+  if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+    return schema.patternMessage || `${name} is invalid`
+  }
+  // FieldSchema.validate has always been part of the published type and was
+  // never called, so a custom rule silently passed. It runs last, after the
+  // built-in rules, so it only sees values those already accepted.
+  if (typeof schema.validate === 'function') {
+    const custom = schema.validate(value, allValues || {})
+    if (custom) return custom
+  }
+  return null
+}
+
+// Single field, used by the change/blur paths so one bad field does not wipe the
+// errors of the others the way a full validateForm() would.
+function validateOne(name, value) {
+  if (!validationSchema[name]) return
+  const err = validateField(name, value, values())
+  const next = { ...errors() }
+  if (err) next[name] = err
+  else delete next[name]
+  errors.set(next)
+}
+
+// Delegated on the <form> rather than bound per input: the children arrive
+// through <slot />, so the component never sees them individually. `input` and
+// `focusout` both bubble (`blur` does not, which is why focusout is used).
+function onFieldInput(event) {
+  const name = event.target?.name
+  if (!name) return
+  values.set({ ...values(), [name]: event.target.value })
+  if (validateOnChange) validateOne(name, event.target.value)
+}
+
+function onFieldBlur(event) {
+  const name = event.target?.name
+  if (!name) return
+  if (validateOnBlur) validateOne(name, event.target.value)
+}
+
+function validateForm(values) {
+  const next = {}
+  let valid = true
+  for (const name of Object.keys(validationSchema)) {
+    const err = validateField(name, values[name], values)
+    if (err) {
+      next[name] = err
+      valid = false
+    }
+  }
+  errors.set(next)
+  return valid
+}
+
+async function onSubmit(event) {
+  event.preventDefault()
+  submitCount.set(submitCount() + 1)
+
+  // initialValues supplies anything the form does not post (an untouched field
+  // with no input, a value held outside the DOM); FormData still wins where both
+  // have the key, so what the user actually typed is never overridden.
+  const formData = new FormData(event.target)
+  const submitted = { ...initialValues }
+  for (const [k, v] of formData.entries()) submitted[k] = v
+  values.set(submitted)
+
+  if (!validateForm(submitted)) {
+    emit('error', errors())
+    return
+  }
+
+  isSubmitting.set(true)
+  try {
+    // Second argument is FormHelpers, which the published type has always
+    // promised and which nothing used to pass.
+    emit('submit', submitted, helpers)
+  }
+  finally {
+    isSubmitting.set(false)
+  }
+}
+
+function setErrors(next) {
+  errors.set({ ...errors(), ...next })
+}
+
+function setValues(next) {
+  values.set({ ...values(), ...next })
+}
+
+function reset(form) {
+  errors.set({})
+  isSubmitting.set(false)
+  submitCount.set(0)
+  values.set({ ...initialValues })
+  if (form?.reset) form.reset()
+}
+
+// FormHelpers named setValues/resetForm; the component exposed setErrors/reset
+// and no setValues at all, so the documented shape could not be destructured.
+// Both spellings are exposed: resetForm/setValues to satisfy the type, reset to
+// keep the existing call sites working.
+function resetForm(form) {
+  reset(form)
+}
+
+const helpers = { setErrors, setValues, resetForm }
+
+defineExpose({ errors, values, isSubmitting, submitCount, setErrors, setValues, reset, resetForm, validateForm, validateField })
+</script>
+
+<form
+  class="{{ formClasses }}"
+  @if(action)action="{{ action }}"@endif
+  method="{{ method }}"
+  @submit="onSubmit($event)"
+  @input="onFieldInput($event)"
+  @focusout="onFieldBlur($event)"
+  novalidate
+>
+  <slot />
+</form>

package/dist/{SidebarSpace-61b662jx.stx → SidebarSpace-h50n47va.stx}

@@ -64,6 +64,7 @@ function onAction(event) {
   data-space
   data-space-id="{{ id }}"
   data-space-active="{{ active ? 'true' : 'false' }}"
+  @if(!active)inert@endif
   class="flex min-w-0 flex-1 flex-col"
   role="tabpanel"
   aria-label="{{ label || id }}"

package/dist/{SidebarSpaces-gq3mx984.stx → SidebarSpaces-sy8dy0gb.stx}

@@ -51,6 +51,19 @@ export const config = JSON.stringify({
 </script>
 
 <script client>
+import {
+  clampIndex,
+  nativeVelocityToPanels,
+  panelStep,
+  pointerAxis,
+  settleTarget,
+  SETTLE_EASE,
+  SETTLE_MS,
+  wheelClaims,
+  WHEEL_IDLE_MS,
+  withResistance,
+} from './swipe'
+
 const emit = defineEmits()
 const componentRoot = window.__STX_CURRENT_ELEMENT__
 
@@ -72,39 +85,9 @@ let tints = []
 // 220px pane and a 320px pane need the same flick to advance.
 // ---------------------------------------------------------------------------
 
-const SETTLE_MS = 420
-const SETTLE_EASE = 'cubic-bezier(0.22, 0.61, 0.36, 1)'
-// Distance past the first/last space is compressed towards this asymptote, the
-// same thing UIScrollView does at the end of a list: the track keeps answering
-// the finger, but tells you there is nothing further.
-const RUBBER_LIMIT = 0.28
-// Commit thresholds. Either drag a third of the way, or flick — 1.5 panels per
-// second — in the direction you were already going.
-const COMMIT_DISTANCE = 0.3
-const COMMIT_VELOCITY = 0.0015
-
-function panelStep() {
-  return 100 / Math.max(1, ids.length)
-}
-
 function paint(offset, animate) {
   track.style.transition = animate ? `transform ${SETTLE_MS}ms ${SETTLE_EASE}` : 'none'
-  track.style.transform = `translate3d(${-offset * panelStep()}%, 0, 0)`
-}
-
-function rubber(distance) {
-  return (1 - 1 / (distance / RUBBER_LIMIT + 1)) * RUBBER_LIMIT
-}
-
-function withResistance(offset) {
-  const last = ids.length - 1
-  if (offset < 0) return -rubber(-offset)
-  if (offset > last) return last + rubber(offset - last)
-  return offset
-}
-
-function clampIndex(value) {
-  return Math.max(0, Math.min(ids.length - 1, value))
+  track.style.transform = `translate3d(${-offset * panelStep(ids.length)}%, 0, 0)`
 }
 
 function animates() {
@@ -174,7 +157,7 @@ function restored() {
 /** Move to a space. Always repaints — a rejected swipe still animates home. */
 function goTo(next, options) {
   const opts = options || {}
-  const target = clampIndex(next)
+  const target = clampIndex(next, ids.length)
   const changed = target !== index()
 
   paint(target, opts.animate !== false && animates())
@@ -192,8 +175,9 @@ function goTo(next, options) {
 // Gestures
 //
 // All three input paths (wheel, pointer, native) funnel into the same two
-// helpers: they track live with `paint(withResistance(offset), false)` while
-// moving, then hand the final offset and velocity to `settle`.
+// helpers: they track live with `paint(withResistance(…), false)` while moving,
+// then hand the final offset and velocity to `settle`. The thresholds and the
+// resistance curve live in `./swipe` so they can be tested directly.
 // ---------------------------------------------------------------------------
 
 let gestureStart = 0
@@ -204,12 +188,7 @@ function beginGesture() {
 }
 
 function settle(offset, velocity, source) {
-  const moved = offset - gestureStart
-  const direction = Math.sign(moved) || Math.sign(velocity)
-  const dragged = Math.abs(moved) > COMMIT_DISTANCE
-  const flicked = Math.abs(velocity) > COMMIT_VELOCITY && Math.sign(velocity) === direction
-  const commit = direction !== 0 && (dragged || flicked)
-  goTo(commit ? gestureStart + direction : gestureStart, { source })
+  goTo(settleTarget(offset, gestureStart, velocity, ids.length), { source })
 }
 
 // --- Trackpad ---------------------------------------------------------------
@@ -222,13 +201,18 @@ let wheelOffset = null
 let wheelIdle = null
 let wheelVelocity = 0
 let wheelLastAt = 0
+// Set the first time the host delivers a real gesture phase. From then on the
+// wheel stream is the same physical events arriving a second time, so running
+// the heuristic as well would drive the track twice and settle it twice.
+let nativeGesturesConfirmed = false
 
 function onWheel(event) {
+  if (nativeGesturesConfirmed) return
   if (ids.length < 2) return
   if (event.ctrlKey) return // pinch-zoom, not a swipe
 
   if (wheelOffset === null) {
-    if (Math.abs(event.deltaX) <= Math.abs(event.deltaY)) return
+    if (!wheelClaims(event.deltaX, event.deltaY)) return
     beginGesture()
     wheelOffset = gestureStart
     wheelLastAt = event.timeStamp
@@ -240,10 +224,10 @@ function onWheel(event) {
   wheelLastAt = event.timeStamp
   wheelVelocity = delta / elapsed
   wheelOffset += delta
-  paint(withResistance(wheelOffset), false)
+  paint(withResistance(wheelOffset, ids.length), false)
 
   clearTimeout(wheelIdle)
-  wheelIdle = setTimeout(endWheel, 90)
+  wheelIdle = setTimeout(endWheel, WHEEL_IDLE_MS)
 }
 
 function endWheel() {
@@ -253,10 +237,17 @@ function endWheel() {
   settle(offset, wheelVelocity, 'swipe')
 }
 
-/** Drop an in-flight wheel gesture without settling it. */
+/**
+ * Drop an in-flight wheel gesture without settling it, returning wherever it
+ * had dragged the track to. The caller adopts that offset so the handover to
+ * the native stream is invisible — resetting to the logical index instead
+ * would snap the track backwards at the exact moment the gesture gets better.
+ */
 function cancelWheelGesture() {
   clearTimeout(wheelIdle)
+  const carried = wheelOffset
   wheelOffset = null
+  return carried
 }
 
 // --- Touch and pen ----------------------------------------------------------
@@ -290,10 +281,9 @@ function onPointerMove(event) {
     // Axis lock. The first 8px of travel decides swipe or scroll, and the
     // decision stands for the rest of the gesture — re-deciding mid-drag is
     // what makes web carousels feel slippery.
-    const dx = event.clientX - pointerStartX
-    const dy = event.clientY - pointerStartY
-    if (Math.abs(dx) < 8 && Math.abs(dy) < 8) return
-    if (Math.abs(dx) <= Math.abs(dy)) { pointerId = null; return }
+    const axis = pointerAxis(event.clientX - pointerStartX, event.clientY - pointerStartY)
+    if (axis === 'undecided') return
+    if (axis === 'vertical') { pointerId = null; return }
     beginGesture()
     pointerOffset = gestureStart
     viewport.setPointerCapture(event.pointerId)
@@ -305,7 +295,7 @@ function onPointerMove(event) {
   pointerLastAt = event.timeStamp
   pointerVelocity = delta / elapsed
   pointerOffset += delta
-  paint(withResistance(pointerOffset), false)
+  paint(withResistance(pointerOffset, ids.length), false)
 }
 
 function onPointerUp(event) {
@@ -347,10 +337,24 @@ function onShortcut(event) {
   if (!event.metaKey || !event.altKey) return
   const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0
   if (step === 0) return
+  // Window-level, so a page with two spaces sidebars would otherwise advance
+  // both at once. Whichever one contains the focus owns the shortcut; with
+  // focus outside every sidebar the sole sidebar still answers, because that
+  // is the common case and requiring a click first would be surprising.
+  if (!ownsShortcut()) return
   event.preventDefault()
   goTo(index() + step, { source: 'keyboard' })
 }
 
+function ownsShortcut() {
+  const focused = document.activeElement
+  const owner = focused && focused !== document.body
+    ? focused.closest('[data-stx-sidebar-spaces]')
+    : null
+  if (owner) return owner === root
+  return document.querySelectorAll('[data-stx-sidebar-spaces]').length === 1
+}
+
 // ---------------------------------------------------------------------------
 // Craft
 //
@@ -381,11 +385,15 @@ function bindCraftGestures() {
       // Take over from the wheel path. The bridge exposes `onSwipe`
       // unconditionally but a host that does not implement gestures never
       // emits, so the wheel listener stays bound and this is the only moment
-      // we know the native stream is real. Cancelling any in-flight wheel
-      // gesture here stops the two paths settling the same swipe twice.
-      cancelWheelGesture()
+      // we know the native stream is real. From here the heuristic is not just
+      // redundant but harmful — the same physical scroll arrives on both paths
+      // — so it is retired for good, not merely cancelled.
+      nativeGesturesConfirmed = true
+      const carried = cancelWheelGesture()
       beginGesture()
-      offset = gestureStart
+      // Adopt whatever the wheel path had already dragged to, so the handover
+      // does not snap the track back to the logical index.
+      offset = carried === null ? gestureStart : carried
       return
     }
     if (offset === null) return
@@ -395,12 +403,12 @@ function bindCraftGestures() {
       offset = null
       // Craft reports velocity in points per second; the thresholds here are
       // panels per millisecond.
-      settle(settled, (swipe.velocityX || 0) / (viewport.clientWidth || 1) / 1000, 'swipe')
+      settle(settled, nativeVelocityToPanels(swipe.velocityX || 0, viewport.clientWidth), 'swipe')
       return
     }
 
     offset += (swipe.deltaX || 0) / (viewport.clientWidth || 1)
-    paint(withResistance(offset), false)
+    paint(withResistance(offset, ids.length), false)
   })
 
   if (typeof off === 'function') craftTeardown.push(off)
@@ -444,7 +452,7 @@ onMount(() => {
   tints = spaces.map(space => space.tint)
   if (ids.length === 0) return
 
-  const startIndex = clampIndex(config.index || 0)
+  const startIndex = clampIndex(config.index || 0, ids.length)
   const saved = restored()
   const initial = saved === -1 ? startIndex : saved
   index.set(initial)
@@ -523,6 +531,57 @@ defineExpose({
 </div>
 
 <style scoped>
+/* ---------------------------------------------------------------------------
+ * Standalone tinting.
+ *
+ * `applyTint` writes the palette onto `root.closest('[data-stx-sidebar]')` and
+ * falls back to this component's own root — the documented way to use
+ * `<SidebarSpaces>` without a `<Sidebar>` around it. But the rules that
+ * *consume* those variables live in Sidebar.stx, so the fallback target used to
+ * publish a palette nothing read: standalone spaces rendered with no gradient
+ * and no crossfade at all.
+ *
+ * These mirror Sidebar.stx's spaces block for the standalone case only. The
+ * `:not([data-stx-sidebar] *)` guard keeps them out of the nested case, where
+ * the pane is the thing that should be painted, not this inner column.
+ * ------------------------------------------------------------------------- */
+@property --stx-space-from { syntax: "<color>"; inherits: true; initial-value: #f2f0ec; }
+@property --stx-space-to { syntax: "<color>"; inherits: true; initial-value: #e6e3dd; }
+@property --stx-space-ink { syntax: "<color>"; inherits: true; initial-value: #2c2a28; }
+@property --stx-space-accent { syntax: "<color>"; inherits: true; initial-value: #5b5b63; }
+
+[data-stx-sidebar-spaces]:not([data-stx-sidebar] *) {
+  --stx-space-from: var(--stx-space-light-from, #f2f0ec);
+  --stx-space-to: var(--stx-space-light-to, #e6e3dd);
+  --stx-space-ink: var(--stx-space-light-ink, #2c2a28);
+  --stx-space-accent: var(--stx-space-light-accent, #5b5b63);
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.34) 0%, rgba(255, 255, 255, 0) 32%),
+    linear-gradient(180deg, var(--stx-space-from) 0%, var(--stx-space-to) 100%);
+  color: var(--stx-space-ink);
+  transition:
+    --stx-space-from 420ms ease,
+    --stx-space-to 420ms ease,
+    --stx-space-ink 420ms ease,
+    --stx-space-accent 420ms ease;
+}
+
+@media (prefers-color-scheme: dark) {
+  [data-stx-sidebar-spaces]:not([data-stx-sidebar] *) {
+    --stx-space-from: var(--stx-space-dark-from, #17171b);
+    --stx-space-to: var(--stx-space-dark-to, #0e0e11);
+    --stx-space-ink: var(--stx-space-dark-ink, #ededf0);
+    --stx-space-accent: var(--stx-space-dark-accent, #b9b9c2);
+    background:
+      linear-gradient(180deg, rgba(255, 255, 255, 0.06) 0%, rgba(255, 255, 255, 0) 30%),
+      linear-gradient(180deg, var(--stx-space-from) 0%, var(--stx-space-to) 100%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-stx-sidebar-spaces]:not([data-stx-sidebar] *) { transition: none; }
+}
+
 .stx-space-viewport {
   /* Vertical scrolling stays with the browser; horizontal belongs to us. */
   touch-action: pan-y;

package/dist/index.js

@@ -1,11 +1,11 @@
 // @bun
-// ../../../../../../../tmp/stx-components-build-bwsTuP/stubs/stub-0.js
+// ../../../../../../../tmp/stx-components-build-ghpOHJ/stubs/stub-0.js
 var stub_0_default = { __stx: true, src: "./components/CodeBlock.stx" };
-// ../../../../../../../tmp/stx-components-build-bwsTuP/stubs/stub-1.js
+// ../../../../../../../tmp/stx-components-build-ghpOHJ/stubs/stub-1.js
 var stub_1_default = { __stx: true, src: "./components/Footer.stx" };
-// ../../../../../../../tmp/stx-components-build-bwsTuP/stubs/stub-2.js
+// ../../../../../../../tmp/stx-components-build-ghpOHJ/stubs/stub-2.js
 var stub_2_default = { __stx: true, src: "./components/Hero.stx" };
-// ../../../../../../../tmp/stx-components-build-bwsTuP/stubs/stub-3.js
+// ../../../../../../../tmp/stx-components-build-ghpOHJ/stubs/stub-3.js
 var stub_3_default = { __stx: true, src: "./components/Installation.stx" };
 // src/composables/useCopyCode.ts
 function useCopyCode(options) {
@@ -969,7 +969,7 @@ var DropdownItem_default = "./DropdownItem-c7rz08e5.stx";
 // src/ui/dropdown/DropdownItems.stx
 var DropdownItems_default = "./DropdownItems-1sxnd5qn.stx";
 // src/ui/form/Form.stx
-var Form_default = "./Form-mas630hy.stx";
+var Form_default = "./Form-bpnpbymb.stx";
 
 // src/ui/form/index.ts
 var formPropSchema = {
@@ -1144,9 +1144,9 @@ var SidebarPinned_default = "./SidebarPinned-tvj28bm0.stx";
 // src/ui/sidebar/SidebarSection.stx
 var SidebarSection_default = "./SidebarSection-zd9z35ch.stx";
 // src/ui/sidebar/SidebarSpace.stx
-var SidebarSpace_default = "./SidebarSpace-61b662jx.stx";
+var SidebarSpace_default = "./SidebarSpace-h50n47va.stx";
 // src/ui/sidebar/SidebarSpaces.stx
-var SidebarSpaces_default = "./SidebarSpaces-gq3mx984.stx";
+var SidebarSpaces_default = "./SidebarSpaces-sy8dy0gb.stx";
 // src/ui/sidebar/SidebarSpaceSwitcher.stx
 var SidebarSpaceSwitcher_default = "./SidebarSpaceSwitcher-882njcxq.stx";
 // src/ui/sidebar/themes.ts

package/dist/ui/form/index.d.ts

@@ -21,10 +21,18 @@ export declare interface FieldSchema {
 export declare interface ValidationSchema {
   [fieldName: string]: FieldSchema
 }
+/**
+ * Passed as the second argument of the `submit` event.
+ *
+ * These names are the ones the component actually exposes. Before #1874 the type
+ * named `setValues` and `resetForm` while the component implemented `setErrors`
+ * and `reset` and had no `setValues` at all, so destructuring this shape gave you
+ * two undefined functions.
+ */
 export declare interface FormHelpers {
   setErrors: (errors: Record<string, string>) => void
   setValues: (values: Record<string, any>) => void
-  resetForm: () => void
+  resetForm: (form?: HTMLFormElement) => void
 }
 export declare interface FormProps {
   action?: string

package/dist/ui/sidebar/swipe.d.ts

@@ -0,0 +1,67 @@
+/** Width of one panel as a percentage of the whole track. */
+export declare function panelStep(count: number): number;
+/** The compression curve applied beyond either end of the track. */
+export declare function rubber(distance: number): number;
+/** Clamp an offset to the track, compressing rather than stopping at the ends. */
+export declare function withResistance(offset: number, count: number): number;
+export declare function clampIndex(value: number, count: number): number;
+/**
+ * Where a released gesture lands.
+ *
+ * A swipe advances at most one space however far or fast it was dragged —
+ * Arc behaves the same way, and it keeps a fast flick from skipping past the
+ * space you were looking at.
+ */
+export declare function settleTarget(offset: number, gestureStart: number, velocity: number, count: number): number;
+/**
+ * Whether a wheel event should start a swipe.
+ *
+ * Claimed only when the very first event is unambiguously horizontal. A DOM
+ * wheel stream carries no phase information, so this is a guess — the native
+ * path in Craft replaces it with real `NSEvent` phases when the host provides
+ * them.
+ */
+export declare function wheelClaims(deltaX: number, deltaY: number): boolean;
+/**
+ * Axis lock for touch and pen. The first 8px of travel decides, and the
+ * decision stands for the rest of the gesture — re-deciding mid-drag is what
+ * makes web carousels feel slippery.
+ */
+export declare function pointerAxis(dx: number, dy: number): PointerAxis;
+/**
+ * Convert Craft's release velocity (points per second) into the panels per
+ * millisecond the commit thresholds are expressed in.
+ */
+export declare function nativeVelocityToPanels(velocityX: number, viewportWidth: number): number;
+/**
+ * The geometry and commit rules behind a spaces swipe.
+ *
+ * Extracted from `SidebarSpaces.stx` for the same reason `route-selection.ts`
+ * is: the component's client script cannot be imported, and this is the part
+ * worth pinning down. Everything here is pure — no DOM, no state — so the
+ * thresholds that decide whether a swipe advances can be asserted directly
+ * instead of inferred from a rendered pane.
+ *
+ * Position is measured in *panels*, not pixels: 1.5 means halfway between the
+ * second and third space. Keeping the gesture in panel units makes every
+ * threshold independent of how wide the sidebar happens to be, so a 220px pane
+ * and a 320px pane need the same flick to advance.
+ */
+/** Settle animation, matched by the tint crossfade so colour and motion agree. */
+export declare const SETTLE_MS: 420;
+export declare const SETTLE_EASE: 'cubic-bezier(0.22, 0.61, 0.36, 1)';
+/**
+ * Travel past the first/last space is compressed towards this asymptote, the
+ * same thing a UIScrollView does at the end of a list: the track keeps
+ * answering the finger, but tells you there is nothing further.
+ */
+export declare const RUBBER_LIMIT: 0.28;
+/** Drag this fraction of a panel and release, and the swipe commits. */
+export declare const COMMIT_DISTANCE: 0.3;
+/** Or flick: panels per millisecond, i.e. 1.5 panels/second. */
+export declare const COMMIT_VELOCITY: 0.0015;
+/** The first pointer travel that decides swipe-or-scroll, in CSS pixels. */
+export declare const AXIS_LOCK_PX: 8;
+/** A wheel gesture ends when the stream goes quiet for this long. */
+export declare const WHEEL_IDLE_MS: 90;
+export type PointerAxis = 'undecided' | 'horizontal' | 'vertical';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/components",
   "type": "module",
-  "version": "0.2.154",
+  "version": "0.2.156",
   "description": "A modern component library built with STX, featuring headwind utility classes and TypeScript syntax highlighting.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -64,8 +64,8 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@cwcss/crosswind": "^0.2.14",
-    "@stacksjs/stx": "0.2.153",
-    "bun-plugin-stx": "0.2.153",
+    "@stacksjs/stx": "0.2.156",
+    "bun-plugin-stx": "0.2.156",
     "ts-syntax-highlighter": "^0.2.1"
   },
   "devDependencies": {

package/src/ui/form/Form.stx

@@ -3,6 +3,11 @@ export const action = $props.action || ''
 export const method = $props.method || 'POST'
 export const validationSchema = $props.validationSchema || {}
 export const className = $props.className || ''
+// These three were declared in FormProps and read by nothing, so passing them
+// did exactly nothing. See #1874.
+export const initialValues = $props.initialValues || {}
+export const validateOnChange = $props.validateOnChange === true
+export const validateOnBlur = $props.validateOnBlur === true
 
 export const formClasses = `space-y-6 ${className}`.trim()
 export const errorClasses = `mt-1 text-sm text-red-600 dark:text-red-400`.trim()
@@ -11,10 +16,16 @@ export const errorClasses = `mt-1 text-sm text-red-600 dark:text-red-400`.trim()
 <script client>
 const emit = defineEmits()
 const validationSchema = {{ validationSchema }}
+const initialValues = {{ initialValues }}
+const validateOnChange = {{ validateOnChange }}
+const validateOnBlur = {{ validateOnBlur }}
 
 const errors = state({})
 const isSubmitting = state(false)
 const submitCount = state(0)
+// Seeded from initialValues so the prop has an effect before the first submit,
+// and so resetForm() has something to restore to.
+const values = state({ ...initialValues })
 
 function validateField(name, value, allValues) {
   const schema = validationSchema[name]
@@ -31,9 +42,43 @@ function validateField(name, value, allValues) {
   if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
     return schema.patternMessage || `${name} is invalid`
   }
+  // FieldSchema.validate has always been part of the published type and was
+  // never called, so a custom rule silently passed. It runs last, after the
+  // built-in rules, so it only sees values those already accepted.
+  if (typeof schema.validate === 'function') {
+    const custom = schema.validate(value, allValues || {})
+    if (custom) return custom
+  }
   return null
 }
 
+// Single field, used by the change/blur paths so one bad field does not wipe the
+// errors of the others the way a full validateForm() would.
+function validateOne(name, value) {
+  if (!validationSchema[name]) return
+  const err = validateField(name, value, values())
+  const next = { ...errors() }
+  if (err) next[name] = err
+  else delete next[name]
+  errors.set(next)
+}
+
+// Delegated on the <form> rather than bound per input: the children arrive
+// through <slot />, so the component never sees them individually. `input` and
+// `focusout` both bubble (`blur` does not, which is why focusout is used).
+function onFieldInput(event) {
+  const name = event.target?.name
+  if (!name) return
+  values.set({ ...values(), [name]: event.target.value })
+  if (validateOnChange) validateOne(name, event.target.value)
+}
+
+function onFieldBlur(event) {
+  const name = event.target?.name
+  if (!name) return
+  if (validateOnBlur) validateOne(name, event.target.value)
+}
+
 function validateForm(values) {
   const next = {}
   let valid = true
@@ -52,18 +97,24 @@ async function onSubmit(event) {
   event.preventDefault()
   submitCount.set(submitCount() + 1)
 
+  // initialValues supplies anything the form does not post (an untouched field
+  // with no input, a value held outside the DOM); FormData still wins where both
+  // have the key, so what the user actually typed is never overridden.
   const formData = new FormData(event.target)
-  const values = {}
-  for (const [k, v] of formData.entries()) values[k] = v
+  const submitted = { ...initialValues }
+  for (const [k, v] of formData.entries()) submitted[k] = v
+  values.set(submitted)
 
-  if (!validateForm(values)) {
+  if (!validateForm(submitted)) {
     emit('error', errors())
     return
   }
 
   isSubmitting.set(true)
   try {
-    emit('submit', values)
+    // Second argument is FormHelpers, which the published type has always
+    // promised and which nothing used to pass.
+    emit('submit', submitted, helpers)
   }
   finally {
     isSubmitting.set(false)
@@ -74,14 +125,29 @@ function setErrors(next) {
   errors.set({ ...errors(), ...next })
 }
 
+function setValues(next) {
+  values.set({ ...values(), ...next })
+}
+
 function reset(form) {
   errors.set({})
   isSubmitting.set(false)
   submitCount.set(0)
+  values.set({ ...initialValues })
   if (form?.reset) form.reset()
 }
 
-defineExpose({ errors, isSubmitting, submitCount, setErrors, reset, validateForm })
+// FormHelpers named setValues/resetForm; the component exposed setErrors/reset
+// and no setValues at all, so the documented shape could not be destructured.
+// Both spellings are exposed: resetForm/setValues to satisfy the type, reset to
+// keep the existing call sites working.
+function resetForm(form) {
+  reset(form)
+}
+
+const helpers = { setErrors, setValues, resetForm }
+
+defineExpose({ errors, values, isSubmitting, submitCount, setErrors, setValues, reset, resetForm, validateForm, validateField })
 </script>
 
 <form
@@ -89,6 +155,8 @@ defineExpose({ errors, isSubmitting, submitCount, setErrors, reset, validateForm
   @if(action)action="{{ action }}"@endif
   method="{{ method }}"
   @submit="onSubmit($event)"
+  @input="onFieldInput($event)"
+  @focusout="onFieldBlur($event)"
   novalidate
 >
   <slot />

package/src/ui/form/index.ts

@@ -19,20 +19,37 @@ export interface ValidationSchema {
   [fieldName: string]: FieldSchema
 }
 
+/**
+ * Passed as the second argument of the `submit` event.
+ *
+ * These names are the ones the component actually exposes. Before #1874 the type
+ * named `setValues` and `resetForm` while the component implemented `setErrors`
+ * and `reset` and had no `setValues` at all, so destructuring this shape gave you
+ * two undefined functions.
+ */
 export interface FormHelpers {
   setErrors: (errors: Record<string, string>) => void
   setValues: (values: Record<string, any>) => void
-  resetForm: () => void
+  resetForm: (form?: HTMLFormElement) => void
 }
 
 export interface FormProps {
   action?: string
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
   validationSchema?: ValidationSchema
+  /** Seeds the form's values, fills gaps in the submitted payload, and is what resetForm() restores to. */
   initialValues?: Record<string, any>
+  /** Validate a field as it is typed into. Delegated from the form's `input` event. */
   validateOnChange?: boolean
+  /** Validate a field when it loses focus. Delegated from the form's `focusout` event. */
   validateOnBlur?: boolean
+  /**
+   * Bound as the `submit` EVENT, not as a callback prop: `<Form @submit="…">`.
+   * Receives (values, helpers). stx components communicate upward through
+   * defineEmits, so there is no prop-callback channel to pass a function down.
+   */
   onSubmit?: (values: Record<string, any>, helpers: FormHelpers) => void | Promise<void>
+  /** Bound as the `error` EVENT: `<Form @error="…">`. Receives the error map. */
   onError?: (errors: Record<string, string> | Error) => void
   className?: string
 }

package/src/ui/sidebar/SidebarSpace.stx

@@ -64,6 +64,7 @@ function onAction(event) {
   data-space
   data-space-id="{{ id }}"
   data-space-active="{{ active ? 'true' : 'false' }}"
+  @if(!active)inert@endif
   class="flex min-w-0 flex-1 flex-col"
   role="tabpanel"
   aria-label="{{ label || id }}"

package/src/ui/sidebar/SidebarSpaces.stx

@@ -51,6 +51,19 @@ export const config = JSON.stringify({
 </script>
 
 <script client>
+import {
+  clampIndex,
+  nativeVelocityToPanels,
+  panelStep,
+  pointerAxis,
+  settleTarget,
+  SETTLE_EASE,
+  SETTLE_MS,
+  wheelClaims,
+  WHEEL_IDLE_MS,
+  withResistance,
+} from './swipe'
+
 const emit = defineEmits()
 const componentRoot = window.__STX_CURRENT_ELEMENT__
 
@@ -72,39 +85,9 @@ let tints = []
 // 220px pane and a 320px pane need the same flick to advance.
 // ---------------------------------------------------------------------------
 
-const SETTLE_MS = 420
-const SETTLE_EASE = 'cubic-bezier(0.22, 0.61, 0.36, 1)'
-// Distance past the first/last space is compressed towards this asymptote, the
-// same thing UIScrollView does at the end of a list: the track keeps answering
-// the finger, but tells you there is nothing further.
-const RUBBER_LIMIT = 0.28
-// Commit thresholds. Either drag a third of the way, or flick — 1.5 panels per
-// second — in the direction you were already going.
-const COMMIT_DISTANCE = 0.3
-const COMMIT_VELOCITY = 0.0015
-
-function panelStep() {
-  return 100 / Math.max(1, ids.length)
-}
-
 function paint(offset, animate) {
   track.style.transition = animate ? `transform ${SETTLE_MS}ms ${SETTLE_EASE}` : 'none'
-  track.style.transform = `translate3d(${-offset * panelStep()}%, 0, 0)`
-}
-
-function rubber(distance) {
-  return (1 - 1 / (distance / RUBBER_LIMIT + 1)) * RUBBER_LIMIT
-}
-
-function withResistance(offset) {
-  const last = ids.length - 1
-  if (offset < 0) return -rubber(-offset)
-  if (offset > last) return last + rubber(offset - last)
-  return offset
-}
-
-function clampIndex(value) {
-  return Math.max(0, Math.min(ids.length - 1, value))
+  track.style.transform = `translate3d(${-offset * panelStep(ids.length)}%, 0, 0)`
 }
 
 function animates() {
@@ -174,7 +157,7 @@ function restored() {
 /** Move to a space. Always repaints — a rejected swipe still animates home. */
 function goTo(next, options) {
   const opts = options || {}
-  const target = clampIndex(next)
+  const target = clampIndex(next, ids.length)
   const changed = target !== index()
 
   paint(target, opts.animate !== false && animates())
@@ -192,8 +175,9 @@ function goTo(next, options) {
 // Gestures
 //
 // All three input paths (wheel, pointer, native) funnel into the same two
-// helpers: they track live with `paint(withResistance(offset), false)` while
-// moving, then hand the final offset and velocity to `settle`.
+// helpers: they track live with `paint(withResistance(…), false)` while moving,
+// then hand the final offset and velocity to `settle`. The thresholds and the
+// resistance curve live in `./swipe` so they can be tested directly.
 // ---------------------------------------------------------------------------
 
 let gestureStart = 0
@@ -204,12 +188,7 @@ function beginGesture() {
 }
 
 function settle(offset, velocity, source) {
-  const moved = offset - gestureStart
-  const direction = Math.sign(moved) || Math.sign(velocity)
-  const dragged = Math.abs(moved) > COMMIT_DISTANCE
-  const flicked = Math.abs(velocity) > COMMIT_VELOCITY && Math.sign(velocity) === direction
-  const commit = direction !== 0 && (dragged || flicked)
-  goTo(commit ? gestureStart + direction : gestureStart, { source })
+  goTo(settleTarget(offset, gestureStart, velocity, ids.length), { source })
 }
 
 // --- Trackpad ---------------------------------------------------------------
@@ -222,13 +201,18 @@ let wheelOffset = null
 let wheelIdle = null
 let wheelVelocity = 0
 let wheelLastAt = 0
+// Set the first time the host delivers a real gesture phase. From then on the
+// wheel stream is the same physical events arriving a second time, so running
+// the heuristic as well would drive the track twice and settle it twice.
+let nativeGesturesConfirmed = false
 
 function onWheel(event) {
+  if (nativeGesturesConfirmed) return
   if (ids.length < 2) return
   if (event.ctrlKey) return // pinch-zoom, not a swipe
 
   if (wheelOffset === null) {
-    if (Math.abs(event.deltaX) <= Math.abs(event.deltaY)) return
+    if (!wheelClaims(event.deltaX, event.deltaY)) return
     beginGesture()
     wheelOffset = gestureStart
     wheelLastAt = event.timeStamp
@@ -240,10 +224,10 @@ function onWheel(event) {
   wheelLastAt = event.timeStamp
   wheelVelocity = delta / elapsed
   wheelOffset += delta
-  paint(withResistance(wheelOffset), false)
+  paint(withResistance(wheelOffset, ids.length), false)
 
   clearTimeout(wheelIdle)
-  wheelIdle = setTimeout(endWheel, 90)
+  wheelIdle = setTimeout(endWheel, WHEEL_IDLE_MS)
 }
 
 function endWheel() {
@@ -253,10 +237,17 @@ function endWheel() {
   settle(offset, wheelVelocity, 'swipe')
 }
 
-/** Drop an in-flight wheel gesture without settling it. */
+/**
+ * Drop an in-flight wheel gesture without settling it, returning wherever it
+ * had dragged the track to. The caller adopts that offset so the handover to
+ * the native stream is invisible — resetting to the logical index instead
+ * would snap the track backwards at the exact moment the gesture gets better.
+ */
 function cancelWheelGesture() {
   clearTimeout(wheelIdle)
+  const carried = wheelOffset
   wheelOffset = null
+  return carried
 }
 
 // --- Touch and pen ----------------------------------------------------------
@@ -290,10 +281,9 @@ function onPointerMove(event) {
     // Axis lock. The first 8px of travel decides swipe or scroll, and the
     // decision stands for the rest of the gesture — re-deciding mid-drag is
     // what makes web carousels feel slippery.
-    const dx = event.clientX - pointerStartX
-    const dy = event.clientY - pointerStartY
-    if (Math.abs(dx) < 8 && Math.abs(dy) < 8) return
-    if (Math.abs(dx) <= Math.abs(dy)) { pointerId = null; return }
+    const axis = pointerAxis(event.clientX - pointerStartX, event.clientY - pointerStartY)
+    if (axis === 'undecided') return
+    if (axis === 'vertical') { pointerId = null; return }
     beginGesture()
     pointerOffset = gestureStart
     viewport.setPointerCapture(event.pointerId)
@@ -305,7 +295,7 @@ function onPointerMove(event) {
   pointerLastAt = event.timeStamp
   pointerVelocity = delta / elapsed
   pointerOffset += delta
-  paint(withResistance(pointerOffset), false)
+  paint(withResistance(pointerOffset, ids.length), false)
 }
 
 function onPointerUp(event) {
@@ -347,10 +337,24 @@ function onShortcut(event) {
   if (!event.metaKey || !event.altKey) return
   const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0
   if (step === 0) return
+  // Window-level, so a page with two spaces sidebars would otherwise advance
+  // both at once. Whichever one contains the focus owns the shortcut; with
+  // focus outside every sidebar the sole sidebar still answers, because that
+  // is the common case and requiring a click first would be surprising.
+  if (!ownsShortcut()) return
   event.preventDefault()
   goTo(index() + step, { source: 'keyboard' })
 }
 
+function ownsShortcut() {
+  const focused = document.activeElement
+  const owner = focused && focused !== document.body
+    ? focused.closest('[data-stx-sidebar-spaces]')
+    : null
+  if (owner) return owner === root
+  return document.querySelectorAll('[data-stx-sidebar-spaces]').length === 1
+}
+
 // ---------------------------------------------------------------------------
 // Craft
 //
@@ -381,11 +385,15 @@ function bindCraftGestures() {
       // Take over from the wheel path. The bridge exposes `onSwipe`
       // unconditionally but a host that does not implement gestures never
       // emits, so the wheel listener stays bound and this is the only moment
-      // we know the native stream is real. Cancelling any in-flight wheel
-      // gesture here stops the two paths settling the same swipe twice.
-      cancelWheelGesture()
+      // we know the native stream is real. From here the heuristic is not just
+      // redundant but harmful — the same physical scroll arrives on both paths
+      // — so it is retired for good, not merely cancelled.
+      nativeGesturesConfirmed = true
+      const carried = cancelWheelGesture()
       beginGesture()
-      offset = gestureStart
+      // Adopt whatever the wheel path had already dragged to, so the handover
+      // does not snap the track back to the logical index.
+      offset = carried === null ? gestureStart : carried
       return
     }
     if (offset === null) return
@@ -395,12 +403,12 @@ function bindCraftGestures() {
       offset = null
       // Craft reports velocity in points per second; the thresholds here are
       // panels per millisecond.
-      settle(settled, (swipe.velocityX || 0) / (viewport.clientWidth || 1) / 1000, 'swipe')
+      settle(settled, nativeVelocityToPanels(swipe.velocityX || 0, viewport.clientWidth), 'swipe')
       return
     }
 
     offset += (swipe.deltaX || 0) / (viewport.clientWidth || 1)
-    paint(withResistance(offset), false)
+    paint(withResistance(offset, ids.length), false)
   })
 
   if (typeof off === 'function') craftTeardown.push(off)
@@ -444,7 +452,7 @@ onMount(() => {
   tints = spaces.map(space => space.tint)
   if (ids.length === 0) return
 
-  const startIndex = clampIndex(config.index || 0)
+  const startIndex = clampIndex(config.index || 0, ids.length)
   const saved = restored()
   const initial = saved === -1 ? startIndex : saved
   index.set(initial)
@@ -523,6 +531,57 @@ defineExpose({
 </div>
 
 <style scoped>
+/* ---------------------------------------------------------------------------
+ * Standalone tinting.
+ *
+ * `applyTint` writes the palette onto `root.closest('[data-stx-sidebar]')` and
+ * falls back to this component's own root — the documented way to use
+ * `<SidebarSpaces>` without a `<Sidebar>` around it. But the rules that
+ * *consume* those variables live in Sidebar.stx, so the fallback target used to
+ * publish a palette nothing read: standalone spaces rendered with no gradient
+ * and no crossfade at all.
+ *
+ * These mirror Sidebar.stx's spaces block for the standalone case only. The
+ * `:not([data-stx-sidebar] *)` guard keeps them out of the nested case, where
+ * the pane is the thing that should be painted, not this inner column.
+ * ------------------------------------------------------------------------- */
+@property --stx-space-from { syntax: "<color>"; inherits: true; initial-value: #f2f0ec; }
+@property --stx-space-to { syntax: "<color>"; inherits: true; initial-value: #e6e3dd; }
+@property --stx-space-ink { syntax: "<color>"; inherits: true; initial-value: #2c2a28; }
+@property --stx-space-accent { syntax: "<color>"; inherits: true; initial-value: #5b5b63; }
+
+[data-stx-sidebar-spaces]:not([data-stx-sidebar] *) {
+  --stx-space-from: var(--stx-space-light-from, #f2f0ec);
+  --stx-space-to: var(--stx-space-light-to, #e6e3dd);
+  --stx-space-ink: var(--stx-space-light-ink, #2c2a28);
+  --stx-space-accent: var(--stx-space-light-accent, #5b5b63);
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.34) 0%, rgba(255, 255, 255, 0) 32%),
+    linear-gradient(180deg, var(--stx-space-from) 0%, var(--stx-space-to) 100%);
+  color: var(--stx-space-ink);
+  transition:
+    --stx-space-from 420ms ease,
+    --stx-space-to 420ms ease,
+    --stx-space-ink 420ms ease,
+    --stx-space-accent 420ms ease;
+}
+
+@media (prefers-color-scheme: dark) {
+  [data-stx-sidebar-spaces]:not([data-stx-sidebar] *) {
+    --stx-space-from: var(--stx-space-dark-from, #17171b);
+    --stx-space-to: var(--stx-space-dark-to, #0e0e11);
+    --stx-space-ink: var(--stx-space-dark-ink, #ededf0);
+    --stx-space-accent: var(--stx-space-dark-accent, #b9b9c2);
+    background:
+      linear-gradient(180deg, rgba(255, 255, 255, 0.06) 0%, rgba(255, 255, 255, 0) 30%),
+      linear-gradient(180deg, var(--stx-space-from) 0%, var(--stx-space-to) 100%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-stx-sidebar-spaces]:not([data-stx-sidebar] *) { transition: none; }
+}
+
 .stx-space-viewport {
   /* Vertical scrolling stays with the browser; horizontal belongs to us. */
   touch-action: pan-y;

package/src/ui/sidebar/swipe.ts

@@ -0,0 +1,115 @@
+/**
+ * The geometry and commit rules behind a spaces swipe.
+ *
+ * Extracted from `SidebarSpaces.stx` for the same reason `route-selection.ts`
+ * is: the component's client script cannot be imported, and this is the part
+ * worth pinning down. Everything here is pure — no DOM, no state — so the
+ * thresholds that decide whether a swipe advances can be asserted directly
+ * instead of inferred from a rendered pane.
+ *
+ * Position is measured in *panels*, not pixels: 1.5 means halfway between the
+ * second and third space. Keeping the gesture in panel units makes every
+ * threshold independent of how wide the sidebar happens to be, so a 220px pane
+ * and a 320px pane need the same flick to advance.
+ */
+
+/** Settle animation, matched by the tint crossfade so colour and motion agree. */
+export const SETTLE_MS = 420
+export const SETTLE_EASE = 'cubic-bezier(0.22, 0.61, 0.36, 1)'
+
+/**
+ * Travel past the first/last space is compressed towards this asymptote, the
+ * same thing a UIScrollView does at the end of a list: the track keeps
+ * answering the finger, but tells you there is nothing further.
+ */
+export const RUBBER_LIMIT = 0.28
+
+/** Drag this fraction of a panel and release, and the swipe commits. */
+export const COMMIT_DISTANCE = 0.3
+
+/** Or flick: panels per millisecond, i.e. 1.5 panels/second. */
+export const COMMIT_VELOCITY = 0.0015
+
+/** The first pointer travel that decides swipe-or-scroll, in CSS pixels. */
+export const AXIS_LOCK_PX = 8
+
+/** A wheel gesture ends when the stream goes quiet for this long. */
+export const WHEEL_IDLE_MS = 90
+
+/** Width of one panel as a percentage of the whole track. */
+export function panelStep(count: number): number {
+  return 100 / Math.max(1, count)
+}
+
+/** The compression curve applied beyond either end of the track. */
+export function rubber(distance: number): number {
+  return (1 - 1 / (distance / RUBBER_LIMIT + 1)) * RUBBER_LIMIT
+}
+
+/** Clamp an offset to the track, compressing rather than stopping at the ends. */
+export function withResistance(offset: number, count: number): number {
+  const last = count - 1
+  if (offset < 0)
+    return -rubber(-offset)
+  if (offset > last)
+    return last + rubber(offset - last)
+  return offset
+}
+
+export function clampIndex(value: number, count: number): number {
+  return Math.max(0, Math.min(count - 1, value))
+}
+
+/**
+ * Where a released gesture lands.
+ *
+ * A swipe advances at most one space however far or fast it was dragged —
+ * Arc behaves the same way, and it keeps a fast flick from skipping past the
+ * space you were looking at.
+ */
+export function settleTarget(
+  offset: number,
+  gestureStart: number,
+  velocity: number,
+  count: number,
+): number {
+  const moved = offset - gestureStart
+  const direction = Math.sign(moved) || Math.sign(velocity)
+  const dragged = Math.abs(moved) > COMMIT_DISTANCE
+  const flicked = Math.abs(velocity) > COMMIT_VELOCITY && Math.sign(velocity) === direction
+  const commit = direction !== 0 && (dragged || flicked)
+  return clampIndex(commit ? gestureStart + direction : gestureStart, count)
+}
+
+/**
+ * Whether a wheel event should start a swipe.
+ *
+ * Claimed only when the very first event is unambiguously horizontal. A DOM
+ * wheel stream carries no phase information, so this is a guess — the native
+ * path in Craft replaces it with real `NSEvent` phases when the host provides
+ * them.
+ */
+export function wheelClaims(deltaX: number, deltaY: number): boolean {
+  return Math.abs(deltaX) > Math.abs(deltaY)
+}
+
+export type PointerAxis = 'undecided' | 'horizontal' | 'vertical'
+
+/**
+ * Axis lock for touch and pen. The first 8px of travel decides, and the
+ * decision stands for the rest of the gesture — re-deciding mid-drag is what
+ * makes web carousels feel slippery.
+ */
+export function pointerAxis(dx: number, dy: number): PointerAxis {
+  if (Math.abs(dx) < AXIS_LOCK_PX && Math.abs(dy) < AXIS_LOCK_PX)
+    return 'undecided'
+  return Math.abs(dx) > Math.abs(dy) ? 'horizontal' : 'vertical'
+}
+
+/**
+ * Convert Craft's release velocity (points per second) into the panels per
+ * millisecond the commit thresholds are expressed in.
+ */
+export function nativeVelocityToPanels(velocityX: number, viewportWidth: number): number {
+  return velocityX / (viewportWidth || 1) / 1000
+}

package/dist/Form-mas630hy.stx

@@ -1,95 +0,0 @@
-<script server>
-export const action = $props.action || ''
-export const method = $props.method || 'POST'
-export const validationSchema = $props.validationSchema || {}
-export const className = $props.className || ''
-
-export const formClasses = `space-y-6 ${className}`.trim()
-export const errorClasses = `mt-1 text-sm text-red-600 dark:text-red-400`.trim()
-</script>
-
-<script client>
-const emit = defineEmits()
-const validationSchema = {{ validationSchema }}
-
-const errors = state({})
-const isSubmitting = state(false)
-const submitCount = state(0)
-
-function validateField(name, value, allValues) {
-  const schema = validationSchema[name]
-  if (!schema) return null
-  if (schema.required && !value) {
-    return schema.requiredMessage || `${name} is required`
-  }
-  if (schema.minLength && String(value).length < schema.minLength) {
-    return schema.minLengthMessage || `${name} must be at least ${schema.minLength} characters`
-  }
-  if (schema.maxLength && String(value).length > schema.maxLength) {
-    return schema.maxLengthMessage || `${name} must be at most ${schema.maxLength} characters`
-  }
-  if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
-    return schema.patternMessage || `${name} is invalid`
-  }
-  return null
-}
-
-function validateForm(values) {
-  const next = {}
-  let valid = true
-  for (const name of Object.keys(validationSchema)) {
-    const err = validateField(name, values[name], values)
-    if (err) {
-      next[name] = err
-      valid = false
-    }
-  }
-  errors.set(next)
-  return valid
-}
-
-async function onSubmit(event) {
-  event.preventDefault()
-  submitCount.set(submitCount() + 1)
-
-  const formData = new FormData(event.target)
-  const values = {}
-  for (const [k, v] of formData.entries()) values[k] = v
-
-  if (!validateForm(values)) {
-    emit('error', errors())
-    return
-  }
-
-  isSubmitting.set(true)
-  try {
-    emit('submit', values)
-  }
-  finally {
-    isSubmitting.set(false)
-  }
-}
-
-function setErrors(next) {
-  errors.set({ ...errors(), ...next })
-}
-
-function reset(form) {
-  errors.set({})
-  isSubmitting.set(false)
-  submitCount.set(0)
-  if (form?.reset) form.reset()
-}
-
-defineExpose({ errors, isSubmitting, submitCount, setErrors, reset, validateForm })
-</script>
-
-<form
-  class="{{ formClasses }}"
-  @if(action)action="{{ action }}"@endif
-  method="{{ method }}"
-  @submit="onSubmit($event)"
-  novalidate
->
-  <slot />
-</form>