@inglorious/charts 1.0.1

package/src/component/brush.js

@@ -0,0 +1,264 @@
+/* eslint-disable no-magic-numbers */
+import { svg } from "@inglorious/web"
+
+import { isValidNumber } from "../utils/data-utils.js"
+import { createXScale } from "../utils/scales.js"
+
+/**
+ * Brush Component - allows zooming and panning on cartesian charts
+ * Similar to Recharts Brush component
+ *
+ * @param {any} entity - Chart entity
+ * @param {Object} props
+ * @param {import('d3-scale').ScaleLinear|import('d3-scale').ScaleTime|import('d3-scale').ScaleBand} props.xScale - X scale
+ * @param {number} props.width - Chart width
+ * @param {number} props.height - Chart height
+ * @param {Object} props.padding - Chart padding
+ * @param {number} [props.height=30] - Brush height (default 30)
+ * @param {string} [props.dataKey] - Data key for X axis
+ * @param {any} api - Web API instance
+ * @returns {import('lit-html').TemplateResult}
+ */
+export function renderBrush(entity, props, api) {
+  // Note: xScale from props is not used - we create our own brushXScale
+  // to ensure it always represents the full unfiltered data
+  const { width, height, padding, brushHeight = 30 } = props
+
+  // CRITICAL: Use original entity data for brush calculations
+  // In Config mode, entity may have filtered data, but brush needs original data
+  // The createBrushComponent already passes ctx.fullEntity which has original data
+  // But we need to ensure entity.brush is on the correct entity (the one with original data)
+  // For brush state management, we need to use the entity that has the brush state
+  // This is typically the original entity, not the filtered one
+
+  // Initialize state: ensures we have a valid selection range on first render
+  if (!entity.brush) {
+    entity.brush = {
+      startIndex: 0,
+      endIndex: entity.data ? entity.data.length - 1 : 0,
+      enabled: true,
+    }
+  }
+
+  // Ensure brush.enabled is true if brush exists
+  if (entity.brush && entity.brush.enabled === undefined) {
+    entity.brush.enabled = true
+  }
+
+  // Ensure startIndex and endIndex are defined
+  if (
+    entity.brush.startIndex === undefined ||
+    entity.brush.endIndex === undefined
+  ) {
+    entity.brush.startIndex = 0
+    entity.brush.endIndex = entity.data ? entity.data.length - 1 : 0
+  }
+
+  if (!entity.brush.enabled || !entity.data || entity.data.length === 0) {
+    return svg``
+  }
+
+  // Use entity.data directly - this should be original data from ctx.fullEntity
+  const brushData = entity.data
+  const brushAreaWidth = width - padding.left - padding.right
+  const brushAreaX = padding.left
+
+  // Refined positioning: ensure it stays below the main chart area
+  // Position brush at the bottom of the SVG, just below the main chart
+  // The main chart ends at `height`, so brush should start right after it
+  // Use height (chart height) as the base, not totalHeight
+  const brushY = height
+
+  // CRITICAL: Create a "clean" fixed scale for the Brush based on TOTAL data
+  // The xScale from props may have a filtered domain (zoom applied)
+  // The Brush always needs a scale that represents the full unfiltered data
+  // This prevents the Brush from "jumping" when the chart is zoomed
+  // Always use index-based scale for brush (simpler and more reliable)
+  const brushXScale = createXScale(brushData, width, padding)
+  // IMPORTANT: Force domain to always be the full index range [0, length-1]
+  // This ensures the Brush scale is completely independent of the chart's zoom
+  brushXScale.domain([0, brushData.length - 1])
+
+  /** Maps data index to pixel X coordinate */
+  // Simplified: since brushXScale.domain is always [0, length-1], we can directly use the index
+  const getXPosition = (index) => {
+    const safeIndex = Math.max(0, Math.min(index, brushData.length - 1))
+    // brushXScale is always linear with domain [0, length-1], so we can use index directly
+    return brushXScale(safeIndex)
+  }
+
+  const startX = getXPosition(entity.brush.startIndex)
+  const endX = getXPosition(entity.brush.endIndex)
+
+  if (!isValidNumber(startX) || !isValidNumber(endX)) {
+    return svg``
+  }
+
+  // Visual width of the selection area
+  const brushWidth = endX - startX
+
+  const handleMouseDown = (e, action) => {
+    e.preventDefault()
+    e.stopPropagation()
+
+    const svgElement = e.currentTarget.closest("svg")
+    if (!svgElement) return
+
+    const svgRect = svgElement.getBoundingClientRect()
+    const startMouseX = e.clientX - svgRect.left
+
+    // Snapshots: Capture current state at the start of interaction to prevent "drifting"
+    const initialStartIndex = entity.brush.startIndex
+    const initialEndIndex = entity.brush.endIndex
+    const selectionSize = initialEndIndex - initialStartIndex
+    const totalIndices = brushData.length - 1
+
+    const handleMouseMove = (moveEvent) => {
+      const currentMouseX = moveEvent.clientX - svgRect.left
+      // Important: deltaX is the mouse movement in pixels since the start of drag
+      const deltaX = currentMouseX - startMouseX
+
+      if (action === "pan") {
+        // 1. Calculate how much the mouse moved in pixels
+        // 2. Transform pixel movement into "index delta" using the real proportion
+        // Uses percentage of displacement relative to the total Brush area
+        // This is mathematically more stable than pixelsPerIndex
+        const indexDelta = Math.round((deltaX / brushAreaWidth) * totalIndices)
+
+        let nextStart = initialStartIndex + indexDelta
+        let nextEnd = initialEndIndex + indexDelta
+
+        // 3. Clamping (lock the limits)
+        if (nextStart < 0) {
+          nextStart = 0
+          nextEnd = selectionSize
+        }
+        if (nextEnd > totalIndices) {
+          nextEnd = totalIndices
+          nextStart = totalIndices - selectionSize
+        }
+
+        // Only notify if indices actually changed to optimize rendering
+        if (
+          nextStart !== entity.brush.startIndex ||
+          nextEnd !== entity.brush.endIndex
+        ) {
+          entity.brush.startIndex = nextStart
+          entity.brush.endIndex = nextEnd
+          api.notify(`#${entity.id}:update`)
+        }
+      } else if (action === "resize-left" || action === "resize-right") {
+        // For resize, we use the same proportion logic as pan
+        // This avoids index "jumps" when the user clicks on the handle
+        // Calculates the movement delta in indices and applies it to the initial index
+        const indexDelta = Math.round((deltaX / brushAreaWidth) * totalIndices)
+
+        if (action === "resize-left") {
+          // Keep endIndex fixed and move only startIndex
+          let nextStart = initialStartIndex + indexDelta
+
+          // Clamping: cannot be less than 0 nor greater than endIndex
+          if (nextStart < 0) {
+            nextStart = 0
+          } else if (nextStart >= initialEndIndex) {
+            nextStart = initialEndIndex - 1
+          }
+
+          if (nextStart !== entity.brush.startIndex) {
+            entity.brush.startIndex = nextStart
+            api.notify(`#${entity.id}:update`)
+          }
+        } else {
+          // resize-right: keep startIndex fixed and move only endIndex
+          let nextEnd = initialEndIndex + indexDelta
+
+          // Clamping: cannot be greater than totalIndices nor less than startIndex
+          if (nextEnd > totalIndices) {
+            nextEnd = totalIndices
+          } else if (nextEnd <= initialStartIndex) {
+            nextEnd = initialStartIndex + 1
+          }
+
+          if (nextEnd !== entity.brush.endIndex) {
+            entity.brush.endIndex = nextEnd
+            api.notify(`#${entity.id}:update`)
+          }
+        }
+      }
+    }
+
+    const handleMouseUp = () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+    }
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+  }
+
+  const result = svg`
+    <g class="iw-chart-brush" transform="translate(0, ${brushY})">
+      <rect x=${brushAreaX} y=0 width=${brushAreaWidth} height=${brushHeight} fill="#f5f5f5" stroke="#ddd" />
+      
+      <g class="iw-chart-brush-preview" style="pointer-events: none;">
+        <path
+          d="${brushData
+            .map((d, i) => {
+              const x = getXPosition(i)
+              const value = d.value ?? d.y ?? 0
+              const maxValue =
+                Math.max(...brushData.map((dd) => dd.value ?? dd.y ?? 0)) || 1
+              const y = brushHeight - 2 - (value / maxValue) * (brushHeight - 4)
+              return `M${x},${brushHeight - 2} L${x},${y}`
+            })
+            .join(" ")}"
+          stroke="#8884d8" stroke-width="1" opacity="0.3"
+        />
+      </g>
+
+      <rect x=${startX} y=2 width=${brushWidth} height=${brushHeight - 4} fill="#8884d8" fill-opacity="0.3" stroke="#8884d8" 
+            style="cursor: move;" @mousedown=${(e) => handleMouseDown(e, "pan")} />
+      
+      <rect x=${startX - 4} y=0 width=8 height=${brushHeight} fill="#8884d8" stroke="#fff" 
+            style="cursor: ew-resize;" @mousedown=${(e) => handleMouseDown(e, "resize-left")} />
+      <rect x=${endX - 4} y=0 width=8 height=${brushHeight} fill="#8884d8" stroke="#fff" 
+            style="cursor: ew-resize;" @mousedown=${(e) => handleMouseDown(e, "resize-right")} />
+    </g>`
+
+  // Add identification flag to the result object
+  result.isBrush = true
+  return result
+}
+
+/**
+ * Creates the Brush component function
+ * * @param {Object} defaultConfig
+ * @returns {Function}
+ */
+export function createBrushComponent(defaultConfig = {}) {
+  return (entity, props, api) => {
+    const brushFn = (ctx) => {
+      const entityFromContext = ctx.fullEntity || ctx.entity || entity
+      const config = { ...defaultConfig, ...(props.config || {}) }
+
+      const result = renderBrush(
+        entityFromContext,
+        {
+          xScale: ctx.xScale,
+          ...ctx.dimensions,
+          totalHeight: ctx.totalHeight,
+          dataKey: config.dataKey || entityFromContext.dataKey || "name",
+          brushHeight: config.height || 30,
+        },
+        api,
+      )
+
+      // Ensure the returned TemplateResult also carries the flag
+      if (result) result.isBrush = true
+      return result
+    }
+
+    // Crucial for identification in Config Style mode
+    brushFn.isBrush = true
+    return brushFn
+  }
+}

package/src/component/empty-state.js

@@ -0,0 +1,33 @@
+import { svg } from "@inglorious/web"
+
+/**
+ * Renders an empty state message when there's no data
+ * @param {any} entity
+ * @param {Object} props
+ * @param {number} props.width - Chart width
+ * @param {number} props.height - Chart height
+ * @param {string} [props.message="No data"] - Message to display
+ * @param {any} api
+ * @returns {import('lit-html').TemplateResult}
+ */
+// eslint-disable-next-line no-unused-vars
+export function renderEmptyState(entity, props, api) {
+  const { width, height, message = "No data" } = props
+  return svg`
+    <svg
+      width=${width}
+      height=${height}
+      viewBox="0 0 ${width} ${height}"
+    >
+      <text
+        x="50%"
+        y="50%"
+        text-anchor="middle"
+        fill="#999"
+        font-size="0.875em"
+      >
+        ${message}
+      </text>
+    </svg>
+  `
+}

package/src/component/empty-state.test.js

@@ -0,0 +1,81 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render } from "@inglorious/web/test"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import { renderEmptyState } from "./empty-state.js"
+
+describe("renderEmptyState", () => {
+  let entity
+  let props
+  let api
+
+  beforeEach(() => {
+    entity = {
+      id: "test-chart",
+      type: "line",
+      data: [],
+      width: 800,
+      height: 400,
+    }
+
+    props = {
+      message: "No data available",
+    }
+
+    api = {
+      notify: vi.fn(),
+    }
+  })
+
+  describe("basic rendering", () => {
+    it("should render empty state message", () => {
+      props.width = 800
+      props.height = 400
+
+      const result = renderEmptyState(entity, props, api)
+      const container = document.createElement("div")
+      render(result, container)
+
+      const svg = container.querySelector("svg")
+      expect(svg).toBeTruthy()
+
+      const text = container.querySelector("text")
+      expect(text).toBeTruthy()
+      expect(text.textContent).toContain("No data available")
+    })
+
+    it("should use default message when not provided", () => {
+      props.width = 800
+      props.height = 400
+      delete props.message
+
+      const result = renderEmptyState(entity, props, api)
+      const container = document.createElement("div")
+      render(result, container)
+
+      const svg = container.querySelector("svg")
+      expect(svg).toBeTruthy()
+
+      const text = container.querySelector("text")
+      expect(text).toBeTruthy()
+      expect(text.textContent).toBeTruthy()
+    })
+  })
+
+  describe("with custom message", () => {
+    it("should render custom message", () => {
+      props.width = 800
+      props.height = 400
+      props.message = "Custom empty message"
+
+      const result = renderEmptyState(entity, props, api)
+      const container = document.createElement("div")
+      render(result, container)
+
+      const text = container.querySelector("text")
+      expect(text.textContent).toContain("Custom empty message")
+    })
+  })
+})

package/src/component/grid.js

@@ -0,0 +1,123 @@
+/* eslint-disable no-magic-numbers */
+
+import { repeat, svg } from "@inglorious/web"
+
+import { isValidNumber } from "../utils/data-utils.js"
+import { calculateXTicks } from "../utils/scales.js"
+
+/**
+ * Grid Component - renders independent grid
+ * Receives scales from context, does not decide layout
+ *
+ * @param {any} entity - Chart entity with data
+ * @param {Object} props
+ * @param {import('d3-scale').ScaleBand|import('d3-scale').ScaleLinear|import('d3-scale').ScaleTime} props.xScale
+ * @param {import('d3-scale').ScaleLinear} props.yScale
+ * @param {number} props.width
+ * @param {number} props.height
+ * @param {Object} props.padding
+ * @param {Array} props.customYTicks
+ * @param {any} api
+ * @returns {import('lit-html').TemplateResult}
+ */
+// eslint-disable-next-line no-unused-vars
+export function renderGrid(entity, props, api) {
+  const { xScale, yScale, width, height, padding, customYTicks } = props
+  // Use entity.data if available, otherwise fallback to scale ticks
+  const data = entity?.data
+
+  // For band scales (bar charts), limit ticks to match X-axis behavior
+  let xTicks
+  if (xScale.bandwidth) {
+    const allCategories = xScale.domain()
+    // Apply same limiting logic as renderXAxis to match grid with axis ticks
+    if (allCategories.length > 20) {
+      // Calculate optimal number of ticks based on available width
+      // Estimate ~60px per label to avoid overlap (same as X-axis)
+      const availableWidth =
+        (width || 800) - (padding?.left || 0) - (padding?.right || 0)
+      const maxTicks = Math.max(5, Math.floor(availableWidth / 60))
+      const step = Math.ceil(allCategories.length / maxTicks)
+      xTicks = allCategories.filter((_, i) => i % step === 0)
+    } else {
+      xTicks = allCategories
+    }
+  } else {
+    // For linear/time scales, use calculateXTicks (same as X-axis)
+    xTicks =
+      data && data.length > 0
+        ? calculateXTicks(data, xScale)
+        : xScale.ticks
+          ? xScale.ticks(5)
+          : xScale.domain()
+  }
+
+  // Use custom Y ticks if provided, otherwise use scale ticks
+  const yTicks =
+    customYTicks && Array.isArray(customYTicks) ? customYTicks : yScale.ticks(5)
+
+  return svg`
+    <g class="iw-chart-cartesian-grid">
+      <g class="iw-chart-cartesian-grid-horizontal">
+        ${repeat(
+          yTicks,
+          (t) => t,
+          (t) => {
+            const y = yScale(t)
+            return svg`
+              <line
+                stroke-dasharray="3 3"
+                stroke="#ccc"
+                fill="none"
+                x=${padding.left}
+                y=${padding.top}
+                width=${width - padding.left - padding.right}
+                height=${height - padding.top - padding.bottom}
+                x1=${padding.left}
+                y1=${y}
+                x2=${width - padding.right}
+                y2=${y}
+              />
+            `
+          },
+        )}
+      </g>
+      <g class="iw-chart-cartesian-grid-vertical">
+        ${repeat(
+          xTicks,
+          (t) => t,
+          (t) => {
+            // For band scales (bar charts), center the grid line in the middle of the band
+            // For linear/time scales, use the tick position directly
+            const x = xScale.bandwidth
+              ? xScale(t) + xScale.bandwidth() / 2
+              : xScale(t)
+            // Only render if x is a valid number within the range
+            if (
+              !isValidNumber(x) ||
+              x < padding.left ||
+              x > width - padding.right
+            ) {
+              return svg``
+            }
+            return svg`
+              <line
+                stroke-dasharray="3 3"
+                stroke="#ccc"
+                fill="none"
+                x=${padding.left}
+                y=${padding.top}
+                width=${width - padding.left - padding.right}
+                height=${height - padding.top - padding.bottom}
+                x1=${x}
+                y1=${padding.top}
+                x2=${x}
+                y2=${height - padding.bottom}
+              />
+            `
+          },
+        )}
+      </g>
+    </g>
+  `
+}

package/src/component/grid.test.js

@@ -0,0 +1,123 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render } from "@inglorious/web/test"
+import { describe, expect, it } from "vitest"
+
+import { renderGrid } from "./grid.js"
+
+describe("renderGrid", () => {
+  const mockApi = {}
+  const mockEntity = {
+    id: "test",
+    data: [
+      { x: 0, y: 10 },
+      { x: 1, y: 20 },
+      { x: 2, y: 30 },
+    ],
+  }
+
+  const createMockScales = () => {
+    const linearScale = (domain, range) => {
+      const scale = (value) => {
+        const [d0, d1] = domain
+        const [r0, r1] = range
+        return ((value - d0) / (d1 - d0)) * (r1 - r0) + r0
+      }
+      scale.domain = () => domain
+      scale.range = () => range
+      scale.ticks = (count) => {
+        const step = (domain[1] - domain[0]) / count
+        return Array.from({ length: count + 1 }, (_, i) => domain[0] + step * i)
+      }
+      return scale
+    }
+
+    return {
+      xScale: linearScale([0, 2], [50, 750]),
+      yScale: linearScale([0, 30], [350, 50]),
+    }
+  }
+
+  it("should render grid with horizontal and vertical lines", () => {
+    const { xScale, yScale } = createMockScales()
+    const props = {
+      xScale,
+      yScale,
+      width: 800,
+      height: 400,
+      padding: { top: 20, right: 50, bottom: 30, left: 50 },
+    }
+
+    const template = renderGrid(mockEntity, props, mockApi)
+    const container = document.createElement("div")
+    render(template, container)
+
+    const horizontalLines = container.querySelectorAll(
+      ".iw-chart-cartesian-grid-horizontal line",
+    )
+    const verticalLines = container.querySelectorAll(
+      ".iw-chart-cartesian-grid-vertical line",
+    )
+
+    expect(horizontalLines.length).toBeGreaterThan(0)
+    expect(verticalLines.length).toBeGreaterThan(0)
+  })
+
+  it("should use custom Y ticks if provided", () => {
+    const { xScale, yScale } = createMockScales()
+    const props = {
+      xScale,
+      yScale,
+      width: 800,
+      height: 400,
+      padding: { top: 20, right: 50, bottom: 30, left: 50 },
+      customYTicks: [0, 10, 20, 30],
+    }
+
+    const template = renderGrid(mockEntity, props, mockApi)
+    const container = document.createElement("div")
+    render(template, container)
+
+    const horizontalLines = container.querySelectorAll(
+      ".iw-chart-cartesian-grid-horizontal line",
+    )
+
+    expect(horizontalLines.length).toBe(4)
+  })
+
+  it("should handle band scale for X axis", () => {
+    const bandScale = (domain, range) => {
+      const [r0, r1] = range
+      const bandwidth = (r1 - r0) / domain.length
+      const scale = (value) => {
+        const index = domain.indexOf(value)
+        return r0 + index * bandwidth
+      }
+      scale.domain = () => domain
+      scale.range = () => range
+      scale.bandwidth = () => bandwidth
+      return scale
+    }
+
+    const { yScale } = createMockScales()
+    const xScale = bandScale(["A", "B", "C"], [50, 750])
+    const props = {
+      xScale,
+      yScale,
+      width: 800,
+      height: 400,
+      padding: { top: 20, right: 50, bottom: 30, left: 50 },
+    }
+
+    const template = renderGrid(mockEntity, props, mockApi)
+    const container = document.createElement("div")
+    render(template, container)
+
+    const verticalLines = container.querySelectorAll(
+      ".iw-chart-cartesian-grid-vertical line",
+    )
+
+    expect(verticalLines.length).toBeGreaterThan(0)
+  })
+})

package/src/component/legend.js

@@ -0,0 +1,76 @@
+/* eslint-disable no-magic-numbers */
+
+import { repeat, svg } from "@inglorious/web"
+
+/**
+ * Legend Component - renders independent legend
+ * Receives data and colors, does not decide layout
+ *
+ * @param {any} entity
+ * @param {Object} props
+ * @param {any[]} props.series
+ * @param {string[]} props.colors
+ * @param {number} props.width
+ * @param {Object} props.padding
+ * @param {any} api
+ * @returns {import('lit-html').TemplateResult}
+ */
+// eslint-disable-next-line no-unused-vars
+export function renderLegend(entity, props, api) {
+  const { series, colors, width, padding } = props
+  if (!series || series.length === 0) {
+    return svg``
+  }
+
+  const legendY = padding.top / 2
+  const squareSize = 12
+  const gap = 8
+  const itemGap = 40
+
+  const totalWidth = series.reduce((acc, s) => {
+    const label = s.name || s.label || `Series ${series.indexOf(s) + 1}`
+    return acc + squareSize + gap + label.length * 6 + itemGap
+  }, 0)
+
+  const startX = (width - totalWidth) / 2
+  let currentX = startX
+
+  return svg`
+    <g class="iw-chart-legend-wrapper">
+      ${repeat(
+        series,
+        (s, i) => i,
+        (s, i) => {
+          const color = s.color || colors[i % colors.length]
+          const label = s.name || s.label || `Series ${i + 1}`
+
+          const item = svg`
+            <g class="iw-chart-legend-item">
+              <rect
+                x=${currentX}
+                y=${legendY - squareSize / 2}
+                width=${squareSize}
+                height=${squareSize}
+                fill=${color}
+                rx="0.125em"
+                ry="0.125em"
+              />
+              <text
+                x=${currentX + squareSize + gap}
+                y=${legendY + 4}
+                text-anchor="start"
+                font-size="0.75em"
+                fill="#333"
+                class="iw-chart-legend-item-text"
+              >
+                ${label}
+              </text>
+            </g>
+          `
+          currentX += squareSize + gap + label.length * 6 + itemGap
+          return item
+        },
+      )}
+    </g>
+  `
+}