@astryxdesign/core 0.5.0-canary.f4d494c → 0.5.0

package/src/DateInput/NativeDateField.tsx

@@ -1,623 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-/**
- * @file NativeDateField.tsx
- * @input Uses React, Field, Icon, InputClearButton, Spinner, useCalendarConstraints
- * @output Exports NativeDateField — the OS-picker touch surface
- * @position One of DateInput's three surfaces. `DateInput` picks the pointer
- *   field on a mouse and, on touch, either `TouchDateField` (the default) or
- *   this one when the consumer opts in with `nativePicker`.
- *
- * Hands date picking to the platform: a real `<input type="date">`, whose
- * picker the OS draws — the iOS wheel, the Android calendar dialog. The field
- * itself still looks like every other Astryx input, and DateInput paints its
- * text so `format` and `placeholder` keep applying.
- *
- * Everything unusual in here was measured on a real iOS device; the comments
- * say which behaviour forced which decision, because none of them are
- * reproducible in a desktop browser.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/DateInput/DateInput.tsx (the `nativePicker` prop)
- * - /packages/core/src/DateInput/DateInput.doc.mjs (prop table)
- * - /packages/core/src/DateInput/DateInputNative.test.tsx (tests)
- */
-
-import {useCallback, useEffect, useId, useRef, useState} from 'react';
-import * as stylex from '@stylexjs/stylex';
-import {useCalendarConstraints} from '../Calendar';
-import type {DateInputProps} from './DateInput';
-import {
-  Field,
-  InputClearButton,
-  inputStatusBorderStyles,
-  inputStatusFocusWithinStyles,
-  inputStatusHoverShadowStyles,
-  inputWrapperStyles,
-} from '../Field';
-import {useInputStatusIcon, useMergedRefs} from '../hooks';
-import {useResolvedRequired} from '../hooks/useResolvedRequired';
-import {Icon} from '../Icon';
-import {useLocale, useTranslator} from '../i18n';
-import {useInputGroup} from '../InputGroup';
-import {groupStyles} from '../InputGroup/groupStyles';
-import {stableClassName} from '../naming';
-import {useSize} from '../SizeContext';
-import {Spinner} from '../Spinner';
-import {
-  colorVars,
-  radiusVars,
-  sizeVars,
-  typeScaleVars,
-  typographyVars,
-} from '../theme/tokens.stylex';
-import {useTooltip} from '../Tooltip';
-import {VisuallyHidden} from '../VisuallyHidden';
-import {
-  focusOutlineStyles,
-  formatSharedDate,
-  getInputARIA,
-  mergeProps,
-  parseDateInput,
-  plainDateFromISO,
-  plainDateToISO,
-  themeProps,
-  type ISODateString,
-} from '../utils';
-
-const styles = stylex.create({
-  wrapper: {
-    gap: 8,
-  },
-  iconButton: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: 0,
-    margin: 0,
-    borderWidth: 0,
-    borderStyle: 'none',
-    backgroundColor: 'transparent',
-    cursor: {
-      default: 'pointer',
-      ':is(:disabled,[aria-disabled="true"])': 'default',
-    },
-    borderRadius: radiusVars['--radius-element'],
-  },
-  iconButtonDisabled: {
-    cursor: 'default',
-  },
-  input: {
-    display: 'block',
-    flex: 1,
-    minWidth: 0,
-    borderWidth: 0,
-    borderStyle: 'none',
-    padding: 0,
-    fontFamily: typographyVars['--font-family-body'],
-    // Below 16px iOS zooms the page when the field takes focus.
-    fontSize: {
-      default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
-    },
-    lineHeight: typeScaleVars['--text-body-leading'],
-    color: colorVars['--color-text-primary'],
-    backgroundColor: 'transparent',
-    outline: 'none',
-    // A date control's intrinsic height comes from its inner edit fields, not
-    // from `line-height`, so it renders ~2px taller than a text input and its
-    // value sits off the shared baseline inside the same flex row. One line
-    // box is exactly what the text field occupies.
-    height: stylex.firstThatWorks(
-      '1lh',
-      `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
-    ),
-    // iOS gives date controls their own button-like chrome, with inner
-    // spacing and a centred value that no reset of ours can reach.
-    WebkitAppearance: 'none',
-    appearance: 'none',
-    // Chromium paints a second calendar glyph inside the field; this surface
-    // already ships a toggle button, so drop the duplicate.
-    '::-webkit-calendar-picker-indicator': {
-      display: 'none',
-    },
-    '::-webkit-date-and-time-value': {
-      textAlign: 'start',
-      marginBlock: 0,
-      marginInline: 0,
-      paddingBlock: 0,
-      paddingInline: 0,
-      lineHeight: 'inherit',
-      minHeight: 0,
-    },
-    '::-webkit-datetime-edit': {
-      paddingBlock: 0,
-      paddingInline: 0,
-      lineHeight: 'inherit',
-    },
-  },
-  inputDisabled: {
-    cursor: 'default',
-  },
-  inputInvalid: {
-    color: colorVars['--color-text-secondary'],
-  },
-  // Hides whatever the engine paints inside the control so this field's own
-  // text can take that space. WebKit renders the value into a single
-  // `::-webkit-date-and-time-value` run which the UA stylesheet gives no
-  // colour of its own (the iOS UA colour sits on the INPUT), so it inherits
-  // this; Chromium's `::-webkit-datetime-edit` fields inherit it too.
-  // `-webkit-text-fill-color` is what actually wins inside a WebKit date
-  // control.
-  inputTextHidden: {
-    color: 'transparent',
-    WebkitTextFillColor: 'transparent',
-  },
-  // Positioning context for the overlay, standing in for the input's own box
-  // in the field's flex row.
-  slot: {
-    position: 'relative',
-    display: 'flex',
-    alignItems: 'center',
-    flex: 1,
-    minWidth: 0,
-  },
-  // This field's own text, laid over the control. Decorative: the input still
-  // holds the value and keeps its label, description, and status wiring, so
-  // announcing this too would just double-speak.
-  overlay: {
-    position: 'absolute',
-    insetInlineStart: 0,
-    // Both insets, so the overlay is bounded by the slot rather than
-    // shrink-to-fit. Without the end inset a long formatted date paints past
-    // the slot and over whatever follows it in the field — measured running
-    // 24px across the clear button.
-    insetInlineEnd: 0,
-    insetBlock: 0,
-    // A BLOCK box, not a flex one: `text-overflow` only applies to a block
-    // container, so on a flex container a too-long date hard-clips mid-glyph
-    // instead of ellipsising (measured identical to `text-overflow: clip` in
-    // both WebKit and Chromium). Centring then comes from the line box, so
-    // the overlay carries the same font size and leading as the input it
-    // covers — one line of that leading fills its height exactly, which puts
-    // the glyphs on the input's own baseline.
-    display: 'block',
-    fontSize: {
-      default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
-    },
-    lineHeight: typeScaleVars['--text-body-leading'],
-    // A tap has to reach the control underneath — that is what raises the
-    // picker.
-    pointerEvents: 'none',
-    overflow: 'hidden',
-    whiteSpace: 'nowrap',
-    textOverflow: 'ellipsis',
-  },
-  overlayValue: {
-    color: colorVars['--color-text-primary'],
-  },
-  overlayPlaceholder: {
-    color: colorVars['--color-text-secondary'],
-  },
-});
-
-const sizeStyles = stylex.create({
-  sm: {height: sizeVars['--size-element-sm'], minWidth: 180},
-  md: {height: sizeVars['--size-element-md'], minWidth: 180},
-  lg: {height: sizeVars['--size-element-lg'], minWidth: 180},
-});
-
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-
-/**
- * The OS-picker surface. Takes `DateInput`'s props verbatim; see
- * {@link DateInput} for when it is chosen over the other two.
- */
-export function NativeDateField({
-  label,
-  isLabelHidden = false,
-  description,
-  isOptional = false,
-  isRequired = false,
-  isDisabled = false,
-  disabledMessage,
-  value,
-  onChange,
-  isLoading = false,
-  min,
-  max,
-  dateConstraints,
-  placeholder: placeholderFromProps,
-  size: sizeProp,
-  status,
-  statusVariant = 'attached',
-  labelTooltip,
-  hasClear = false,
-  // The OS draws the picker, so neither reaches it: both describe a calendar
-  // grid it does not have. Accepted (the prop types are shared) and ignored.
-  numberOfMonths: _numberOfMonths,
-  weekStartsOn: _weekStartsOn,
-  format = 'date_long',
-  width,
-  xstyle,
-  className,
-  style,
-  ref,
-  ...rest
-}: DateInputProps) {
-  const t = useTranslator();
-  const locale = useLocale();
-  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
-  const placeholder =
-    placeholderFromProps ?? t('@astryx.dateInput.placeholder');
-  const size = useSize(sizeProp, 'md');
-
-  const id = useId();
-  const inputLabelID = useId();
-  const descriptionID = useId();
-  const statusMessageID = useId();
-  const inputRef = useRef<HTMLInputElement | null>(null);
-  const mergedInputRef = useMergedRefs(ref, inputRef);
-  const inputGroup = useInputGroup();
-
-  const isEffectivelyDisabled = isDisabled || isLoading;
-
-  // Disabled-reason tooltip, same contract as the other two surfaces: a
-  // disabled control swallows pointer events, so the listeners attach to the
-  // wrapper and the input stays focusable via aria-disabled.
-  const showsDisabledMessage = isDisabled && !!disabledMessage;
-  const disabledMessageTooltip = useTooltip({
-    placement: 'above',
-    focusTrigger: 'always',
-    isEnabled: showsDisabledMessage,
-  });
-
-  const {isDateDisabled} = useCalendarConstraints({min, max, dateConstraints});
-
-  const {statusIcon, describedBy: statusTooltipDescribedBy} =
-    useInputStatusIcon({
-      status,
-      statusVariant,
-      isInGroup: !!inputGroup,
-    });
-
-  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
-    inputLabelID,
-    [
-      description ? descriptionID : null,
-      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
-      statusTooltipDescribedBy,
-      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
-    ],
-    inputGroup,
-  );
-
-  // A date the picker produced that `dateConstraints` refuses, held so the
-  // refusal can be announced instead of looking like a dead tap.
-  const [rejectedValue, setRejectedValue] = useState<string | null>(null);
-  // Whether the control has focus — which, on a touch device, means its
-  // picker is open.
-  const [isFocused, setIsFocused] = useState(false);
-  // The raw value the control last reported and we acted on, so the same edit
-  // arriving through both commit paths only fires one change.
-  const lastCommitRef = useRef<string | null>(null);
-
-  const prevValueRef = useRef(value);
-  if (value !== prevValueRef.current) {
-    prevValueRef.current = value;
-    lastCommitRef.current = null;
-    if (rejectedValue !== null) {
-      setRejectedValue(null);
-    }
-  }
-
-  // The control's own value is always ISO — the only form it accepts, and
-  // what the picker reads and writes. `format` rides on the overlay instead.
-  const nativeValue = value && ISO_DATE.test(value) ? value : '';
-  const isInputValid = rejectedValue === null;
-
-  const formatValue = useCallback(
-    (iso: ISODateString): string =>
-      typeof format === 'function'
-        ? format(iso)
-        : formatSharedDate(plainDateFromISO(iso), format, locale),
-    [format, locale],
-  );
-
-  // This field paints the closed control's text itself, which is what keeps
-  // `format` and `placeholder` applying: the OS picker has no segments to
-  // edit, so our text holds even while the picker is open, and tracks it live.
-  const overlayText = nativeValue ? formatValue(nativeValue) : placeholder;
-  const showsOverlay = !!overlayText;
-
-  const commitValue = useCallback(
-    (newValue: string) => {
-      if (isEffectivelyDisabled) {
-        return;
-      }
-      // The same edit can arrive twice — React's synthetic change and the
-      // native listener below both report it — so act on a raw value once.
-      if (lastCommitRef.current === newValue) {
-        return;
-      }
-      lastCommitRef.current = newValue;
-
-      if (!newValue) {
-        setRejectedValue(null);
-        if (value !== undefined) {
-          onChange?.(undefined);
-        }
-        return;
-      }
-
-      const parsed = parseDateInput(newValue, locale);
-      if (!parsed) {
-        return;
-      }
-      if (isDateDisabled(parsed)) {
-        // iOS does not enforce min/max in its picker — those attributes are
-        // constraint-validation flags, not clamps, and the sheet lets the
-        // user land on any date. Refuse it here and let the sync effect snap
-        // the control back; the live region below announces the refusal.
-        setRejectedValue(newValue);
-        return;
-      }
-
-      setRejectedValue(null);
-      const parsedISO = plainDateToISO(parsed);
-      if (parsedISO !== value) {
-        onChange?.(parsedISO);
-      }
-    },
-    [value, onChange, isDateDisabled, isEffectivelyDisabled, locale],
-  );
-
-  const handleChange = useCallback(
-    (e: React.ChangeEvent<HTMLInputElement>) => {
-      commitValue(e.target.value);
-    },
-    [commitValue],
-  );
-
-  // React's synthetic change system does not reliably observe the iOS
-  // picker's edits. Measured on an iPhone: picking a date fired a native
-  // `input` event carrying the new date while React's `onChange` never ran —
-  // so React re-rendered and wrote its own stale value straight back over the
-  // picker's, and the user's pick (and their Reset) silently reverted. A
-  // native listener reads what the control actually holds, whatever React's
-  // synthetic layer made of it.
-  const commitRef = useRef(commitValue);
-  useEffect(() => {
-    commitRef.current = commitValue;
-  });
-  useEffect(() => {
-    const input = inputRef.current;
-    if (!input) {
-      return;
-    }
-    const handleNative = () => commitRef.current(input.value);
-    input.addEventListener('input', handleNative);
-    input.addEventListener('change', handleNative);
-    return () => {
-      input.removeEventListener('input', handleNative);
-      input.removeEventListener('change', handleNative);
-    };
-  }, []);
-
-  // The value the control mounts with. Deliberately captured once: React
-  // writes to the element whenever a `value` OR `defaultValue` prop changes,
-  // and on iOS ANY write while the picker sheet is open detaches the sheet
-  // from the field — the wheel and Reset keep moving the sheet's own
-  // highlight, but nothing they do reaches the input and no event fires, so
-  // the user's pick appears to do nothing. Holding this constant means React
-  // touches the element exactly once, at mount; the effect below owns every
-  // later update and only writes while the field is unfocused.
-  const initialValueRef = useRef<string | null>(null);
-  if (initialValueRef.current === null) {
-    initialValueRef.current = nativeValue;
-  }
-
-  // Push an externally-changed value in — but never while the control has
-  // focus, for the reason above. Blur flips `isFocused`, so this doubles as
-  // the reconcile once the picker closes. (Self-heals a stale
-  // `initialValueRef` too, on the commit right after a remount.)
-  useEffect(() => {
-    if (isFocused) {
-      return;
-    }
-    const input = inputRef.current;
-    if (input && input.value !== nativeValue) {
-      input.value = nativeValue;
-    }
-  }, [isFocused, nativeValue]);
-
-  const handleBlur = useCallback(() => {
-    const domValue = inputRef.current?.value;
-    setIsFocused(false);
-    // A refused date is reverted by the sync effect the moment focus leaves,
-    // so the field is once again showing a date that IS valid. Keeping the
-    // rejection past that point would mark good data invalid, with no way
-    // back except changing the field again. The live region announced the
-    // refusal while it happened; that is the feedback.
-    setRejectedValue(null);
-    if (domValue !== undefined && domValue !== nativeValue) {
-      commitValue(domValue);
-    }
-  }, [commitValue, nativeValue]);
-
-  // Focusing a date control is what raises the OS picker, so the usual
-  // focus-restore after a clear would pop the picker the tap just dismissed —
-  // and on iOS that reads as the clear having done nothing.
-  const handleClear = useCallback(() => {
-    onChange?.(undefined);
-  }, [onChange]);
-
-  const openPicker = useCallback(() => {
-    if (isEffectivelyDisabled) {
-      return;
-    }
-    const input = inputRef.current;
-    if (!input) {
-      return;
-    }
-    // Focus first: on touch browsers focusing the control is itself what
-    // raises the picker, and iOS implements no `showPicker()` for type=date
-    // (WebKit bug 261703), so focus is the whole mechanism there.
-    input.focus();
-    if (typeof input.showPicker === 'function') {
-      try {
-        input.showPicker();
-      } catch {
-        // showPicker throws without transient user activation and inside a
-        // cross-origin iframe. The focus above is the fallback.
-      }
-    }
-  }, [isEffectivelyDisabled]);
-
-  const inputWrapper = (
-    <div
-      ref={el => {
-        disabledMessageTooltip.ref(el);
-      }}
-      {...rest}
-      {...mergeProps(
-        themeProps('date-input', {
-          size,
-          status: status?.type ?? null,
-          disabled: isDisabled ? 'disabled' : null,
-        }),
-        stylex.props(
-          inputWrapperStyles.base,
-          sizeStyles[size],
-          styles.wrapper,
-          isEffectivelyDisabled && inputWrapperStyles.disabled,
-          status && inputStatusBorderStyles[status.type],
-          status &&
-            !isEffectivelyDisabled &&
-            inputStatusHoverShadowStyles[status.type],
-          status && inputStatusFocusWithinStyles[status.type],
-          inputGroup && groupStyles.inGroup,
-          xstyle,
-        ),
-        className,
-        style,
-      )}>
-      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
-      <button
-        type="button"
-        onClick={openPicker}
-        disabled={isEffectivelyDisabled}
-        aria-label={t('@astryx.dateInput.openCalendar')}
-        tabIndex={-1}
-        {...stylex.props(
-          focusOutlineStyles.focusVisible,
-          styles.iconButton,
-          isEffectivelyDisabled && styles.iconButtonDisabled,
-        )}>
-        <Icon
-          icon="calendar"
-          size="sm"
-          color="secondary"
-          {...themeProps('date-input-toggle-icon', {state: 'collapsed'})}
-        />
-      </button>
-      <span {...stylex.props(styles.slot)}>
-        <input
-          ref={mergedInputRef}
-          id={id}
-          type="date"
-          // UNCONTROLLED on purpose, with a value React never rewrites after
-          // mount — see `initialValueRef` and the sync effect above.
-          defaultValue={initialValueRef.current ?? ''}
-          onChange={handleChange}
-          onFocus={() => setIsFocused(true)}
-          onBlur={handleBlur}
-          min={min}
-          max={max}
-          disabled={isEffectivelyDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}
-          readOnly={showsDisabledMessage || undefined}
-          aria-labelledby={ariaLabelledBy}
-          aria-describedby={ariaDescribedBy}
-          aria-required={isEffectivelyRequired ? 'true' : undefined}
-          aria-invalid={
-            status?.type === 'error' || !isInputValid ? 'true' : undefined
-          }
-          aria-busy={isLoading || undefined}
-          {...stylex.props(
-            styles.input,
-            showsOverlay && styles.inputTextHidden,
-            isEffectivelyDisabled && styles.inputDisabled,
-            !isInputValid && styles.inputInvalid,
-          )}
-        />
-        {showsOverlay && (
-          <span
-            aria-hidden="true"
-            {...stylex.props(
-              styles.overlay,
-              nativeValue ? styles.overlayValue : styles.overlayPlaceholder,
-              isEffectivelyDisabled && styles.inputDisabled,
-              !isInputValid && !!nativeValue && styles.inputInvalid,
-            )}>
-            {overlayText}
-          </span>
-        )}
-      </span>
-      {/*
-          Live region announcing a refused date. The value snaps back on its
-          own, so without this a screen-reader user would get no feedback that
-          their pick was rejected (WCAG 3.3.1).
-        */}
-      <VisuallyHidden as="div" role="alert" aria-live="assertive">
-        {!isInputValid ? t('@astryx.dateInput.invalidDate') : ''}
-      </VisuallyHidden>
-      {hasClear && value !== undefined && !isEffectivelyDisabled && (
-        <InputClearButton
-          label={t('@astryx.dateInput.clear', {label})}
-          onClick={handleClear}
-          iconClassName={stableClassName('date-input-clear-icon')}
-        />
-      )}
-      {isLoading && <Spinner size="sm" />}
-      {statusIcon}
-      {showsDisabledMessage &&
-        disabledMessageTooltip.renderTooltip(disabledMessage)}
-    </div>
-  );
-
-  if (inputGroup) {
-    return inputWrapper;
-  }
-
-  return (
-    <Field
-      label={label}
-      isLabelHidden={isLabelHidden}
-      description={description}
-      inputID={id}
-      descriptionID={description ? descriptionID : undefined}
-      isOptional={isOptional}
-      isRequired={isRequired}
-      isDisabled={isDisabled}
-      status={
-        status
-          ? {
-              type: status.type,
-              message: status.message,
-              messageID: status.message ? statusMessageID : undefined,
-            }
-          : undefined
-      }
-      statusVariant={statusVariant}
-      labelTooltip={labelTooltip}
-      width={width}>
-      {inputWrapper}
-    </Field>
-  );
-}
-
-NativeDateField.displayName = 'NativeDateField';

package/src/utils/isApplePlatform.test.ts

@@ -1,61 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file isApplePlatform.test.ts
- * @input Uses vitest, isApplePlatform
- * @output Unit tests for isApplePlatform
- * @position Testing; validates isApplePlatform.ts implementation
- */
-
-import {describe, it, expect, vi, afterEach} from 'vitest';
-import {isApplePlatform} from './isApplePlatform';
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-});
-
-describe('isApplePlatform', () => {
-  it('trusts a client-hints platform that names one', () => {
-    vi.stubGlobal('navigator', {
-      userAgentData: {platform: 'macOS'},
-      platform: 'Win32',
-    });
-    expect(isApplePlatform()).toBe(true);
-
-    vi.stubGlobal('navigator', {
-      userAgentData: {platform: 'Windows'},
-      platform: 'MacIntel',
-    });
-    expect(isApplePlatform()).toBe(false);
-  });
-
-  it.each([
-    ['blank', ''],
-    ['whitespace', '   '],
-    ['the spec Unknown sentinel', 'Unknown'],
-    ['unknown in any case', 'UNKNOWN'],
-    ['a non-string', null],
-  ])('falls through to navigator.platform on %s', (_label, platform) => {
-    vi.stubGlobal('navigator', {
-      userAgentData: {platform},
-      platform: 'MacIntel',
-    });
-    expect(isApplePlatform()).toBe(true);
-
-    vi.stubGlobal('navigator', {userAgentData: {platform}, platform: 'Win32'});
-    expect(isApplePlatform()).toBe(false);
-  });
-
-  it('falls back to navigator.platform when client hints are absent', () => {
-    vi.stubGlobal('navigator', {platform: 'iPhone'});
-    expect(isApplePlatform()).toBe(true);
-
-    vi.stubGlobal('navigator', {platform: 'Linux x86_64'});
-    expect(isApplePlatform()).toBe(false);
-  });
-
-  it('answers false when there is no navigator at all', () => {
-    vi.stubGlobal('navigator', undefined);
-    expect(isApplePlatform()).toBe(false);
-  });
-});