@surrealdb/ui 1.2.12 → 1.2.13

package/dist/ui.d.ts

@@ -6,6 +6,7 @@ import { ButtonProps } from '@mantine/core';
 import { CodeProps } from '@mantine/core';
 import { Command } from '@codemirror/view';
 import { ComponentType } from 'react';
+import { CSSProperties } from 'react';
 import { default as default_2 } from 'github-slugger';
 import { EditorSelection } from '@codemirror/state';
 import { EditorState } from '@codemirror/state';
@@ -24,8 +25,10 @@ import { MantineColor } from '@mantine/core';
 import { MantineColorScheme } from '@mantine/core';
 import { MantineFontSize } from '@mantine/core';
 import { MantineSize } from '@mantine/core';
+import { MantineSpacing } from '@mantine/core';
 import { MantineThemeOverride } from '@mantine/core';
 import { PaperProps } from '@mantine/core';
+import * as portals from 'react-reverse-portal';
 import { PropsWithChildren } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
@@ -413,7 +416,6 @@ export declare interface CodeEditorProps extends BoxProps {
     autoFocus?: boolean;
     innerProps?: BoxProps;
     withPadding?: boolean;
-    ref?: RefObject<EditorView>;
 }
 
 /** React component keyed by lower-cased fenced-code info string. */
@@ -464,6 +466,12 @@ export declare interface ConfirmOptions<T> {
     onConfirm: (value: T) => void;
 }
 
+/**
+ * Open ephemeral overlays that would be covered by `topId` — they should close
+ * instead of staying mounted behind the new top.
+ */
+export declare function coveredEphemeral(items: StackerItem[], topId: string): StackerItem[];
+
 /**
  * Get a cached style highlighter for the given color scheme
  */
@@ -533,6 +541,77 @@ export declare interface DiagramNode {
     children: RailroadNode[];
 }
 
+export declare const Drawer: DrawerCompound;
+
+declare function DrawerBody({ lane, children, className, ...rest }: DrawerBodyProps): ReactNode;
+
+export declare interface DrawerBodyProps extends Omit<BoxProps, "children"> {
+    lane: string;
+    children: ReactNode;
+}
+
+export declare interface DrawerCompound {
+    (props: DrawerProps): ReactNode;
+    Lanes: typeof DrawerLanes;
+    Lane: typeof DrawerLane;
+    Body: typeof DrawerBody;
+}
+
+export declare interface DrawerConfig {
+    lanes: string[];
+    defaultCurrentLane: string;
+    pinnedLane?: string;
+}
+
+/**
+ * Depth transform for a drawer sheet covered by `depth` sheets above it. The
+ * transform-origin sits at the free edge and the sheet is pushed outward, so
+ * scaling never eats the peek strip and lower sheets stick out from behind.
+ */
+export declare function drawerDepthStyle(side: StackerSide, depth: number): CSSProperties;
+
+declare function DrawerLane({ lane, label, icon, className, ...rest }: DrawerLaneProps): ReactNode;
+
+export declare interface DrawerLaneProps extends Omit<BoxProps, "children"> {
+    lane: string;
+    label: string;
+    icon: string;
+    children?: ReactNode;
+}
+
+declare function DrawerLanes({ children, className, ...rest }: DrawerLanesProps): ReactNode;
+
+export declare interface DrawerLanesProps extends Omit<BoxProps, "children"> {
+    children: ReactNode;
+}
+
+export declare interface DrawerProps {
+    children: ReactNode;
+}
+
+export declare function DrawerProvider({ children, state }: DrawerProviderProps): ReactNode;
+
+export declare interface DrawerProviderProps {
+    children: ReactNode;
+    state: DrawerState;
+}
+
+export declare interface DrawerState {
+    open: boolean;
+    currentLane: string;
+    activeLane: string;
+    progress: number;
+    dragging: boolean;
+    translate: number;
+    expandedHeight: number;
+    maxTranslate: number;
+    config: DrawerConfig;
+    dragRef: (node: HTMLDivElement | null) => void;
+    selectLane: (lane: string) => void;
+    collapse: () => void;
+    portal: portals.HtmlPortalNode;
+}
+
 declare type DynamicNode<T> = ReactNode | ((value: T) => ReactNode);
 
 export declare interface EditorController {
@@ -2658,6 +2737,19 @@ export declare function resolveHeadingId(node: SyntaxNode, source: MarkdownSourc
  */
 export declare function resolveImageDescriptor(url: string, alt: string, title?: string, onResolveMedia?: (node: MediaDescriptor) => MediaDescriptor): MediaDescriptor;
 
+/**
+ * Resolve overlay kind from an explicit variant hint or the viewport.
+ */
+export declare function resolveKind(variant: StackerKind | undefined, isMobile: boolean): StackerKind;
+
+/**
+ * Live render kind for the current stack. Empty stacks render nothing. Otherwise:
+ * stack-level `forcedKind` (from the founding overlay's `variant`) → first item's
+ * `variant` → viewport. `forcedKind` keeps a forced kind after the founding
+ * overlay is removed (e.g. ephemeral covered by a push).
+ */
+export declare function resolveLiveKind(items: StackerItem[], isMobile: boolean, forcedKind?: StackerKind | null): StackerKind | null;
+
 /** Normalise a component registration into its `{ component, block, preserveNewlines }` form. */
 export declare function resolveMarkdownComponent(def: MarkdownComponentDef | undefined): MarkdownComponentConfig | undefined;
 
@@ -2998,6 +3090,12 @@ export declare const setMarkdownEditorReady: StateEffectType<boolean>;
  */
 export declare const setMarkdownMode: StateEffectType<MarkdownEditMode>;
 
+/**
+ * Decide whether a released drag should dismiss the drawer: either a fast flick
+ * towards the edge, or dragged past halfway.
+ */
+export declare function shouldDismiss(closeAmount: number, extent: number, towardsVelocity: number): boolean;
+
 export declare function Since({ v, prefix, ...props }: SinceProps): ReactNode;
 
 export declare interface SinceProps extends Omit<BadgeProps, "children"> {
@@ -3116,6 +3214,128 @@ export declare interface SpinnerProps extends BoxProps {
     title?: string;
 }
 
+export declare const STACKER_INITIAL_STATE: StackerState;
+
+export declare type StackerAction = {
+    type: "OPEN";
+    item: StackerItem;
+} | {
+    type: "CLOSE";
+    id: string;
+} | {
+    type: "CLOSE_ALL";
+} | {
+    type: "REMOVE";
+    id: string;
+} | {
+    type: "UPDATE";
+    id: string;
+    patch: Partial<StackerSettings>;
+};
+
+/** Value exposed by {@link useStacker}. */
+export declare interface StackerContextValue {
+    /** Push an overlay onto the stack. Returns the overlay id. */
+    open: (settings?: StackerSettings) => string;
+    /** Close an overlay by id, or the top overlay when the id is omitted. */
+    close: (id?: string) => void;
+    /** Close every open overlay. */
+    closeAll: () => void;
+    /** Merge new settings into an overlay on the stack. */
+    update: (id: string, patch: Partial<StackerSettings>) => void;
+    /** Current stack, ordered bottom-to-top. */
+    stack: StackerItem[];
+    /** Live render kind from the viewport and first stack item, or null when empty. */
+    kind: StackerKind | null;
+}
+
+/** A single entry on the stack. */
+export declare interface StackerItem {
+    id: string;
+    /** False while the overlay plays its exit transition before removal. */
+    opened: boolean;
+    settings: StackerSettings;
+}
+
+/** How an overlay is rendered: a centered modal or an edge-anchored drawer. */
+export declare type StackerKind = "modal" | "drawer";
+
+/**
+ * Provides {@link useStacker}. Overlays render as modals on desktop and drawers
+ * on mobile (or the forced `variant`), stack like Mantine's modal manager, and
+ * the page content scales back slightly while a drawer stack is open.
+ */
+export declare function StackerProvider({ children, mobileQuery, zIndex, }: StackerProviderProps): ReactNode;
+
+export declare interface StackerProviderProps {
+    children?: ReactNode;
+    /** Viewport query selecting the drawer kind. @default "(max-width: 48em)" */
+    mobileQuery?: string;
+    /** Base z-index for the stack. @default 200 */
+    zIndex?: number;
+}
+
+/**
+ * Pure state transitions for the stack. Closing an overlay flips its `opened`
+ * flag (so it can play an exit transition); a later `REMOVE` drops it once the
+ * transition finishes.
+ */
+export declare function stackerReducer(state: StackerState, action: StackerAction): StackerState;
+
+/** Options accepted by {@link StackerContextValue.open}. */
+export declare interface StackerSettings {
+    /** Explicit id. Defaults to a random id. Opening an id already on the stack is a no-op. */
+    id?: string;
+    /** Heading rendered in the overlay header. */
+    title?: ReactNode;
+    /** Secondary text rendered underneath the title. */
+    subtitle?: ReactNode;
+    /** Overlay body content. */
+    children?: ReactNode;
+    /**
+     * Force this overlay kind instead of choosing from the viewport. When set on
+     * the founding overlay of a stack, the kind is remembered for the whole stack
+     * even if that overlay is later removed (e.g. ephemeral). Later items' hints
+     * are ignored while the stack is non-empty.
+     */
+    variant?: StackerKind;
+    /** Edge the drawer is anchored to. Ignored for modals. @default "right" */
+    side?: StackerSide;
+    /** Allow dragging the drawer towards its edge to dismiss it. Ignored for modals. @default false */
+    draggable?: boolean;
+    /** Content area size — modal width or drawer extent. Defaults: modal `"lg"`, drawer `"md"`. */
+    size?: MantineSize | (string & {}) | number;
+    /** Header/body padding. @default "xl" */
+    padding?: MantineSpacing;
+    /** Render the header close button. @default true */
+    withCloseButton?: boolean;
+    /** Close this overlay with Escape while it is on top. @default true */
+    closeOnEscape?: boolean;
+    /** Close this overlay by clicking the scrim while it is on top. @default true */
+    closeOnClickOutside?: boolean;
+    /**
+     * When true, this overlay is closed (and removed after its exit) as soon as
+     * another overlay is pushed on top of it — it never stays covered/peeking.
+     * @default false
+     */
+    ephemeral?: boolean;
+    /** Called when the overlay begins closing. */
+    onClose?: () => void;
+}
+
+/** Edge a drawer is anchored to. */
+export declare type StackerSide = "left" | "right" | "top" | "bottom";
+
+export declare interface StackerState {
+    /**
+     * Forced kind from the stack-founding overlay's `variant`. Survives removal of
+     * that overlay (e.g. ephemeral covered) until the stack is empty.
+     */
+    forcedKind: StackerKind | null;
+    /** Stack entries, ordered bottom-to-top. `opened: false` = playing exit. */
+    items: StackerItem[];
+}
+
 export declare type StateFields = {
     [prop: string]: StateField<any>;
 };
@@ -3221,6 +3441,9 @@ export declare interface ThemedImageProps extends ImageProps {
     darkSrc?: string;
 }
 
+/** The top-most open item, or undefined when nothing is open. */
+export declare function topOpened(items: StackerItem[]): StackerItem | undefined;
+
 /** Trim `{#id}` from the end of a heading source range (returns new exclusive `titleTo`). */
 export declare function trimCustomHeadingIdFromRange(source: {
     slice(from: number, to: number): string;
@@ -3234,6 +3457,10 @@ export declare function trimCustomHeadingIdFromRange(source: {
  */
 export declare function useConfirmation<T = void>(options: ConfirmOptions<T>): (value?: T) => void;
 
+export declare function useDrawer(config: DrawerConfig): DrawerState;
+
+export declare function useDrawerState(): DrawerState;
+
 export declare function useEditor(options?: EditorOptions): EditorController;
 
 /**
@@ -3285,6 +3512,12 @@ export declare function useSort<T = DefaultSort>(options?: SortOptions<T>): Sort
  */
 export declare function useStable<T extends AnyFn>(callback: T): T;
 
+/**
+ * Access the nearest {@link StackerProvider}. Multiple providers can be nested;
+ * each hook call resolves to the closest one.
+ */
+export declare function useStacker(): StackerContextValue;
+
 /**
  * A state used to track an active/inactive switch state (boolean)
  *