aeon-ui-engine 1.5.1 → 1.9.0

package/packages/react/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, RefObject, ImgHTMLAttributes, FormHTMLAttributes } from 'react';
+import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, CSSProperties, ForwardedRef, LabelHTMLAttributes, RefObject, ImgHTMLAttributes, FormHTMLAttributes } from 'react';
 import * as xstate from 'xstate';
 import { AnyStateMachine } from 'xstate';
 import { useMachine } from '@xstate/react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { AsyncContext, ContentRegionState, AppNavChild, StickyBarState } from '@aeon-ui/primitives';
 export { AppNavChild, AppNavContext, createAsyncMachine, fieldMachine } from '@aeon-ui/primitives';
-import { fieldFace, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
+import { fieldFace, ListWindowAxis, ListWindow, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
 export { AeonColorMode as AeonMode } from '@aeon-ui/core';
 
 /** Action button lifecycle — see STATES.md and `buttonLifecycleMachine`. */
@@ -134,7 +134,7 @@ declare const StatusBanner: {
     Action: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
 };
 
-interface TabsRootProps {
+interface TabsRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'> {
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
@@ -162,6 +162,64 @@ declare const Separator: {
     Root: react.ForwardRefExoticComponent<SeparatorRootProps & react.RefAttributes<HTMLDivElement>>;
 };
 
+type ProseRootProps = HTMLAttributes<HTMLDivElement>;
+declare const Prose: {
+    Root: react.ForwardRefExoticComponent<ProseRootProps & react.RefAttributes<HTMLDivElement>>;
+};
+
+/** Row limits as the CSS variables Aeon's auto-growing textareas read (Textarea, Composer.Input). */
+declare function rowLimits(minRows?: number, maxRows?: number): CSSProperties;
+/**
+ * Grows a textarea to its content where CSS `field-sizing` is missing (Firefox); the recipe's
+ * min / max height still clamp it. Spread the result onto the textarea.
+ */
+declare function useAutoGrow(forwarded: ForwardedRef<HTMLTextAreaElement>, value: unknown): {
+    ref: (el: HTMLTextAreaElement | null) => void;
+    onInput: () => void;
+};
+interface TextareaRootProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Height floor in lines. */
+    minRows?: number;
+    /** Height ceiling in lines; past it the textarea scrolls. Omit to grow without limit. */
+    maxRows?: number;
+}
+declare const Textarea: {
+    Root: react.ForwardRefExoticComponent<TextareaRootProps & react.RefAttributes<HTMLTextAreaElement>>;
+};
+
+interface SegmentGroupRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    disabled?: boolean;
+    orientation?: 'horizontal' | 'vertical';
+}
+interface SegmentGroupItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+    value: string;
+}
+declare const SegmentGroup: {
+    Root: react.ForwardRefExoticComponent<SegmentGroupRootProps & react.RefAttributes<HTMLDivElement>>;
+    Item: react.ForwardRefExoticComponent<SegmentGroupItemProps & react.RefAttributes<HTMLButtonElement>>;
+};
+
+/** Read the copy status from any part inside Clipboard.Root. */
+declare const useClipboardStatus: () => "idle" | "copying" | "copied" | "failed";
+interface ClipboardRootProps extends HTMLAttributes<HTMLDivElement> {
+    /** Text written to the clipboard; read at the moment of copying. */
+    value: string;
+    /** How long copied / failed show, in ms. */
+    timeout?: number;
+}
+interface ClipboardIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Shown while copied; `children` show otherwise. */
+    copied?: ReactNode;
+}
+declare const Clipboard: {
+    Root: react.ForwardRefExoticComponent<ClipboardRootProps & react.RefAttributes<HTMLDivElement>>;
+    Trigger: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+    Indicator: react.ForwardRefExoticComponent<ClipboardIndicatorProps & react.RefAttributes<HTMLSpanElement>>;
+};
+
 interface ProgressRootProps extends HTMLAttributes<HTMLDivElement> {
     value?: number;
     max?: number;
@@ -176,7 +234,7 @@ declare const Progress: {
     Label: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
 };
 
-interface RadioGroupRootProps {
+interface RadioGroupRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'> {
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
@@ -194,6 +252,30 @@ declare const RadioGroup: {
     ItemLabel: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
 };
 
+/** Bridge executable statecharts to React — UI = f(snapshot). */
+declare function useAeonMachine<M extends AnyStateMachine>(machine: M, options?: Parameters<typeof useMachine<M>>[1]): [xstate.StateFrom<M>, (event: xstate.EventFromLogic<M>) => void, xstate.Actor<M>];
+
+interface SliderContextValue {
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    disabled: boolean;
+    dragging: boolean;
+    /** Nested region value from the machine: `interaction.idle` | `interaction.dragging`. */
+    interaction: 'idle' | 'dragging';
+    send: ReturnType<typeof useAeonMachine<typeof sliderMachine>>[1];
+    onValueChange?: (value: number) => void;
+    /** Snap, store and report a user-intended value. */
+    commit: (value: number) => void;
+    setValueFromClientX: (clientX: number) => void;
+    trackRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * Read the slider's live machine state from inside `Slider.Root`.
+ * `interaction` is the nested region value — the same thing the snapshot holds.
+ */
+declare function useSliderContext(): SliderContextValue;
 interface SliderRootProps {
     value?: number;
     defaultValue?: number;
@@ -237,9 +319,6 @@ declare const RangeSlider: {
     ValueText: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
 };
 
-/** Bridge executable statecharts to React — UI = f(snapshot). */
-declare function useAeonMachine<M extends AnyStateMachine>(machine: M, options?: Parameters<typeof useMachine<M>>[1]): [xstate.StateFrom<M>, (event: xstate.EventFromLogic<M>) => void, xstate.Actor<M>];
-
 interface FileUploadContextValue {
     phase: 'idle' | 'dragging' | 'rejected';
     accept: string;
@@ -451,6 +530,33 @@ declare const Field: {
 /** Subscribe to scroll + resize; returns data-aeon-state value for a viewport. */
 declare function useScrollState(ref: RefObject<HTMLElement | null>): string;
 
+interface UseWindowedRangeOptions {
+    total: number;
+    /** Fallback row pitch, used until a row can be measured. */
+    itemExtent: number;
+    /** Fallback column count for grids; the real count is read from the grid. */
+    columns?: number;
+    overscan?: number;
+    /** Restrict measuring to real rows when the list also holds other chrome. */
+    rowSelector?: string;
+    minItems?: number;
+    /** `x` windows a horizontal strip by item width; columns do not apply. */
+    axis?: ListWindowAxis;
+    /** The list element itself; its scrollable ancestor drives the window. */
+    scrollRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Windowed slice for long lists and grids. Render `items.slice(start, end)`
+ * between spacers of `padStart` / `padEnd` (spread `listWindowPadAttrs`) or
+ * as list padding; each row keeps its own data-aeon-* projection.
+ *
+ * The first render windows from the hints, so a long list never mounts whole.
+ * Measuring reads layout, so it runs at most once per frame, and the window is
+ * published only when it moves: a scroll inside the current window renders
+ * nothing.
+ */
+declare function useWindowedRange(options: UseWindowedRangeOptions): ListWindow;
+
 interface ScrollContextValue {
     stateAttr: string;
 }
@@ -467,6 +573,10 @@ declare const Scroll: {
     Content: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
+type AnchorSide = 'top' | 'bottom';
+type AnchorAlign = 'start' | 'end' | 'center';
+type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`;
+
 interface SelectRootProps {
     value: string;
     onValueChange?: (value: string) => void;
@@ -477,6 +587,11 @@ interface SelectRootProps {
 interface SelectPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount listbox in document.body (default true). */
     portalled?: boolean;
+    placement?: AnchorPlacement;
+    /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+    anchorRef?: RefObject<HTMLElement | null>;
+    /** Size the listbox to the anchor (default true). */
+    matchAnchorWidth?: boolean;
     children?: ReactNode;
 }
 interface SelectContentProps extends HTMLAttributes<HTMLDivElement> {
@@ -519,10 +634,6 @@ declare const Combobox: {
     Empty: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
-type AnchorSide = 'top' | 'bottom';
-type AnchorAlign = 'start' | 'end' | 'center';
-type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`;
-
 interface PopoverRootProps {
     open?: boolean;
     defaultOpen?: boolean;
@@ -534,6 +645,10 @@ interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount panel in document.body (default true). */
     portalled?: boolean;
     placement?: AnchorPlacement;
+    /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+    anchorRef?: React.RefObject<HTMLElement | null>;
+    /** Size the panel to the anchor, so it spans the region it belongs to. */
+    matchAnchorWidth?: boolean;
     /** Gap between trigger and panel (default 4). */
     gutter?: number;
     /** Stack level for the portalled surface (default 50). */
@@ -875,9 +990,15 @@ interface ComposerRootProps extends FormHTMLAttributes<HTMLFormElement> {
     state?: ComposerState;
     children?: ReactNode;
 }
+interface ComposerInputProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Height floor in lines (default 1). */
+    minRows?: number;
+    /** Height ceiling in lines before the input scrolls (default 4). */
+    maxRows?: number;
+}
 declare const Composer: {
     Root: react.ForwardRefExoticComponent<ComposerRootProps & react.RefAttributes<HTMLFormElement>>;
-    Input: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
+    Input: react.ForwardRefExoticComponent<ComposerInputProps & react.RefAttributes<HTMLTextAreaElement>>;
     Actions: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
     Send: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
     Toolbar: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
@@ -1186,4 +1307,4 @@ declare const Slot: react.ForwardRefExoticComponent<HTMLAttributes<HTMLElement>
     children?: ReactNode;
 } & react.RefAttributes<HTMLElement>>;
 
-export { Accordion, type AccordionItemContentProps, type AccordionItemProps, type AccordionItemTriggerProps, type AccordionRootProps, AppNav, type AppNavBreadcrumbProps, type AppNavRootProps, type AppNavSectionProps, AppShell, type AppShellRootProps, Async, AsyncActions, AsyncProvider, AsyncReadout, AsyncRoot, AsyncTrack, Avatar, type AvatarRootProps, type AvatarStatus, Bar, type BarRootProps, Button, type ButtonRootProps, type ButtonStatus, Checkbox, type CheckboxRootProps, Combobox, type ComboboxItemProps, type ComboboxRootProps, Composer, type ComposerRootProps, type ComposerState, Content, type ContentRootProps, Conversation, type ConversationItemProps, type ConversationItemState, type ConversationRootProps, Dialog, type DialogPortalProps, type DialogRootProps, Entry, type EntryListProps, type EntryRootProps, type EntryState, Field, type FieldControlProps, type FieldRootProps, type FieldTextareaProps, FileUpload, type FileUploadRootProps, Identity, type IdentityRootProps, ListRow, type ListRowRootProps, Menu, type MenuItemProps, type MenuPositionerProps, type MenuRootProps, MetricStrip, type MetricStripRootProps, Nav, type NavItemProps, type NavRootProps, Panel, type PanelContentProps, type PanelGroupProps, type PanelLabelProps, type PanelRootProps, type PanelTriggerProps, PinInput, type PinInputInputProps, type PinInputRootProps, Popover, type PopoverPositionerProps, type PopoverRootProps, type PresenceState, ProfileHeader, type ProfileHeaderRootProps, Progress, type ProgressRootProps, Prompt, type PromptRootProps, type PromptStatus, RadioGroup, type RadioGroupItemProps, type RadioGroupRootProps, RangeSlider, type RangeSliderRootProps, type RangeSliderThumbProps, Scroll, type ScrollRootProps, type ScrollViewportProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderRootProps, Slot, StatusBanner, type StatusBannerRootProps, type StatusBannerTone, StickyBar, type StickyBarRootProps, Switch, type SwitchRootProps, Tabs, type TabsContentProps, type TabsRootProps, type TabsTriggerProps, ThemeSwitcher, type ThemeSwitcherModeBtnProps, type ThemeSwitcherModesProps, type ThemeSwitcherRootProps, type ThemeSwitcherThemeSelectProps, Thread, type ThreadItemFace, type ThreadItemProps, type ThreadMessageState, type ThreadRootProps, Toast, ToastItem, type ToastPlacement, type ToastProviderProps, type ToastPublishOptions, type ToastRecord, type ToastRootProps, type ToastStore, type ToastViewportProps, Tooltip, type TooltipPositionerProps, type TooltipRootProps, asyncStatusToContentState, useAeonMachine, useAppNav, useAppNavMachine, useAppShellContext, useAsyncContext, useContentContext, useFieldContext, useFileUploadCtx as useFileUpload, useFitText, useLayoutMode, useScrollContext, useScrollState, useStickyBarContext, useToast, useToastStore };
+export { Accordion, type AccordionItemContentProps, type AccordionItemProps, type AccordionItemTriggerProps, type AccordionRootProps, AppNav, type AppNavBreadcrumbProps, type AppNavRootProps, type AppNavSectionProps, AppShell, type AppShellRootProps, Async, AsyncActions, AsyncProvider, AsyncReadout, AsyncRoot, AsyncTrack, Avatar, type AvatarRootProps, type AvatarStatus, Bar, type BarRootProps, Button, type ButtonRootProps, type ButtonStatus, Checkbox, type CheckboxRootProps, Clipboard, type ClipboardIndicatorProps, type ClipboardRootProps, Combobox, type ComboboxItemProps, type ComboboxRootProps, Composer, type ComposerInputProps, type ComposerRootProps, type ComposerState, Content, type ContentRootProps, Conversation, type ConversationItemProps, type ConversationItemState, type ConversationRootProps, Dialog, type DialogPortalProps, type DialogRootProps, Entry, type EntryListProps, type EntryRootProps, type EntryState, Field, type FieldControlProps, type FieldRootProps, type FieldTextareaProps, FileUpload, type FileUploadRootProps, Identity, type IdentityRootProps, ListRow, type ListRowRootProps, Menu, type MenuItemProps, type MenuPositionerProps, type MenuRootProps, MetricStrip, type MetricStripRootProps, Nav, type NavItemProps, type NavRootProps, Panel, type PanelContentProps, type PanelGroupProps, type PanelLabelProps, type PanelRootProps, type PanelTriggerProps, PinInput, type PinInputInputProps, type PinInputRootProps, Popover, type PopoverPositionerProps, type PopoverRootProps, type PresenceState, ProfileHeader, type ProfileHeaderRootProps, Progress, type ProgressRootProps, Prompt, type PromptRootProps, type PromptStatus, Prose, type ProseRootProps, RadioGroup, type RadioGroupItemProps, type RadioGroupRootProps, RangeSlider, type RangeSliderRootProps, type RangeSliderThumbProps, Scroll, type ScrollRootProps, type ScrollViewportProps, SegmentGroup, type SegmentGroupItemProps, type SegmentGroupRootProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderContextValue, type SliderRootProps, Slot, StatusBanner, type StatusBannerRootProps, type StatusBannerTone, StickyBar, type StickyBarRootProps, Switch, type SwitchRootProps, Tabs, type TabsContentProps, type TabsRootProps, type TabsTriggerProps, Textarea, type TextareaRootProps, ThemeSwitcher, type ThemeSwitcherModeBtnProps, type ThemeSwitcherModesProps, type ThemeSwitcherRootProps, type ThemeSwitcherThemeSelectProps, Thread, type ThreadItemFace, type ThreadItemProps, type ThreadMessageState, type ThreadRootProps, Toast, ToastItem, type ToastPlacement, type ToastProviderProps, type ToastPublishOptions, type ToastRecord, type ToastRootProps, type ToastStore, type ToastViewportProps, Tooltip, type TooltipPositionerProps, type TooltipRootProps, type UseWindowedRangeOptions, asyncStatusToContentState, rowLimits, useAeonMachine, useAppNav, useAppNavMachine, useAppShellContext, useAsyncContext, useAutoGrow, useClipboardStatus, useContentContext, useFieldContext, useFileUploadCtx as useFileUpload, useFitText, useLayoutMode, useScrollContext, useScrollState, useSliderContext, useStickyBarContext, useToast, useToastStore, useWindowedRange };