aeon-ui-engine 1.9.0 → 1.10.0

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

@@ -4,7 +4,7 @@ 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';
+import { AsyncContext, ContentRegionState, AppNavChild, StickyBarState, AnySlices, AeonStore, QueryOf, QueryResult, EntityOf, StoreState } from '@aeon-ui/primitives';
 export { AppNavChild, AppNavContext, createAsyncMachine, fieldMachine } from '@aeon-ui/primitives';
 import { fieldFace, ListWindowAxis, ListWindow, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
 export { AeonColorMode as AeonMode } from '@aeon-ui/core';
@@ -1282,6 +1282,15 @@ declare const StickyBar: {
     Seam: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
+/**
+ * Reads a slice of an Aeon store. Re-renders only when the selected value
+ * changes under `equals` (shallow by default), so a component that selects
+ * one entity ignores writes to every other.
+ */
+declare function useAeonSelector<S extends AnySlices, T>(store: AeonStore<S>, selector: (state: StoreState<S>) => T, equals?: (a: T, b: T) => boolean): T;
+/** Fetches a query while mounted and returns its result; the entities stay in the store. */
+declare function useAeonQuery<S extends AnySlices, N extends keyof S & string>(store: AeonStore<S>, slice: N, query: QueryOf<S[N]>): QueryResult<EntityOf<S[N]>>;
+
 declare function useLayoutMode(spec: ResponsiveLayoutSpec): {
     mode: LayoutMode;
     composition: LayoutCompositionSpec;
@@ -1307,4 +1316,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, 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 };
+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, useAeonQuery, useAeonSelector, useAppNav, useAppNavMachine, useAppShellContext, useAsyncContext, useAutoGrow, useClipboardStatus, useContentContext, useFieldContext, useFileUploadCtx as useFileUpload, useFitText, useLayoutMode, useScrollContext, useScrollState, useSliderContext, useStickyBarContext, useToast, useToastStore, useWindowedRange };

package/packages/react/dist/index.js

@@ -6218,13 +6218,40 @@ var StickyBar = {
   Seam
 };
 
+// src/hooks/use-aeon-store.ts
+import { useEffect as useEffect27, useRef as useRef15, useSyncExternalStore } from "react";
+import {
+  shallowEqual
+} from "@aeon-ui/primitives";
+function useAeonSelector(store, selector, equals = shallowEqual) {
+  const held = useRef15(null);
+  const getSelection = () => {
+    const state = store.getSnapshot();
+    const last = held.current;
+    if (last && last.state === state && last.selector === selector) return last.value;
+    const next = selector(state);
+    const value = last && equals(last.value, next) ? last.value : next;
+    held.current = { state, selector, value };
+    return value;
+  };
+  return useSyncExternalStore(store.subscribe, getSelection, getSelection);
+}
+function useAeonQuery(store, slice, query) {
+  const key = typeof query === "string" ? query : JSON.stringify(query);
+  useEffect27(() => {
+    store.send({ type: "QUERY.FETCH", slice, query });
+  }, [store, slice, key]);
+  const read = () => store.query(slice, query);
+  return useSyncExternalStore(store.subscribe, read, read);
+}
+
 // src/hooks/use-layout-mode.ts
 import { getCompactMq, layoutCompositionForMode, matchLayoutMode } from "@aeon-ui/core";
-import { useEffect as useEffect27, useMemo as useMemo32, useState as useState14 } from "react";
+import { useEffect as useEffect28, useMemo as useMemo32, useState as useState14 } from "react";
 function useLayoutMode(spec) {
   const mq = useMemo32(() => getCompactMq(spec), [spec.compactMq]);
   const [mode, setMode] = useState14(() => matchLayoutMode(spec, mq));
-  useEffect27(() => {
+  useEffect28(() => {
     const sync = () => setMode(matchLayoutMode(spec, mq));
     sync();
     mq.addEventListener("change", sync);
@@ -6330,6 +6357,8 @@ export {
   fieldMachine,
   rowLimits,
   useAeonMachine,
+  useAeonQuery,
+  useAeonSelector,
   useAppNav,
   useAppNavMachine,
   useAppShellContext,

package/packages/react/src/hooks/use-aeon-store.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useSyncExternalStore } from 'react'
+import {
+  shallowEqual,
+  type AeonStore,
+  type AnySlices,
+  type EntityOf,
+  type QueryOf,
+  type QueryResult,
+  type StoreEvent,
+  type StoreState,
+} from '@aeon-ui/primitives'
+
+/**
+ * Reads a slice of an Aeon store. Re-renders only when the selected value
+ * changes under `equals` (shallow by default), so a component that selects
+ * one entity ignores writes to every other.
+ */
+export function useAeonSelector<S extends AnySlices, T>(
+  store: AeonStore<S>,
+  selector: (state: StoreState<S>) => T,
+  equals: (a: T, b: T) => boolean = shallowEqual,
+): T {
+  const held = useRef<{ state: StoreState<S>; selector: (state: StoreState<S>) => T; value: T } | null>(null)
+  const getSelection = () => {
+    const state = store.getSnapshot()
+    const last = held.current
+    if (last && last.state === state && last.selector === selector) return last.value
+    const next = selector(state)
+    const value = last && equals(last.value, next) ? last.value : next
+    held.current = { state, selector, value }
+    return value
+  }
+  return useSyncExternalStore(store.subscribe, getSelection, getSelection)
+}
+
+/** Fetches a query while mounted and returns its result; the entities stay in the store. */
+export function useAeonQuery<S extends AnySlices, N extends keyof S & string>(
+  store: AeonStore<S>,
+  slice: N,
+  query: QueryOf<S[N]>,
+): QueryResult<EntityOf<S[N]>> {
+  const key = typeof query === 'string' ? query : JSON.stringify(query)
+  useEffect(() => {
+    store.send({ type: 'QUERY.FETCH', slice, query } as StoreEvent<S>)
+    // `key` stands for `query`, which callers often rebuild each render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, slice, key])
+  const read = () => store.query(slice, query)
+  return useSyncExternalStore(store.subscribe, read, read)
+}

package/packages/react/src/index.ts

@@ -44,6 +44,7 @@ export * from './content/index.js'
 export * from './nav/index.js'
 export * from './sticky-bar/index.js'
 export { useAeonMachine } from './hooks/use-aeon-machine.js'
+export { useAeonQuery, useAeonSelector } from './hooks/use-aeon-store.js'
 export { useLayoutMode } from './hooks/use-layout-mode.js'
 export { useFitText } from './hooks/use-fit-text.js'
 export { Slot } from './utils/slot.js'