@octanejs/aria 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/aria",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -38,11 +38,14 @@
     "./stately": "./src/stately/index.ts"
   },
   "dependencies": {
+    "@internationalized/date": "^3.12.2",
+    "@internationalized/number": "^3.6.7",
+    "@internationalized/string": "^3.2.9",
     "@react-types/shared": "^3.36.0",
     "clsx": "^2.1.1"
   },
   "peerDependencies": {
-    "octane": "0.1.7"
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@tsrx/react": "^0.2.37",
@@ -52,7 +55,7 @@
     "react-dom": "^19.2.0",
     "react-stately": "3.48.0",
     "vitest": "^4.1.9",
-    "octane": "0.1.7"
+    "octane": "0.1.9"
   },
   "scripts": {
     "test": "vitest run"

package/src/breadcrumbs/useBreadcrumbItem.ts

@@ -0,0 +1,95 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/breadcrumbs/useBreadcrumbItem.ts).
+// octane adaptations: React's `ReactNode` children type → `any` (octane renderables);
+// `DOMAttributes` is a local structural prop-bag alias; public-hook slot threading.
+import { AriaLinkProps, useLink } from '../link/useLink';
+import type { DOMProps, FocusableElement, LinkDOMProps, RefObject } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface BreadcrumbItemProps extends AriaLinkProps, LinkDOMProps {
+	/** Whether the breadcrumb item represents the current page. */
+	isCurrent?: boolean;
+	/**
+	 * The type of current location the breadcrumb item represents, if `isCurrent` is true.
+	 *
+	 * @default 'page'
+	 */
+	'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | boolean | 'true' | 'false';
+	/** Whether the breadcrumb item is disabled. */
+	isDisabled?: boolean;
+	/** The contents of the breadcrumb item. */
+	children: any;
+}
+
+export interface AriaBreadcrumbItemProps extends BreadcrumbItemProps, DOMProps {
+	/**
+	 * The HTML element used to render the breadcrumb link, e.g. 'a', or 'span'.
+	 *
+	 * @default 'a'
+	 */
+	elementType?: string;
+}
+
+export interface BreadcrumbItemAria {
+	/** Props for the breadcrumb item link element. */
+	itemProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for an in a breadcrumbs component.
+ * See `useBreadcrumbs` for details about breadcrumbs.
+ */
+export function useBreadcrumbItem(
+	props: AriaBreadcrumbItemProps,
+	ref: RefObject<FocusableElement | null>,
+): BreadcrumbItemAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useBreadcrumbItem(
+	props: AriaBreadcrumbItemProps,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): BreadcrumbItemAria;
+export function useBreadcrumbItem(...args: any[]): BreadcrumbItemAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useBreadcrumbItem');
+	const props = user[0] as AriaBreadcrumbItemProps;
+	const ref = user[1] as RefObject<FocusableElement | null>;
+
+	let {
+		isCurrent,
+		isDisabled,
+		'aria-current': ariaCurrent,
+		elementType = 'a',
+		...otherProps
+	} = props;
+
+	let { linkProps } = useLink(
+		{ isDisabled: isDisabled || isCurrent, elementType, ...otherProps },
+		ref,
+		subSlot(slot, 'link'),
+	);
+	let isHeading = /^h[1-6]$/.test(elementType);
+	let itemProps: DOMAttributes = {};
+
+	if (!isHeading) {
+		itemProps = linkProps;
+	}
+
+	if (isCurrent) {
+		itemProps['aria-current'] = ariaCurrent || 'page';
+		// isCurrent sets isDisabled === true for the current item,
+		// so we have to restore the tabIndex in order to support autoFocus.
+		itemProps.tabIndex = props.autoFocus ? -1 : undefined;
+	}
+
+	return {
+		itemProps: {
+			'aria-disabled': isDisabled,
+			...itemProps,
+		},
+	};
+}

package/src/breadcrumbs/useBreadcrumbs.ts

@@ -0,0 +1,51 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/breadcrumbs/useBreadcrumbs.ts).
+// octane adaptations: the Parcel glob intl import becomes the generated
+// src/intl/breadcrumbs index (verbatim dictionaries); `DOMAttributes` is a local
+// structural prop-bag alias; public-hook slot threading.
+import type { AriaLabelingProps, DOMProps } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import intlMessages from '../intl/breadcrumbs';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface AriaBreadcrumbsProps extends DOMProps, AriaLabelingProps {}
+
+export interface BreadcrumbsAria {
+	/** Props for the breadcrumbs navigation element. */
+	navProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a breadcrumbs component.
+ * Breadcrumbs display a hierarchy of links to the current page or resource in an application.
+ */
+export function useBreadcrumbs(props: AriaBreadcrumbsProps): BreadcrumbsAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useBreadcrumbs(
+	props: AriaBreadcrumbsProps,
+	slot: symbol | undefined,
+): BreadcrumbsAria;
+export function useBreadcrumbs(...args: any[]): BreadcrumbsAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useBreadcrumbs');
+	const props = user[0] as AriaBreadcrumbsProps;
+
+	let { 'aria-label': ariaLabel, ...otherProps } = props;
+
+	let strings = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/breadcrumbs',
+		subSlot(slot, 'strings'),
+	);
+	return {
+		navProps: {
+			...filterDOMProps(otherProps, { labelable: true }),
+			'aria-label': ariaLabel || strings.format('breadcrumbs'),
+		},
+	};
+}

package/src/button/useButton.ts

@@ -0,0 +1,273 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/button/useButton.ts).
+// octane adaptations:
+// - React's `ElementType`/`JSXElementConstructor` → a local structural `ElementType`
+//   (octane components are plain functions); the per-element attribute types
+//   (`ButtonHTMLAttributes` etc.) → a structural prop bag, so the per-element-type
+//   overloads keep upstream's ref typing with a shared structural result.
+// - `ReactNode` children → `any` (octane descriptors).
+// - `onClick` receives the NATIVE MouseEvent (upstream's `PressEvents.onClick` is typed
+//   over React's synthetic event), matching the ported `usePress`.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type {
+	AriaLabelingProps,
+	FocusableDOMProps,
+	PressEvents,
+	RefObject,
+} from '@react-types/shared';
+
+import type { FocusableProps } from '../interactions/useFocusable';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { useFocusable } from '../interactions/useFocusable';
+import { usePress } from '../interactions/usePress';
+
+// octane adaptation: minimal structural element/prop-bag types (upstream's drag React's
+// element and per-element attribute types).
+export type ElementType = string | ((props: any) => any);
+type DOMAttributes = Record<string, any>;
+
+export interface ButtonProps extends Omit<PressEvents, 'onClick'>, FocusableProps {
+	/**
+	 * **Not recommended – use `onPress` instead.** octane adaptation: native MouseEvent
+	 * (upstream's `PressEvents.onClick` is typed over React's synthetic event).
+	 */
+	onClick?: (e: MouseEvent) => void;
+	/** Whether the button is disabled. */
+	isDisabled?: boolean;
+	/** The content to display in the button. */
+	children?: any;
+}
+
+export interface AriaBaseButtonProps extends FocusableDOMProps, AriaLabelingProps {
+	/** Indicates whether the element is disabled to users of assistive technology. */
+	'aria-disabled'?: boolean | 'true' | 'false';
+	/**
+	 * Indicates whether the element, or another grouping element it controls, is currently expanded
+	 * or collapsed.
+	 */
+	'aria-expanded'?: boolean | 'true' | 'false';
+	/**
+	 * Indicates the availability and type of interactive popup element, such as menu or dialog, that
+	 * can be triggered by an element.
+	 */
+	'aria-haspopup'?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | 'true' | 'false';
+	/**
+	 * Identifies the element (or elements) whose contents or presence are controlled by the current
+	 * element.
+	 */
+	'aria-controls'?: string;
+	/** Indicates the current "pressed" state of toggle buttons. */
+	'aria-pressed'?: boolean | 'true' | 'false' | 'mixed';
+	/**
+	 * Indicates whether this element represents the current item within a container or set of related
+	 * elements.
+	 */
+	'aria-current'?: boolean | 'true' | 'false' | 'page' | 'step' | 'location' | 'date' | 'time';
+	/**
+	 * The behavior of the button when used in an HTML form.
+	 *
+	 * @default 'button'
+	 */
+	type?: 'button' | 'submit' | 'reset';
+	/**
+	 * Whether to prevent focus from moving to the button when pressing it.
+	 *
+	 * Caution, this can make the button inaccessible and should only be used when alternative
+	 * keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's
+	 * increment/decrement control.
+	 */
+	preventFocusOnPress?: boolean;
+	/**
+	 * The `<form>` element to associate the button with.
+	 * The value of this attribute must be the id of a `<form>` in the same document.
+	 * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form).
+	 */
+	form?: string;
+	/**
+	 * The URL that processes the information submitted by the button.
+	 * Overrides the action attribute of the button's form owner.
+	 *
+	 * octane adaptation: typed locally (upstream borrows React's `formAction` attribute type,
+	 * which also admits a function form action).
+	 */
+	formAction?: string | ((formData: FormData) => void | Promise<void>);
+	/** Indicates how to encode the form data that is submitted. */
+	formEncType?: string;
+	/** Indicates the HTTP method used to submit the form. */
+	formMethod?: string;
+	/** Indicates that the form is not to be validated when it is submitted. */
+	formNoValidate?: boolean;
+	/** Overrides the target attribute of the button's form owner. */
+	formTarget?: string;
+	/** Submitted as a pair with the button's value as part of the form data. */
+	name?: string;
+	/** The value associated with the button's name when it's submitted with the form data. */
+	value?: string;
+}
+
+export interface AriaButtonElementTypeProps<T extends ElementType = 'button'> {
+	/**
+	 * The HTML element or octane component used to render the button, e.g. 'div', 'a', or
+	 * `RouterLink`.
+	 *
+	 * @default 'button'
+	 */
+	elementType?: T | ((props: any) => any);
+}
+
+export interface LinkButtonProps<
+	T extends ElementType = 'button',
+> extends AriaButtonElementTypeProps<T> {
+	/** A URL to link to if elementType="a". */
+	href?: string;
+	/** The target window for the link. */
+	target?: string;
+	/**
+	 * The relationship between the linked resource and the current page. See
+	 * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
+	 */
+	rel?: string;
+}
+
+export interface AriaButtonProps<T extends ElementType = 'button'>
+	extends ButtonProps, LinkButtonProps<T>, AriaBaseButtonProps {}
+
+export interface AriaButtonOptions<E extends ElementType> extends Omit<
+	AriaButtonProps<E>,
+	'children'
+> {}
+
+export interface ButtonAria<T> {
+	/** Props for the button element. */
+	buttonProps: T;
+	/** Whether the button is currently pressed. */
+	isPressed: boolean;
+}
+
+// Order with overrides is important: 'button' should be default
+export function useButton(
+	props: AriaButtonOptions<'button'>,
+	ref: RefObject<HTMLButtonElement | null>,
+): ButtonAria<DOMAttributes>;
+export function useButton(
+	props: AriaButtonOptions<'a'>,
+	ref: RefObject<HTMLAnchorElement | null>,
+): ButtonAria<DOMAttributes>;
+export function useButton(
+	props: AriaButtonOptions<'div'>,
+	ref: RefObject<HTMLDivElement | null>,
+): ButtonAria<DOMAttributes>;
+export function useButton(
+	props: AriaButtonOptions<'input'>,
+	ref: RefObject<HTMLInputElement | null>,
+): ButtonAria<DOMAttributes>;
+export function useButton(
+	props: AriaButtonOptions<'span'>,
+	ref: RefObject<HTMLSpanElement | null>,
+): ButtonAria<DOMAttributes>;
+export function useButton(
+	props: AriaButtonOptions<ElementType>,
+	ref: RefObject<Element | null>,
+): ButtonAria<DOMAttributes>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useButton(
+	props: AriaButtonOptions<ElementType>,
+	ref: RefObject<any>,
+	slot: symbol | undefined,
+): ButtonAria<DOMAttributes>;
+/**
+ * Provides the behavior and accessibility implementation for a button component. Handles mouse,
+ * keyboard, and touch interactions, focus behavior, and ARIA props for both native button elements
+ * and custom element types.
+ *
+ * @param props - Props to be applied to the button.
+ * @param ref - A ref to a DOM element for the button.
+ */
+export function useButton(...args: any[]): ButtonAria<DOMAttributes> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useButton');
+	const props = user[0] as AriaButtonOptions<ElementType>;
+	const ref = user[1] as RefObject<any>;
+
+	let {
+		elementType = 'button',
+		isDisabled,
+		onPress,
+		onPressStart,
+		onPressEnd,
+		onPressUp,
+		onPressChange,
+		preventFocusOnPress,
+		// @ts-ignore - undocumented
+		allowFocusWhenDisabled,
+		onClick,
+		href,
+		target,
+		rel,
+		type = 'button',
+	} = props;
+	let additionalProps;
+	if (elementType === 'button') {
+		additionalProps = {
+			type,
+			disabled: isDisabled,
+			form: props.form,
+			formAction: props.formAction,
+			formEncType: props.formEncType,
+			formMethod: props.formMethod,
+			formNoValidate: props.formNoValidate,
+			formTarget: props.formTarget,
+			name: props.name,
+			value: props.value,
+		};
+	} else {
+		additionalProps = {
+			role: 'button',
+			href: elementType === 'a' && !isDisabled ? href : undefined,
+			target: elementType === 'a' ? target : undefined,
+			type: elementType === 'input' ? type : undefined,
+			disabled: elementType === 'input' ? isDisabled : undefined,
+			'aria-disabled': !isDisabled || elementType === 'input' ? undefined : isDisabled,
+			rel: elementType === 'a' ? rel : undefined,
+		};
+	}
+
+	let { pressProps, isPressed } = usePress(
+		{
+			onPressStart,
+			onPressEnd,
+			onPressChange,
+			onPress,
+			onPressUp,
+			onClick,
+			isDisabled,
+			preventFocusOnPress,
+			ref,
+		},
+		subSlot(slot, 'press'),
+	);
+
+	let { focusableProps } = useFocusable(props, ref, subSlot(slot, 'focusable'));
+	if (allowFocusWhenDisabled) {
+		focusableProps.tabIndex = isDisabled ? -1 : focusableProps.tabIndex;
+	}
+	let buttonProps = mergeProps(
+		focusableProps,
+		pressProps,
+		filterDOMProps(props, { labelable: true }),
+	);
+
+	return {
+		isPressed, // Used to indicate press state for visual
+		buttonProps: mergeProps(additionalProps, buttonProps, {
+			'aria-haspopup': props['aria-haspopup'],
+			'aria-expanded': props['aria-expanded'],
+			'aria-controls': props['aria-controls'],
+			'aria-pressed': props['aria-pressed'],
+			'aria-current': props['aria-current'],
+			'aria-disabled': props['aria-disabled'],
+		}),
+	};
+}

package/src/button/useToggleButton.ts

@@ -0,0 +1,131 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/button/useToggleButton.ts).
+// octane adaptations:
+// - `react-stately/useToggleState` → the ported `../stately/toggle/useToggleState`.
+// - React's per-element attribute types → the shared structural prop bag (see useButton).
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type { RefObject } from '@react-types/shared';
+
+import {
+	AriaBaseButtonProps,
+	AriaButtonElementTypeProps,
+	ButtonAria,
+	ButtonProps,
+	ElementType,
+	useButton,
+} from './useButton';
+import { chain } from '../utils/chain';
+import { mergeProps } from '../utils/mergeProps';
+import { S, splitSlot, subSlot } from '../internal';
+import type { ToggleState } from '../stately/toggle/useToggleState';
+
+// octane adaptation: minimal structural prop bag (upstream's drags React attribute types).
+type DOMAttributes = Record<string, any>;
+
+export interface ToggleButtonProps extends ButtonProps {
+	/** Whether the element should be selected (controlled). */
+	isSelected?: boolean;
+	/** Whether the element should be selected (uncontrolled). */
+	defaultSelected?: boolean;
+	/** Handler that is called when the element's selection state changes. */
+	onChange?: (isSelected: boolean) => void;
+}
+
+export interface AriaToggleButtonProps<T extends ElementType = 'button'>
+	extends
+		ToggleButtonProps,
+		Omit<
+			AriaBaseButtonProps,
+			| 'aria-current'
+			| 'form'
+			| 'formAction'
+			| 'formEncType'
+			| 'formMethod'
+			| 'formNoValidate'
+			| 'formTarget'
+			| 'name'
+			| 'value'
+			| 'type'
+		>,
+		AriaButtonElementTypeProps<T> {}
+
+export interface AriaToggleButtonOptions<E extends ElementType> extends Omit<
+	AriaToggleButtonProps<E>,
+	'children'
+> {}
+
+export interface ToggleButtonAria<T> extends ButtonAria<T> {
+	/** Whether the button is selected. */
+	isSelected: boolean;
+	/** Whether the button is disabled. */
+	isDisabled: boolean;
+}
+
+// Order with overrides is important: 'button' should be default
+export function useToggleButton(
+	props: AriaToggleButtonOptions<'button'>,
+	state: ToggleState,
+	ref: RefObject<HTMLButtonElement | null>,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButton(
+	props: AriaToggleButtonOptions<'a'>,
+	state: ToggleState,
+	ref: RefObject<HTMLAnchorElement | null>,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButton(
+	props: AriaToggleButtonOptions<'div'>,
+	state: ToggleState,
+	ref: RefObject<HTMLDivElement | null>,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButton(
+	props: AriaToggleButtonOptions<'input'>,
+	state: ToggleState,
+	ref: RefObject<HTMLInputElement | null>,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButton(
+	props: AriaToggleButtonOptions<'span'>,
+	state: ToggleState,
+	ref: RefObject<HTMLSpanElement | null>,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButton(
+	props: AriaToggleButtonOptions<ElementType>,
+	state: ToggleState,
+	ref: RefObject<Element | null>,
+): ToggleButtonAria<DOMAttributes>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useToggleButton(
+	props: AriaToggleButtonOptions<ElementType>,
+	state: ToggleState,
+	ref: RefObject<any>,
+	slot: symbol | undefined,
+): ToggleButtonAria<DOMAttributes>;
+/**
+ * Provides the behavior and accessibility implementation for a toggle button component.
+ * ToggleButtons allow users to toggle a selection on or off, for example switching between two
+ * states or modes.
+ */
+export function useToggleButton(...args: any[]): ToggleButtonAria<DOMAttributes> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useToggleButton');
+	const props = user[0] as AriaToggleButtonOptions<ElementType>;
+	const state = user[1] as ToggleState;
+	const ref = user[2] as RefObject<any>;
+
+	const { isSelected } = state;
+	const { isPressed, buttonProps } = useButton(
+		{
+			...props,
+			onPress: chain(state.toggle, props.onPress),
+		},
+		ref,
+		subSlot(slot, 'button'),
+	);
+
+	return {
+		isPressed,
+		isSelected,
+		isDisabled: props.isDisabled || false,
+		buttonProps: mergeProps(buttonProps, {
+			'aria-pressed': isSelected,
+		}),
+	};
+}