@astryxdesign/core 0.3.0 → 0.4.0

package/src/NumberInput/NumberInput.tsx

@@ -30,6 +30,7 @@ import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   sizeVars,
+  spacingVars,
   radiusVars,
   typographyVars,
   typeScaleVars,
@@ -37,6 +38,7 @@ import {
 } from '../theme/tokens.stylex';
 import {
   Field,
+  InputClearButton,
   type InputStatus,
   inputWrapperStyles,
   inputStatusBorderStyles,
@@ -57,22 +59,8 @@ const styles = stylex.create({
   wrapper: {
     zIndex: 1,
   },
-  clearButton: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: 0,
-    margin: 0,
-    borderWidth: 0,
-    borderStyle: 'none',
-    backgroundColor: 'transparent',
-    cursor: 'pointer',
-    borderRadius: radiusVars['--radius-element'],
-    outline: {
-      default: 'none',
-      ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: 1,
+  wrapperWithNumberSteppers: {
+    paddingInlineEnd: 0,
   },
   input: {
     display: 'block',
@@ -81,18 +69,6 @@ const styles = stylex.create({
     borderWidth: 0,
     borderStyle: 'none',
     padding: 0,
-    // Hide the browser's native number spinners; the component provides its own
-    // affordances (keyboard entry, optional clear button) and the spinners
-    // clash with the input's visual treatment and sizing.
-    MozAppearance: 'textfield',
-    '::-webkit-inner-spin-button': {
-      WebkitAppearance: 'none',
-      margin: 0,
-    },
-    '::-webkit-outer-spin-button': {
-      WebkitAppearance: 'none',
-      margin: 0,
-    },
     fontFamily: typographyVars['--font-family-body'],
     fontSize: {
       default: typeScaleVars['--text-body-size'],
@@ -119,6 +95,56 @@ const styles = stylex.create({
     color: colorVars['--color-text-secondary'],
     flexShrink: 0,
   },
+  numberSteppers: {
+    alignSelf: 'stretch',
+    display: 'flex',
+    flexDirection: 'column',
+    flexShrink: 0,
+    width: spacingVars['--spacing-4'],
+    marginBlock: `calc(-1 * ${spacingVars['--spacing-1']})`,
+    borderInlineStartWidth: borderVars['--border-width'],
+    borderInlineStartStyle: 'solid',
+    borderInlineStartColor: colorVars['--color-border-emphasized'],
+    overflow: 'hidden',
+    borderStartEndRadius: radiusVars['--radius-element'],
+    borderEndEndRadius: radiusVars['--radius-element'],
+  },
+  numberStepperButton: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flex: 1,
+    minHeight: 0,
+    padding: 0,
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    color: colorVars['--color-icon-secondary'],
+    backgroundColor: colorVars['--color-background-surface'],
+    backgroundImage: {
+      default: null,
+      ':hover': {
+        '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
+      },
+      ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
+    },
+    cursor: 'pointer',
+    outline: 'none',
+  },
+  numberStepperButtonDisabled: {
+    color: colorVars['--color-icon-disabled'],
+    cursor: 'not-allowed',
+    backgroundImage: 'none',
+  },
+  decrementButton: {
+    borderBlockStartWidth: borderVars['--border-width'],
+    borderBlockStartStyle: 'solid',
+    borderBlockStartColor: colorVars['--color-border-emphasized'],
+  },
+  incrementIcon: {
+    transform: 'rotate(180deg)',
+  },
 });
 
 const sizeStyles = stylex.create({
@@ -183,6 +209,17 @@ interface NumberInputPropsBase extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Whether the input is read-only.
+   * The value is shown at full opacity and still submits with the form, but
+   * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
+   * stays in the tab order — use it for a value the user should see and send
+   * but not change. Stepping is off in every form while read-only: arrow keys,
+   * the wheel, and the number steppers. `isDisabled` takes precedence when both
+   * are set.
+   * @default false
+   */
+  isReadOnly?: boolean;
   /**
    * Explains why the input is disabled. When set together with `isDisabled`,
    * the input shows a tooltip with this text on hover and keyboard focus, and
@@ -282,6 +319,21 @@ interface NumberInputPropsBase extends Omit<
    * @default 1
    */
   step?: number | null;
+  /**
+   * Formats the committed value while the input is not being edited.
+   * The raw numeric value is shown on focus so it remains editable.
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Whether scrolling the wheel over a focused input steps the value.
+   * @default true
+   */
+  isWheelEnabled?: boolean;
+  /**
+   * Whether to show increment and decrement buttons at the end of the input.
+   * @default false
+   */
+  hasNumberSteppers?: boolean;
   /**
    * Units text to display at the end of the input (e.g., "%" or "GB").
    */
@@ -373,6 +425,88 @@ function parseNumberInput(
   return num;
 }
 
+type StepDirection = -1 | 1;
+
+function getDecimalPlaces(value: number): number {
+  const [coefficient, exponentText] = String(value).toLowerCase().split('e');
+  const fractionLength = coefficient.split('.')[1]?.length ?? 0;
+  const exponent = exponentText == null ? 0 : Number(exponentText);
+  return Math.max(0, fractionLength - exponent);
+}
+
+function getEffectiveStep(
+  step: number | null | undefined,
+  isIntegerOnly: boolean,
+): number {
+  if (
+    step == null ||
+    !Number.isFinite(step) ||
+    step <= 0 ||
+    (isIntegerOnly && !Number.isInteger(step))
+  ) {
+    return 1;
+  }
+  return step;
+}
+
+function getSteppedValue({
+  currentValue,
+  direction,
+  min,
+  max,
+  step,
+  isIntegerOnly,
+}: {
+  currentValue: number | null;
+  direction: StepDirection;
+  min?: number | null;
+  max?: number | null;
+  step?: number | null;
+  isIntegerOnly: boolean;
+}): number | null {
+  const effectiveStep = getEffectiveStep(step, isIntegerOnly);
+  const stepBase =
+    min != null && (!isIntegerOnly || Number.isInteger(min)) ? min : 0;
+
+  let nextValue: number;
+  if (currentValue == null) {
+    nextValue = direction === 1 ? (min ?? 0) : (max ?? 0);
+    if (isIntegerOnly) {
+      nextValue =
+        direction === 1 ? Math.ceil(nextValue) : Math.floor(nextValue);
+    }
+  } else {
+    const stepPosition = (currentValue - stepBase) / effectiveStep;
+    const tolerance = Number.EPSILON * Math.max(1, Math.abs(stepPosition)) * 4;
+    const nextStepPosition =
+      direction === 1
+        ? Math.floor(stepPosition + tolerance) + 1
+        : Math.ceil(stepPosition - tolerance) - 1;
+    nextValue = stepBase + nextStepPosition * effectiveStep;
+  }
+
+  if (min != null) {
+    nextValue = Math.max(min, nextValue);
+  }
+  if (max != null) {
+    nextValue = Math.min(max, nextValue);
+  }
+
+  if (!Number.isFinite(nextValue)) {
+    return currentValue;
+  }
+
+  const precision = Math.min(
+    12,
+    Math.max(getDecimalPlaces(effectiveStep), getDecimalPlaces(stepBase)),
+  );
+  const roundedValue = Number(nextValue.toFixed(precision));
+  if (isIntegerOnly && !Number.isInteger(roundedValue)) {
+    return currentValue;
+  }
+  return Object.is(roundedValue, -0) ? 0 : roundedValue;
+}
+
 /**
  * A number input component for collecting numeric user input.
  * Only calls onChange when the entered value passes validation.
@@ -390,6 +524,7 @@ export function NumberInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  isReadOnly = false,
   disabledMessage,
   startIcon,
   labelIcon,
@@ -406,6 +541,9 @@ export function NumberInput({
   min,
   max,
   step,
+  formatValue,
+  isWheelEnabled = true,
+  hasNumberSteppers = false,
   units,
   isIntegerOnly = false,
   onFocus,
@@ -433,6 +571,7 @@ export function NumberInput({
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
+  const [isFocused, setIsFocused] = useState(false);
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the input container (which already exists) and
@@ -473,8 +612,15 @@ export function NumberInput({
     inputGroup,
   );
 
-  // Display value: pending input if typing, otherwise the raw value
-  // Note: With type="number", we can't use formatted display values
+  const formattedValue = useMemo(() => {
+    if (value == null) {
+      return '';
+    }
+    return formatValue?.(value) ?? String(value);
+  }, [formatValue, value]);
+
+  // Preserve pending text while editing. Otherwise show the formatted value
+  // at rest and the raw numeric value while focused so it remains editable.
   const displayValue = useMemo(() => {
     if (pendingInput !== null) {
       return pendingInput;
@@ -482,8 +628,8 @@ export function NumberInput({
     if (value == null) {
       return '';
     }
-    return String(value);
-  }, [pendingInput, value]);
+    return isFocused ? String(value) : formattedValue;
+  }, [formattedValue, isFocused, pendingInput, value]);
 
   // Check if current pending input is valid (for styling purposes)
   const isInputValid = useMemo(() => {
@@ -499,7 +645,7 @@ export function NumberInput({
       // Value can't change while showing a disabled message (the field is
       // read-only and non-native-disabled), but guard the handler too so the
       // pending value and onChange never fire.
-      if (isDisabled) {
+      if (isDisabled || isReadOnly) {
         return;
       }
       const newValue = e.target.value;
@@ -511,12 +657,13 @@ export function NumberInput({
         onChange(parsed);
       }
     },
-    [value, onChange, min, max, isIntegerOnly, isDisabled],
+    [value, onChange, min, max, isIntegerOnly, isDisabled, isReadOnly],
   );
 
   // Handle focus
   const handleFocus = useCallback(
     (e: FocusEvent<HTMLInputElement>) => {
+      setIsFocused(true);
       onFocus?.(e);
     },
     [onFocus],
@@ -546,14 +693,69 @@ export function NumberInput({
 
       // Clear pending input - display will revert to formatted value
       setPendingInput(null);
+      setIsFocused(false);
       onBlur?.(e);
     },
     [pendingInput, value, onChange, min, max, isIntegerOnly, onBlur, hasClear],
   );
 
+  const valueForStepping = useMemo(() => {
+    if (pendingInput === null) {
+      return value ?? null;
+    }
+    if (pendingInput.trim() === '') {
+      return null;
+    }
+    return (
+      parseNumberInput(pendingInput, {min, max, isIntegerOnly}) ?? value ?? null
+    );
+  }, [isIntegerOnly, max, min, pendingInput, value]);
+
+  const getNextValue = useCallback(
+    (direction: StepDirection) =>
+      getSteppedValue({
+        currentValue: valueForStepping,
+        direction,
+        min,
+        max,
+        step,
+        isIntegerOnly,
+      }),
+    [isIntegerOnly, max, min, step, valueForStepping],
+  );
+
+  const stepValue = useCallback(
+    (direction: StepDirection) => {
+      // A read-only field is not steppable by any route: keyboard, wheel, or
+      // the stepper buttons all land here.
+      if (isDisabled || isReadOnly) {
+        return;
+      }
+      const nextValue = getNextValue(direction);
+      if (nextValue == null) {
+        return;
+      }
+      setPendingInput(null);
+      if (nextValue !== value) {
+        onChange(nextValue);
+      }
+    },
+    [getNextValue, isDisabled, isReadOnly, onChange, value],
+  );
+
   // Handle keyboard events
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      const hasModifier = e.altKey || e.ctrlKey || e.metaKey || e.shiftKey;
+      if (!hasModifier && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+        onKeyDown?.(e);
+        if (e.defaultPrevented) {
+          return;
+        }
+        e.preventDefault();
+        stepValue(e.key === 'ArrowUp' ? 1 : -1);
+        return;
+      }
       if (e.key === 'Enter') {
         // Validate and commit on Enter
         if (pendingInput !== null) {
@@ -588,18 +790,52 @@ export function NumberInput({
       onEnter,
       onKeyDown,
       hasClear,
+      stepValue,
     ],
   );
 
-  // While focused, a wheel gesture steps the value — keep that gesture from
-  // also bubbling up and scrolling an ancestor container (page, Dialog,
-  // ScrollArea). When the input isn't focused the wheel isn't stepping the
-  // value, so normal scrolling is left alone.
-  const handleWheel = useCallback((e: React.WheelEvent<HTMLInputElement>) => {
-    if (document.activeElement === e.currentTarget) {
-      e.stopPropagation();
-    }
-  }, []);
+  // React's delegated wheel listener can be passive, so use a native,
+  // explicitly non-passive listener to prevent page scrolling only when this
+  // focused input is intentionally consuming the gesture to step its value.
+  const wheelListenerRef = useCallback(
+    (input: HTMLInputElement | null) => {
+      if (input == null || !isWheelEnabled) {
+        return;
+      }
+
+      const handleWheel = (event: WheelEvent) => {
+        // Bail before preventDefault so a read-only input never swallows the
+        // page scroll it cannot act on.
+        if (
+          document.activeElement !== input ||
+          isDisabled ||
+          isReadOnly ||
+          event.deltaY === 0 ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.metaKey ||
+          event.shiftKey
+        ) {
+          return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        stepValue(event.deltaY < 0 ? 1 : -1);
+      };
+
+      input.addEventListener('wheel', handleWheel, {passive: false});
+      return () => input.removeEventListener('wheel', handleWheel);
+    },
+    [isDisabled, isReadOnly, isWheelEnabled, stepValue],
+  );
+
+  const mergedInputRef = useMemo(
+    () => mergeRefs(ref, inputRef, wheelListenerRef),
+    [ref, wheelListenerRef],
+  );
+
+  const canIncrement = getNextValue(1) !== valueForStepping;
+  const canDecrement = getNextValue(-1) !== valueForStepping;
 
   // Handle clear button click
   const handleClear = useCallback(() => {
@@ -630,10 +866,16 @@ export function NumberInput({
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
       {...mergeProps(
-        themeProps('number-input', {size, status: status?.type ?? null}),
+        themeProps('number-input', {
+          size,
+          status: status?.type ?? null,
+          disabled: isDisabled ? 'disabled' : null,
+          readonly: isReadOnly ? 'readonly' : null,
+        }),
         stylex.props(
           inputWrapperStyles.base,
           styles.wrapper,
+          hasNumberSteppers && styles.wrapperWithNumberSteppers,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
@@ -649,29 +891,33 @@ export function NumberInput({
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
         {...rest}
-        ref={mergeRefs(ref, inputRef)}
+        ref={mergedInputRef}
         id={id}
-        name={htmlName}
-        type="number"
+        name={isDisabled || formatValue ? undefined : htmlName}
+        type="text"
+        inputMode={isIntegerOnly ? 'numeric' : 'decimal'}
+        role="spinbutton"
         autoComplete={autoComplete}
         value={displayValue}
         onChange={handleInputChange}
         onFocus={handleFocus}
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
-        onWheel={handleWheel}
         placeholder={placeholder}
         // With a disabledMessage the input keeps focusability via aria-disabled
         // so the reason is focus-discoverable; readOnly + the handler guards
         // keep the value from changing.
         disabled={isDisabled && !showsDisabledMessage}
         aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={showsDisabledMessage || undefined}
+        readOnly={isReadOnly || showsDisabledMessage || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
-        min={min ?? undefined}
-        max={max ?? undefined}
-        step={step ?? undefined}
+        aria-valuemin={min ?? undefined}
+        aria-valuemax={max ?? undefined}
+        aria-valuenow={value ?? undefined}
+        aria-valuetext={
+          value == null || !formatValue ? undefined : formattedValue
+        }
         aria-describedby={ariaDescribedBy}
         aria-required={isRequired === true ? 'true' : undefined}
         aria-invalid={
@@ -684,6 +930,13 @@ export function NumberInput({
           !isInputValid && styles.inputInvalid,
         )}
       />
+      {formatValue && htmlName && !isDisabled && (
+        <input
+          type="hidden"
+          name={htmlName}
+          value={value == null ? '' : String(value)}
+        />
+      )}
       {units && (
         <span id={unitsID} {...stylex.props(styles.units)}>
           {units}
@@ -697,16 +950,57 @@ export function NumberInput({
       <VisuallyHidden as="div" role="alert" aria-live="assertive">
         {!isInputValid ? 'Invalid number' : ''}
       </VisuallyHidden>
-      {hasClear && value != null && !isDisabled && (
-        <button
-          type="button"
+      {hasClear && value != null && !isDisabled && !isReadOnly && (
+        <InputClearButton
+          label={t('@astryx.numberInput.clearLabel', {label})}
           onClick={handleClear}
-          aria-label={t('@astryx.numberInput.clearLabel', {label})}
-          {...stylex.props(styles.clearButton)}>
-          <Icon icon="close" size="sm" color="secondary" />
-        </button>
+        />
       )}
       {statusIcon}
+      {hasNumberSteppers && (
+        <div {...stylex.props(styles.numberSteppers)}>
+          <button
+            type="button"
+            tabIndex={-1}
+            disabled={isDisabled || isReadOnly || !canIncrement}
+            aria-label={t('@astryx.numberInput.incrementLabel', {label})}
+            onPointerDown={event => event.preventDefault()}
+            onClick={() => {
+              inputRef.current?.focus();
+              stepValue(1);
+            }}
+            {...stylex.props(
+              styles.numberStepperButton,
+              (isDisabled || isReadOnly || !canIncrement) &&
+                styles.numberStepperButtonDisabled,
+            )}>
+            <Icon
+              icon="chevronDown"
+              size="xsm"
+              color="inherit"
+              xstyle={styles.incrementIcon}
+            />
+          </button>
+          <button
+            type="button"
+            tabIndex={-1}
+            disabled={isDisabled || isReadOnly || !canDecrement}
+            aria-label={t('@astryx.numberInput.decrementLabel', {label})}
+            onPointerDown={event => event.preventDefault()}
+            onClick={() => {
+              inputRef.current?.focus();
+              stepValue(-1);
+            }}
+            {...stylex.props(
+              styles.numberStepperButton,
+              styles.decrementButton,
+              (isDisabled || isReadOnly || !canDecrement) &&
+                styles.numberStepperButtonDisabled,
+            )}>
+            <Icon icon="chevronDown" size="xsm" color="inherit" />
+          </button>
+        </div>
+      )}
     </div>
   );
 

package/src/Outline/Outline.tsx

@@ -42,6 +42,7 @@ import type {BaseProps} from '../BaseProps';
 import {useScrollSpy} from './useScrollSpy';
 import type {OutlineItem} from './types';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 export type {OutlineItem} from './types';
@@ -211,10 +212,6 @@ const styles = stylex.create({
     ':active': {
       backgroundColor: colorVars['--color-overlay-pressed'],
     },
-    ':focus-visible': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: 2,
-    },
   },
   activeLink: {
     color: colorVars['--color-text-primary'],
@@ -473,7 +470,7 @@ export function Outline({
                     active: isActive ? 'active' : null,
                     level: item.level,
                   }),
-                  stylex.props(
+                  focusOutlineProps.focusVisible(
                     styles.link,
                     densityStyles[density],
                     getIndentStyle(item.level),

package/src/Pagination/Pagination.doc.mjs

@@ -66,7 +66,7 @@ export const docs = {
       name: 'variant',
       type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
       description:
-        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label — 'Page [ n ] / N' — flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
+        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
       default: "'pages'",
     },
     {