@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/utils/timeFormat.test.ts

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timeFormat.test.ts
+ * @input Uses vitest and the timeFormat helpers
+ * @output Unit tests for locale hour cycles, locale time text, and parsing it back
+ * @position Testing; validates utils/timeFormat.ts
+ *
+ * SYNC: When timeFormat.ts changes, update tests to match new behavior
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  formatLocaleTime,
+  parseLocaleTime,
+  resolveHourFormat,
+  type HourFormat,
+} from './timeFormat';
+import {parseTimeInput, type ISOTimeString} from './timeParser';
+
+const iso = (time: string) => time as ISOTimeString;
+
+describe('resolveHourFormat', () => {
+  it.each([
+    ['en', '12h'],
+    ['en-US', '12h'],
+    ['ko-KR', '12h'],
+    ['en-GB', '24h'],
+    ['de-DE', '24h'],
+    ['vi-VN', '24h'],
+    ['fr-FR', '24h'],
+  ] as const)('reads the hour cycle of %s as %s', (locale, expected) => {
+    expect(resolveHourFormat(locale)).toBe(expected);
+  });
+
+  it('honors a -u-hc- preference carried on the locale tag', () => {
+    expect(resolveHourFormat('en-US-u-hc-h23')).toBe('24h');
+    expect(resolveHourFormat('de-DE-u-hc-h12')).toBe('12h');
+  });
+
+  it('lets an explicit hour format win over the locale', () => {
+    expect(resolveHourFormat('de-DE', '12h')).toBe('12h');
+    expect(resolveHourFormat('en-US', '24h')).toBe('24h');
+  });
+
+  it('falls back to twelve-hour for a malformed tag', () => {
+    expect(resolveHourFormat('not a locale')).toBe('12h');
+  });
+});
+
+describe('formatLocaleTime', () => {
+  it('keeps the released English text exactly, with a plain space', () => {
+    expect(formatLocaleTime(iso('14:30'), 'en', '12h')).toBe('2:30 PM');
+    expect(formatLocaleTime(iso('00:05'), 'en', '12h')).toBe('12:05 AM');
+    expect(formatLocaleTime(iso('14:30:05'), 'en', '12h', true)).toBe(
+      '2:30:05 PM',
+    );
+    expect(formatLocaleTime(iso('09:05'), 'en', '24h')).toBe('09:05');
+    expect(formatLocaleTime(iso('09:05:07'), 'en', '24h', true)).toBe(
+      '09:05:07',
+    );
+  });
+
+  it("uses the locale's day-period words and their position", () => {
+    expect(formatLocaleTime(iso('14:30'), 'ko-KR', '12h')).toBe('오후 2:30');
+    expect(formatLocaleTime(iso('09:05'), 'zh-CN', '12h')).toBe('上午9:05');
+    expect(formatLocaleTime(iso('14:30'), 'es-ES', '12h')).toBe('2:30 p. m.');
+  });
+
+  it('writes noon as 12 in a twelve-hour reading, not 0', () => {
+    expect(formatLocaleTime(iso('12:30'), 'ja-JP', '12h')).toBe('午後12:30');
+  });
+
+  it('writes English twelve-hour text when the locale would drop the day period', () => {
+    // fr-CM's twelve-hour reading writes 02:30 and 14:30 both as "2:30".
+    expect(formatLocaleTime(iso('14:30'), 'fr-CM', '12h')).toBe('2:30 PM');
+    expect(formatLocaleTime(iso('02:30'), 'fr-CM', '12h')).toBe('2:30 AM');
+    expect(formatLocaleTime(iso('14:30'), 'fr-CM', '24h')).toBe('14:30');
+  });
+
+  it("uses the locale's separator and digits", () => {
+    expect(formatLocaleTime(iso('14:30'), 'fi-FI', '24h')).toBe('14.30');
+    expect(formatLocaleTime(iso('14:30'), 'ar-EG', '12h')).toBe('٢:٣٠ م');
+  });
+
+  it('returns empty text for an empty or malformed time', () => {
+    expect(formatLocaleTime(undefined, 'en', '12h')).toBe('');
+    expect(formatLocaleTime(iso('25:00'), 'en', '12h')).toBe('');
+  });
+});
+
+describe('parseLocaleTime', () => {
+  const LOCALES = [
+    'en-US',
+    'en-GB',
+    'de-DE',
+    'fi-FI',
+    'fr-CA',
+    'es-ES',
+    'sv-SE',
+    'vi-VN',
+    'ja-JP',
+    'ko-KR',
+    'zh-TW',
+    'ar-EG',
+    'fa-IR',
+    'he-IL',
+    // Twelve-hour readings whose separators or surrounding words differ from
+    // the twenty-four-hour reading: a dot (as, nds), "h" (oc), a word between
+    // the day period and the hour (brx, ee), a word before the hour (dz, nds,
+    // tok), and Tibetan digits (dz).
+    'as',
+    'brx',
+    'dz',
+    'ee',
+    'nds',
+    'oc',
+    'tok',
+    // A one-letter day period that English input contains ("m" in "pm").
+    'gd',
+    // A twelve-hour reading with no day period at all.
+    'fr-CM',
+  ];
+  const TIMES = ['00:00', '00:30', '09:05', '11:59', '12:00', '12:30', '23:45'];
+  const FORMATS: HourFormat[] = ['12h', '24h'];
+
+  it.each(LOCALES)('reads back every time %s writes', locale => {
+    for (const hourFormat of FORMATS) {
+      for (const time of TIMES) {
+        const text = formatLocaleTime(iso(time), locale, hourFormat);
+        expect(
+          parseLocaleTime(text, locale),
+          `${locale} ${hourFormat} "${text}"`,
+        ).toBe(time);
+      }
+      const withSeconds = formatLocaleTime(
+        iso('14:30:05'),
+        locale,
+        hourFormat,
+        true,
+      );
+      expect(parseLocaleTime(withSeconds, locale, true)).toBe('14:30:05');
+    }
+  });
+
+  it('reads a spaced day period as the half of the day it names', () => {
+    // Previously parsed as 02:30: the English matcher missed "p. m.".
+    expect(parseLocaleTime('2:30 p. m.', 'es-ES')).toBe('14:30');
+    expect(parseLocaleTime('午後2:30', 'ja-JP')).toBe('14:30');
+  });
+
+  it('reads twelve-hour text whose pattern differs from the 24-hour one', () => {
+    expect(parseLocaleTime('অপৰাহ্ন ২.৩০', 'as')).toBe('14:30');
+    expect(parseLocaleTime('ɣetrɔ ga 2:30', 'ee')).toBe('14:30');
+    expect(parseLocaleTime('Klock 2.30:05 PM', 'nds', true)).toBe('14:30:05');
+    expect(parseLocaleTime('2h30:05 PM', 'oc', true)).toBe('14:30:05');
+  });
+
+  it("reads the locale's separator", () => {
+    // Previously "14.30" read only its "14" prefix.
+    expect(parseLocaleTime('14.30', 'fi-FI')).toBe('14:30');
+    expect(parseLocaleTime('14 h 30', 'fr-CA')).toBe('14:30');
+  });
+
+  it('does not read a day-period word out of the middle of an English word', () => {
+    // gd writes the morning as "m": the "m" of "pm" is not that word.
+    expect(parseLocaleTime('2:30 PM', 'gd')).toBe('14:30');
+    expect(parseLocaleTime('12:00 PM', 'gd')).toBe('12:00');
+    expect(parseLocaleTime('2pm', 'gd')).toBe('14:00');
+    expect(parseLocaleTime('2:30 p.m', 'gd')).toBe('14:30');
+    expect(parseLocaleTime('12:00 p.m', 'gd')).toBe('12:00');
+    expect(parseLocaleTime('2 p.m', 'gd')).toBe('14:00');
+    expect(parseLocaleTime('11 a.m', 'gd')).toBe('11:00');
+    expect(parseLocaleTime('2:30m', 'gd')).toBe('02:30');
+  });
+
+  it('still reads English input in every locale exactly as before', () => {
+    const inputs = [
+      '2:30 PM',
+      '2:30 p.m',
+      '2:30 p.m.',
+      '12:00 PM',
+      '12:00 AM',
+      '2pm',
+      '2 p.m',
+      '11 a.m',
+      '14:30',
+      '1430',
+    ];
+    for (const locale of LOCALES) {
+      for (const input of inputs) {
+        expect(parseLocaleTime(input, locale), `${locale} "${input}"`).toBe(
+          parseTimeInput(input),
+        );
+      }
+    }
+  });
+
+  it('rejects text no reading fits', () => {
+    expect(parseLocaleTime('', 'en-US')).toBeNull();
+    expect(parseLocaleTime('25:99', 'de-DE')).toBeNull();
+    expect(parseLocaleTime('午後14:30', 'ja-JP')).toBeNull();
+  });
+});

package/src/utils/timeFormat.ts

@@ -0,0 +1,314 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timeFormat.ts
+ * @input An ISO time or typed text, plus the provider's BCP 47 locale
+ * @output Exports resolveHourFormat, formatLocaleTime, and parseLocaleTime
+ * @position Internal shared helper for TimeInput and DateTimeInput; not part
+ *   of the public surface
+ *
+ * Time of day as the locale writes it. The hour cycle, digits, separator, and
+ * day-period words all come from Intl rather than a table, so a field reads
+ * the same way `Timestamp` does beside it.
+ *
+ * The hour cycle is the locale's own: `en-US` and `ko-KR` read twelve-hour,
+ * `en-GB`, `de-DE`, and `vi-VN` read twenty-four-hour. A `-u-hc-` extension
+ * on the provider locale (`en-US-u-hc-h23`) carries an app's per-user
+ * preference through the same path, so every Astryx time honors it.
+ *
+ * The parser reads back what the formatter writes: the locale's digits, its
+ * hour-minute separator, and its day-period words, on either side of the time.
+ * Whatever is left goes through the shared English-tolerant parser, so "2:30
+ * PM" and "14:30" keep working in every locale.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/utils/timeFormat.test.ts
+ * - /packages/core/src/TimeInput/TimeInput.tsx
+ * - /packages/core/src/DateTimeInput/DateTimeInput.tsx
+ */
+
+import type {Locale} from '../i18n/types';
+import {parseISOTime, parseTimeInput, type ISOTimeString} from './timeParser';
+import {INVISIBLE_CHARS, toAsciiDigits} from './unicodeDigits';
+
+export type HourFormat = '12h' | '24h';
+
+interface LocaleTimeSymbols {
+  hourFormat: HourFormat;
+  /**
+   * The text between hour and minute and between minute and second, trimmed:
+   * ":" nearly everywhere, "." in fi-FI, "h" and "min" in fr-CA. Read from
+   * both readings, because some locales write them differently: `as` writes
+   * "১৪:৩০" but "অপৰাহ্ন ২.৩০".
+   */
+  separators: string[];
+  /**
+   * Words the locale writes before or after the digits other than the day
+   * period, trimmed: "s" after fr-CA seconds, "kl." before nds-DE times, "ga"
+   * between an ee day period and its hour. Longest first.
+   */
+  edgeWords: string[];
+  /** Every day-period word the locale writes, longest first. */
+  dayPeriods: {word: string; isPM: boolean}[];
+  /**
+   * The locale's twelve-hour reading writes 02:00 and 14:00 the same (fr-CM
+   * writes no day period), so its twelve-hour text is English instead.
+   */
+  twelveHourIsAmbiguous: boolean;
+}
+
+const symbolsByLocale = new Map<string, LocaleTimeSymbols>();
+
+// The space family Intl writes between a time and its day period ("2:30 PM"
+// uses U+202F). A typed field shows a plain space so people can edit it.
+const SPACES = /[\u00A0\u2007\u202F]/g;
+// What may sit on a peeled word's inner side: a digit (digits are already
+// ASCII here), whitespace, or nothing.
+const WORD_BOUNDARY = /^[\d\s]?$/;
+
+function utcDate(hour: number, minute: number, second: number): Date {
+  return new Date(Date.UTC(2000, 0, 1, hour, minute, second));
+}
+
+function timeFormatter(
+  locale: Locale,
+  hourFormat: HourFormat,
+  includeSeconds: boolean,
+): Intl.DateTimeFormat {
+  const options: Intl.DateTimeFormatOptions = {
+    hour: hourFormat === '12h' ? 'numeric' : '2-digit',
+    minute: '2-digit',
+    second: includeSeconds ? '2-digit' : undefined,
+    // `hourCycle`, not `hour12`: `hour12: true` resolves to h11 in ja-JP and
+    // writes noon as "午後0:30".
+    hourCycle: hourFormat === '12h' ? 'h12' : 'h23',
+    timeZone: 'UTC',
+  };
+  try {
+    return new Intl.DateTimeFormat(locale, options);
+  } catch {
+    return new Intl.DateTimeFormat('en', options);
+  }
+}
+
+function getLocaleTimeSymbols(locale: Locale): LocaleTimeSymbols {
+  let symbols = symbolsByLocale.get(locale);
+  if (symbols !== undefined) {
+    return symbols;
+  }
+
+  let hourFormat: HourFormat;
+  let resolved: Intl.ResolvedDateTimeFormatOptions;
+  try {
+    resolved = new Intl.DateTimeFormat(locale, {
+      hour: 'numeric',
+    }).resolvedOptions();
+  } catch {
+    // A malformed tag formats as English everywhere else in this module.
+    resolved = new Intl.DateTimeFormat('en', {
+      hour: 'numeric',
+    }).resolvedOptions();
+  }
+  if (resolved.hourCycle !== undefined) {
+    hourFormat =
+      resolved.hourCycle === 'h11' || resolved.hourCycle === 'h12'
+        ? '12h'
+        : '24h';
+  } else {
+    // Engines that leave hourCycle unresolved still write a day period for a
+    // twelve-hour locale when no cycle is forced.
+    let ambient: Intl.DateTimeFormat;
+    try {
+      ambient = new Intl.DateTimeFormat(locale, {hour: 'numeric'});
+    } catch {
+      ambient = new Intl.DateTimeFormat('en', {hour: 'numeric'});
+    }
+    hourFormat = ambient
+      .formatToParts(utcDate(13, 0, 0))
+      .some(part => part.type === 'dayPeriod')
+      ? '12h'
+      : '24h';
+  }
+
+  // Literals of every reading this module writes: twelve- and twenty-four-hour,
+  // with and without seconds. A literal between two numbers is a separator;
+  // one outside them is an edge word.
+  const separatorSet = new Set<string>();
+  const edgeSet = new Set<string>();
+  for (const cycle of ['12h', '24h'] as const) {
+    for (const withSeconds of [false, true]) {
+      const parts = timeFormatter(locale, cycle, withSeconds).formatToParts(
+        utcDate(13, 30, 5),
+      );
+      const isNumber = (part: Intl.DateTimeFormatPart) =>
+        part.type === 'hour' ||
+        part.type === 'minute' ||
+        part.type === 'second';
+      const first = parts.findIndex(isNumber);
+      const last = parts.length - 1 - [...parts].reverse().findIndex(isNumber);
+      parts.forEach((part, index) => {
+        if (part.type !== 'literal') {
+          return;
+        }
+        const text = normalizeText(part.value).trim();
+        if (text === '' || text === ':') {
+          return;
+        }
+        (index > first && index < last ? separatorSet : edgeSet).add(text);
+      });
+    }
+  }
+  const separators = [...separatorSet];
+  const edgeWords = [...edgeSet].sort((a, b) => b.length - a.length);
+
+  // Every hour, because some locales name several periods across the day
+  // (flexible day periods). A word that appears on both sides of noon cannot
+  // say which half it means, so it is left out.
+  const twelveHour = timeFormatter(locale, '12h', false);
+  const sides = new Map<string, Set<boolean>>();
+  for (let hour = 0; hour < 24; hour++) {
+    const word = twelveHour
+      .formatToParts(utcDate(hour, 0, 0))
+      .find(part => part.type === 'dayPeriod')?.value;
+    if (word === undefined) {
+      continue;
+    }
+    const key = normalizeText(word).trim();
+    if (key === '') {
+      continue;
+    }
+    const seen = sides.get(key) ?? new Set<boolean>();
+    seen.add(hour >= 12);
+    sides.set(key, seen);
+  }
+  const dayPeriods = [...sides]
+    .filter(([, seen]) => seen.size === 1)
+    .map(([word, seen]) => ({word, isPM: seen.has(true)}))
+    .sort((a, b) => b.word.length - a.word.length);
+
+  const twelveHourIsAmbiguous =
+    normalizeText(twelveHour.format(utcDate(2, 0, 0))) ===
+    normalizeText(twelveHour.format(utcDate(14, 0, 0)));
+
+  symbols = {
+    hourFormat,
+    separators,
+    edgeWords,
+    dayPeriods,
+    twelveHourIsAmbiguous,
+  };
+  symbolsByLocale.set(locale, symbols);
+  return symbols;
+}
+
+function normalizeText(text: string): string {
+  const folded = text
+    .normalize('NFKC')
+    .replace(INVISIBLE_CHARS, '')
+    .replace(SPACES, ' ');
+  return (toAsciiDigits(folded) ?? folded).toLowerCase();
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The hour format a field shows: the caller's explicit choice, else the
+ * locale's hour cycle (including a `-u-hc-` extension on the tag).
+ */
+export function resolveHourFormat(
+  locale: Locale,
+  hourFormat?: HourFormat,
+): HourFormat {
+  return hourFormat ?? getLocaleTimeSymbols(locale).hourFormat;
+}
+
+/**
+ * Formats an ISO time as the locale writes it, in the given hour format.
+ * en-US: "14:30" → "2:30 PM"; de-DE 24h: "14:30"; ko-KR 12h: "오후 2:30".
+ * Returns '' for an empty or malformed time.
+ */
+export function formatLocaleTime(
+  time: ISOTimeString | undefined,
+  locale: Locale,
+  hourFormat: HourFormat,
+  includeSeconds: boolean = false,
+): string {
+  if (!time) {
+    return '';
+  }
+  const parsed = parseISOTime(time);
+  if (!parsed) {
+    return '';
+  }
+  const formatLocale =
+    hourFormat === '12h' && getLocaleTimeSymbols(locale).twelveHourIsAmbiguous
+      ? 'en'
+      : locale;
+  return timeFormatter(formatLocale, hourFormat, includeSeconds)
+    .format(utcDate(parsed.hour, parsed.minute, parsed.second))
+    .replace(SPACES, ' ');
+}
+
+/**
+ * Parses typed text into an ISO time, accepting the locale's digits,
+ * separator, and day-period words as well as everything `parseTimeInput`
+ * accepts. Returns null when no reading fits.
+ */
+export function parseLocaleTime(
+  input: string,
+  locale: Locale,
+  includeSeconds: boolean = false,
+): ISOTimeString | null {
+  if (!input) {
+    return null;
+  }
+  const {separators, edgeWords, dayPeriods} = getLocaleTimeSymbols(locale);
+  let text = normalizeText(input).trim();
+
+  // Peel the day period and edge words off both ends, in whatever order the
+  // locale writes them ("ŋdi ga 2:30", "kl. 2.30 pm").
+  let isPM: boolean | null = null;
+  // A word counts only when a digit, whitespace, or nothing sits on its inner
+  // side, so gd's "m" (morning) is not read out of an English "pm" or "p.m".
+  const strip = (word: string) => {
+    if (text.startsWith(word) && WORD_BOUNDARY.test(text.charAt(word.length))) {
+      text = text.slice(word.length).trim();
+      return true;
+    }
+    if (
+      text.endsWith(word) &&
+      WORD_BOUNDARY.test(text.charAt(text.length - word.length - 1))
+    ) {
+      text = text.slice(0, -word.length).trim();
+      return true;
+    }
+    return false;
+  };
+  for (let peeled = true; peeled;) {
+    peeled = false;
+    if (isPM === null) {
+      const period = dayPeriods.find(({word}) => strip(word));
+      if (period !== undefined) {
+        isPM = period.isPM;
+        peeled = true;
+      }
+    }
+    if (edgeWords.some(strip)) {
+      peeled = true;
+    }
+  }
+
+  for (const separator of separators) {
+    text = text.replace(
+      new RegExp(`(\\d)\\s*${escapeRegExp(separator)}\\s*(?=\\d)`, 'g'),
+      '$1:',
+    );
+  }
+
+  if (isPM !== null) {
+    text = `${text} ${isPM ? 'pm' : 'am'}`;
+  }
+  return parseTimeInput(text, includeSeconds);
+}

package/src/utils/touchPresentation.stylex.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchPresentation.stylex.ts
+ * @input Uses StyleX defineConsts
+ * @output Exports touchKeys: the touch presentation resolver's queries as
+ *   StyleX at-rule keys
+ * @position The reference spellings of the touch, compact and iOS-gate
+ *   conditions. Core styles write these as literal keys wherever they need
+ *   them (`spec:AST-094` FR13, `spec:AST-012` FR9), and a test pins each
+ *   literal to these values; utils/touchPresentation.ts holds the same
+ *   queries for script (matchMedia)
+ *
+ * These are the spellings to match. A style that changes with these
+ * conditions writes the same literal key (`'@media (pointer: coarse)'`, the
+ * iOS gate as that media key outside `'@supports (-webkit-touch-callout:
+ * none)'`), and a test pins every literal in core to these values. Do not use
+ * an imported key as a computed StyleX key: it compiles to a different
+ * priority than the literal (6000 against 3200) and reorders the cascade.
+ * The iOS supports gate is only for a style iOS WebKit itself requires (the
+ * 16px input floor), never a behaviour.
+ *
+ * SYNC: When modified, update touchPresentation.ts and
+ * touchPresentation.test.ts.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const touchKeys = stylex.defineConsts({
+  /** The primary pointer is coarse (TOUCH_QUERY). */
+  touch: '@media (pointer: coarse)',
+  /** The viewport is compact (COMPACT_QUERY, `spec:AST-012` FR9). */
+  compact: '@media (width < 768px), (height < 500px)',
+  /** Both: a presentation such as a sheet in place of a popover. */
+  compactTouch:
+    '@media (width < 768px) and (pointer: coarse), (height < 500px) and (pointer: coarse)',
+  /**
+   * The iOS WebKit gate, inside `touch` (IOS_SUPPORTS_QUERY): only for a
+   * style iOS WebKit itself requires (the 16px input floor), never a
+   * behaviour; touch behaviour is one model on every touch device.
+   */
+  iosSupports: '@supports (-webkit-touch-callout: none)',
+});