@inglorious/charts 1.0.1

package/src/utils/cartesian-layout.js

@@ -0,0 +1,164 @@
+/**
+ * Cartesian layout utilities
+ * Common layout logic for cartesian charts (area, line, bar)
+ */
+
+import { html, svg } from "@inglorious/web"
+
+import { renderBrush } from "../component/brush.js"
+import { renderEmptyState } from "../component/empty-state.js"
+import { renderGrid } from "../component/grid.js"
+import { renderLegend } from "../component/legend.js"
+import { renderTooltip } from "../component/tooltip.js"
+import { renderXAxis } from "../component/x-axis.js"
+import { renderYAxis } from "../component/y-axis.js"
+import { isMultiSeries } from "./data-utils.js"
+import { createCartesianContext } from "./scales.js"
+import { createTooltipMoveHandler } from "./tooltip-handlers.js"
+
+/**
+ * Renders the common cartesian chart layout
+ * @param {any} entity - Chart entity
+ * @param {Object} props
+ * @param {string} props.chartType - Chart type ("area", "line", "bar")
+ * @param {import('lit-html').TemplateResult} props.chartContent - Chart-specific content (areas, lines, bars)
+ * @param {boolean} [props.showLegend] - Whether to show legend (defaults to entity.showLegend for multi-series)
+ * @param {import('@inglorious/web').Api} api - Web API instance
+ * @returns {import('lit-html').TemplateResult} Complete chart HTML
+ */
+export function renderCartesianLayout(entity, props, api) {
+  const { chartType, chartContent, showLegend = undefined } = props || {}
+  // Check for empty state
+  // eslint-disable-next-line no-magic-numbers
+  if (!entity.data || entity.data.length === 0) {
+    return html`
+      <div class="iw-chart">
+        ${renderEmptyState(
+          entity,
+          {
+            width: entity.width,
+            height: entity.height,
+          },
+          api,
+        )}
+      </div>
+    `
+  }
+
+  // Check if brush is enabled and adjust height accordingly
+  // eslint-disable-next-line no-magic-numbers
+  const brushHeight = entity.brush?.enabled ? 60 : 0
+  // eslint-disable-next-line no-magic-numbers
+  const chartHeight = entity.height || 400
+  const totalHeight = chartHeight + brushHeight
+
+  // Create context with scales and dimensions
+  const context = createCartesianContext(entity, chartType)
+  let { xScale, yScale, dimensions } = context
+  const { width, height, padding } = dimensions
+
+  // Apply zoom if brush is enabled (similar to composition mode)
+  if (entity.brush?.enabled && entity.brush.startIndex !== undefined) {
+    const { startIndex, endIndex } = entity.brush
+    xScale = xScale.copy().domain([startIndex, endIndex])
+  }
+
+  // Independent components - declarative composition
+  const grid = entity.showGrid
+    ? renderGrid(
+        entity,
+        {
+          xScale,
+          yScale,
+          width,
+          height,
+          padding,
+        },
+        api,
+      )
+    : svg``
+
+  const xAxis = renderXAxis(
+    entity,
+    {
+      xScale,
+      yScale,
+      width,
+      height,
+      padding,
+    },
+    api,
+  )
+
+  const yAxis = renderYAxis(
+    entity,
+    {
+      yScale,
+      height,
+      padding,
+    },
+    api,
+  )
+
+  // Legend - only for multiple series
+  const shouldShowLegend =
+    showLegend !== undefined
+      ? showLegend
+      : isMultiSeries(entity.data) && entity.showLegend
+  const legend = shouldShowLegend
+    ? renderLegend(
+        entity,
+        {
+          series: entity.data,
+          colors: entity.colors,
+          width,
+          padding,
+        },
+        api,
+      )
+    : svg``
+
+  // Brush - render if enabled in config mode
+  const brush = entity.brush?.enabled
+    ? renderBrush(
+        entity,
+        {
+          xScale,
+          width,
+          height,
+          padding,
+          // eslint-disable-next-line no-magic-numbers
+          brushHeight: entity.brush.height || 30,
+          dataKey: entity.dataKey || "name",
+        },
+        api,
+      )
+    : svg``
+
+  // SVG container
+  const svgContent = svg`
+    <svg
+      width=${width}
+      height=${totalHeight}
+      viewBox="0 0 ${width} ${totalHeight}"
+      class="iw-chart-svg"
+      @mousemove=${createTooltipMoveHandler({ entity, api })}
+    >
+      ${grid}
+      ${xAxis}
+      ${yAxis}
+      ${chartContent}
+      ${legend}
+      ${brush}
+    </svg>
+  `
+
+  return html`
+    <div
+      class="iw-chart"
+      style="display: block; margin: 0; padding: 0; position: relative; width: 100%; box-sizing: border-box;"
+    >
+      ${svgContent} ${renderTooltip(entity, {}, api)}
+    </div>
+  `
+}

package/src/utils/chart-utils.js

@@ -0,0 +1,30 @@
+/**
+ * Chart utilities
+ * Functions for chart creation and configuration
+ */
+
+import { area } from "../cartesian/area.js"
+import { bar } from "../cartesian/bar.js"
+import { line } from "../cartesian/line.js"
+import * as handlers from "../handlers.js"
+import { donut } from "../polar/donut.js"
+import { pie } from "../polar/pie.js"
+import { render } from "../template.js"
+
+export const areaChart = combineRenderer(area)
+export const barChart = combineRenderer(bar)
+export const lineChart = combineRenderer(line)
+export const pieChart = combineRenderer(pie)
+export const donutChart = combineRenderer(donut)
+
+// Export chart object for declarative helpers (composition style)
+export { chart } from "../index.js"
+
+/**
+ * Combines handlers, template, and chart-specific renderer into a complete chart type.
+ * @param {Object} chartRenderer - Chart-specific renderer (e.g., { renderChart })
+ * @returns {Object} Combined chart object with handlers, template, and renderer methods
+ */
+function combineRenderer(chartRenderer) {
+  return { ...handlers, render, ...chartRenderer }
+}

package/src/utils/colors.js

@@ -0,0 +1,77 @@
+/* eslint-disable no-magic-numbers */
+
+const DEFAULT_COLORS = ["#3b82f6", "#ef4444", "#10b981", "#f59e0b", "#8b5cf6"]
+
+const EXTENDED_COLORS = [
+  "#3b82f6",
+  "#ef4444",
+  "#10b981",
+  "#f59e0b",
+  "#8b5cf6",
+  "#ec4899",
+  "#06b6d4",
+  "#84cc16",
+  "#f97316",
+  "#6366f1",
+  "#14b8a6",
+  "#a855f7",
+  "#eab308",
+  "#22c55e",
+  "#3b82f6",
+  "#64748b",
+  "#f43f5e",
+  "#8b5cf6",
+  "#0ea5e9",
+  "#06b6d4",
+  "#10b981",
+  "#f59e0b",
+  "#ef4444",
+  "#6366f1",
+  "#ec4899",
+  "#14b8a6",
+]
+
+/**
+ * @param {number} count
+ * @param {string[]} [customColors]
+ * @returns {string[]}
+ */
+export function generateColors(count, customColors = null) {
+  const baseColors = customColors || EXTENDED_COLORS
+
+  if (count <= baseColors.length) {
+    return baseColors.slice(0, count)
+  }
+
+  const colors = [...baseColors]
+  const needed = count - baseColors.length
+
+  for (let i = 0; i < needed; i++) {
+    const baseIndex = i % baseColors.length
+    const baseColor = baseColors[baseIndex]
+    const variation = Math.floor(i / baseColors.length) + 1
+
+    const hex = baseColor.replace("#", "")
+    const r = parseInt(hex.substr(0, 2), 16)
+    const g = parseInt(hex.substr(2, 2), 16)
+    const b = parseInt(hex.substr(4, 2), 16)
+
+    const factor = 0.7 + variation * 0.1
+    const newR = Math.min(255, Math.floor(r * factor))
+    const newG = Math.min(255, Math.floor(g * factor))
+    const newB = Math.min(255, Math.floor(b * factor))
+
+    colors.push(
+      `#${newR.toString(16).padStart(2, "0")}${newG.toString(16).padStart(2, "0")}${newB.toString(16).padStart(2, "0")}`,
+    )
+  }
+
+  return colors
+}
+
+/**
+ * @returns {string[]}
+ */
+export function getDefaultColors() {
+  return [...DEFAULT_COLORS]
+}

package/src/utils/data-utils.js

@@ -0,0 +1,155 @@
+/* eslint-disable no-magic-numbers */
+
+/**
+ * Data utilities
+ * Functions for data manipulation and formatting
+ */
+
+import { format } from "d3-format"
+import { timeFormat } from "d3-time-format"
+
+/**
+ * Format a number with the specified format
+ * @param {number} value - Number to format
+ * @param {string} [fmt] - Format string (d3-format syntax). If not provided, uses smart formatting (integers without decimals)
+ * @returns {string} Formatted number string
+ */
+export function formatNumber(value, fmt) {
+  if (fmt) {
+    return format(fmt)(value)
+  }
+  // Smart formatting: if integer, show without decimals; otherwise show 2 decimals
+  if (Number.isInteger(value)) {
+    return format(",")(value) // No decimals for integers
+  }
+  return format(",.2f")(value) // 2 decimals for non-integers
+}
+
+/**
+ * Format a date with the specified format
+ * @param {Date|string|number} date - Date to format
+ * @param {string} [fmt="%Y-%m-%d"] - Format string (d3-time-format syntax)
+ * @returns {string} Formatted date string
+ */
+export function formatDate(date, fmt = "%Y-%m-%d") {
+  return timeFormat(fmt)(new Date(date))
+}
+
+/**
+ * Gets values from a series object
+ * @param {any} series - Series object that may have a values array or be a single value
+ * @returns {any[]} Array of values
+ */
+export function getSeriesValues(series) {
+  return Array.isArray(series.values) ? series.values : [series]
+}
+
+/**
+ * Checks if the data represents multiple series
+ * @param {any[]} data - Chart data array
+ * @returns {boolean} True if data represents multiple series (has values array)
+ */
+export function isMultiSeries(data) {
+  return (
+    Array.isArray(data) && data.length > 0 && Array.isArray(data[0]?.values)
+  )
+}
+
+/**
+ * Gets the X coordinate value from a data point
+ * @param {any} d - Data point object
+ * @param {any} [fallback=0] - Fallback value if x/date is not found
+ * @returns {any} X coordinate value (x, date, or fallback)
+ */
+export function getDataPointX(d, fallback = 0) {
+  return d?.x ?? d?.date ?? fallback
+}
+
+/**
+ * Gets the Y coordinate value from a data point
+ * @param {any} d - Data point object
+ * @param {any} [fallback=0] - Fallback value if y/value is not found
+ * @returns {any} Y coordinate value (y, value, or fallback)
+ */
+export function getDataPointY(d, fallback = 0) {
+  return d?.y ?? d?.value ?? fallback
+}
+
+/**
+ * Gets the label from a data point
+ * @param {any} d - Data point object
+ * @param {string} [fallback="Value"] - Fallback label if x/date is not found
+ * @returns {string} Label value (x, date, or fallback)
+ */
+export function getDataPointLabel(d, fallback = "Value") {
+  return d?.x ?? d?.date ?? fallback
+}
+
+/**
+ * Checks if a value is a valid number (not NaN and finite)
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a valid number
+ */
+export function isValidNumber(value) {
+  return typeof value === "number" && !isNaN(value) && isFinite(value)
+}
+
+/**
+ * Ensures a value is a valid number, returning a fallback if not
+ * @param {any} value - Value to validate
+ * @param {number} [fallback=0] - Fallback value if validation fails
+ * @returns {number} Valid number value
+ */
+export function ensureValidNumber(value, fallback = 0) {
+  return isValidNumber(value) ? value : fallback
+}
+
+/**
+ * Transforms entity data to standardized format with x, y, and name properties.
+ * Used for rendering lines and areas in composition mode.
+ *
+ * @param {any} entity - Chart entity with data
+ * @param {string} dataKey - Data key to extract values from
+ * @returns {Array|null} Transformed data array or null if entity/data is invalid
+ */
+export function getTransformedData(entity, dataKey) {
+  if (!entity || !entity.data) return null
+
+  // Transform data to use indices for x (like Recharts does with categorical data)
+  // Ensure y is always a valid number (handles negatives, NaN, etc.)
+  return entity.data.map((d, i) => {
+    const yValue =
+      d[dataKey] !== undefined
+        ? d[dataKey]
+        : d.y !== undefined
+          ? d.y
+          : d.value !== undefined
+            ? d.value
+            : 0
+    const y = typeof yValue === "number" && !isNaN(yValue) ? yValue : 0
+
+    return {
+      x: i, // Use index for positioning
+      y,
+      name: d[dataKey] || d.name || d.x || d.date || i, // Keep name for labels
+    }
+  })
+}
+
+/**
+ * Parses a dimension value (width/height) from config or entity
+ * Returns numeric value if possible, undefined otherwise
+ * @param {number|string|undefined} value - Dimension value to parse
+ * @returns {number|undefined} Parsed numeric value or undefined
+ */
+export function parseDimension(value) {
+  if (typeof value === "number") return value
+  if (typeof value === "string") {
+    // Try to parse as number (e.g., "800" -> 800)
+    const num = parseFloat(value)
+    if (!isNaN(num) && !value.includes("%") && !value.includes("px")) {
+      return num
+    }
+  }
+  return undefined
+}

package/src/utils/data-utils.test.js

@@ -0,0 +1,210 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, expect, it } from "vitest"
+
+import {
+  ensureValidNumber,
+  formatDate,
+  formatNumber,
+  getDataPointLabel,
+  getDataPointX,
+  getDataPointY,
+  getSeriesValues,
+  getTransformedData,
+  isMultiSeries,
+  isValidNumber,
+  parseDimension,
+} from "./data-utils.js"
+
+describe("data-utils", () => {
+  describe("formatNumber", () => {
+    it("should format number with default format", () => {
+      expect(formatNumber(1234.56)).toBe("1,234.56")
+    })
+
+    it("should format number with custom format", () => {
+      expect(formatNumber(1234.56, ".0f")).toBe("1235")
+    })
+  })
+
+  describe("formatDate", () => {
+    it("should format date with default format", () => {
+      const date = new Date("2024-01-15")
+      const result = formatDate(date)
+      expect(result).toContain("2024")
+    })
+
+    it("should format date with custom format", () => {
+      const date = new Date("2024-01-15")
+      const result = formatDate(date, "%Y-%m-%d")
+      expect(result).toBe("2024-01-15")
+    })
+  })
+
+  describe("getSeriesValues", () => {
+    it("should return values array if present", () => {
+      const series = { name: "Series A", values: [{ x: 0, y: 10 }] }
+      expect(getSeriesValues(series)).toEqual([{ x: 0, y: 10 }])
+    })
+
+    it("should wrap single value in array", () => {
+      const series = { x: 0, y: 10 }
+      expect(getSeriesValues(series)).toEqual([{ x: 0, y: 10 }])
+    })
+  })
+
+  describe("isMultiSeries", () => {
+    it("should return true for multi-series data", () => {
+      const data = [
+        { name: "Series A", values: [{ x: 0, y: 10 }] },
+        { name: "Series B", values: [{ x: 0, y: 20 }] },
+      ]
+      expect(isMultiSeries(data)).toBe(true)
+    })
+
+    it("should return false for single series data", () => {
+      const data = [
+        { x: 0, y: 10 },
+        { x: 1, y: 20 },
+      ]
+      expect(isMultiSeries(data)).toBe(false)
+    })
+
+    it("should return false for empty array", () => {
+      expect(isMultiSeries([])).toBe(false)
+    })
+  })
+
+  describe("getDataPointX", () => {
+    it("should return x value if present", () => {
+      expect(getDataPointX({ x: 5 })).toBe(5)
+    })
+
+    it("should return date value if x is not present", () => {
+      expect(getDataPointX({ date: "2024-01-01" })).toBe("2024-01-01")
+    })
+
+    it("should return fallback if neither x nor date present", () => {
+      expect(getDataPointX({ value: 10 }, 0)).toBe(0)
+    })
+  })
+
+  describe("getDataPointY", () => {
+    it("should return y value if present", () => {
+      expect(getDataPointY({ y: 100 })).toBe(100)
+    })
+
+    it("should return value if y is not present", () => {
+      expect(getDataPointY({ value: 200 })).toBe(200)
+    })
+
+    it("should return fallback if neither y nor value present", () => {
+      expect(getDataPointY({ name: "Jan" }, 0)).toBe(0)
+    })
+  })
+
+  describe("getDataPointLabel", () => {
+    it("should return x value if present", () => {
+      expect(getDataPointLabel({ x: "Jan" })).toBe("Jan")
+    })
+
+    it("should return date value if x is not present", () => {
+      expect(getDataPointLabel({ date: "2024-01-01" })).toBe("2024-01-01")
+    })
+
+    it("should return fallback if neither x nor date present", () => {
+      expect(getDataPointLabel({ value: 10 }, "Value")).toBe("Value")
+    })
+  })
+
+  describe("isValidNumber", () => {
+    it("should return true for valid numbers", () => {
+      expect(isValidNumber(100)).toBe(true)
+      expect(isValidNumber(0)).toBe(true)
+      expect(isValidNumber(-50)).toBe(true)
+      expect(isValidNumber(3.14)).toBe(true)
+    })
+
+    it("should return false for invalid numbers", () => {
+      expect(isValidNumber(NaN)).toBe(false)
+      expect(isValidNumber(Infinity)).toBe(false)
+      expect(isValidNumber("100")).toBe(false)
+      expect(isValidNumber(null)).toBe(false)
+      expect(isValidNumber(undefined)).toBe(false)
+    })
+  })
+
+  describe("ensureValidNumber", () => {
+    it("should return value if valid", () => {
+      expect(ensureValidNumber(100)).toBe(100)
+    })
+
+    it("should return fallback if invalid", () => {
+      expect(ensureValidNumber(NaN, 0)).toBe(0)
+      expect(ensureValidNumber("100", 0)).toBe(0)
+    })
+  })
+
+  describe("parseDimension", () => {
+    it("should return number if already a number", () => {
+      expect(parseDimension(800)).toBe(800)
+    })
+
+    it("should parse numeric string", () => {
+      expect(parseDimension("800")).toBe(800)
+    })
+
+    it("should return undefined for percentage strings", () => {
+      expect(parseDimension("100%")).toBeUndefined()
+    })
+
+    it("should return undefined for pixel strings", () => {
+      expect(parseDimension("800px")).toBeUndefined()
+    })
+
+    it("should return undefined for non-numeric strings", () => {
+      expect(parseDimension("auto")).toBeUndefined()
+    })
+  })
+
+  describe("getTransformedData", () => {
+    it("should transform data with dataKey", () => {
+      const entity = {
+        id: "test",
+        data: [
+          { name: "Jan", value: 100 },
+          { name: "Feb", value: 200 },
+        ],
+      }
+
+      const result = getTransformedData(entity, "value")
+
+      // When dataKey exists, name fallback uses d[dataKey] first, then d.name
+      // So name will be the value (100, 200) if dataKey exists
+      expect(result).toEqual([
+        { x: 0, y: 100, name: 100 },
+        { x: 1, y: 200, name: 200 },
+      ])
+    })
+
+    it("should fallback to y or value if dataKey not found", () => {
+      const entity = {
+        id: "test",
+        data: [{ name: "Jan", y: 100 }],
+      }
+
+      const result = getTransformedData(entity, "missingKey")
+
+      expect(result).toEqual([{ x: 0, y: 100, name: "Jan" }])
+    })
+
+    it("should return null if entity is missing", () => {
+      expect(getTransformedData(null, "value")).toBeNull()
+    })
+
+    it("should return null if entity.data is missing", () => {
+      expect(getTransformedData({ id: "test" }, "value")).toBeNull()
+    })
+  })
+})

package/src/utils/extract-data-keys.js

@@ -0,0 +1,22 @@
+/**
+ * Extracts dataKeys from chart children components automatically.
+ * This allows the chart to determine which data fields to use for Y-axis scaling
+ * without requiring explicit dataKeys configuration.
+ *
+ * @param {Array|Function} children - Array of chart child components (Line, Area, Bar, etc.)
+ * @returns {Array<string>} Array of unique dataKeys found in the children
+ */
+export function extractDataKeysFromChildren(children) {
+  const dataKeys = new Set()
+  const childrenArray = Array.isArray(children) ? children : [children]
+
+  for (const child of childrenArray) {
+    if (typeof child === "function") {
+      if (child.dataKey) {
+        dataKeys.add(child.dataKey)
+      }
+    }
+  }
+
+  return Array.from(dataKeys)
+}

package/src/utils/padding.js

@@ -0,0 +1,16 @@
+/* eslint-disable no-magic-numbers */
+
+/**
+ * Calculate padding based on chart dimensions
+ * @param {number} [width=800] - Chart width
+ * @param {number} [height=400] - Chart height
+ * @returns {Object} Padding object with top, right, bottom, left
+ */
+export function calculatePadding(width = 800, height = 400) {
+  return {
+    top: Math.max(20, height * 0.05),
+    right: Math.max(20, width * 0.05),
+    bottom: Math.max(40, height * 0.1),
+    left: Math.max(50, width * 0.1),
+  }
+}