@octanejs/aria 0.0.1 → 0.0.4

package/src/i18n/I18nProvider.ts

@@ -0,0 +1,97 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/I18nProvider.tsx).
+// octane adaptations:
+// - `.tsx` → `.ts`: JSX → createElement (plain-`.ts` components get no compiled slots —
+//   hooks use the stable S()/subSlot component-slot convention). The Provider descriptor
+//   keeps a stable `{ value, children }` shape.
+// - React's `ReactNode`/`JSX.Element` types → `any` (octane descriptors).
+// - `useLocale` gets the public-hook slot threading (splitSlot/subSlot) per the binding
+//   convention; `useContext` needs no slot (context-identity keyed).
+import type { Direction } from '@react-types/shared';
+import { createContext, createElement, useContext, useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { isRTL } from './utils';
+import { useDefaultLocale } from './useDefaultLocale';
+
+export interface Locale {
+	/** The [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code for the locale. */
+	locale: string;
+	/** The writing direction for the locale. */
+	direction: Direction;
+}
+
+export interface I18nProviderProps {
+	/** Contents that should have the locale applied. */
+	children: any;
+	/** The locale to apply to the children. */
+	locale?: string;
+}
+
+const I18nContext = createContext<Locale | null>(null);
+
+interface I18nProviderWithLocaleProps extends I18nProviderProps {
+	locale: string;
+}
+
+/**
+ * Internal component that handles the case when locale is provided.
+ */
+function I18nProviderWithLocale(props: I18nProviderWithLocaleProps): any {
+	const slot = S('I18nProviderWithLocale');
+	let { locale, children } = props;
+	let value: Locale = useMemo(
+		() => ({
+			locale,
+			direction: isRTL(locale) ? 'rtl' : 'ltr',
+		}),
+		[locale],
+		subSlot(slot, 'value'),
+	);
+
+	return createElement(I18nContext.Provider, { value, children });
+}
+
+interface I18nProviderWithDefaultLocaleProps {
+	children: any;
+}
+
+/**
+ * Internal component that handles the case when no locale is provided.
+ */
+function I18nProviderWithDefaultLocale(props: I18nProviderWithDefaultLocaleProps): any {
+	const slot = S('I18nProviderWithDefaultLocale');
+	let { children } = props;
+	let defaultLocale = useDefaultLocale(subSlot(slot, 'default'));
+
+	return createElement(I18nContext.Provider, { value: defaultLocale, children });
+}
+
+/**
+ * Provides the locale for the application to all child components.
+ */
+export function I18nProvider(props: I18nProviderProps): any {
+	let { locale, children } = props;
+
+	// Conditionally render different components to avoid calling useDefaultLocale.
+	// This is necessary because useDefaultLocale triggers a re-render.
+	if (locale) {
+		return createElement(I18nProviderWithLocale, { locale, children });
+	}
+
+	return createElement(I18nProviderWithDefaultLocale, { children });
+}
+
+/**
+ * Returns the current locale and layout direction.
+ */
+export function useLocale(): Locale;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLocale(slot: symbol | undefined): Locale;
+export function useLocale(...args: any[]): Locale {
+	const [, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLocale');
+
+	let defaultLocale = useDefaultLocale(subSlot(slot, 'default'));
+	let context = useContext(I18nContext);
+	return context || defaultLocale;
+}

package/src/i18n/server.ts

@@ -0,0 +1,115 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/server.tsx).
+// NOT React-Server-Components machinery — a portable SSR helper: a component rendered
+// during server rendering that injects the locale + localized string tables into the
+// initial HTML via an inline <script> (read back on the client through the
+// `react-aria.i18n.locale` / `react-aria.i18n.strings` window symbols that
+// `useDefaultLocale` and `@internationalized/string` consume). octane adaptations:
+// - `.tsx` → `.ts`: JSX → createElement; octane supports `dangerouslySetInnerHTML` and
+//   `suppressHydrationWarning` with React semantics.
+// - React's `JSX.Element` type → `any` (octane descriptors).
+// - The dev-only "should only be rendered on the server" console.log is not ported
+//   (repo policy); the client-side `return null` guard is kept.
+import type { LocalizedString } from '@internationalized/string';
+import { createElement } from 'octane';
+
+type PackageLocalizedStrings = {
+	[packageName: string]: Record<string, LocalizedString>;
+};
+
+interface PackageLocalizationProviderProps {
+	locale: string;
+	strings: PackageLocalizedStrings;
+	nonce?: string;
+}
+
+/**
+ * A PackageLocalizationProvider can be rendered on the server to inject the localized strings
+ * needed by the client into the initial HTML.
+ */
+export function PackageLocalizationProvider(props: PackageLocalizationProviderProps): any {
+	if (typeof document !== 'undefined') {
+		return null;
+	}
+
+	let { nonce, locale, strings } = props;
+	// suppressHydrationWarning is necessary because the browser
+	// remove the nonce parameter from the DOM before hydration
+	return createElement('script', {
+		nonce: typeof window === 'undefined' ? nonce : '',
+		suppressHydrationWarning: true,
+		dangerouslySetInnerHTML: { __html: getPackageLocalizationScript(locale, strings) },
+	});
+}
+
+/**
+ * Returns the content for an inline `<script>` tag to inject localized strings into initial HTML.
+ */
+export function getPackageLocalizationScript(
+	locale: string,
+	strings: PackageLocalizedStrings,
+): string {
+	return `window[Symbol.for('react-aria.i18n.locale')]=${JSON.stringify(locale)};{${serialize(strings)}}`;
+}
+
+const cache = new WeakMap<PackageLocalizedStrings, string>();
+
+// octane adaptation (upstream bug): upstream names hoisted strings with
+// `String.fromCharCode(common.size > 25 ? common.size + 97 : common.size + 65)`,
+// which is 'A'-'Z' for the first 26 but char codes 123+ ('{', '|', …) from the
+// 27th on — the emitted script is a SyntaxError. A-Z matches upstream's valid
+// range byte-for-byte; a-z and then _N continue with valid identifiers ('_N'
+// rather than two-letter names, which could collide with reserved words).
+function commonName(i: number): string {
+	if (i < 26) return String.fromCharCode(i + 65);
+	if (i < 52) return String.fromCharCode(i + 71);
+	return '_' + (i - 52);
+}
+
+function serialize(strings: PackageLocalizedStrings): string {
+	let cached = cache.get(strings);
+	if (cached) {
+		return cached;
+	}
+
+	// Find common strings between packages and hoist them into variables.
+	let seen = new Set();
+	let common = new Map();
+	for (let pkg in strings) {
+		for (let key in strings[pkg]) {
+			let v = strings[pkg][key];
+			let s = typeof v === 'string' ? JSON.stringify(v) : v.toString();
+			if (seen.has(s) && !common.has(s)) {
+				common.set(s, commonName(common.size));
+			}
+			seen.add(s);
+		}
+	}
+
+	let res = '';
+	if (common.size > 0) {
+		res += 'let ';
+	}
+	for (let [string, name] of common) {
+		res += `${name}=${string},`;
+	}
+	if (common.size > 0) {
+		res = res.slice(0, -1) + ';';
+	}
+
+	res += "window[Symbol.for('react-aria.i18n.strings')]={";
+	for (let pkg in strings) {
+		res += `'${pkg}':{`;
+		for (let key in strings[pkg]) {
+			let v = strings[pkg][key];
+			let s = typeof v === 'string' ? JSON.stringify(v) : v.toString();
+			if (common.has(s)) {
+				s = common.get(s);
+			}
+			res += `${/[ ()]/.test(key) ? JSON.stringify(key) : key}:${s},`;
+		}
+		res = res.slice(0, -1) + '},';
+	}
+	res = res.slice(0, -1) + '};';
+	cache.set(strings, res);
+	return res;
+}

package/src/i18n/useCollator.ts

@@ -0,0 +1,42 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useCollator.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the module-level collator cache ports verbatim.
+import { S, splitSlot, subSlot } from '../internal';
+import { useLocale } from './I18nProvider';
+
+let cache = new Map<string, Intl.Collator>();
+
+/**
+ * Provides localized string collation for the current locale. Automatically updates when the locale
+ * changes, and handles caching of the collator for performance.
+ *
+ * @param options - Collator options.
+ */
+export function useCollator(options?: Intl.CollatorOptions): Intl.Collator;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCollator(
+	options: Intl.CollatorOptions | undefined,
+	slot: symbol | undefined,
+): Intl.Collator;
+export function useCollator(...args: any[]): Intl.Collator {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCollator');
+	const options = user[0] as Intl.CollatorOptions | undefined;
+
+	let { locale } = useLocale(subSlot(slot, 'locale'));
+
+	let cacheKey =
+		locale +
+		(options
+			? Object.entries(options)
+					.sort((a, b) => (a[0] < b[0] ? -1 : 1))
+					.join()
+			: '');
+	if (cache.has(cacheKey)) {
+		return cache.get(cacheKey)!;
+	}
+
+	let formatter = new Intl.Collator(locale, options);
+	cache.set(cacheKey, formatter);
+	return formatter;
+}

package/src/i18n/useDateFormatter.ts

@@ -0,0 +1,64 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useDateFormatter.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[locale, options]` memo deps are preserved exactly; the
+// `isEqual` key reads cast through `Record<string, any>` (strict index typing).
+import { DateFormatter } from '@internationalized/date';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useDeepMemo } from '../utils/useDeepMemo';
+import { useLocale } from './I18nProvider';
+
+export interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
+	calendar?: string;
+}
+
+/**
+ * Provides localized date formatting for the current locale. Automatically updates when the locale
+ * changes, and handles caching of the date formatter for performance.
+ *
+ * @param options - Formatting options.
+ */
+export function useDateFormatter(options?: DateFormatterOptions): DateFormatter;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDateFormatter(
+	options: DateFormatterOptions | undefined,
+	slot: symbol | undefined,
+): DateFormatter;
+export function useDateFormatter(...args: any[]): DateFormatter {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDateFormatter');
+
+	// Reuse last options object if it is shallowly equal, which allows the useMemo result to also be reused.
+	let options = useDeepMemo(
+		(user[0] as DateFormatterOptions | undefined) ?? {},
+		isEqual,
+		subSlot(slot, 'options'),
+	);
+	let { locale } = useLocale(subSlot(slot, 'locale'));
+	return useMemo(
+		() => new DateFormatter(locale, options),
+		[locale, options],
+		subSlot(slot, 'formatter'),
+	);
+}
+
+function isEqual(a: DateFormatterOptions, b: DateFormatterOptions) {
+	if (a === b) {
+		return true;
+	}
+
+	let aKeys = Object.keys(a);
+	let bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) {
+		return false;
+	}
+
+	for (let key of aKeys) {
+		if ((b as Record<string, any>)[key] !== (a as Record<string, any>)[key]) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/i18n/useDefaultLocale.ts

@@ -0,0 +1,93 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useDefaultLocale.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[]` effect dep array is preserved exactly; `window[localeSymbol]`
+// reads cast through `any` (symbol-keyed Window access). The server-injected locale symbol
+// keeps upstream's exact key so `PackageLocalizationProvider` output stays compatible.
+import { useEffect, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { isRTL } from './utils';
+import type { Locale } from './I18nProvider';
+import { useIsSSR } from '../ssr/SSRProvider';
+
+// Locale passed from server by PackageLocalizationProvider.
+const localeSymbol = Symbol.for('react-aria.i18n.locale');
+
+/**
+ * Gets the locale setting of the browser.
+ */
+export function getDefaultLocale(): Locale {
+	let locale =
+		(typeof window !== 'undefined' && (window as any)[localeSymbol]) ||
+		// @ts-ignore
+		(typeof navigator !== 'undefined' && (navigator.language || navigator.userLanguage)) ||
+		'en-US';
+
+	try {
+		Intl.DateTimeFormat.supportedLocalesOf([locale]);
+	} catch {
+		locale = 'en-US';
+	}
+	return {
+		locale,
+		direction: isRTL(locale) ? 'rtl' : 'ltr',
+	};
+}
+
+let currentLocale = getDefaultLocale();
+let listeners = new Set<(locale: Locale) => void>();
+
+function updateLocale() {
+	currentLocale = getDefaultLocale();
+	for (let listener of listeners) {
+		listener(currentLocale);
+	}
+}
+
+/**
+ * Returns the current browser/system language, and updates when it changes.
+ */
+export function useDefaultLocale(): Locale;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDefaultLocale(slot: symbol | undefined): Locale;
+export function useDefaultLocale(...args: any[]): Locale {
+	const [, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDefaultLocale');
+
+	let isSSR = useIsSSR(subSlot(slot, 'ssr'));
+	let [defaultLocale, setDefaultLocale] = useState(currentLocale, subSlot(slot, 'locale'));
+
+	useEffect(
+		() => {
+			if (listeners.size === 0) {
+				window.addEventListener('languagechange', updateLocale);
+			}
+
+			listeners.add(setDefaultLocale);
+
+			return () => {
+				listeners.delete(setDefaultLocale);
+				if (listeners.size === 0) {
+					window.removeEventListener('languagechange', updateLocale);
+				}
+			};
+		},
+		[],
+		subSlot(slot, 'listen'),
+	);
+
+	// We cannot determine the browser's language on the server, so default to
+	// en-US. This will be updated after hydration on the client to the correct value.
+	if (isSSR) {
+		let locale = typeof window !== 'undefined' && (window as any)[localeSymbol];
+		// octane adaptation (upstream bug): upstream hardcodes 'ltr' here even when
+		// the server-injected locale is RTL, disagreeing with getDefaultLocale's
+		// isRTL derivation for the very same value — derive it from what we return.
+		return {
+			locale: locale || 'en-US',
+			direction: locale && isRTL(locale) ? 'rtl' : 'ltr',
+		};
+	}
+
+	return defaultLocale;
+}

package/src/i18n/useFilter.ts

@@ -0,0 +1,107 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useFilter.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit `[collator]` / `[startsWith, endsWith, contains]` dep arrays are
+// preserved exactly; the callback params get explicit `string` types (strict implicit-any).
+import { useCallback, useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useCollator } from './useCollator';
+
+export interface Filter {
+	/** Returns whether a string starts with a given substring. */
+	startsWith: (string: string, substring: string) => boolean;
+	/** Returns whether a string ends with a given substring. */
+	endsWith: (string: string, substring: string) => boolean;
+	/** Returns whether a string contains a given substring. */
+	contains: (string: string, substring: string) => boolean;
+}
+
+/**
+ * Provides localized string search functionality that is useful for filtering or matching items in
+ * a list. Options can be provided to adjust the sensitivity to case, diacritics, and other
+ * parameters.
+ */
+export function useFilter(options?: Intl.CollatorOptions): Filter;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFilter(
+	options: Intl.CollatorOptions | undefined,
+	slot: symbol | undefined,
+): Filter;
+export function useFilter(...args: any[]): Filter {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFilter');
+	const options = user[0] as Intl.CollatorOptions | undefined;
+
+	let collator = useCollator(
+		{
+			usage: 'search',
+			...options,
+		},
+		subSlot(slot, 'collator'),
+	);
+
+	// TODO(later): these methods don't currently support the ignorePunctuation option.
+	let startsWith = useCallback(
+		(string: string, substring: string) => {
+			if (substring.length === 0) {
+				return true;
+			}
+
+			// Normalize both strings so we can slice safely
+			// TODO: take into account the ignorePunctuation option as well...
+			string = string.normalize('NFC');
+			substring = substring.normalize('NFC');
+			return collator.compare(string.slice(0, substring.length), substring) === 0;
+		},
+		[collator],
+		subSlot(slot, 'startsWith'),
+	);
+
+	let endsWith = useCallback(
+		(string: string, substring: string) => {
+			if (substring.length === 0) {
+				return true;
+			}
+
+			string = string.normalize('NFC');
+			substring = substring.normalize('NFC');
+			return collator.compare(string.slice(-substring.length), substring) === 0;
+		},
+		[collator],
+		subSlot(slot, 'endsWith'),
+	);
+
+	let contains = useCallback(
+		(string: string, substring: string) => {
+			if (substring.length === 0) {
+				return true;
+			}
+
+			string = string.normalize('NFC');
+			substring = substring.normalize('NFC');
+
+			let scan = 0;
+			let sliceLen = substring.length;
+			for (; scan + sliceLen <= string.length; scan++) {
+				let slice = string.slice(scan, scan + sliceLen);
+				if (collator.compare(substring, slice) === 0) {
+					return true;
+				}
+			}
+
+			return false;
+		},
+		[collator],
+		subSlot(slot, 'contains'),
+	);
+
+	return useMemo(
+		() => ({
+			startsWith,
+			endsWith,
+			contains,
+		}),
+		[startsWith, endsWith, contains],
+		subSlot(slot, 'filter'),
+	);
+}

package/src/i18n/useListFormatter.ts

@@ -0,0 +1,33 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useListFormatter.tsx).
+// octane adaptations: `.tsx` → `.ts` (the file contains no JSX); public-hook slot threading
+// (splitSlot/subSlot) per the binding convention; the explicit `[locale, options]` memo deps
+// are preserved exactly.
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLocale } from './I18nProvider';
+
+/**
+ * Provides localized list formatting for the current locale. Automatically updates when the locale
+ * changes, and handles caching of the list formatter for performance.
+ *
+ * @param options - Formatting options.
+ */
+export function useListFormatter(options?: Intl.ListFormatOptions): Intl.ListFormat;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useListFormatter(
+	options: Intl.ListFormatOptions | undefined,
+	slot: symbol | undefined,
+): Intl.ListFormat;
+export function useListFormatter(...args: any[]): Intl.ListFormat {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useListFormatter');
+	const options = (user[0] as Intl.ListFormatOptions | undefined) ?? {};
+
+	let { locale } = useLocale(subSlot(slot, 'locale'));
+	return useMemo(
+		() => new Intl.ListFormat(locale, options),
+		[locale, options],
+		subSlot(slot, 'formatter'),
+	);
+}

package/src/i18n/useLocalizedStringFormatter.ts

@@ -0,0 +1,90 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useLocalizedStringFormatter.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention (`useLocalizedStringDictionary` calls no octane hooks today but keeps the
+// slot-threading shape for uniformity); the explicit `[locale, dictionary]` memo deps are
+// preserved exactly.
+import {
+	LocalizedString,
+	LocalizedStringDictionary,
+	LocalizedStringFormatter,
+	LocalizedStrings,
+} from '@internationalized/string';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLocale } from './I18nProvider';
+
+const cache = new WeakMap();
+function getCachedDictionary<K extends string, T extends LocalizedString>(
+	strings: LocalizedStrings<K, T>,
+): LocalizedStringDictionary<K, T> {
+	let dictionary = cache.get(strings);
+	if (!dictionary) {
+		dictionary = new LocalizedStringDictionary(strings);
+		cache.set(strings, dictionary);
+	}
+
+	return dictionary;
+}
+
+/**
+ * Returns a cached LocalizedStringDictionary for the given strings.
+ */
+export function useLocalizedStringDictionary<
+	K extends string = string,
+	T extends LocalizedString = string,
+>(strings: LocalizedStrings<K, T>, packageName?: string): LocalizedStringDictionary<K, T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLocalizedStringDictionary<
+	K extends string = string,
+	T extends LocalizedString = string,
+>(
+	strings: LocalizedStrings<K, T>,
+	packageName: string | undefined,
+	slot: symbol | undefined,
+): LocalizedStringDictionary<K, T>;
+export function useLocalizedStringDictionary(...args: any[]): LocalizedStringDictionary<any, any> {
+	const [user] = splitSlot(args);
+	const strings = user[0] as LocalizedStrings<any, any>;
+	const packageName = user[1] as string | undefined;
+
+	return (
+		(packageName && LocalizedStringDictionary.getGlobalDictionaryForPackage(packageName)) ||
+		getCachedDictionary(strings)
+	);
+}
+
+/**
+ * Provides localized string formatting for the current locale. Supports interpolating variables,
+ * selecting the correct pluralization, and formatting numbers. Automatically updates when the
+ * locale changes.
+ *
+ * @param strings - A mapping of languages to localized strings by key.
+ */
+export function useLocalizedStringFormatter<
+	K extends string = string,
+	T extends LocalizedString = string,
+>(strings: LocalizedStrings<K, T>, packageName?: string): LocalizedStringFormatter<K, T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLocalizedStringFormatter<
+	K extends string = string,
+	T extends LocalizedString = string,
+>(
+	strings: LocalizedStrings<K, T>,
+	packageName: string | undefined,
+	slot: symbol | undefined,
+): LocalizedStringFormatter<K, T>;
+export function useLocalizedStringFormatter(...args: any[]): LocalizedStringFormatter<any, any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLocalizedStringFormatter');
+	const strings = user[0] as LocalizedStrings<any, any>;
+	const packageName = user[1] as string | undefined;
+
+	let { locale } = useLocale(subSlot(slot, 'locale'));
+	let dictionary = useLocalizedStringDictionary(strings, packageName, subSlot(slot, 'dictionary'));
+	return useMemo(
+		() => new LocalizedStringFormatter(locale, dictionary),
+		[locale, dictionary],
+		subSlot(slot, 'formatter'),
+	);
+}

package/src/i18n/useNumberFormatter.ts

@@ -0,0 +1,33 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/i18n/useNumberFormatter.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[locale, options]` memo deps are preserved exactly.
+import { NumberFormatOptions, NumberFormatter } from '@internationalized/number';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLocale } from './I18nProvider';
+
+/**
+ * Provides localized number formatting for the current locale. Automatically updates when the
+ * locale changes, and handles caching of the number formatter for performance.
+ *
+ * @param options - Formatting options.
+ */
+export function useNumberFormatter(options?: NumberFormatOptions): Intl.NumberFormat;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useNumberFormatter(
+	options: NumberFormatOptions | undefined,
+	slot: symbol | undefined,
+): Intl.NumberFormat;
+export function useNumberFormatter(...args: any[]): Intl.NumberFormat {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useNumberFormatter');
+	const options = (user[0] as NumberFormatOptions | undefined) ?? {};
+
+	let { locale } = useLocale(subSlot(slot, 'locale'));
+	return useMemo(
+		() => new NumberFormatter(locale, options),
+		[locale, options],
+		subSlot(slot, 'formatter'),
+	);
+}