Bubble Sort Animation

1. Giải nén bubble-sort-animation-vanilla.zip. Chép bubble-sort-animation.css và bubble-sort-animation.js cạnh trang của bạn (hoặc vào thư mục assets của website).

2. Trong <head> của trang, nhúng stylesheet và script một lần:

   <link rel="stylesheet" href="bubble-sort-animation.css" />
   <script src="bubble-sort-animation.js" defer></script>
   

3. Chỗ nào cần animation, đặt một phần tử rỗng có data-bubble-sort-animation:

   <!-- dữ liệu của video: 5 2 8 1 7 3 6 4 -->
   <div class="bubble-sort-animation" data-bubble-sort-animation></div>
   
   <!-- dãy số của bạn, ẩn hàng nhập và khung code: đủ gọn để đặt vào slide -->
   <div
     class="bubble-sort-animation"
     data-bubble-sort-animation
     data-bubble-sort-animation-values="9 4 7 1 8"
     data-bubble-sort-animation-inputs="false"
     data-bubble-sort-animation-code="false"
   ></div>
   

4. Mở trang lên. Animation tự chạy; bấm vào nó một lần để nhận phím, sau đó Space để chạy / dừng, ← / → để đi từng bước, Home để chạy lại từ đầu.

Tuỳ chọn qua data attribute, đều bắt đầu bằng data-bubble-sort-animation-:

Attribute	Mặc định	Tác dụng
-values	theo preset	Dãy số của bạn, cách nhau bằng dấu cách hoặc dấu phẩy: số nguyên từ -999 đến 999, tối đa 24 số
-preset	video	video (5 2 8 1 7 3 6 4), random, nearly-sorted hoặc reversed; bị bỏ qua khi có -values
-size	8	Số cột của random, nearly-sorted và reversed (2–24)
-seed	7	Chọn mảng ngẫu nhiên nào: cùng seed luôn ra cùng một mảng
-speed	1	Từ 0.25 đến 4
-autoplay	true	Tự chạy khi tải xong (không bao giờ tự chạy khi bật giảm chuyển động)
-loop	false	Dừng một chút ở kết quả rồi chạy lại từ đầu
-code	true	false để ẩn khung code
-inputs	true	false để ẩn hàng preset và ô nhập số của bạn

Muốn xem một lượt dừng sớm, thử data-bubble-sort-animation-preset="nearly-sorted": một lượt đã đưa các cặp về đúng chỗ, lượt kế tiếp không đổi chỗ lần nào.

Phần tử thêm vào sau khi trang đã tải (một tab, một modal, một route chuyển bằng JavaScript): gọi BubbleSortAnimation.init(container), hàm này trả về một hàm để gỡ bỏ. Muốn điều khiển toàn bộ thì dùng BubbleSortAnimation.createBubbleSortAnimation(element, options): nó trả về một handle có setValues, setPreset, shuffle, player (play, pause, stepForward, stepBack, seek, reset, setSpeed, setLoop) và destroy.

• Slide làm từ HTML (reveal.js, Slidev, bản xuất HTML của Marp): đặt <link> và <script> vào head của bộ slide, còn <div> đặt trên slide. Dùng -inputs="false", -code="false" và -autoplay="false" cho slide gọn gàng, rồi bấm Space khi chiếu tới slide đó.
• Blog hoặc website tĩnh (Hugo, Jekyll, Astro, Eleventy, khối Custom HTML của WordPress): tải hai file lên, thêm <link> và <script> vào template trang (hoặc một lần cho mỗi bài), rồi dán <div> vào bài viết. Một trang có nhiều animation cũng không sao.
• LMS hoặc bất kỳ trang nào cho phép thêm HTML (Moodle, Canvas, ô nhúng kiểu Notion nhận iframe): đưa hai file cùng một trang nhỏ chứa <div> lên host, rồi nhúng trang đó bằng <iframe>.
• PowerPoint hoặc Keynote: mở trang, chọn tốc độ rồi quay màn hình, hoặc chụp lại khung hình bạn cần; dùng -autoplay="false" và bấm → để đi từng bước.

Animation sắp xếp đúng dữ liệu của video, nên bạn có thể chiếu video trước rồi để học sinh tự đi từng bước. Khung code là đoạn JavaScript trên trang thuật toán, nên hai nơi luôn khớp nhau.

Chép BubbleSortAnimation.tsx, bubble-sort-animation.css và thư mục core vào dự án:

import { BubbleSortAnimation } from "./BubbleSortAnimation";

<BubbleSortAnimation />
<BubbleSortAnimation values={[9, 4, 7, 1, 8]} inputs={false} code={false} autoplay={false} />
<BubbleSortAnimation preset="nearly-sorted" size={10} seed={3} loop onFrame={(frame) => console.log(frame.caption)} />

Props chính là các tuỳ chọn ở trên viết kiểu camelCase (values, preset, size, seed, speed, autoplay, loop, code, inputs), thêm onFrame(frame, index) được gọi mỗi khi vẽ một khung hình. Đổi một prop là thuật toán chạy lại từ đầu. Mọi prop khác được truyền xuống thẻ <div> gốc (className, id, aria-*…). Dùng được với React 18 hoặc 19.

File bắt đầu bằng "use client", nên dùng được từ bất kỳ page hay server component nào. Với App Router thì không cần làm gì thêm. Với Pages Router, chuyển dòng import CSS vào pages/_app.

Đặt các biến này trên .bubble-sort-animation (hoặc class của riêng bạn):

Biến	Thay đổi gì
--bubble-bar, --bubble-compare, --bubble-swap, --bubble-sorted	Màu cột chưa sắp xếp (tím), cặp đang so sánh (xanh ngọc), lần đổi chỗ (hồng) và đuôi đã sắp xếp (xanh lá)
--bubble-flag	Công tắc swapped khi bật, và màu các con số trong code
--bubble-bg, --bubble-surface, --bubble-surface-strong, --bubble-blur	Nền và lớp kính mờ
--bubble-edge, --bubble-shadow, --bubble-code-bg	Viền, bóng đổ, nền khung code
--bubble-text, --bubble-muted, --bubble-on-accent, --bubble-ring	Chữ, chữ phụ, chữ trên nhãn và nút có màu, viền focus
--bubble-font, --bubble-mono	Font cho chữ và cho code, con số
--bubble-radius, --bubble-bar-radius	Bo góc của trình phát và của các cột
--bubble-duration, --bubble-ease	Các cột bắt chéo và trượt nhanh hay chậm, mượt đến đâu

Màu dùng light-dark() nên tự theo color-scheme của trang. Khi bật prefers-reduced-motion, không có gì tự chạy và khung hình đổi ngay lập tức; mọi nút điều khiển vẫn dùng được.

• Không thấy gì: phần tử cần có data-bubble-sort-animation, và cả CSS lẫn script đều phải tải được (kiểm tra đường dẫn trong tab Network của trình duyệt).
• Bấm Space hay phím mũi tên mà không có phản ứng: bấm vào animation một lần trước đã; phím tắt chỉ hoạt động khi nó đang được focus, và không bao giờ hoạt động khi bạn đang gõ trong ô số.
• Số của tôi bị đổi: giá trị được làm tròn thành số nguyên, giữ trong khoảng -999 đến 999 và cắt ở 24 số. Ô nhập luôn hiện đúng dãy đã được sắp xếp.