تغییر صفحه (Transaction)

هر تغییر صفحه در یک محصول Tokapps، شامل لینک داخلی، جستجو، و بازگشت یا پیش‌روی مرورگر، باید با انجام شود. این قانون در ARCH.md بخش ۱۸ تعریف شده است.

قواعد

تابع یکتا: از در همهٔ جای محصول قابل فراخوانی است: کامپوننت، hook، کد غیر React، میان‌بر کیبورد و داک.
قالب می‌سازد: هر پروژه خودش را در با استفاده از قالب می‌سازد و در ثبت می‌کند. قرارداد در TDS است؛ پروژه آن را بازتعریف نمی‌کند.
فقط هنگام تغییر صفحه: روی سرور کاری نمی‌کند، با همان صفحه انیمیشن ندارد، و با کاهش حرکت یا نبود قالب فوراً ناوبری می‌کند.
تا mount کامل صبر می‌کند: ورود صفحهٔ جدید فقط بعد از اعلان شروع می‌شود و transaction بعد از آن تمام می‌شود.
داک ثابت است: انیمیشن فقط روی (محتوای ) اجرا می‌شود. داک شیشه‌ای، TopBar و پخش‌کنندهٔ کوچک‌شدهٔ داک بیرون این عنصرند و نمی‌پرند.

۱. ساخت transaction در قالب

فایل را بسازید. هر قالب فقط مرحله‌ها و توکن‌های خودش را می‌دهد؛ زمان و منحنی باید نام توکن باشند تا کاهش حرکت خودکار اعمال شود.

TypeScript

import { keyframeTransaction, type TransactionConfig } from '@tokapps/tuk/transaction';/** هویت نمونه: محو شدن به بالا و ورود از پایین */export const transactionConfig: TransactionConfig = keyframeTransaction({  out: {    duration: '--tds-dur-quick',    easing: '--tds-ease-soft',    keyframes: () => [{ opacity: 1, transform: 'translateY(0)' }, { opacity: 0, transform: 'translateY(-6px)' }],  },  in: {    duration: '--tds-dur-deliberate',    easing: '--tds-ease-out',    keyframes: () => [{ opacity: 0, transform: 'translateY(10px)' }, { opacity: 1, transform: 'translateY(0)' }],  },});

یک تابع است؛ برای لغزش افقی از استفاده کنید تا جهت در راست‌به‌چپ برعکس شود. فقط ، و مجازند (ARCH §۶.۱).

۲. ثبت در قالب

TypeScript

// theme/index.tsimport { registerTransaction } from '@tokapps/tuk/transaction';import { transactionConfig } from './transaction';export { transactionConfig } from './transaction';registerTransaction(transactionConfig);

۳. اتصال ناوبری اپ

ناوبری اپ (مثلاً در Next) را یک بار در ریشهٔ اپ وصل کنید. این اتصال باید در کلاینت باشد.

TSX

'use client';import { useEffect, type ReactNode } from 'react';import { usePathname, useRouter } from 'next/navigation';import { bindTransactionNavigator, notifyPageMounted } from '@tokapps/tuk/transaction';export function TransactionBridge({ children }: { children: ReactNode }) {  const router = useRouter();  const pathname = usePathname();  useEffect(() => bindTransactionNavigator((to) => router.push(to)), [router]);  // صفحه بعد از commit؛ ورود منتظر این اعلان است  useEffect(() => {    const frame = requestAnimationFrame(() => notifyPageMounted(pathname));    return () => cancelAnimationFrame(frame);  }, [pathname]);  return <>{children}</>;}

ناحیهٔ محتوا باید ویژگی داشته باشد تا انیمیشن روی آن اجرا شود:

TSX

<main id="main" data-tds-transition>{children}</main>

۴. تغییر صفحه از هر جا

TypeScript

import { transaction } from '@tokapps/tuk/transaction';// لینک داخلی یا دکمهvoid transaction('/components/dock', 'link');// نتیجهٔ جستجو یا کدvoid transaction('/dashboard', 'programmatic');

یکی از ، ، یا است و در به runner می‌رسد. تابع یک برمی‌گرداند که بعد از mount و پایان ورود resolve می‌شود.

۵. رفتار هنگام خطا و لغو

وضعیت	رفتار
ناوبری پیاپی	انتقال قبلی لغو و ناوبری آن فوراً انجام می‌شود؛ دو صفحه هم‌زمان ساخته نمی‌شوند
کاهش حرکت	بدون انیمیشن، فقط ناوبری
قالب ثبت نشده	ناوبری فوری و یک هشدار توسعه‌ای
صفحه بعد از سقف زمانی (، پیش‌فرض ۳۰۰۰ms) mount نشود	ناوبری اجباری، کاربر گیر نمی‌کند
خطای runner	ناوبری انجام می‌شود و promise رد نمی‌شود

۶. تست

تست‌های این موارد را پوشش می‌دهند: navigate دقیقاً یک بار، لغو با ناوبری پیاپی، کاهش حرکت، سقف زمانی، ورود بعد از mount، و عدم باقی‌ماندن روی محتوا.

محدودیت‌های فعلی

دکمه‌های بازگشت و پیش‌روی مرورگر هنوز به وصل نشده‌اند.
گیت در ناوبری مستقیم (، ) را هشدار می‌دهد، نه خطا.

تغییر صفحه (Transaction)

قواعد

تابع یکتا: از در همهٔ جای محصول قابل فراخوانی است: کامپوننت، hook، کد غیر React، میان‌بر کیبورد و داک.
قالب می‌سازد: هر پروژه خودش را در با استفاده از قالب می‌سازد و در ثبت می‌کند. قرارداد در TDS است؛ پروژه آن را بازتعریف نمی‌کند.
فقط هنگام تغییر صفحه: روی سرور کاری نمی‌کند، با همان صفحه انیمیشن ندارد، و با کاهش حرکت یا نبود قالب فوراً ناوبری می‌کند.
تا mount کامل صبر می‌کند: ورود صفحهٔ جدید فقط بعد از اعلان شروع می‌شود و transaction بعد از آن تمام می‌شود.
داک ثابت است: انیمیشن فقط روی (محتوای ) اجرا می‌شود. داک شیشه‌ای، TopBar و پخش‌کنندهٔ کوچک‌شدهٔ داک بیرون این عنصرند و نمی‌پرند.

۱. ساخت transaction در قالب

TypeScript

import { keyframeTransaction, type TransactionConfig } from '@tokapps/tuk/transaction';/** هویت نمونه: محو شدن به بالا و ورود از پایین */export const transactionConfig: TransactionConfig = keyframeTransaction({  out: {    duration: '--tds-dur-quick',    easing: '--tds-ease-soft',    keyframes: () => [{ opacity: 1, transform: 'translateY(0)' }, { opacity: 0, transform: 'translateY(-6px)' }],  },  in: {    duration: '--tds-dur-deliberate',    easing: '--tds-ease-out',    keyframes: () => [{ opacity: 0, transform: 'translateY(10px)' }, { opacity: 1, transform: 'translateY(0)' }],  },});

یک تابع است؛ برای لغزش افقی از استفاده کنید تا جهت در راست‌به‌چپ برعکس شود. فقط ، و مجازند (ARCH §۶.۱).

۲. ثبت در قالب

TypeScript

// theme/index.tsimport { registerTransaction } from '@tokapps/tuk/transaction';import { transactionConfig } from './transaction';export { transactionConfig } from './transaction';registerTransaction(transactionConfig);

۳. اتصال ناوبری اپ

ناوبری اپ (مثلاً در Next) را یک بار در ریشهٔ اپ وصل کنید. این اتصال باید در کلاینت باشد.

TSX

'use client';import { useEffect, type ReactNode } from 'react';import { usePathname, useRouter } from 'next/navigation';import { bindTransactionNavigator, notifyPageMounted } from '@tokapps/tuk/transaction';export function TransactionBridge({ children }: { children: ReactNode }) {  const router = useRouter();  const pathname = usePathname();  useEffect(() => bindTransactionNavigator((to) => router.push(to)), [router]);  // صفحه بعد از commit؛ ورود منتظر این اعلان است  useEffect(() => {    const frame = requestAnimationFrame(() => notifyPageMounted(pathname));    return () => cancelAnimationFrame(frame);  }, [pathname]);  return <>{children}</>;}

ناحیهٔ محتوا باید ویژگی داشته باشد تا انیمیشن روی آن اجرا شود:

TSX

<main id="main" data-tds-transition>{children}</main>

۴. تغییر صفحه از هر جا

TypeScript

import { transaction } from '@tokapps/tuk/transaction';// لینک داخلی یا دکمهvoid transaction('/components/dock', 'link');// نتیجهٔ جستجو یا کدvoid transaction('/dashboard', 'programmatic');

یکی از ، ، یا است و در به runner می‌رسد. تابع یک برمی‌گرداند که بعد از mount و پایان ورود resolve می‌شود.

۵. رفتار هنگام خطا و لغو

وضعیت	رفتار
ناوبری پیاپی	انتقال قبلی لغو و ناوبری آن فوراً انجام می‌شود؛ دو صفحه هم‌زمان ساخته نمی‌شوند
کاهش حرکت	بدون انیمیشن، فقط ناوبری
قالب ثبت نشده	ناوبری فوری و یک هشدار توسعه‌ای
صفحه بعد از سقف زمانی (، پیش‌فرض ۳۰۰۰ms) mount نشود	ناوبری اجباری، کاربر گیر نمی‌کند
خطای runner	ناوبری انجام می‌شود و promise رد نمی‌شود

۶. تست

محدودیت‌های فعلی

دکمه‌های بازگشت و پیش‌روی مرورگر هنوز به وصل نشده‌اند.
گیت در ناوبری مستقیم (، ) را هشدار می‌دهد، نه خطا.