Special Elements (อิลิเมนต์พิเศษ)

เอกสารสำหรับ form elements พิเศษ: ColorElementFactory, RangeElementFactory, TagsElementFactory, MaskElementFactory และ TextareaElementFactory

📋 สารบัญ

1. ภาพรวม
2. ColorElementFactory
3. RangeElementFactory
4. TagsElementFactory
5. MaskElementFactory
6. TextareaElementFactory
7. แนวทางปฏิบัติที่ดี

ภาพรวม

Special elements มอบ UI ที่ปรับปรุงสำหรับ input types เฉพาะที่ต้องการมากกว่าการจัดการ text หรือ number พื้นฐาน

ColorElementFactory

ColorElementFactory สร้าง custom color picker พร้อม predefined palette และ hex input

การใช้งานพื้นฐาน

<input type="color"
       data-element="color"
       name="theme_color"
       value="#007bff">

HTML Attributes

จานสีเริ่มต้น

const COLOR_PALETTE = [
  '#FF5722', '#F44336', '#E91E63', '#9C27B0',
  '#673AB7', '#3F51B5', '#2196F3', '#03A9F4',
  '#00BCD4', '#009688', '#4CAF50', '#8BC34A',
  '#CDDC39', '#FFEB3B', '#FFC107', '#FF9800',
  // ... and more standard colors
  '#FFFFFF', '#000000'
];

JavaScript API

const instance = ElementManager.getInstance(colorInput);

// รับสีปัจจุบัน
const color = instance.getColor();  // '#007bff'

// ตั้งค่าสี
instance.setColor('#ff5722');

// เปิด/ปิด picker
instance.open();
instance.close();
instance.toggle();

// ปิด/เปิดการใช้งาน
instance.setDisabled(true);
instance.setReadonly(true);

ฟีเจอร์

• Color Palette: คลิกสีที่กำหนดไว้
• Hex Input: พิมพ์ค่า hex กำหนดเอง
• Preview: แสดงตัวอย่างสีในปุ่ม
• Copy/Paste: Ctrl+C คัดลอก, Ctrl+V วาง
• Contrast Text: สีตัวอักษรบนปุ่มปรับเองให้อ่านออกเสมอ

เหตุการณ์

colorInput.addEventListener('change', (e) => {
  console.log('Selected color:', e.target.value);
});

RangeElementFactory

RangeElementFactory สร้าง range sliders พร้อม UX ที่ดีกว่า native range inputs รองรับ single และ dual range modes

การใช้งานพื้นฐาน

<!-- Single range slider -->
<input type="range"
       data-element="range"
       min="0"
       max="100"
       value="50"
       name="volume">

<!-- Dual range slider (min-max) -->
<input type="range"
       data-element="range"
       min="0"
       max="1000"
       data-value="200-800"
       data-dual="true"
       name="price_range">

HTML Attributes

Range เดี่ยว

<input type="range"
       data-element="range"
       min="0"
       max="100"
       step="5"
       value="75"
       data-format="{value}%"
       name="opacity">

Range คู่ (ต่ำสุด-สูงสุด)

<input type="range"
       data-element="range"
       min="0"
       max="10000"
       step="100"
       data-value="2000-8000"
       data-dual="true"
       data-format="฿{value}"
       name="budget">

JavaScript API

const instance = ElementManager.getInstance(rangeInput);

// รับค่า
const value = instance.getValue();
// Single: 75
// Dual: {min: 2000, max: 8000}

// ตั้งค่า
instance.setValue(80);                       // Single
instance.setValue({min: 1000, max: 5000});   // Dual

// อัพเดท constraints
instance.setMin(10);
instance.setMax(200);
instance.setStep(10);

// ปิด/เปิดการใช้งาน
instance.setDisabled(true);
instance.setReadonly(true);

การใช้คีย์บอร์ด

เหตุการณ์

// Input event (while dragging)
rangeInput.addEventListener('input', (e) => {
  console.log('Current value:', e.detail.value);
});

// Change event (after release)
rangeInput.addEventListener('change', (e) => {
  console.log('Final value:', e.detail.value);
});

TagsElementFactory

TagsElementFactory แปลง text input เป็น tags/chips input พร้อม visual tags, keyboard navigation และ optional autocomplete

การใช้งานพื้นฐาน

<!-- Simple tags input -->
<input type="text"
       data-element="tags"
       name="keywords"
       placeholder="เพิ่ม tags...">

<!-- Tags พร้อม autocomplete -->
<input type="text"
       data-element="tags"
       data-source="/api/tags"
       name="categories">

HTML Attributes

การตั้งค่า

TagsElementFactory.config = {
  type: 'text',
  placeholder: 'Add tags...',
  separator: ',',
  maxTags: null,
  allowDuplicate: false,
  minLength: 2,
  maxResults: 10,
  delay: 300
};

Keyboard Interaction

JavaScript API

const instance = ElementManager.getInstance(tagsInput);

// รับ tags ทั้งหมด
const tags = instance.getTags();
// [{key: '1', value: 'JavaScript'}, {key: '2', value: 'Python'}]

// เพิ่ม tag
instance.addTag('3', 'React');

// ลบ tag
instance.removeTag('2');

// ล้างทั้งหมด
instance.clear();

การส่งค่าไปกับฟอร์ม

tags ถูกส่งไปเป็น hidden input

<!-- Original input -->
<input data-element="tags" name="skills">

<!-- Generated hidden inputs -->
<input type="hidden" name="skills[]" value="1">
<input type="hidden" name="skills[]" value="2">
<input type="hidden" name="skills[]" value="3">

เหตุการณ์

tagsInput.addEventListener('change', (e) => {
  const instance = ElementManager.getInstance(e.target);
  console.log('Tags:', instance.getTags());
});

TagsElementFactory ไม่ได้ส่งเหตุการณ์ tags:* เลย การเพิ่มหรือลบแท็กยิงแค่
change แบบ native เท่านั้น ถ้าต้องการรู้ว่าแท็กไหนเปลี่ยน ให้เทียบ
instance.getTags() กับรายการก่อนหน้าเอง

MaskElementFactory

MaskElementFactory ใช้ input masks สำหรับข้อมูลที่มีโครงสร้าง เช่น หมายเลขโทรศัพท์ วันที่ หมายเลขบัตร ฯลฯ

การใช้งานพื้นฐาน

<!-- หมายเลขโทรศัพท์ไทย -->
<input type="tel"
       data-element="tel"
       name="mobile">

<!-- บัตรเครดิต -->
<input type="text"
       data-element="mask"
       data-mask="#### #### #### ####"
       name="card">

<!-- วันที่ -->
<input type="text"
       data-element="mask"
       data-mask="##/##/####"
       name="date">

HTML Attributes

Mask Pattern Characters

Common Patterns

TelElementFactory

mask เฉพาะสำหรับหมายเลขโทรศัพท์ไทย

<input type="tel"
       data-element="tel"
       name="phone">
<!-- Auto applies: ###-###-#### -->

JavaScript API

const instance = ElementManager.getInstance(maskedInput);

// รับค่าที่ยังไม่ใส่ mask
const raw = instance.getUnmaskedValue();  // '0812345678'

// รับค่าที่ใส่ mask แล้ว
const masked = instance.getValue();       // '081-234-5678'

// ตั้งค่า (ใส่ mask ให้เอง)
instance.setValue('0898765432');
// Shows: 089-876-5432

เหตุการณ์

maskedInput.addEventListener('change', (e) => {
  const instance = ElementManager.getInstance(e.target);
  console.log('Masked:', e.target.value);
  console.log('Raw:', instance.getUnmaskedValue());
});

TextareaElementFactory

TextareaElementFactory ปรับปรุง textarea ด้วยฟังก์ชัน auto-resize

การใช้งานพื้นฐาน

<textarea data-element="textarea"
          name="description"
          rows="3"
          placeholder="กรอกคำอธิบาย..."></textarea>

HTML Attributes

พฤติกรรมการขยายอัตโนมัติ

textarea ปรับความสูงตามเนื้อหาให้เอง

/* Textarea expands with content */
[data-element="textarea"] {
  min-height: calc(3 * 1.5em);  /* 3 rows minimum */
  max-height: calc(10 * 1.5em); /* 10 rows maximum */
  overflow-y: auto;             /* Scroll when max reached */
  resize: vertical;             /* Allow manual resize */
}

ตัวนับตัวอักษร

<textarea data-element="textarea"
          data-show-counter="true"
          maxlength="500"
          name="bio"></textarea>
<!-- Shows: 0/500 characters -->

JavaScript API

const instance = ElementManager.getInstance(textareaEl);

// สั่งคำนวณความสูงใหม่
instance.resize();

// อ่านความสูงปัจจุบัน
const height = instance.getHeight();

แนวทางปฏิบัติที่ดี

1. ✅ ใช้ Element ที่เหมาะกับประเภทข้อมูล

<!-- ✅ สี -->
<input data-element="color" name="theme">

<!-- ✅ ช่วงราคา -->
<input data-element="range" data-dual="true" name="budget">

<!-- ✅ หลายหมวดหมู่ -->
<input data-element="tags" name="categories">

<!-- ✅ Input มีโครงสร้าง -->
<input data-element="mask" data-mask="##/##/####" name="date">

2. ✅ กำหนดขอบเขตที่สมเหตุสมผล

<!-- ✅ ดี: จำกัด tags -->
<input data-element="tags" data-max-tags="5" name="keywords">

<!-- ✅ ดี: จำกัด textarea -->
<textarea data-element="textarea" maxlength="1000" data-max-rows="15"></textarea>

3. ✅ ใส่ Autocomplete ให้ Tags

<!-- ✅ ดี: ผู้ใช้เห็น tag ที่มีอยู่แล้ว -->
<input data-element="tags"
       data-source="/api/tags"
       name="skills">

<!-- ❌ ไม่ดี: ผู้ใช้ต้องเดาชื่อ tag เอง -->
<input data-element="tags" name="skills">

4. ✅ ใช้ tel Type สำหรับหมายเลขโทรศัพท์

<!-- ✅ ดี: Keyboard มือถือแสดงตัวเลข -->
<input type="tel"
       data-element="tel"
       name="phone">

5. ✅ พิจารณาถอด mask ก่อนส่ง

<!-- ✅ ดี: เซิร์ฟเวอร์ได้ตัวเลขล้วน -->
<input data-element="mask"
       data-mask="(###) ###-####"
       data-unmask-on-submit="true"
       name="phone">
<!-- Form submits: 1234567890 instead of (123) 456-7890 -->

6. ✅ ใช้ Dual Range สำหรับ Filters

<!-- ✅ ดี: Price filter พร้อม min-max -->
<input data-element="range"
       data-dual="true"
       min="0"
       max="10000"
       step="100"
       data-format="฿{value}"
       name="price">

เอกสารที่เกี่ยวข้อง

• Form Elements ภาพรวม
• ElementFactory - Base class
• Text Elements - Text inputs
• Number Elements - Number inputs
• FormManager - Form-level validation