message-scroller headless API

declare function connectMessageScroller(service: MessageScrollerService, scope: PartScope, options?: MessageScrollerConnectOptions): MessageScrollerApi;

declare function createMessageScrollerController(host: MessageScrollerControllerHost, initialOptions?: MessageScrollerControllerOptions): MessageScrollerController;

export declare const MESSAGE_SCROLLER_JUMP_DELAY_MS: 260;

export declare const MESSAGE_SCROLLER_JUMP_KEY: "message-scroller.jump";

export declare const messageScrollerAnatomy: {
  readonly scope: "message-scroller";
  readonly parts: readonly ["root", "viewport", "content", "item", "spacer", "button"];
};

interface MessageScrollerApi {
  rootProps(): PartProps;
  viewportProps(): PartProps;
  contentProps(): PartProps;
  itemProps(id: string, scrollAnchor?: boolean): PartProps;
  spacerProps(): PartProps;
  buttonProps(): PartProps;
  readonly following: boolean;
  readonly anchored: boolean;
  readonly jumping: boolean;
  readonly anchorId: string | null;
  readonly label: string;
  readonly busy: boolean;
}

type MessageScrollerCommand = (CommandObject & {
  readonly type: "SCROLL_TO";
  readonly target: MessageScrollerScrollTarget;
  readonly behavior: MessageScrollerScrollBehavior;
}) | (CommandObject & {
  readonly type: "PRESERVE_PREPEND";
}) | (CommandObject & {
  readonly type: "CLEAR_SPACER";
}) | (CommandObject & {
  readonly type: "REANCHOR";
}) | ScheduleCommand<MessageScrollerEvent> | CancelCommand;

interface MessageScrollerConnectOptions {
  readonly label?: string;
  readonly busy?: boolean;
  readonly buttonDirection?: "start" | "end";
  readonly getScrollable?: () => MessageScrollerScrollable;
}

type MessageScrollerContext = {
  readonly jumping: boolean;
  readonly anchorId: string | null;
  readonly defaultApplied: boolean;
  readonly pendingJumpId: string | null;
};

interface MessageScrollerController {
  readonly observerCount: () => number;
  readonly listenerCount: () => number;
  attach(service: MessageScrollerService): void;
  ensureStarted(service: MessageScrollerService): void;
  destroy(): void;
  refresh(): void;
  scrollToEnd(options?: MessageScrollerScrollOptions): boolean;
  scrollToMessage(messageId: string, options?: MessageScrollerScrollOptions): boolean;
  scrollToStart(options?: MessageScrollerScrollOptions): boolean;
  update(options: MessageScrollerControllerOptions): void;
  applyScroll(target: MessageScrollerScrollTarget, behavior: MessageScrollerScrollBehavior): void;
  applyPreservePrepend(): void;
  clearSpacer(): void;
  applyReanchor(): void;
}

interface MessageScrollerControllerHost {
  readonly getRoot: () => HTMLElement | null;
  readonly getViewport: () => HTMLElement | null;
  readonly getContent: () => HTMLElement | null;
  readonly matchMedia?: (query: string) => {
    readonly matches: boolean;
  };
  readonly createMutationObserver?: (callback: MutationCallback) => MessageScrollerObserverLike & {
    observe(target: Node, options?: MutationObserverInit): void;
  };
  readonly createResizeObserver?: (callback: ResizeObserverCallback) => MessageScrollerObserverLike;
  readonly createIntersectionObserver?: (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => MessageScrollerObserverLike;
  readonly requestAnimationFrame?: (callback: FrameRequestCallback) => number;
  readonly cancelAnimationFrame?: (handle: number) => void;
  readonly getSelection?: () => Selection | null;
  readonly elementsFromPoint?: (x: number, y: number) => Element[];
}

interface MessageScrollerControllerOptions {
  autoScroll?: boolean;
  defaultScrollPosition?: MessageScrollerDefaultScrollPosition;
  preserveScrollOnPrepend?: boolean;
  scrollEdgeThreshold?: number;
  scrollMargin?: number;
  scrollPreviousItemPeek?: number;
  onScrollableChange?: (state: MessageScrollerScrollable) => void;
  onVisibilityChange?: (state: MessageScrollerVisibility) => void;
}

type MessageScrollerEvent = {
  readonly type: "USER_RELEASE";
} | {
  readonly type: "SCROLL_REPORT";
  readonly atEnd: boolean;
} | {
  readonly type: "PREPEND";
} | {
  readonly type: "APPLY_DEFAULT";
  readonly action: "start" | "end" | "anchor";
  readonly anchorId?: string;
} | {
  readonly type: "APPEND";
  readonly newAnchorId: string | null;
  readonly newAnchorCount: number;
} | {
  readonly type: "ANCHOR";
  readonly id: string;
} | {
  readonly type: "FOLLOW_END";
} | {
  readonly type: "JUMP_START";
  readonly behavior: MessageScrollerScrollBehavior;
} | {
  readonly type: "JUMP_END";
  readonly behavior: MessageScrollerScrollBehavior;
} | {
  readonly type: "JUMP_MESSAGE";
  readonly messageId: string;
  readonly found: boolean;
  readonly rowsMounted: boolean;
  readonly alreadyVisible: boolean;
  readonly behavior: MessageScrollerScrollBehavior;
  readonly align?: MessageScrollerScrollAlign;
  readonly scrollMargin?: number;
} | {
  readonly type: "JUMP_COMPLETE";
} | {
  readonly type: "REANCHOR_REQUEST";
} | {
  readonly type: "ANCHOR_LOST";
} | {
  readonly type: "REANCHOR_RELEASED";
} | {
  readonly type: "RESIZE";
} | {
  readonly type: "AUTO_SCROLL_EDGE";
  readonly atEnd: boolean;
} | {
  readonly type: "STOP";
};

type MessageScrollerInput = {
  readonly autoScroll?: boolean;
  readonly defaultScrollPosition?: MessageScrollerDefaultScrollPosition;
  readonly preserveScrollOnPrepend?: boolean;
  /** Presentation-only. The machine ignores it. @default "Messages" */
  readonly label?: string;
  /** Presentation-only. The machine ignores it. @default false */
  readonly busy?: boolean;
  /** Presentation-only. The machine ignores it. @default "end" */
  readonly buttonDirection?: "start" | "end";
};

export declare const messageScrollerMachine: MessageScrollerMachine;

interface MessageScrollerMount {
  readonly service: MessageScrollerService;
  readonly connector: MessageScrollerApi;
  readonly controller: MessageScrollerController;
  readonly root: HTMLElement;
  readonly viewport: HTMLElement;
  readonly content: HTMLElement;
  destroy(): void;
}

interface MessageScrollerObserverLike {
  observe(target: Element): void;
  disconnect(): void;
}

type MessageScrollerPart = (typeof messageScrollerAnatomy.parts)[number];

type MessageScrollerScrollable = {
  readonly start: boolean;
  readonly end: boolean;
};

interface MessageScrollerScrollOptions {
  align?: MessageScrollerScrollAlign;
  behavior?: ScrollBehavior | "instant";
  scrollMargin?: number;
}

export declare const messageScrollerSelectors: {
  following: (snapshot: MessageScrollerSnapshot) => boolean;
  anchored: (snapshot: MessageScrollerSnapshot) => boolean;
  idle: (snapshot: MessageScrollerSnapshot) => boolean;
  jumping: (snapshot: MessageScrollerSnapshot) => boolean;
  anchorId: (snapshot: MessageScrollerSnapshot) => string | null;
  pendingJumpId: (snapshot: MessageScrollerSnapshot) => string | null;
  defaultApplied: (snapshot: MessageScrollerSnapshot) => boolean;
};

type MessageScrollerService = Service<MessageScrollerInput, MessageScrollerStateValue, MessageScrollerContext, MessageScrollerEvent, MessageScrollerCommand>;

type MessageScrollerSnapshot = Snapshot<MessageScrollerStateValue, MessageScrollerContext>;

type MessageScrollerStateValue = "idle" | "following" | "anchored";

declare function mountMessageScroller(container: HTMLElement, options?: MountMessageScrollerOptions): MessageScrollerMount;

interface MountMessageScrollerOptions extends MessageScrollerInput, Omit<MessageScrollerControllerOptions, keyof MessageScrollerInput> {
  readonly scheduler?: Scheduler;
  readonly host?: Partial<Omit<MessageScrollerControllerHost, "getRoot" | "getViewport" | "getContent">>;
  readonly label?: string;
  readonly busy?: boolean;
  readonly buttonDirection?: "start" | "end";
  readonly showButton?: boolean;
  readonly messages?: ReadonlyArray<{
    readonly id: string;
    readonly content: string;
    readonly scrollAnchor?: boolean;
  }>;
}

declare function runMessageScrollerCommand(command: MessageScrollerCommand, _scope: PartScope, options?: {
  readonly controller?: Pick<MessageScrollerController, "applyScroll" | "applyPreservePrepend" | "clearSpacer" | "applyReanchor">;
}): void;