@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/internal/forms-b/forms-b.css

@@ -0,0 +1,341 @@
+/* Shared parts of the forms-b group: field lines, picker trigger, floating
+   surface / phone tray, year stepper, month grid, chips (design direction
+   §2.2, §2.4, §2.5, §2.6, §2.7, §2.10). */
+@layer tympan.components {
+  .ty-fb-line {
+    margin: 0;
+    font-family: var(--ty-font-sans);
+  }
+  .ty-fb-line[data-line='label'] {
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-label);
+  }
+  .ty-fb-line[data-line='hint'] {
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-fb-line[data-line='error'] {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--ty-space-1);
+    color: var(--ty-danger);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-fb-line .ty-icon {
+    flex: none;
+    inline-size: 1.2em;
+    block-size: 1.2em;
+  }
+
+  /* A field-shaped button that opens a picker. */
+  .ty-fb-trigger {
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-2);
+    inline-size: 100%;
+    min-block-size: var(--ty-control-height);
+    padding-inline: var(--ty-space-3);
+    border: 1px solid var(--ty-input);
+    border-radius: var(--ty-radius-control);
+    background: var(--ty-surface-solid);
+    color: var(--ty-ink);
+    font: inherit;
+    font-size: var(--ty-font-size-body);
+    text-align: start;
+    cursor: pointer;
+    outline: none;
+    transition: border-color var(--ty-dur-instant) var(--ty-ease);
+  }
+  .ty-fb-trigger::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    /* physical: centring with translate(-50%) is the same in both directions */
+    left: 50%;
+    inline-size: max(100%, var(--ty-control-target));
+    block-size: max(100%, var(--ty-control-target));
+    transform: translate(-50%, -50%);
+  }
+  .ty-fb-trigger[data-hovered] {
+    border-color: var(--ty-ink-3);
+  }
+  .ty-fb-trigger[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-fb-trigger[data-invalid] {
+    border-color: var(--ty-danger);
+  }
+  .ty-fb-trigger[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+  .ty-fb-trigger[data-embedded] {
+    border-color: transparent;
+    background: transparent;
+  }
+  .ty-fb-trigger__glyph {
+    display: inline-flex;
+    flex: none;
+    color: var(--ty-ink-3);
+  }
+  .ty-fb-trigger__glyph > svg {
+    inline-size: 1.15em;
+    block-size: 1.15em;
+  }
+  .ty-fb-trigger__text {
+    flex: 1;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .ty-fb-trigger__text[data-placeholder] {
+    color: var(--ty-ink-3);
+  }
+
+  /* Floating surface (level 3) and its phone tray. */
+  .ty-fb-float {
+    box-sizing: border-box;
+    min-inline-size: 18rem;
+    max-inline-size: calc(100vw - 2 * var(--ty-space-4));
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-card);
+    background: var(--ty-surface-raised);
+    color: var(--ty-on-surface-raised);
+    box-shadow: var(--ty-shadow-floating);
+    backdrop-filter: blur(var(--ty-glass-blur-floating)) saturate(var(--ty-glass-saturate));
+    -webkit-backdrop-filter: blur(var(--ty-glass-blur-floating)) saturate(var(--ty-glass-saturate));
+    z-index: var(--ty-z-popover);
+    outline: none;
+  }
+  .ty-fb-float[data-entering] {
+    animation: ty-fb-fade var(--ty-dur-quick) var(--ty-ease);
+  }
+  .ty-fb-float[data-exiting] {
+    animation: ty-fb-fade var(--ty-dur-quick) var(--ty-ease-out) reverse;
+  }
+  .ty-fb-float[data-presentation='tray'] {
+    position: fixed !important;
+    inset: auto 0 0 0 !important;
+    z-index: var(--ty-z-modal);
+    inline-size: 100%;
+    max-inline-size: none;
+    max-block-size: 85vh;
+    overflow-y: auto;
+    border-block-end: 0;
+    border-radius: var(--ty-radius-sheet) var(--ty-radius-sheet) 0 0;
+    padding-block-end: env(safe-area-inset-bottom, 0px);
+  }
+  .ty-fb-float__dialog {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-3);
+    padding: var(--ty-space-4);
+    outline: none;
+  }
+  @keyframes ty-fb-fade {
+    from {
+      opacity: 0;
+    }
+  }
+
+  .ty-fb-stepper {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ty-space-2);
+  }
+  /* Icon-only step control (previous / next) with a 44 px hit area. */
+  .ty-fb-nav {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--ty-control-height-compact);
+    block-size: var(--ty-control-height-compact);
+    padding: 0;
+    border: 0;
+    border-radius: var(--ty-radius-control);
+    background: transparent;
+    color: var(--ty-ink-2);
+    cursor: pointer;
+    outline: none;
+  }
+  .ty-fb-nav::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    /* physical: centring with translate(-50%) is the same in both directions */
+    left: 50%;
+    inline-size: max(100%, var(--ty-control-target));
+    block-size: max(100%, var(--ty-control-target));
+    transform: translate(-50%, -50%);
+  }
+  .ty-fb-nav[data-hovered] {
+    background: var(--ty-surface-sunken);
+  }
+  .ty-fb-nav[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-fb-nav[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.4;
+  }
+  .ty-fb-nav .ty-icon {
+    inline-size: 18px;
+    block-size: 18px;
+  }
+  .ty-fb-stepper__heading {
+    flex: 1;
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-label);
+    text-align: center;
+  }
+
+  .ty-fb-months__grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: var(--ty-space-1);
+    outline: none;
+  }
+  .ty-fb-months__cell {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-block-size: var(--ty-control-target);
+    border-radius: var(--ty-radius-control);
+    color: var(--ty-ink-2);
+    font-size: var(--ty-font-size-body);
+    text-transform: capitalize;
+    cursor: pointer;
+    outline: none;
+  }
+  .ty-fb-months__cell[data-hovered] {
+    background: var(--ty-surface-sunken);
+  }
+  .ty-fb-months__cell[data-selected] {
+    background: var(--ty-accent);
+    color: var(--ty-accent-ink);
+    font-weight: var(--ty-font-weight-semibold);
+  }
+  .ty-fb-months__cell[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: -2px;
+  }
+  .ty-fb-months__cell[data-disabled] {
+    color: var(--ty-ink-3);
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+
+  /* Small pill buttons (year chips, shortcuts). */
+  .ty-fb-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--ty-space-1);
+  }
+  .ty-fb-chip {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    min-block-size: calc(var(--ty-space-6) + var(--ty-space-1));
+    padding-inline: var(--ty-space-3);
+    border: 1px solid var(--ty-line-strong);
+    border-radius: var(--ty-radius-pill);
+    background: transparent;
+    color: var(--ty-ink-2);
+    font: inherit;
+    font-size: var(--ty-font-size-label);
+    font-variant-numeric: tabular-nums;
+    cursor: pointer;
+    outline: none;
+  }
+  .ty-fb-chip::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    /* physical: centring with translate(-50%) is the same in both directions */
+    left: 50%;
+    inline-size: max(100%, var(--ty-control-target));
+    block-size: max(100%, var(--ty-control-target));
+    transform: translate(-50%, -50%);
+  }
+  .ty-fb-chip[aria-pressed='true'],
+  .ty-fb-chip[data-current] {
+    border-color: var(--ty-accent);
+    background: var(--ty-accent-soft);
+    color: var(--ty-on-accent-soft);
+    font-weight: var(--ty-font-weight-semibold);
+  }
+  .ty-fb-chip[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-fb-chip[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+
+  @media (max-width: 1023.98px) {
+    .ty-fb-trigger {
+      min-block-size: var(--ty-control-height-touch);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ty-fb-trigger {
+      transition: none;
+    }
+    .ty-fb-float[data-entering],
+    .ty-fb-float[data-exiting] {
+      animation: none;
+    }
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-fb-float {
+      background: var(--ty-surface-raised-solid);
+      backdrop-filter: none;
+      -webkit-backdrop-filter: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-fb-trigger,
+    .ty-fb-chip {
+      border: 1px solid ButtonText;
+    }
+    .ty-fb-float {
+      border: 1px solid CanvasText;
+      background: Canvas;
+      backdrop-filter: none;
+    }
+    .ty-fb-months__cell[data-selected],
+    .ty-fb-chip[aria-pressed='true'] {
+      background: Highlight;
+      color: HighlightText;
+      forced-color-adjust: none;
+    }
+    .ty-fb-months__cell[data-disabled],
+    .ty-fb-trigger[data-disabled] {
+      color: GrayText;
+      opacity: 1;
+    }
+    .ty-fb-trigger[data-focus-visible],
+    .ty-fb-chip[data-focus-visible],
+    .ty-fb-months__cell[data-focus-visible] {
+      outline: 2px solid Highlight;
+    }
+  }
+}

package/src/internal/forms-b/parts.tsx

@@ -0,0 +1,151 @@
+// Shared pieces of the pickers and fields in the "forms-b" group: field text
+// lines, a floating surface that becomes a bottom tray on phones, a year
+// stepper and a twelve-month grid (used by DateField and MonthField).
+import { ChevronLeft, ChevronRight, CircleAlert } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { Button as AriaButton, Dialog, GridList, GridListItem, Popover, type Key } from 'react-aria-components'
+import { cx } from '../cx'
+import { useMediaQuery } from '../media'
+
+/** Space-separated id list without empty entries (or undefined). */
+export const joinIds = (...ids: Array<string | false | null | undefined>): string | undefined => ids.filter(Boolean).join(' ') || undefined
+
+/** True below 640 px, where floating pickers become a bottom tray. */
+export function usePhoneWidth(): boolean {
+  return useMediaQuery('(max-width: 639.98px)')
+}
+
+type LineKind = 'label' | 'hint' | 'error'
+
+/** One text line of a field: label (above), hint (below the label) or error (below the control). */
+export function FieldLine({ kind, id, htmlFor, children }: { kind: LineKind; id?: string; htmlFor?: string; children: ReactNode }) {
+  if (kind === 'label') {
+    return htmlFor ? (
+      <label className="ty-fb-line" data-line="label" id={id} htmlFor={htmlFor}>
+        {children}
+      </label>
+    ) : (
+      <span className="ty-fb-line" data-line="label" id={id}>
+        {children}
+      </span>
+    )
+  }
+  return (
+    <p className="ty-fb-line" data-line={kind} id={id}>
+      {kind === 'error' ? <CircleAlert className="ty-icon" aria-hidden="true" focusable="false" /> : null}
+      <span>{children}</span>
+    </p>
+  )
+}
+
+export type FloatSide = 'top' | 'bottom' | 'left' | 'right'
+
+/** Non-modal floating dialog; below 640 px the same popover is laid out as a bottom tray. */
+export function FloatSurface(props: {
+  label?: string
+  labelledBy?: string
+  side?: FloatSide
+  className?: string
+  children: ReactNode
+}) {
+  const phone = usePhoneWidth()
+  return (
+    <Popover
+      className={cx('ty-fb-float', props.className)}
+      placement={props.side ?? 'bottom'}
+      offset={6}
+      data-presentation={phone ? 'tray' : 'popover'}
+    >
+      <Dialog className="ty-fb-float__dialog" aria-label={props.labelledBy ? undefined : props.label} aria-labelledby={props.labelledBy}>
+        {props.children}
+      </Dialog>
+    </Popover>
+  )
+}
+
+/** Previous / heading / next row; the heading is a polite live region. */
+export function StepperHeader(props: {
+  heading: ReactNode
+  previousLabel: string
+  nextLabel: string
+  onPrevious: () => void
+  onNext: () => void
+  previousDisabled?: boolean
+  nextDisabled?: boolean
+  headingId?: string
+}) {
+  return (
+    <div className="ty-fb-stepper">
+      <AriaButton className="ty-fb-nav" aria-label={props.previousLabel} isDisabled={props.previousDisabled} onPress={props.onPrevious}>
+        <ChevronLeft className="ty-icon ty-mirror-rtl" aria-hidden="true" focusable="false" />
+      </AriaButton>
+      <span className="ty-fb-stepper__heading" id={props.headingId} aria-live="polite">
+        {props.heading}
+      </span>
+      <AriaButton className="ty-fb-nav" aria-label={props.nextLabel} isDisabled={props.nextDisabled} onPress={props.onNext}>
+        <ChevronRight className="ty-icon ty-mirror-rtl" aria-hidden="true" focusable="false" />
+      </AriaButton>
+    </div>
+  )
+}
+
+/** Localised month names, January first. */
+export function monthNames(locale: string, width: 'long' | 'short' = 'long'): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { month: width, timeZone: 'UTC' })
+  return Array.from({ length: 12 }, (_, m) => fmt.format(Date.UTC(2020, m, 15)))
+}
+
+/** "YYYY-MM" key of a year and a zero-based month. */
+export const monthKey = (year: number, monthIndex: number) => `${year}-${String(monthIndex + 1).padStart(2, '0')}`
+
+/**
+ * Twelve months of one year as a grid list (APG grid-like navigation);
+ * unavailable months stay visible but disabled. PageUp/PageDown step years.
+ */
+export function MonthGrid(props: {
+  year: number
+  locale: string
+  label: string
+  isAvailable: (key: string) => boolean
+  selected?: string | null
+  onChoose: (key: string) => void
+  onYearStep?: (delta: number) => void
+}) {
+  const names = monthNames(props.locale, 'short')
+  const longNames = monthNames(props.locale, 'long')
+  const cells = names.map((short, m) => ({ key: monthKey(props.year, m), short, long: longNames[m]! }))
+  const disabled = cells.filter((c) => !props.isAvailable(c.key)).map((c) => c.key)
+  const pick = (keys: 'all' | Set<Key>) => {
+    if (keys === 'all') return
+    const [first] = [...keys]
+    if (first != null) props.onChoose(String(first))
+  }
+  return (
+    <div
+      className="ty-fb-months"
+      onKeyDown={(e) => {
+        if (!props.onYearStep || (e.key !== 'PageUp' && e.key !== 'PageDown')) return
+        e.preventDefault()
+        props.onYearStep(e.key === 'PageUp' ? -1 : 1)
+      }}
+    >
+      <GridList
+        aria-label={props.label}
+        layout="grid"
+        className="ty-fb-months__grid"
+        items={cells}
+        selectionMode="single"
+        disallowEmptySelection
+        selectedKeys={props.selected ? [props.selected] : []}
+        disabledKeys={disabled}
+        onSelectionChange={pick}
+      >
+        {(cell) => (
+          <GridListItem id={cell.key} textValue={`${cell.long} ${props.year}`} className="ty-fb-months__cell">
+            {cell.short}
+          </GridListItem>
+        )}
+      </GridList>
+    </div>
+  )
+}

package/src/internal/haptics.ts

@@ -0,0 +1,77 @@
+import { createContext, useContext } from 'react'
+import { prefersReducedMotion } from './media'
+
+export type HapticStrength = 'none' | 'light' | 'medium'
+
+const pattern: Record<Exclude<HapticStrength, 'none'>, number> = { light: 8, medium: 16 }
+
+/* ------------------------------------------------------------------------ */
+/* User-gesture gate                                                         */
+/* ------------------------------------------------------------------------ */
+
+// Browsers ignore (and warn about) navigator.vibrate before the page has had a
+// user gesture, so nothing here calls it until one has happened. Where the
+// User Activation API exists it decides; elsewhere a first pointer, touch or
+// key press seen by this module opens the gate.
+let gestureSeen = false
+const GESTURES = ['pointerdown', 'touchstart', 'keydown', 'mousedown'] as const
+
+function onGesture() {
+  gestureSeen = true
+  for (const type of GESTURES) window.removeEventListener(type, onGesture, true)
+}
+
+if (typeof window !== 'undefined') {
+  for (const type of GESTURES) window.addEventListener(type, onGesture, { capture: true, passive: true })
+}
+
+/** True once the person has interacted with the page (sticky user activation). */
+export function hasUserGesture(): boolean {
+  if (typeof navigator === 'undefined') return false
+  const activation = (navigator as Navigator & { userActivation?: { hasBeenActive: boolean } }).userActivation
+  if (activation && typeof activation.hasBeenActive === 'boolean') return activation.hasBeenActive || gestureSeen
+  return gestureSeen
+}
+
+/** Test hook: forget any gesture seen so far. */
+export function resetUserGestureForTests(): void {
+  gestureSeen = false
+  if (typeof window !== 'undefined') for (const type of GESTURES) window.addEventListener(type, onGesture, { capture: true, passive: true })
+}
+
+/* ------------------------------------------------------------------------ */
+/* The person's preference                                                   */
+/* ------------------------------------------------------------------------ */
+
+/** The person's "haptics" preference (HapticsPreference provides it; on by default). */
+export const HapticsEnabledContext = createContext(true)
+
+export function useHapticsEnabled(): boolean {
+  return useContext(HapticsEnabledContext)
+}
+
+/* ------------------------------------------------------------------------ */
+
+/** The Vibration API, or null. Only callable after a user gesture. */
+export function gatedVibrate(): ((p: number | number[]) => boolean) | null {
+  if (typeof navigator === 'undefined' || !hasUserGesture()) return null
+  const fn = (navigator as { vibrate?: unknown }).vibrate
+  return typeof fn === 'function' ? (p) => (fn as (p: number | number[]) => boolean).call(navigator, p) : null
+}
+
+/**
+ * Short feedback vibration for components: silent without the Vibration API,
+ * under reduced motion, when the person turned haptics off (`enabled: false`)
+ * and before any user gesture.
+ */
+export function requestHaptic(strength: HapticStrength, options: { enabled?: boolean } = {}): void {
+  if (strength === 'none' || options.enabled === false) return
+  if (prefersReducedMotion()) return
+  const vibrate = gatedVibrate()
+  if (!vibrate) return
+  try {
+    vibrate(pattern[strength])
+  } catch {
+    /* unsupported */
+  }
+}

package/src/internal/icuCatalogue.ts

@@ -0,0 +1,60 @@
+// ICU MessageFormat bridge and pseudo-localization for the copy catalogue.
+//
+// Every key of `Messages` accepts an ICU string. Keys whose default is a
+// function receive their arguments positionally as {0}, {1}, … so a host can
+// write, for example:
+//   pagination.range: '{0}–{1} de {2, number}'
+//   rail.count: '{0, plural, one {# pendente} other {# pendentes}}'
+import { formatMessage } from '../utilities/i18n-adapter/icu'
+import type { MessageOverrides, Messages } from './messages'
+
+export interface IcuCatalogue {
+  [key: string]: string | IcuCatalogue
+}
+
+type Tree = Record<string, unknown>
+const isTree = (v: unknown): v is Tree => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** Compiles ICU strings (shaped like the catalogue) into catalogue overrides for `locale`. */
+export function compileIcuMessages(icu: IcuCatalogue, base: Messages, locale: string): MessageOverrides {
+  const walk = (source: IcuCatalogue, reference: unknown): Tree => {
+    const out: Tree = {}
+    for (const [key, value] of Object.entries(source)) {
+      const ref = isTree(reference) ? reference[key] : undefined
+      if (typeof value === 'string') {
+        out[key] =
+          typeof ref === 'function'
+            ? (...args: unknown[]) => formatMessage(value, Object.fromEntries(args.map((a, i) => [String(i), a])), locale)
+            : formatMessage(value, {}, locale)
+      } else out[key] = walk(value, ref)
+    }
+    return out
+  }
+  return walk(icu, base) as MessageOverrides
+}
+
+const ACCENTED: Record<string, string> = {
+  a: 'à', b: 'ƀ', c: 'ç', d: 'ď', e: 'é', f: 'ƒ', g: 'ĝ', h: 'ĥ', i: 'î', j: 'ĵ', k: 'ķ', l: 'ļ', m: 'ɱ',
+  n: 'ñ', o: 'ö', p: 'þ', q: 'ǫ', r: 'ŕ', s: 'š', t: 'ţ', u: 'û', v: 'ṽ', w: 'ŵ', x: 'ẋ', y: 'ý', z: 'ž',
+  A: 'Å', B: 'Ɓ', C: 'Ç', D: 'Đ', E: 'É', F: 'Ƒ', G: 'Ĝ', H: 'Ĥ', I: 'Î', J: 'Ĵ', K: 'Ķ', L: 'Ļ', M: 'Ṁ',
+  N: 'Ñ', O: 'Ö', P: 'Þ', Q: 'Ǫ', R: 'Ŕ', S: 'Š', T: 'Ţ', U: 'Û', V: 'Ṽ', W: 'Ŵ', X: 'Ẋ', Y: 'Ý', Z: 'Ž',
+}
+
+/** One pseudo-localized string: accented, about 40 % longer, bracketed so clipping shows. */
+export function pseudoString(text: string): string {
+  if (!text) return text
+  const accented = [...text].map((ch) => ACCENTED[ch] ?? ch).join('')
+  const letters = [...text].filter((ch) => /\p{L}/u.test(ch)).length
+  return `⟦${accented}${'~'.repeat(Math.ceil(letters * 0.4))}⟧`
+}
+
+/** Pseudo-localizes a whole catalogue (strings and the output of message functions). */
+export function pseudoLocalize(messages: Messages): Messages {
+  const walk = (node: unknown): unknown => {
+    if (typeof node === 'string') return pseudoString(node)
+    if (typeof node === 'function') return (...args: unknown[]) => pseudoString(String((node as (...a: unknown[]) => unknown)(...args)))
+    if (isTree(node)) return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v)]))
+    return node
+  }
+  return walk(messages) as Messages
+}

package/src/internal/inert.ts

@@ -0,0 +1,15 @@
+import { version } from 'react'
+
+const major = Number.parseInt(version, 10)
+
+/**
+ * Props that set the HTML `inert` attribute on a host element, portable across
+ * React 18.3 and 19. React 19 treats `inert` as a boolean attribute; React 18
+ * does not know it, drops `true` with a warning and writes a string as is, so
+ * there an empty string is the way to set it. Spread the result on the element:
+ * `<div {...inertProps(hidden)} />`.
+ */
+export function inertProps(on: boolean | undefined): { inert?: boolean } {
+  if (!on) return {}
+  return (major >= 19 ? { inert: true } : { inert: '' }) as { inert?: boolean }
+}

package/src/internal/media.ts

@@ -0,0 +1,35 @@
+import { useSyncExternalStore } from 'react'
+
+/** Breakpoints of design direction §2.8 (px). */
+export const breakpoints = { sm: 640, md: 768, lg: 1024, xl: 1280, xxl: 1536 } as const
+
+function subscribe(query: string) {
+  return (onChange: () => void) => {
+    if (typeof window === 'undefined' || !window.matchMedia) return () => {}
+    const mql = window.matchMedia(query)
+    mql.addEventListener('change', onChange)
+    return () => mql.removeEventListener('change', onChange)
+  }
+}
+
+/** Live result of a media query; `serverValue` is used without a window. */
+export function useMediaQuery(query: string, serverValue = false): boolean {
+  return useSyncExternalStore(
+    subscribe(query),
+    () => (typeof window !== 'undefined' && window.matchMedia ? window.matchMedia(query).matches : serverValue),
+    () => serverValue,
+  )
+}
+
+/** True when the viewport is at least `px` wide (desktop-first layouts). */
+export function useMinWidth(px: number, serverValue = true): boolean {
+  return useMediaQuery(`(min-width: ${px}px)`, serverValue)
+}
+
+export function useReducedMotion(): boolean {
+  return useMediaQuery('(prefers-reduced-motion: reduce)')
+}
+
+export function prefersReducedMotion(): boolean {
+  return typeof window !== 'undefined' && !!window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}