در حال فکر، در جریان است

Lattice Loaderلودر و وضعیت

لودر مشبک

شبکه‌ای از خونه‌های ریز که با الگوهای آماده می‌دوه و آخرش به تیک یا ضربدر می‌نشینه، همراه با برچسب و شمارنده‌ی زمان.

پیش‌نمایش لودر مشبک
اختصاصی فارسی‌فایطراحی و توسعه در فارسی‌فای

وابستگی‌ها

بدون وابستگی

نوع تعامل

کامپوننت ورودی نمی‌گیره و با `status` اداره می‌شه. توی «working» خونه‌ها یکی‌یکی با تأخیرِ ناشی از الگو روشن می‌شن و شمارنده دهم‌ثانیه‌شمار می‌شه؛ با رفتن به «done» یا «error» شبکه می‌ایسته، لایه‌ی دونده محو می‌شه و نقشِ پایان (تیک یا ضربدر) با کمی بزرگ‌نمایی می‌نشینه و برچسب با محو و رفعِ بلور عوض می‌شه.

پراپ‌ها

گزینه‌هایی که می‌تونی به کامپوننت بدی؛ ستاره‌دارها اجباری‌اند.

label
stringپیش‌فرض: "در حال فکر"

برچسبِ حالتِ کار.

doneLabel
stringپیش‌فرض: "انجام شد در"

برچسبی که قبل از زمانِ پایان می‌آد.

errorLabel
stringپیش‌فرض: "شکست پس از"

برچسبی که قبل از زمانِ شکست می‌آد.

status
"working" | "done" | "error"پیش‌فرض: "working"working · done · error

وضعیتِ فعلی.

pattern
string | LatticePatternپیش‌فرض: "orbit"

نامِ الگوی آماده یا الگوی دست‌ساز با آرایه‌ی `cells`.

grid
numberپیش‌فرض: 33 · 4

اندازه‌ی شبکه؛ هر مقدارِ دیگه‌ای جز ۴ به ۳ گرد می‌شه.

نصب

۱. این آدرس رو یک‌بار توی components.json بذار تا shadcn مخزن فارسی‌فای رو بشناسه.

components.jsonjson
{
  "registries": {
    "@farsify": "https://farsifyui.ir/r/{name}.json"
  }
}

۲. بعد با دستور زیر کامپوننت رو نصب کن.

npx shadcn@latest add @farsify/lattice-loader

پیش‌نیاز: Tailwind CSS v4 و صفحهٔ راست‌به‌چپ dir="rtl".

نمونه

lattice-loader.tsxtsx
"use client";

import { useEffect, useState } from "react";
import {
  LatticeLoader,
  type LatticeLoaderStatus,
} from "@/components/farsify/lattice-loader";

/** چند میلی‌ثانیه تا رسیدنِ پاسخ. */
const ANSWER_MS = 1600;

export function ThinkingRow() {
  const [status, setStatus] = useState<LatticeLoaderStatus>("working");

  useEffect(() => {
    const timer = setTimeout(() => setStatus("done"), ANSWER_MS);
    return () => clearTimeout(timer);
  }, []);

  return (
    <LatticeLoader
      status={status}
      pattern="orbit"
      label="در حال فکر"
      doneLabel="انجام شد در"
      errorLabel="شکست پس از"
    />
  );
}

// شبکه‌ی ۴×۴ با هاله — برای پس‌زمینه‌ی روشن
<LatticeLoader status="working" grid={4} pattern="pulse" glow glowColor="var(--color-brand)" />

// الگوی اختصاصی: هر عدد یعنی خانه‌ای که با آن تأخیر روشن می‌شود،
// null یعنی خانه‌ای که هرگز روشن نمی‌شود
<LatticeLoader
  pattern={{ cells: [0, 2, null, 4, 1, 3, null, 5, 0], loop: 6, scale: 1.2 }}
  cellSize={8}
  gap={3}
/>

// زمان از بیرون می‌آید و کرنومترِ داخلی خاموش می‌شود
<LatticeLoader status={status} elapsed={1.4} showTimer />

نکته‌ها

  • `doneLabel` و `errorLabel` **قبل از** زمان می‌آن و شمارنده پشتشون می‌نشینه، پس «انجام شد در ۱٫۴ ثانیه» خونده می‌شه؛ اگه تعدادِ پله‌ها رو می‌دونی، `elapsed` رو بده تا زمان از منبعِ خودت بیاد نه از کرنومترِ کامپوننت.
  • ده الگوی آماده داری و هر کدوم فقط توی بعضی شبکه‌ها معنا داره: `arrow`/`dots`/`ripple`/`spiral` فقط ۳×۳ و `sweep`/`spin`/`rain`/`pulse` فقط ۴×۴. `orbit` و `snake` هر دو رو دارن. اگه الگویی برای شبکه‌ی خواسته‌شده موجود نباشه، خودکار به پیش‌فرضِ همون شبکه می‌افته.
  • برای الگوی اختصاصی، جای نام یه شیء بده: `pattern={{ cells: [...], loop: 5, scale: 1.2 }}`. آرایه‌ی کوتاه‌تر از شبکه خودکار با حفره پر می‌شه و بلندتر بریده می‌شه؛ `null` یعنی خونه‌ای که هرگز روشن نمی‌شه.
  • برای شبکه‌ی روشن و کم‌کنتراست `glow` رو روشن کن و `glowColor` رو هم‌رنگِ برند بده — چون خونه‌ها ریزن، هاله تنها چیزیه که توی نگاهِ اول دیده می‌شه.
  • کلِ حرکت توی CSSـه، نه توی جاوااسکریپت؛ فقط شمارنده با یه تایمرِ ۱۰۰ میلی‌ثانیه‌ای جلو می‌ره. یعنی ده‌ها بارگذار روی یه صفحه هم هزینه‌ی محسوسی ندارن.
  • زمانِ اعلامِ پایان از `performance.now()` می‌آد نه از شمارشِ تیک؛ اگه مرورگر تب رو خواب کنه شمارنده عقب نمی‌مونه.

هم‌خانواده‌ها

کامپوننت‌های دیگری از همان دسته که با این یکی جور درمی‌آیند.

مجوز

کد بعد از نصب مال خودته؛ هر تغییری خواستی بده و توی پروژه‌ی خودت نگهش دار. برای پروژه‌های شخصی و تجاری آزاده، حتی اگه کدت بسته باشه. فقط اسم و لینک فارسی‌فای رو یه جا توی پروژه نگه دار.