@yaebal/morda

pnpm add @yaebal/morda

import { Bot } from "@yaebal/core";
import { dialogs, switchTo, back, button, url } from "@yaebal/morda";

const bot = new Bot(process.env.BOT_TOKEN!)
  .install(dialogs({
    main: () => ({
      text: "main menu",
      keyboard: [
        [switchTo("settings →", "settings")],
        [button("ping", { id: "ping", onClick: (ctx) => ctx.answerCallbackQuery({ text: "pong" }) })],
        [url("docs", "https://example.com")],
      ],
    }),
    settings: () => ({
      text: "settings",
      keyboard: [[back("← back")]],
    }),
  }));

// window ids are typed: start("mian") is a compile error
bot.command("menu", (ctx) => ctx.dialog.start("main"));
bot.start();

// ctx.dialog is available on every update after .install(dialogs(...))

// open a fresh dialog (closes any previous one, sends a new message)
await ctx.dialog.start("main", { params: { orderId: 42 }, data: { step: 1 } });

// push a window onto the stack (edits the message); params land in frame.params
await ctx.dialog.push("confirm", { orderId: 42 });

// replace the top window without growing the stack
await ctx.dialog.replace("done");

// pop one window; the result (if any) reaches the parent window's onResult.
// at the root this closes the dialog (message deleted, state dropped)
await ctx.dialog.back("2026-07-08");

// close the whole dialog from anywhere
await ctx.dialog.close();

// re-render right now / schedule one re-render after the handler
await ctx.dialog.rerender();
ctx.dialog.invalidate();

// the dialog-wide data bag (persisted; every window's render sees frame.data)
await ctx.dialog.update({ dark: true });   // merge + re-render
await ctx.dialog.setData({ dark: true });  // merge only
const data = await ctx.dialog.getData();   // read (undefined when closed)

import { dialogs } from "@yaebal/morda";
import { format, bold } from "@yaebal/core";

bot.install(dialogs({
  // a window is a render function…
  main: (ctx, frame) => ({
    text: format`hello ${bold(ctx.from?.first_name ?? "there")}`, // entities flow to the wire
    keyboard: [[switchTo("ask →", "ask")]],
  }),

  // …or a full def with lifecycle + free-text input
  ask: {
    render: (ctx, frame) => ({
      text: frame.data.name ? `hi, ${frame.data.name}!` : "what's your name?",
    }),
    onText: (ctx) => ctx.dialog.update({ name: ctx.text }), // commands are never routed here
    onEnter: (ctx, frame) => {},          // pushed / replaced in
    onLeave: (ctx, frame) => {},          // popped / replaced out / dialog closed
    onResult: (ctx, result, frame) => {}, // a child window's back(result)
  },

  // media windows: text becomes the caption; media↔text transitions are
  // handled for you (delete + resend where telegram refuses to edit)
  photo: () => ({
    text: "caption",
    media: { type: "photo", media: "<file_id or url or media.file(...)>" },
  }),
}));

import { defineDialog, dialogs } from "@yaebal/morda";
import { session } from "@yaebal/session";
import type { Context } from "@yaebal/core";

type BotContext = Context & { session: { name: string } };

// curried, so the window map keeps its literal ids while the context stays explicit
const def = defineDialog<BotContext>()({
  profile: {
    render: (ctx) => ({ text: `hi ${ctx.session.name}` }), // typed — no casts
    onText: (ctx) => {
      ctx.session.name = ctx.text;
      return ctx.dialog.rerender();
    },
  },
});

bot
  .install(session({ initial: () => ({ name: "anon" }) }))
  .install(dialogs(def)); // installing where session is missing = compile error

import { dialogs, type DialogState } from "@yaebal/morda";
import { redisStorage } from "@yaebal/sklad";
import Redis from "ioredis"; // or `createClient` from "redis" — both fit structurally

// any @yaebal/sklad StorageAdapter works — redis/sqlite/cloudflare-kv/file survive
// restarts and share dialog state across horizontally-scaled instances
const storage = redisStorage<DialogState>(new Redis(), { prefix: "bot:dialog:" });

bot.install(dialogs(def, {
  storage,                        // default: in-memory (dev only)
  prefix: "shop",                 // callback namespace — unique per install
  getKey: (ctx) => `${ctx.chat?.id}`, // default: chat id, chat:user in groups
  access: (ctx) => ctx.from?.id === ADMIN_ID, // gate who may press buttons
  maxStack: 32,                   // navigation depth cap
  events: {
    onStale: (ctx) => ctx.answerCallbackQuery({ text: "this menu expired" }),
    onAccessDenied: (ctx) => ctx.answerCallbackQuery({ text: "not for you" }),
    onClose: (ctx, result) => {}, // dialog fully closed
  },
}));

import { createDialogs } from "@yaebal/morda";

const { plugin, background } = createDialogs(def, { storage });
bot.install(plugin);

// later — from a timer, queue worker, or webhook, with no incoming update:
const control = await background(bot.api, String(chatId)); // key = getKey's value
if (control) {
  await control.update({ price: 42 }); // merge data + edit the message in place
  await control.push("alert");         // or navigate
}

// tsconfig.json — point the compiler at morda's jsx transform
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@yaebal/morda"
  }
}

/** @jsxImportSource @yaebal/morda */
import { Bot } from "@yaebal/core";
import {
  jsxDialogs,
  Screen, ButtonRow, Button, Url,
  useState, useNavigation,
} from "@yaebal/morda/jsx";

function SettingsScreen() {
  const nav = useNavigation();
  return (
    <Screen>
      Settings page
      <ButtonRow>
        <Button id="back" onClick={() => nav.back()}>← back</Button>
      </ButtonRow>
    </Screen>
  );
}

function MainScreen() {
  const [count, setCount] = useState(0);
  const nav = useNavigation();

  return (
    <Screen>
      {`you tapped ${count} time(s)`}
      <ButtonRow>
        <Button id="tap" onClick={() => setCount((n) => n + 1)}>tap</Button>
        <Button id="settings" onClick={() => nav.push(SettingsScreen)}>settings</Button>
      </ButtonRow>
      <ButtonRow>
        <Url url="https://example.com">docs</Url>
      </ButtonRow>
    </Screen>
  );
}

const bot = new Bot(process.env.BOT_TOKEN!)
  .install(jsxDialogs({ main: MainScreen, settings: SettingsScreen }));

bot.command("menu", (ctx) => ctx.dialog.start("main"));
bot.start();

/** @jsxImportSource @yaebal/morda */
import {
  Screen, ButtonRow, Button,
  useState, useEffect, useNavigation, useParams, useDialogData, useUser,
} from "@yaebal/morda/jsx";

function ProfileScreen() {
  const user = useUser();
  const { userId } = useParams<{ userId: number }>();   // from nav.push(Profile, { userId })
  const [data, patch] = useDialogData<{ theme?: string }>(); // dialog-wide bag
  const [profile, setProfile] = useState<Profile | null>(null);

  // effects run AFTER the render is delivered, so the load-then-show
  // pattern works: the screen shows "loading…", then edits itself.
  useEffect(() => {
    loadProfile(userId).then(setProfile);
  }, [userId]);

  return (
    <Screen onText={(ctx) => patch({ theme: ctx.text })}>
      {profile ? `${profile.name} (${data.theme ?? "light"})` : "loading…"}
      <ButtonRow>
        <Button id="hi">{`hello ${user?.first_name ?? "?"}`}</Button>
      </ButtonRow>
    </Screen>
  );
}

/** @jsxImportSource @yaebal/morda */
import { Screen, Counter, Toggle, Select, Pagination, useState } from "@yaebal/morda/jsx";

function SettingsScreen() {
  const [page, setPage] = useState(1);
  return (
    <Screen>
      settings
      <Counter id="volume" min={0} max={10} />
      <Toggle id="dark">dark mode</Toggle>
      <Select
        id="lang"
        items={[{ code: "en", name: "english" }, { code: "ru", name: "русский" }]}
        itemId={(l) => l.code}
        label={(l) => l.name}
        columns={2}
      />
      <Pagination id="p" page={page} pages={5} onPage={setPage} />
    </Screen>
  );
}

import { Composer, Context } from "@yaebal/core";
import { MemoryStorage } from "@yaebal/session";
import { dialogs, type DialogState } from "@yaebal/morda";

// morda talks to telegram only through api.call — a structural fake records
// every call, and callback_data can be read straight off the recorded keyboard
const storage = new MemoryStorage<DialogState>();
const mw = new Composer<Context>()
  .install(dialogs(def, { storage }))
  .command("go", (ctx) => ctx.dialog.start("main"))
  .toMiddleware();

await mw(msgCtx(api, "/go", chatId), noop);
const sent = calls.find((c) => c.method === "sendMessage");
const data = sent.params.reply_markup.inline_keyboard[0][0].callback_data;
await mw(cbCtx(api, data, chatId, 100), noop); // press the button