@astryxdesign/core 0.7.8-canary.ffd29c5 → 0.7.8

package/src/BottomSheet/useSheetGestures.ts

@@ -354,6 +354,8 @@ export interface UseSheetGesturesOptions {
   snapHeights?: () => number[];
   /** Notified when the settled visible detent height (px) changes. */
   onSnap?: (heightPx: number) => void;
+  /** Called once a drag first moves the sheet off its detent. */
+  onTravelStart?: () => void;
   /**
    * Called with the scrim opacity the sheet should show (1 = fully visible,
    * 0 = hidden) as the drag moves and on settle. Full while the sheet is at
@@ -508,6 +510,7 @@ export function useSheetGestures({
   onDismiss,
   snapHeights,
   onSnap,
+  onTravelStart,
   onScrimOpacity,
   hasFixedHeight = false,
 }: UseSheetGesturesOptions): UseSheetGesturesResult {
@@ -654,6 +657,8 @@ export function useSheetGestures({
   // stops by the time the re-anchor read it.
   const snapHeightsRef = useRef(snapHeights);
   snapHeightsRef.current = snapHeights;
+  const onTravelStartRef = useRef(onTravelStart);
+  onTravelStartRef.current = onTravelStart;
 
   const onDismissRef = useRef(onDismiss);
   const canDismissRef = useRef(canDismiss);
@@ -1312,6 +1317,7 @@ export function useSheetGestures({
       if (!state.hasTraveled && next !== state.baseOffset) {
         state.hasTraveled = true;
         setIsTraveling(true);
+        onTravelStartRef.current?.();
       }
 
       // Mirror the scrim to the live drag: full at/above the mid detent,

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -134,6 +134,13 @@ export const docs = {
         'Whether the group is optional. Shows the optional indicator after the group label, unless a surrounding FormLayout already makes fields optional by default.',
       default: 'false',
     },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description:
+        'Whether the group needs at least one checked box. Shows the required indicator after the group label by the same rules as every input field. While no box is checked, the browser blocks submit and moves focus to the first box that is neither disabled nor read-only, with its own message. A disabled or read-only group requires nothing. Show your own error text through status. Mutually exclusive with isOptional.',
+      default: 'false',
+    },
     {
       name: 'density',
       type: "'compact' | 'balanced' | 'spacious'",

package/src/CheckboxList/CheckboxList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file CheckboxList.tsx
- * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext
+ * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext, requiredGroup
  * @output Exports CheckboxList component, CheckboxListProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -43,6 +43,7 @@ import {
   CheckboxListContext,
   type CheckboxListContextValue,
 } from './CheckboxListContext';
+import {createRequiredGroup} from './requiredGroup';
 
 const EMPTY_ARRAY: string[] = [];
 
@@ -72,6 +73,17 @@ export interface CheckboxListProps extends Omit<
    * @default false
    */
   isOptional?: boolean;
+  /**
+   * Whether the group needs at least one checked box. Shows the required
+   * indicator after the group label by the same rules as every input field.
+   * While no box is checked, the browser blocks submit and moves focus to
+   * the first box that is neither disabled nor read-only. A disabled or
+   * read-only group requires nothing. Show your own error text through
+   * `status`.
+   * Mutually exclusive with isOptional.
+   * @default false
+   */
+  isRequired?: boolean;
   /**
    * Status indicator for the checkbox group.
    * When set with a message, displays a colored message box below the group.
@@ -161,6 +173,7 @@ export function CheckboxList({
   isLabelHidden = false,
   description,
   isOptional = false,
+  isRequired = false,
   status,
   value,
   onChange,
@@ -193,6 +206,18 @@ export function CheckboxList({
   const descriptionID = useId();
   const statusMessageID = useId();
 
+  const requiredGroup = useMemo(
+    () => (isRequired ? createRequiredGroup() : undefined),
+    [isRequired],
+  );
+  const observeRequiredGroup = useCallback(
+    (container: HTMLDivElement | null) =>
+      container != null && requiredGroup != null
+        ? requiredGroup.observe(container)
+        : undefined,
+    [requiredGroup],
+  );
+
   const [, startTransition] = useTransition();
   const isCollectionMode = value !== undefined;
   const effectiveValue = value ?? EMPTY_ARRAY;
@@ -256,6 +281,7 @@ export function CheckboxList({
       isReadOnly,
       isInvalid: status?.type === 'error',
       loadingValues,
+      requiredGroup,
     }),
     [
       isCollectionMode,
@@ -267,6 +293,7 @@ export function CheckboxList({
       isReadOnly,
       status?.type,
       loadingValues,
+      requiredGroup,
     ],
   );
 
@@ -279,6 +306,7 @@ export function CheckboxList({
       labelID={labelID}
       isGroupLabel
       isOptional={isOptional}
+      isRequired={isRequired}
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
       status={
@@ -302,7 +330,11 @@ export function CheckboxList({
           {...rest}
           // The disabled-message tooltip anchors here; its handlers are gated
           // internally by isEnabled, so attaching unconditionally is safe.
-          ref={useMergedRefs(ref, disabledMessageTooltip.ref)}
+          ref={useMergedRefs(
+            ref,
+            disabledMessageTooltip.ref,
+            observeRequiredGroup,
+          )}
           {...mergeProps(
             stylex.props(controlXstyle),
             controlClassName,

package/src/CheckboxList/CheckboxListContext.tsx

@@ -4,12 +4,14 @@
 
 /**
  * @file CheckboxListContext.tsx
- * @input Uses the private layer-scoped context factory
+ * @input Uses the private layer-scoped context factory and the RequiredGroup
+ *   type
  * @output Exports CheckboxListContext for parent-child communication
  * @position Internal context; consumed by CheckboxList.tsx and CheckboxListItem.tsx
  */
 
 import {createLayerScopedContext} from '../Layer/layerScopedContext';
+import type {RequiredGroup} from './requiredGroup';
 
 export interface CheckboxListContextValue {
   value?: string[];
@@ -49,6 +51,12 @@ export interface CheckboxListContextValue {
    * when idle.
    */
   loadingValues?: ReadonlyArray<string>;
+  /**
+   * Present when the list is `isRequired`. Each item registers its checkbox,
+   * so that while no box is checked the first enabled box carries native
+   * `required`.
+   */
+  requiredGroup?: RequiredGroup;
 }
 
 export const CheckboxListContext =

package/src/CheckboxList/CheckboxListItem.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, useId, useRef, type ReactNode} from 'react';
+import {use, useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
@@ -30,6 +30,7 @@ import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
 import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
 import {joinAriaIDs} from '../utils/inputAria';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {ItemAlign} from '../Item';
 import {
   registerEnglishFallback,
@@ -284,6 +285,26 @@ export function CheckboxListItem({
   const checkboxRef = useRef<HTMLInputElement | null>(null);
   const hasRowInteraction = isInteractive || onClickProp != null;
 
+  // A required group decides which box carries native `required` from the
+  // state of every box. A change to this box's state registers it again.
+  const requiredGroup = ctx?.requiredGroup;
+  const isBoxChecked = resolvedChecked === true;
+  const isBoxEnabled = !effectiveDisabled && !effectiveReadOnly;
+  const registerWithRequiredGroup = useCallback(
+    (input: HTMLInputElement | null) =>
+      input != null && requiredGroup != null
+        ? requiredGroup.register(input, {
+            isChecked: isBoxChecked,
+            isEnabled: isBoxEnabled,
+          })
+        : undefined,
+    [requiredGroup, isBoxChecked, isBoxEnabled],
+  );
+  const checkboxInputRef = useMergedRefs(
+    checkboxRef,
+    registerWithRequiredGroup,
+  );
+
   // A read-only checkbox carries aria-readonly, which the row's clickable
   // container treats as a non-interactive target, so a click on it would be
   // delegated straight back to the checkbox without end. Stop that click at
@@ -349,7 +370,7 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <DescribedCheckboxInput
-          ref={checkboxRef}
+          ref={checkboxInputRef}
           label={checkboxLabel}
           aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
           isLabelHidden

package/src/CheckboxList/requiredGroup.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file requiredGroup.ts
+ * @input The checkbox inputs of a required CheckboxList and each box's state;
+ *   Core's shared mutation observer
+ * @output Exports createRequiredGroup, RequiredGroup, and RequiredGroupBox
+ * @position Internal to CheckboxList; CheckboxList creates one for an
+ *   `isRequired` group and CheckboxListItem registers its checkbox with it
+ *
+ * The browser has no required state for a group of checkboxes. While no box
+ * is checked, the first enabled box carries native `required`. The browser
+ * then blocks submit and moves focus to that box with its own message. Once
+ * any box is checked, no box carries `required`.
+ */
+
+import {observeMutations} from '../utils/sharedMutationObserver';
+
+/** The state of one box that decides which box carries `required`. */
+export interface RequiredGroupBox {
+  isChecked: boolean;
+  /** False for a disabled or read-only box, which the user cannot check. */
+  isEnabled: boolean;
+}
+
+export interface RequiredGroup {
+  /**
+   * Adds a checkbox with its state and updates `required` on every box.
+   * Returns a function that removes the checkbox, clears its `required`, and
+   * updates the rest. An item registers again when its state changes.
+   */
+  register: (input: HTMLInputElement, box: RequiredGroupBox) => () => void;
+  /**
+   * Updates `required` when the group's options move, for example after a
+   * keyed reorder, which registers no box again. Returns a function that
+   * stops it.
+   */
+  observe: (container: HTMLElement) => () => void;
+}
+
+const MOVE_OPTIONS: MutationObserverInit = {childList: true, subtree: true};
+
+function byDocumentOrder(a: HTMLInputElement, b: HTMLInputElement): number {
+  return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
+    ? -1
+    : 1;
+}
+
+export function createRequiredGroup(): RequiredGroup {
+  const boxes = new Map<HTMLInputElement, RequiredGroupBox>();
+
+  function update() {
+    const ordered = [...boxes.keys()].sort(byDocumentOrder);
+    const isEmpty = ![...boxes.values()].some(box => box.isChecked);
+    const target = isEmpty
+      ? ordered.find(input => boxes.get(input)?.isEnabled === true)
+      : undefined;
+    for (const input of ordered) {
+      input.required = input === target;
+    }
+  }
+
+  return {
+    register(input, box) {
+      boxes.set(input, box);
+      update();
+      return () => {
+        boxes.delete(input);
+        input.required = false;
+        update();
+      };
+    },
+    observe(container) {
+      return observeMutations(container, MOVE_OPTIONS, update);
+    },
+  };
+}

package/src/DateInput/PickerWheel.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file PickerWheel.tsx
- * @input Wheel's props (wheelOptions.ts): options, value and change callback
+ * @input Wheel's props (wheelOptions.ts): options, value and change callback;
+ *   optionally a ref for programmatic turns
  * @output PickerWheel: one picker column that moves like UIPickerView
  * @position Internal component; the Wheel under a finger (Wheel.tsx picks it)
  *
@@ -15,7 +16,14 @@
  * DateInputTouch.test.tsx, DateInput.doc.mjs and TimeInput.doc.mjs.
  */
 
-import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {scrollTypeOf} from '../gestures/GestureHost';
 import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
@@ -50,6 +58,7 @@ import {
   type WheelLayout,
 } from './wheelPhysics';
 import {
+  canSpinTo,
   endIndex,
   nearestEnabledIndex,
   steppedIndex,
@@ -197,6 +206,7 @@ export function PickerWheel({
   value,
   onChange,
   isActive = true,
+  ref,
 }: WheelProps) {
   const columnRef = useRef<HTMLDivElement | null>(null);
   const rowsRef = useRef<HTMLDivElement | null>(null);
@@ -584,8 +594,31 @@ export function PickerWheel({
     isPointerKept: true,
   });
 
-  // A key commits the row at `position` at once and turns the wheel there
-  // from `offset`.
+  // A spin turns only onto an enabled row (canSpinTo). So its arrival commits
+  // that row, and nothing turns on past it. It reports the row it was asked
+  // for, as the scrolling column does.
+  const spinTo = useCallback(
+    async (index: number): Promise<boolean> =>
+      new Promise(resolve => {
+        if (!canSpinTo(latestRef.current.options, index)) {
+          resolve(false);
+          return;
+        }
+        const offset = motion.offset();
+        move(turnCurve(columnRef.current, offset, index * ROW_HEIGHT), {
+          onEnd: (outcome, end) => {
+            if (outcome === 'arrived') {
+              arrive(end);
+            }
+            resolve(outcome === 'arrived');
+          },
+        });
+      }),
+    [motion, move, arrive],
+  );
+
+  useImperativeHandle(ref, () => ({spinTo}), [spinTo]);
+
   const turnToPosition = useCallback(
     (position: number, offset: number) => {
       const current = latestRef.current;

package/src/DateInput/Wheel.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file Wheel.tsx
- * @input Option list, selected value and change callback
+ * @input Option list, selected value and change callback; a ref for
+ *   programmatic turns
  * @output Exports Wheel (one picker column), ScrollWheel (the scrolling
  *   column) and the shared types of wheelOptions.ts
  * @position Internal component; consumed by MonthYearWheels.tsx,
@@ -27,7 +28,13 @@
  * - /packages/core/src/DateInput/DateInputTouch.test.tsx
  */
 
-import {useCallback, useEffect, useRef, useState} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -51,6 +58,7 @@ import {usePointerDragScroll} from './usePointerDragScroll';
 import {useScrollSettle} from './useScrollSettle';
 import {useWheelListbox} from './useWheelListbox';
 import {
+  canSpinTo,
   endIndex,
   nearestEnabledIndex,
   steppedIndex,
@@ -59,6 +67,7 @@ import {
 
 export {
   nearestEnabledIndex,
+  type WheelHandle,
   type WheelOption,
   type WheelProps,
 } from './wheelOptions';
@@ -299,7 +308,26 @@ export function ScrollWheel({
   value,
   onChange,
   isActive = true,
+  ref,
 }: WheelProps) {
+  // A spin commits the row at once. The new value then scrolls the column
+  // there, as any new value does.
+  useImperativeHandle(
+    ref,
+    () => ({
+      spinTo: async index => {
+        if (!canSpinTo(options, index)) {
+          return false;
+        }
+        const option = options[index];
+        if (option.value !== value) {
+          onChange(option.value);
+        }
+        return true;
+      },
+    }),
+    [options, value, onChange],
+  );
   const scrollerRef = useRef<HTMLDivElement | null>(null);
   const selectedIndex = Math.max(
     0,
@@ -532,7 +560,6 @@ export function ScrollWheel({
   // there is no way to share — it takes every touch that lands on it.
   useOwnScrollGesture(scrollerRef, 'all', {isEnabled: isActive});
 
-  // A key commits the row it moves to and scrolls the column there.
   const moveTo = useCallback(
     (row: number | null) => {
       const option = row == null ? undefined : options[row];

package/src/DateInput/datePickerTouch.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file datePickerTouch.ts
+ * @input The date and time pickers' touch-only pieces
+ * @output Re-exports what the date and time sheets use only under a finger:
+ *   TimeWheels
+ * @position The pickers' touch layer. The sheets import touch behaviour from
+ *   here only, so a desktop build can replace this one module.
+ *
+ * SYNC: When modified, update TouchTimeField.tsx and TouchDateTimeField.tsx.
+ */
+
+export {TimeWheels} from '../TimeInput/TimeWheels';
+export type {TimeWheelsProps} from '../TimeInput/TimeWheels';

package/src/DateInput/wheelOptions.ts

@@ -3,8 +3,8 @@
 /**
  * @file wheelOptions.ts
  * @input Nothing; types, the row height and pure functions
- * @output WheelOption, WheelProps, WHEEL_ROW_HEIGHT, nearestEnabledIndex,
- *   steppedIndex and endIndex: what both wheels share
+ * @output WheelOption, WheelProps, WheelHandle, WHEEL_ROW_HEIGHT, canSpinTo,
+ *   nearestEnabledIndex, steppedIndex and endIndex: what both wheels share
  * @position Internal; read by Wheel.tsx (which re-exports all of it) and
  *   PickerWheel.tsx
  *
@@ -13,6 +13,8 @@
  * - /packages/core/src/DateInput/PickerWheel.tsx
  */
 
+import type {Ref} from 'react';
+
 /**
  * The row height, px (`dateInputTouchSizes.wheelItemSize`): the pitch of both
  * columns' rows, and the unit of the touch wheel's offset.
@@ -37,6 +39,19 @@ export interface WheelOption {
   order?: number;
 }
 
+/** What a Wheel's `ref` exposes. */
+export interface WheelHandle {
+  /**
+   * Turn the wheel onto `index` (an index into `options`) on the tap spin, then
+   * commit it as a rest would. Resolves true once that row is the committed
+   * one, false if a finger or another turn interrupted it or the wheel went
+   * away first. An index outside `options` or a disabled row resolves false at
+   * once, and nothing turns. Under a fine pointer the row commits at once. The
+   * column then scrolls to it as for any new value, on the same rule.
+   */
+  spinTo(index: number): Promise<boolean>;
+}
+
 export interface WheelProps {
   /** Accessible name for the column, e.g. "Month". */
   label: string;
@@ -53,6 +68,20 @@ export interface WheelProps {
    * motion.
    */
   isActive?: boolean;
+  /** Programmatic turns: `spinTo(index)`. */
+  ref?: Ref<WheelHandle>;
+}
+
+/**
+ * Whether `spinTo(index)` may turn onto `index`: an enabled row of `options`.
+ * The touch wheel and the scrolling column answer a spin by the same rule.
+ */
+export function canSpinTo(
+  options: ReadonlyArray<WheelOption>,
+  index: number,
+): boolean {
+  const option = options[index];
+  return option != null && !option.isDisabled;
 }
 
 /**