aeon-ui-engine 1.1.0 → 1.3.0

package/packages/primitives/src/machines/app-nav.ts

@@ -0,0 +1,107 @@
+import { assign, setup } from 'xstate'
+
+/**
+ * Section + detail stack navigation — the pattern every multi-panel product
+ * reinvented (wallet sections, settings drill-in, list→detail).
+ *
+ * Not product-specific: `section` is a string id; `stack` is opaque child records.
+ */
+export type AppNavChild = {
+  id: string
+  /** Free-form type tag (e.g. "detail", "compose", "settings"). */
+  type: string
+  /** Optional payload for the view layer. */
+  data?: unknown
+}
+
+export interface AppNavContext {
+  section: string
+  stack: AppNavChild[]
+}
+
+export type AppNavEvent =
+  | { type: 'SET_SECTION'; section: string }
+  | { type: 'PUSH'; child: AppNavChild }
+  | { type: 'REPLACE'; child: AppNavChild }
+  | { type: 'POP' }
+  | { type: 'POP_TO'; id: string }
+  | { type: 'CLEAR' }
+  | { type: 'RESET'; section: string }
+
+export function appNavDepth(ctx: AppNavContext): number {
+  return ctx.stack.length
+}
+
+export function appNavChild(ctx: AppNavContext): AppNavChild | null {
+  return ctx.stack.length ? ctx.stack[ctx.stack.length - 1]! : null
+}
+
+/** Projected state for data-aeon-state: `section` or `section/childType`. */
+export function appNavStateAttr(ctx: AppNavContext): string {
+  const child = appNavChild(ctx)
+  return child ? `${ctx.section}/${child.type}` : ctx.section
+}
+
+export const appNavMachine = setup({
+  types: {
+    context: {} as AppNavContext,
+    events: {} as AppNavEvent,
+    input: {} as Partial<AppNavContext> & { section?: string },
+  },
+  actions: {
+    setSection: assign({
+      section: ({ event }) => (event.type === 'SET_SECTION' ? event.section : ''),
+      stack: [],
+    }),
+    push: assign({
+      stack: ({ context, event }) =>
+        event.type === 'PUSH' ? [...context.stack, event.child] : context.stack,
+    }),
+    replace: assign({
+      stack: ({ context, event }) => {
+        if (event.type !== 'REPLACE') return context.stack
+        if (!context.stack.length) return [event.child]
+        return [...context.stack.slice(0, -1), event.child]
+      },
+    }),
+    pop: assign({
+      stack: ({ context }) => context.stack.slice(0, -1),
+    }),
+    popTo: assign({
+      stack: ({ context, event }) => {
+        if (event.type !== 'POP_TO') return context.stack
+        const idx = context.stack.findIndex((c) => c.id === event.id)
+        if (idx < 0) return context.stack
+        return context.stack.slice(0, idx + 1)
+      },
+    }),
+    clear: assign({ stack: [] }),
+    reset: assign({
+      section: ({ event }) => (event.type === 'RESET' ? event.section : ''),
+      stack: [],
+    }),
+  },
+  guards: {
+    canPop: ({ context }) => context.stack.length > 0,
+  },
+}).createMachine({
+  id: 'appNav',
+  context: ({ input }) => ({
+    section: input?.section ?? 'home',
+    stack: input?.stack ?? [],
+  }),
+  initial: 'ready',
+  states: {
+    ready: {
+      on: {
+        SET_SECTION: { actions: 'setSection' },
+        PUSH: { actions: 'push' },
+        REPLACE: { actions: 'replace' },
+        POP: { guard: 'canPop', actions: 'pop' },
+        POP_TO: { actions: 'popTo' },
+        CLEAR: { actions: 'clear' },
+        RESET: { actions: 'reset' },
+      },
+    },
+  },
+})

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

@@ -3,8 +3,8 @@ import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, L
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as xstate from 'xstate';
 import { AnyStateMachine } from 'xstate';
-import { AsyncContext, ContentRegionState, StickyBarState } from '@aeon-ui/primitives';
-export { createAsyncMachine, fieldMachine } from '@aeon-ui/primitives';
+import { AsyncContext, ContentRegionState, AppNavChild, StickyBarState } from '@aeon-ui/primitives';
+export { AppNavChild, AppNavContext, createAsyncMachine, fieldMachine } from '@aeon-ui/primitives';
 import { useMachine } from '@xstate/react';
 import { fieldFace, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
 export { AeonColorMode as AeonMode } from '@aeon-ui/core';
@@ -81,6 +81,51 @@ declare const Dialog: {
     CloseTrigger: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
 };
 
+type PromptStatus = 'pending' | 'confirming' | 'dismissed' | 'confirmed';
+interface PromptRootProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Projected onto data-aeon-state (default: pending when open). */
+    status?: PromptStatus;
+    children?: ReactNode;
+    className?: string;
+}
+declare const Prompt: {
+    Root: react.ForwardRefExoticComponent<PromptRootProps & react.RefAttributes<HTMLDivElement>>;
+    Trigger: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+    Portal: react.ForwardRefExoticComponent<DialogPortalProps & react.RefAttributes<HTMLDivElement>>;
+    Backdrop: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Positioner: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Content: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Title: react.ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & react.RefAttributes<HTMLHeadingElement>>;
+    Description: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
+    CloseTrigger: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+    Eyebrow: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
+    Meta: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDListElement> & react.RefAttributes<HTMLDListElement>>;
+    Amount: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Actions: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Primary: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+    Secondary: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+};
+
+type StatusBannerTone = 'info' | 'success' | 'warning' | 'danger';
+interface StatusBannerRootProps extends HTMLAttributes<HTMLDivElement> {
+    tone?: StatusBannerTone;
+    /** Machine-ish status string projected to data-aeon-state (e.g. ready, downloading). */
+    status?: string;
+    children?: ReactNode;
+}
+/** Non-blocking top-of-app notice (updates, sync, offline). */
+declare const StatusBanner: {
+    Root: react.ForwardRefExoticComponent<StatusBannerRootProps & react.RefAttributes<HTMLDivElement>>;
+    Copy: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Title: react.ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & react.RefAttributes<HTMLElement>>;
+    Body: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
+    Actions: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Action: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+};
+
 interface TabsRootProps {
     value?: string;
     defaultValue?: string;
@@ -861,6 +906,81 @@ declare const AppShell: {
     Scrim: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
+interface AppNavContextValue {
+    section: string;
+    stack: AppNavChild[];
+    child: AppNavChild | null;
+    stateAttr: string;
+    send: ReturnType<typeof useAeonMachine<typeof appNavMachine>>[1];
+    setSection: (section: string) => void;
+    push: (child: AppNavChild) => void;
+    replace: (child: AppNavChild) => void;
+    pop: () => void;
+    popTo: (id: string) => void;
+    clear: () => void;
+}
+declare function useAppNav(): AppNavContextValue;
+/** Use the machine without the compound tree. */
+declare function useAppNavMachine(input?: {
+    section?: string;
+    stack?: AppNavChild[];
+}): {
+    section: string;
+    stack: AppNavChild[];
+    child: AppNavChild | null;
+    stateAttr: string;
+    send: (event: {
+        type: "SET_SECTION";
+        section: string;
+    } | {
+        type: "PUSH";
+        child: AppNavChild;
+    } | {
+        type: "REPLACE";
+        child: AppNavChild;
+    } | {
+        type: "POP";
+    } | {
+        type: "POP_TO";
+        id: string;
+    } | {
+        type: "CLEAR";
+    } | {
+        type: "RESET";
+        section: string;
+    }) => void;
+    setSection: (next: string) => void;
+    push: (next: AppNavChild) => void;
+    replace: (next: AppNavChild) => void;
+    pop: () => void;
+    popTo: (id: string) => void;
+    clear: () => void;
+    reset: (next: string) => void;
+};
+interface AppNavRootProps extends HTMLAttributes<HTMLDivElement> {
+    defaultSection?: string;
+    children?: ReactNode;
+}
+interface AppNavSectionProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    value: string;
+}
+interface AppNavBreadcrumbProps extends HTMLAttributes<HTMLElement> {
+    /** Labels for section + each stack entry (length = 1 + stack.length). */
+    labels?: string[];
+}
+/**
+ * AppNav — section rail + detail stack.
+ * Machine: SET_SECTION / PUSH / POP / CLEAR. UI = f(section, stack).
+ */
+declare const AppNav: {
+    Root: react.ForwardRefExoticComponent<AppNavRootProps & react.RefAttributes<HTMLDivElement>>;
+    Rail: react.ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & react.RefAttributes<HTMLElement>>;
+    Section: react.ForwardRefExoticComponent<AppNavSectionProps & react.RefAttributes<HTMLButtonElement>>;
+    Stage: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+    Breadcrumb: react.ForwardRefExoticComponent<AppNavBreadcrumbProps & react.RefAttributes<HTMLElement>>;
+    Back: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+};
+
 interface ContentContextValue {
     state: ContentRegionState;
     error: string | null;
@@ -948,4 +1068,16 @@ declare function useLayoutMode(spec: ResponsiveLayoutSpec): {
     composition: LayoutCompositionSpec;
 };
 
-export { Accordion, type AccordionItemContentProps, type AccordionItemProps, type AccordionItemTriggerProps, type AccordionRootProps, 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, 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, RadioGroup, type RadioGroupItemProps, type RadioGroupRootProps, Scroll, type ScrollRootProps, type ScrollViewportProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderRootProps, StickyBar, type StickyBarRootProps, Switch, type SwitchRootProps, Tabs, type TabsContentProps, type TabsRootProps, type TabsTriggerProps, ThemeSwitcher, type ThemeSwitcherModeBtnProps, type ThemeSwitcherModesProps, type ThemeSwitcherRootProps, type ThemeSwitcherThemeSelectProps, Thread, 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, useAppShellContext, useAsyncContext, useContentContext, useFieldContext, useLayoutMode, useScrollContext, useScrollState, useStickyBarContext, useToast, useToastStore };
+type FitTextOptions = {
+    maxPx?: number;
+    minPx?: number;
+    /** Re-run when this value changes (e.g. display string). */
+    watch?: unknown;
+};
+/**
+ * Shrink font-size (then scale) so `contentRef` fits inside `slotRef`
+ * without expanding parent layout. Universal for balance rows, titles, tickers.
+ */
+declare function useFitText(slotRef: RefObject<HTMLElement | null>, contentRef: RefObject<HTMLElement | null>, opts?: FitTextOptions): void;
+
+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, 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, Scroll, type ScrollRootProps, type ScrollViewportProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderRootProps, 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 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, useFitText, useLayoutMode, useScrollContext, useScrollState, useStickyBarContext, useToast, useToastStore };