GraphComponent - Data Visualization

เอกสารสำหรับ GraphComponent ซึ่งเป็น UI Component สำหรับแสดงกราฟและแผนภูมิข้อมูล

📋 สารบัญ

1. ภาพรวม
2. การติดตั้งและนำเข้า
3. การใช้งานพื้นฐาน
4. ประเภทของกราฟ
5. HTML Attributes
6. Configuration Options
7. Data Format
8. Styling และ Customization
9. Events
10. JavaScript API
11. ตัวอย่างการใช้งาน
12. API Reference
13. Best Practices

ภาพรวม

GraphComponent เป็น UI Component สำหรับแสดงกราฟและแผนภูมิข้อมูลแบบ interactive โดยใช้ SVG rendering

ฟีเจอร์หลัก

• ✅ Multiple Chart Types: Line, Bar, Pie, Donut, Gauge
• ✅ SVG Rendering: เวกเตอร์กราฟิกที่คมชัด
• ✅ Responsive: ปรับขนาดตาม container อัตโนมัติ
• ✅ Interactive: Tooltips, legends, click events
• ✅ Data Loading: จาก API, table, หรือ direct data
• ✅ Auto-Refresh: Polling และ event-based refresh
• ✅ Animation: Smooth transitions
• ✅ Customizable: สี, ฟอนต์, สไตล์
• ✅ Export: ส่งออกเป็นรูปภาพ PNG/JPEG/SVG

เมื่อไหร่ควรใช้ GraphComponent

✅ ใช้ GraphComponent เมื่อ:

• ต้องการแสดงข้อมูลเป็นกราฟหรือแผนภูมิ
• ต้องการความง่ายในการใช้งาน (HTML-based)
• ต้องการกราฟที่ responsive
• ต้องการ auto-refresh ข้อมูล
• ต้องการ export เป็นรูปภาพ

❌ ไม่ควรใช้ GraphComponent เมื่อ:

• ต้องการกราฟที่ซับซ้อนมาก (ใช้ library เช่น Chart.js, D3.js)
• ต้องการ 3D visualization
• ต้องการ real-time streaming มากกว่า 100 data points/sec

การติดตั้งและนำเข้า

GraphComponent โหลดมาพร้อมกับ Now.js Framework และพร้อมใช้งานทันทีผ่าน window object:

// ไม่ต้อง import - พร้อมใช้งานทันที
console.log(window.GraphComponent); // GraphComponent object

Dependencies

GraphComponent ต้องการ dependencies เหล่านี้:

• GraphRenderer - สำหรับ render กราฟ (optional - มี internal renderer)
• ApiService หรือ simpleFetch - สำหรับโหลดข้อมูลจาก API (optional)

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

1. HTML-Based (แนะนำ)

<div data-component="graph"
     data-type="line"
     data-url="/api/sales">
</div>

2. With Direct Data

<div data-component="graph"
     data-type="bar"
     data-props='{
       "data": [
         {
           "name": "Sales",
           "data": [
             {"label": "Jan", "value": 100},
             {"label": "Feb", "value": 120},
             {"label": "Mar", "value": 150}
           ]
         }
       ]
     }'>
</div>

3. From HTML Table

<table id="sales-table">
  <thead>
    <tr>
      <th></th>
      <th>Q1</th>
      <th>Q2</th>
      <th>Q3</th>
      <th>Q4</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Sales</th>
      <td>100</td>
      <td>120</td>
      <td>150</td>
      <td>130</td>
    </tr>
  </tbody>
</table>

<div data-component="graph"
     data-type="line"
     data-table="sales-table">
</div>

4. JavaScript-Based

const element = document.querySelector('#my-graph');

const instance = await GraphComponent.create(element, {
  type: 'line',
  data: [
    {
      name: 'Sales',
      data: [
        {label: 'Jan', value: 100},
        {label: 'Feb', value: 120},
        {label: 'Mar', value: 150}
      ]
    }
  ]
});

ประเภทของกราฟ

GraphComponent รองรับกราฟ 5 ประเภท:

1. Line Chart

แสดงข้อมูลแบบเส้นกราฟ เหมาะสำหรับแสดงแนวโน้มตามเวลา

<div data-component="graph"
     data-type="line"
     data-curve="true"
     data-fill-area="true"
     data-url="/api/sales-trend">
</div>

Use Cases:

• ยอดขายตามเวลา
• Traffic website
• อุณหภูมิ
• ราคาหุ้น

2. Bar Chart

แสดงข้อมูลแบบแท่งกราฟ เหมาะสำหรับเปรียบเทียบค่าต่างๆ

<div data-component="graph"
     data-type="bar"
     data-url="/api/product-sales">
</div>

Use Cases:

• เปรียบเทียบยอดขายสินค้า
• จำนวนผู้ใช้แต่ละภูมิภาค
• คะแนนการประเมิน
• Ranking

3. Pie Chart

แสดงข้อมูลแบบวงกลม แสดงสัดส่วนเปอร์เซ็นต์

<div data-component="graph"
     data-type="pie"
     data-show-value-instead-of-percent="true"
     data-url="/api/market-share">
</div>

Use Cases:

• Market share
• สัดส่วนรายได้
• การกระจายอายุ
• Category distribution

4. Donut Chart

แสดงข้อมูลแบบวงแหวน มีพื้นที่กลางสำหรับข้อความ

<div data-component="graph"
     data-type="donut"
     data-donut-thickness="40"
     data-center-text="Total: 1000"
     data-url="/api/expenses">
</div>

Use Cases:

• งบประมาณ
• ค่าใช้จ่าย
• Resource allocation
• Progress indicators

5. Gauge Chart

แสดงข้อมูลแบบมาตรวัด เหมาะสำหรับแสดงค่าเดียวในช่วง

<div data-component="graph"
     data-type="gauge"
     data-max-gauge-value="100"
     data-gauge-curve-width="30"
     data-url="/api/performance-score">
</div>

Use Cases:

• Performance score
• Progress (%complete)
• KPI indicators
• Battery level
• Speed meter

HTML Attributes

GraphComponent รองรับ attributes เหล่านี้สำหรับการกำหนดค่า:

Basic Attributes

Appearance Attributes

Chart-Specific Attributes

Display Options

Animation & Behavior

Refresh & Polling

Props Attribute

สามารถใช้ data-props เพื่อกำหนดค่าทั้งหมดในรูปแบบ JSON:

<div data-component="graph"
     data-props='{
       "type": "line",
       "url": "/api/sales",
       "colors": ["#FF6B6B", "#4ECDC4"],
       "showGrid": true,
       "animation": true
     }'>
</div>

Configuration Options

เมื่อสร้าง instance ด้วย JavaScript สามารถกำหนดค่าได้ทั้งหมด:

const instance = await GraphComponent.create(element, {
  // Basic
  type: 'line',
  autoload: true,
  debug: false,

  // Data Sources
  url: '/api/sales',
  table: 'sales-table',
  data: null,

  // Appearance
  colors: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
  backgroundColor: '#ffffff',
  showGrid: true,
  gridColor: '#E0E0E0',
  axisColor: '#333333',
  textColor: '#333333',
  fontSize: 16,
  fontFamily: 'Arial, sans-serif',

  // Chart Options
  curve: true,
  fillArea: false,
  fillOpacity: 0.1,
  pointRadius: 4,
  lineWidth: 2,
  borderWidth: 1,
  borderColor: 'auto',
  donutThickness: 30,
  gaugeCurveWidth: 30,
  maxGaugeValue: 100,
  gap: 2,

  // Display
  showLegend: true,
  legendPosition: 'bottom',
  showTooltip: true,
  tooltipFormatter: null,
  showDataLabels: true,
  showAxis: true,
  showAxisLabels: true,
  showCenterText: true,
  centerText: null,
  showValueInsteadOfPercent: true,

  // Animation
  animation: false,
  animationDuration: 1000,

  // Behavior
  maxDataPoints: 20,
  pollingInterval: 0,
  refreshEvent: null,

  // Event Handlers
  onClick: (data) => {},
  onLoad: (data) => {},
  onRender: () => {},
  onDataChange: (data) => {}
});

Data Format

GraphComponent รองรับ data format หลายแบบ:

Format 1: Array of Series (แนะนำ)

[
  {
    name: 'Series 1',
    data: [
      {label: 'Q1', value: 100},
      {label: 'Q2', value: 120},
      {label: 'Q3', value: 150}
    ]
  },
  {
    name: 'Series 2',
    data: [
      {label: 'Q1', value: 80},
      {label: 'Q2', value: 90},
      {label: 'Q3', value: 110}
    ]
  }
]

Format 2: Simple Array (Single Series)

[
  {label: 'Category A', value: 100},
  {label: 'Category B', value: 120},
  {label: 'Category C', value: 80}
]

Format 3: API Response

{
  "data": [
    {
      "name": "Sales",
      "data": [
        {"label": "Jan", "value": 100},
        {"label": "Feb", "value": 120}
      ]
    }
  ]
}

Format 4: From HTML Table

HTML table จะถูกแปลงเป็น data format อัตโนมัติ:

<table id="data-table">
  <thead>
    <tr>
      <th></th>
      <th>Q1</th>
      <th>Q2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Sales</th>
      <td>100</td>
      <td>120</td>
    </tr>
    <tr>
      <th>Revenue</th>
      <td>200</td>
      <td>240</td>
    </tr>
  </tbody>
</table>

จะถูกแปลงเป็น:

[
  {
    name: 'Sales',
    data: [
      {label: 'Q1', value: 100},
      {label: 'Q2', value: 120}
    ]
  },
  {
    name: 'Revenue',
    data: [
      {label: 'Q1', value: 200},
      {label: 'Q2', value: 240}
    ]
  }
]

Styling และ Customization

Color Palette

<div data-component="graph"
     data-type="bar"
     data-colors='["#FF6B6B", "#4ECDC4", "#45B7D1", "#FFA07A"]'
     data-url="/api/sales">
</div>

Custom Colors for Each Series

const data = [
  {
    name: 'Sales',
    color: '#FF6B6B',
    data: [...]
  },
  {
    name: 'Revenue',
    color: '#4ECDC4',
    data: [...]
  }
];

Font Customization

<div data-component="graph"
     data-font-family="'Segoe UI', Tahoma, sans-serif"
     data-font-size="14"
     data-text-color="#555555"
     data-url="/api/data">
</div>

Grid Customization

<div data-component="graph"
     data-show-grid="true"
     data-grid-color="#F0F0F0"
     data-axis-color="#666666"
     data-url="/api/data">
</div>

Custom Tooltip

const instance = await GraphComponent.create(element, {
  type: 'line',
  data: [...],
  tooltipFormatter: (label, value, seriesName) => {
    return `<strong>${seriesName}</strong><br>${label}: ${value.toFixed(2)}`;
  }
});

Events

GraphComponent ส่ง events เมื่อมีการเปลี่ยนแปลง

Event Types

Listen to Events

const element = document.querySelector('#my-graph');

element.addEventListener('graph:loaded', (e) => {
  console.log('Data loaded:', e.detail.data);
});

element.addEventListener('graph:error', (e) => {
  console.error('Error:', e.detail.error);
});

element.addEventListener('graph:data-changed', (e) => {
  console.log('Data changed:', e.detail.data);
});

Event Handlers in Configuration

const instance = await GraphComponent.create(element, {
  type: 'line',
  url: '/api/sales',

  onClick: function(dataPoint, seriesIndex) {
    console.log('Clicked:', dataPoint, seriesIndex);
  },

  onLoad: function(data) {
    console.log('Data loaded:', data);
  },

  onRender: function() {
    console.log('Graph rendered');
  },

  onDataChange: function(data) {
    console.log('Data changed:', data);
  }
});

JavaScript API

GraphComponent มี methods สำหรับควบคุมผ่าน JavaScript

Create Instance

const instance = await GraphComponent.create(element, options);

Get Instance

// From element
const instance = GraphComponent.getInstance(element);

// From ID
const instance = GraphComponent.getInstance('#my-graph');

// From element property
const instance = element.graphInstance;

Set Data

instance.setData([
  {
    name: 'Sales',
    data: [
      {label: 'Jan', value: 100},
      {label: 'Feb', value: 120}
    ]
  }
]);

Load Data from URL

await instance.loadData('/api/sales');

Add Data Point

// Add to first series
instance.addDataPoint({label: 'Mar', value: 150}, 0);

// Add to second series
instance.addDataPoint({label: 'Mar', value: 130}, 1);

Change Chart Type

instance.setType('bar'); // Change to bar chart
instance.setType('pie'); // Change to pie chart

Refresh Data

instance.refresh(); // Reload data from URL

Export to Image

// Export as PNG
instance.exportToImage('sales-chart', 'png');

// Export as JPEG with custom size
instance.exportToImage('sales-chart', 'jpeg', 1920, 1080, 0.9);

// Export as SVG
instance.exportToImage('sales-chart', 'svg');

Polling Control

// Start polling (if configured)
GraphComponent.startPolling(instance);

// Stop polling
GraphComponent.stopPolling(instance);

Destroy Instance

instance.destroy();
// or
GraphComponent.destroy(instance);

ตัวอย่างการใช้งาน

1. Line Chart - Sales Trend

<div style="width: 800px; height: 400px;">
  <div data-component="graph"
       data-type="line"
       data-curve="true"
       data-fill-area="true"
       data-fill-opacity="0.2"
       data-url="/api/sales/monthly"
       data-animation="true">
  </div>
</div>

2. Bar Chart - Product Comparison

<div style="width: 600px; height: 400px;"
     data-component="graph"
     data-type="bar"
     data-props='{
        "data": [
         {
           "name": "Q1",
           "data": [
             {"label": "Product A", "value": 100},
             {"label": "Product B", "value": 120},
             {"label": "Product C", "value": 80}
           ]
         },
         {
           "name": "Q2",
           "data": [
             {"label": "Product A", "value": 110},
             {"label": "Product B", "value": 130},
             {"label": "Product C", "value": 90}
           ]
         }
       ]
     }'>
</div>

3. Pie Chart - Market Share

<div style="width: 500px; height: 400px;"
     data-component="graph"
     data-type="pie"
     data-show-value-instead-of-percent="false"
     data-props='{
        "data": [
        {
          "name": "Browser Usage",
          "data": [
              {"label": "Chrome", "value": 65},
              {"label": "Safari", "value": 18},
              {"label": "Firefox", "value": 10},
              {"label": "Edge", "value": 5},
              {"label": "Others", "value": 2}
            ]
          }
        ]
      }'>
</div>

4. Donut Chart - Budget Distribution

<div style="width: 500px; height: 400px;"
     data-component="graph"
     data-type="donut"
     data-donut-thickness="50"
     data-center-text="Total: $10,000"
     data-props='{
        "data": [
        {
          "name": "Browser Usage",
          "data": [
              {"label": "Chrome", "value": 65},
              {"label": "Safari", "value": 18},
              {"label": "Firefox", "value": 10},
              {"label": "Edge", "value": 5},
              {"label": "Others", "value": 2}
            ]
          }
        ]
      }'>
</div>

5. Gauge Chart - Performance Score

<div style="width: 400px; height: 300px;"
     data-component="graph"
     data-type="gauge"
     data-max-gauge-value="100"
     data-gauge-curve-width="40"
     data-center-text="85/100"
     data-props='{
        "data": [
        {
          "name": "Performance Score",
          "data": [
              {"label": "Score", "value": 85}
            ]
          }
        ]
      }'>
</div>

6. Real-time Graph with Polling

<div style="width: 800px; height: 400px;">
  <div id="realtime-graph"
       data-component="graph"
       data-type="line"
       data-url="/api/server-stats"
       data-polling-interval="5000"
       data-max-data-points="20">
  </div>
</div>

<script>
// Stop polling after 1 minute
setTimeout(() => {
  const instance = GraphComponent.getInstance('#realtime-graph');
  GraphComponent.stopPolling(instance);
}, 60000);
</script>

7. Dynamic Data Update

<div id="dynamic-graph"
     data-component="graph"
     data-type="bar"
     data-autoload="false"
     style="width: 600px; height: 400px;">
</div>

<button onclick="updateGraph()">Update Data</button>

<script>
async function updateGraph() {
  const instance = GraphComponent.getInstance('#dynamic-graph');

  const newData = [
    {
      name: 'Sales',
      data: [
        {label: 'Mon', value: Math.random() * 100},
        {label: 'Tue', value: Math.random() * 100},
        {label: 'Wed', value: Math.random() * 100}
      ]
    }
  ];

  instance.setData(newData);
}

// Initialize
GraphComponent.getInstance('#dynamic-graph');
</script>

8. From HTML Table

<table id="sales-data" style="display: none;">
  <thead>
    <tr>
      <th></th>
      <th>Jan</th>
      <th>Feb</th>
      <th>Mar</th>
      <th>Apr</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Product A</th>
      <td>100</td>
      <td>120</td>
      <td>150</td>
      <td>140</td>
    </tr>
    <tr>
      <th>Product B</th>
      <td>80</td>
      <td>90</td>
      <td>110</td>
      <td>100</td>
    </tr>
  </tbody>
</table>

<div data-component="graph"
     data-type="line"
     data-table="sales-data"
     style="width: 800px; height: 400px;">
</div>

9. Event-Driven Refresh

<div id="orders-graph"
     data-component="graph"
     data-type="bar"
     data-url="/api/orders/daily"
     data-refresh-event="order:created"
     style="width: 600px; height: 400px;">
</div>

<script>
// Somewhere in your app when order is created
async function createOrder(orderData) {
  await fetch('/api/orders', {
    method: 'POST',
    body: JSON.stringify(orderData),
    headers: {'Content-Type': 'application/json'}
  });

  // Trigger graph refresh
  EventManager.emit('order:created');
}
</script>

10. Export Graph

<div id="export-graph"
     data-component="graph"
     data-type="line"
     data-url="/api/analytics"
     style="width: 800px; height: 400px;">
</div>

<button onclick="exportGraph()">Export as PNG</button>
<button onclick="exportGraphJPEG()">Export as JPEG</button>
<button onclick="exportGraphSVG()">Export as SVG</button>

<script>
function exportGraph() {
  const instance = GraphComponent.getInstance('#export-graph');
  instance.exportToImage('analytics-chart', 'png');
}

function exportGraphJPEG() {
  const instance = GraphComponent.getInstance('#export-graph');
  instance.exportToImage('analytics-chart', 'jpeg', 1920, 1080, 0.95);
}

function exportGraphSVG() {
  const instance = GraphComponent.getInstance('#export-graph');
  instance.exportToImage('analytics-chart', 'svg');
}
</script>

API Reference

Methods

// Create & Initialize
create(element: HTMLElement|string, options?: object): Promise<Instance>
init(options?: object): Promise<GraphComponent>

// Get Instance
getInstance(element: HTMLElement|string): Instance|null

// Data Operations
setData(instance: Instance, data: Array): void
loadData(instance: Instance, url?: string): Promise<any>
addDataPoint(instance: Instance, point: object, seriesIndex?: number): void
refresh(instance: Instance): void

// Type & Display
setType(instance: Instance, type: string): void
exportToImage(instance: Instance, filename?: string, format?: string, width?: number, height?: number, quality?: number, scale?: number): void

// Polling
startPolling(instance: Instance): void
stopPolling(instance: Instance): void

// Lifecycle
destroy(instance: Instance|string|HTMLElement): boolean
destroyAll(): void

Instance Properties

{
  id: string,
  element: HTMLElement,
  options: object,
  data: array|null,
  state: {
    loading: boolean,
    error: string|null,
    rendered: boolean,
    width: number,
    height: number
  },
  renderer: object|null,
  timer: number|null
}

Instance Methods

instance.setData(data: Array): void
instance.loadData(url?: string): Promise<any>
instance.addDataPoint(point: object, seriesIndex?: number): void
instance.setType(type: string): void
instance.refresh(): void
instance.exportToImage(filename?: string, format?: string, ...): void
instance.destroy(): void

Best Practices

1. ✅ Set Container Size

<!-- ❌ ไม่ดี: ไม่กำหนดขนาด -->
<div data-component="graph" data-url="/api/data"></div>

<!-- ✅ ดี: กำหนดขนาดชัดเจน -->
<div data-component="graph"
     data-url="/api/data"
     style="width: 800px; height: 400px;">
</div>

2. ✅ Choose Appropriate Chart Type

// Line Chart - สำหรับแนวโน้มตามเวลา
{type: 'line', data: timeSeriesData}

// Bar Chart - สำหรับเปรียบเทียบ
{type: 'bar', data: comparisonData}

// Pie/Donut - สำหรับสัดส่วน
{type: 'pie', data: proportionData}

// Gauge - สำหรับค่าเดียว
{type: 'gauge', data: singleValueData}

3. ✅ Limit Data Points for Performance

<!-- ✅ ดี: จำกัด data points -->
<div data-component="graph"
     data-url="/api/realtime"
     data-max-data-points="50"
     data-polling-interval="5000">
</div>

4. ✅ Use Appropriate Polling Interval

<!-- ❌ ไม่ดี: Polling ทุก 1 วินาที -->
<div data-polling-interval="1000"></div>

<!-- ✅ ดี: Polling ทุก 30 วินาที -->
<div data-polling-interval="30000"></div>

5. ✅ Handle Loading States

element.addEventListener('graph:loading', () => {
  showLoadingSpinner();
});

element.addEventListener('graph:loaded', () => {
  hideLoadingSpinner();
});

element.addEventListener('graph:error', (e) => {
  showError(e.detail.error);
});

6. ✅ Cleanup When Removing

// ✅ ดี: Destroy instance เมื่อไม่ใช้แล้ว
const instance = GraphComponent.getInstance('#my-graph');
GraphComponent.destroy(instance);

7. ✅ Use Responsive Design

/* ✅ ดี: ใช้ responsive container */
.graph-container {
  width: 100%;
  max-width: 800px;
  height: 400px;
}

8. ✅ Provide Meaningful Labels

// ✅ ดี: Label ชัดเจน
const data = [
  {
    name: 'Monthly Revenue',
    data: [
      {label: 'January 2024', value: 100000},
      {label: 'February 2024', value: 120000}
    ]
  }
];

9. ✅ Use Color Schemes Consistently

// ✅ ดี: ใช้ color scheme ที่สอดคล้อง
const colors = [
  '#2196F3', // Primary
  '#4CAF50', // Success
  '#FFC107', // Warning
  '#F44336'  // Danger
];

10. ✅ Test with Different Data Sizes

// ✅ ดี: ทดสอบกับข้อมูลหลายขนาด
// - Empty data
// - Single data point
// - Normal dataset (10-50 points)
// - Large dataset (100+ points)

สรุป

เมื่อไหร่ควรใช้ GraphComponent

Key Features