fwxcss 🚀

fwxcss là một thư viện CSS-in-JS siêu nhẹ, hiệu năng cao, lấy cảm hứng từ cú pháp Emmet. Nó giúp bạn viết mã CSS nhanh hơn bằng cách sử dụng các lớp atomic ngắn gọn, hỗ trợ đầy đủ TypeScript, SSR và khả năng mở rộng mạnh mẽ.

🆚 Tại sao chọn fwxcss? (So sánh với Tailwind CSS)

| Đặc điểm | fwxcss ⚡ | Tailwind CSS 🌬 | | :--- | :--- | :--- | | Kích thước | ~1-3KB (Nano) | Lớn (cần PurgeCSS để giảm) | | Runtime | Zero Build Step (Chạy thẳng trên browser) | Cần Build Step (Node.js, PostCSS) | | Values | Dynamic (m123px tự nhận) | Static/JIT (Cần config spacing) | | Parser | Scan & Slice (Nhanh hơn ~1.6x) | Regex/AST (Chậm hơn) | | Setup | 1 dòng import script | Cài đặt CLI, config phức tạp |

fwxcss là giải pháp nhẹ hơn, nhanh hơn, linh hoạt hơn cho các dự án cần tốc độ triển khai ngay lập tức mà không muốn setup môi trường build cồng kềnh.

📖 Hướng dẫn Cơ bản

1. Cú pháp Cốt lõi

Mỗi class trong fwxcss được cấu tạo theo công thức: [Media]:[Layer][Property][Value][@Selector]

Ví dụ:

• m10px ⮕ margin: 10px
• cRed ⮕ color: red
• sm:p20px ⮕ @media (min-width: 576px) { padding: 20px }
• 3bgWhite ⮕ @layer l3 { background: white }
• cBlue@:hover ⮕ .class:hover { color: blue }

2. Nguyên lý Parser (Scan & Slice) 🧠

fwxcss không sử dụng Regex chậm chạp. Nó quét class từ trái sang phải và tự động cắt Property/Value dựa trên các điểm ngắt:

| Loại điểm ngắt | Ví dụ Class | Phân tích (Prop | Value) | | :--- | :--- | :--- | | Số (0-9) | w100px | w (width) | 100px | | Chữ Hoa (A-Z) | dFlex | d (display) | Flex | | Dấu gạch ngang + Số | m-10px | m (margin) | -10px | | Dấu chấm + Số | w.5px | w (width) | .5px | | Ký tự đặc biệt | bg#333, w[50%] | bg | #333, w | [50%] |

[!IMPORTANT] Lưu ý về CamelCase: marginTop-10px sẽ bị parse SAI (Prop: margin, Value: Top-10px). Hãy dùng margin-top-10px hoặc mt-10px.

3. Hiệu năng (Performance) ⚡

Chúng tôi đã thực hiện Benchmark so sánh parser "Scan & Slice" của fwxcss với Regex thông thường. Kết quả cho thấy fwxcss nhanh hơn ~1.6x (tiết kiệm ~40% thời gian xử lý) nhờ loại bỏ hoàn toàn Regex overhead.

(Bạn có thể tự kiểm chứng bằng cách chạy lệnh npm run test test/benchmark.test.ts)

📚 Bộ Từ điển (Dictionary) - Tra cứu đầy đủ tại đây

1. Thuộc tính phổ biến (Common Properties)

| Alias | CSS Property | Alias | CSS Property | Alias | CSS Property | | :--- | :--- | :--- | :--- | :--- | :--- | | m | margin | p | padding | w / h | width / height | | d | display | pos | position | z | z-index | | c | color | bg | background | bd | border | | fx | flex | g | grid | op | opacity | | ta | text-align | fz | font-size | fw | font-weight | | tr | transition | ani | animation | tf | transform |

2. Thuộc tính Hiện đại & Logical

| Alias | CSS Property | Mô tả | | :--- | :--- | :--- | | cont | container | Container Queries | | mis / mie | margin-inline-start / end | Logical Margin | | isb / isi | inset-block / inline | Logical Inset | | acc | accent-color | Màu nhấn (tránh trùng ac) | | ar | aspect-ratio | Tỉ lệ khung hình | | tw | text-wrap | Ngắt dòng văn bản | | vtn | view-transition-name | View Transitions |

3. Giá trị viết tắt (Values)

Giá trị chung (Global Values)

a: auto, n: none, ini: initial, un: unset, tr: transparent, cc: currentColor, in: inherit, c: center, s: start, e: end.

Giá trị riêng (Specific Values)

• Position (pos): a (absolute), r (relative), f (fixed), st (sticky).
• Display (d): f (flex), g (grid), b (block), i (inline), ib (inline-block), fr (flow-root).
• Flex Direction (fxd): r (row), c (column).

🛠 Tính năng Nâng cao

Arbitrary Values (Giá trị tùy ý)

Dùng ngoặc vuông [] cho các giá trị chứa khoảng trắng hoặc phức tạp. Sử dụng dấu ; để thay thế cho khoảng trắng bên trong:

• w[calc(100vh;-;20px)] ⮕ width: calc(100vh - 20px)
• bg[url('path/to/img.png')]

Important & Negative Values

• w!100px ⮕ width: 100px !important
• m-20px ⮕ margin: -20px

⚙️ Cấu hình (Configuration)

Bạn có thể truyền object config vào cssObserve hoặc xcss.

| Param | Type | Mô tả | Ví dụ | | :--- | :--- | :--- | :--- | | theme | Record<string, string> | Định nghĩa biến/alias giá trị (Màu sắc, Font...). Thay thế cho valueExt. | { 'brand': '#007bff', 'sm': '12px' } | | breakpoints | Record<string, string>[] | Thêm Media Query tùy chỉnh. Thay thế cho mQuery. | [{ 'mobile': 'screen and (max-width: 480px)' }] | | exclude | string[] | Loại trừ các class (hỗ trợ Wildcard *). Thay thế cho exNames. | ['btn-*', 'fa'] | | aliases | Record<string, string[]> | Gom nhóm thuộc tính (Mixins). Thay thế cho gValue. | { 'card': ['p20px', 'bd1px;solid;#ddd'] } | | base | string | CSS cơ bản injected lúc khởi tạo. Thay thế cho css. | body { margin: 0 } |

📦 Hướng dẫn Sử dụng Chi tiết

1. Vanilla JavaScript (Mặc định)

Mặc định, khi import module (hoặc dùng script tag), fwxcss sẽ tự động chạy cssObserve(document) để lắng nghe thay đổi DOM.

Sử dụng cơ bản:

<!-- Không cần cấu hình gì thêm -->
<div class="dFlex cRed">Hello World</div>

Khởi tạo thủ công với cấu hình: Nếu bạn muốn thêm màu sắc hoặc breakpoint riêng:

import { cssObserve } from 'fwxcss';

cssObserve(document, {
  // Thêm màu 'brand'
  theme: {
    brand: '#ff5722',
    dark: '#333333'
  },
  // Thêm breakpoint 'tablet'
  breakpoints: [
    { tablet: 'screen and (min-width: 768px)' }
  ]
});

Sử dụng sau khi cấu hình: cBrand (color: #ff5722), tablet:dBlock.

2. React / Next.js

Sử dụng clsx để kết hợp class động và tối ưu việc gom nhóm string.

import { clsx } from 'fwxcss';
import { useState } from 'react';

function Button({ primary, children }) {
  const [isHover, setHover] = useState(false);

  return (
    <button 
      className={clsx(
        'p10px;20px',    // padding: 10px 20px
        'bdn bdra4px',   // border: none, border-radius: 4px
        'tr0.2s',        // transition: 0.2s
        'cWhite',        // color: white
        {
            'bgBlue': primary,      // Apply 'bgBlue' if primary is true
            'bgGray': !primary,     // Apply 'bgGray' otherwise
            'op0.8': isHover        // Opacity 0.8 when hover
        },
        'bgDarkBlue@:hover' // Native CSS hover (ưu tiên hơn state JS nếu muốn)
      )}
      onMouseEnter={() => setHover(true)}
      onMouseLeave={() => setHover(false)}
    >
      {children}
    </button>
  );
}

3. Server-Side Rendering (SSR)

Để tránh FOUC (Flash of Unstyled Content), hãy inject CSS sinh ra từ server.

import { getCss } from 'fwxcss';

// Trong file entry của server (ví dụ: _document.js của Next.js cũ hoặc App Router layout)
// Sau khi ứng dụng render xong:
const styles = getCss();

// Inject vào thẻ head
<style dangerouslySetInnerHTML={{ __html: styles }} />

🤖 Cấu hình cho AI Assistant (Cursor, Copilot...)

Do fwxcss sử dụng cú pháp Parser "Scan & Slice" độc đáo (khác với Regex của Tailwind hay Bootstrap), các AI thường mặc định viết sai cú pháp (ví dụ viết hover:cRed thay vì cRed@:hover).

Để AI code chuẩn 100%, hãy tạo file .cursorrules (nếu dùng Cursor) hoặc thêm vào "Custom Instructions" của Copilot nội dung sau:

# AI Rules for fwxcss Project

You are an expert in **fwxcss**. When generating code, you MUST follow these strict syntax rules:

1. **Syntax Formula**: `[Media]:[Layer][Property][Value][@Selector]`

2. **Critical DOs and DON'Ts**:
   - ✅ **Layer**: Write directly before property (e.g., `3bgWhite`). ❌ NO colon (`3:bgWhite`).
   - ✅ **Selectors**: Use `@` suffix (e.g., `cRed@:hover`). ❌ NO prefix (`hover:cRed`).
   - ✅ **Values**: Capitalize text values (e.g., `dFlex`, `cRed`, `posAbs`).
   - ✅ **Aliases**: Use brackets for mixins (e.g., `[card]`).

Bạn có thể tham khảo file mẫu đầy đủ tại .cursorrules trong repo này.

⚙️ Cấu hình VS Code

Để có trải nghiệm code tốt nhất (tránh bị gạch chân đỏ khi viết class lạ), bạn nên thêm file .vscode/settings.json vào dự án:

{
  "cSpell.words": ["fwxcss", "clsx", "dFlex", "cRed", "bdra", "posAbs"],
  "editor.formatOnSave": true
}

Kiến nghị cài extension "Code Spell Checker" và "Prettier".

“Tối ưu từng dòng code để mang lại trải nghiệm mượt mà nhất.”