_axes

Shared tick generation + axes + gridline drawing helpers for canvas-hosted charts. Used by Z.plot for axes/gridlines/ticks and by Z.graph for the optional axis labels + gridlines. Single source of truth for the nice-tick algorithm so both widgets render identical- looking tick scales. Underscore prefix marks it as a package-internal helper — not exported from zui.widget and not part of the Z.* surface.

Exports

• M.computeTicks(minV: number, maxV: number, nTicks: number?, customFormat: TickFormatter?) -> TickResult — D3-style nice ticks. Snaps step to {1, 2, 5} × 10^n. nTicks default 5.
• M.axisCommands(viewport: Viewport, bounds: Bounds, opts: AxesOpts?) -> { CanvasCommand } — axes + tick marks + tick labels.
• M.gridCommands(viewport: Viewport, bounds: Bounds, opts: AxesOpts?) -> { CanvasCommand } — gridlines, one per major tick.

Types:

• Viewport = { x: number, y: number, width: number, height: number } — canvas-local pixel rect.
• Bounds = { xMin: number, xMax: number, yMin: number, yMax: number } — data-space range.
• TickResult = { ticks: { number }, labels: { string } }
• TickFormatter = (number) -> string — custom label formatter.
• AxesOpts — visibility + styling (showXAxis, axisColor, labelSize, tickLength, xTickFormat, etc.).
• CanvasCommand = { [string]: any } — opaque canvas-renderer command.

Usage

local Axes = require("@builtin::modules.zui.widget._axes")

local viewport = { x = 0,  y = 0,  width = 200, height = 120 }
local bounds   = { xMin = 0, xMax = 100, yMin = 0, yMax = 1 }

local axisCmds = Axes.axisCommands(viewport, bounds, {})
local gridCmds = Axes.gridCommands(viewport, bounds, { gridY = false })

local r = Axes.computeTicks(0, 100)      -- nice ticks: {0, 20, 40, ...}

-- Custom formatter:
Axes.axisCommands(viewport, bounds, {
    xTickFormat = function(v) return "$" .. v end,
})

Notes

• Coordinate convention matches canvas: origin top-left, +y down. Y values from bounds are flipped at render time so yMax is drawn at the top of the viewport, matching plot conventions.
• mergedOpts overlays caller opts on DEFAULTS and passes unknown keys through — additive opts (xTickFormat, yTickFormat, future ones) don't need bookkeeping in DEFAULTS.
• computeTicks caps iteration at 64 ticks to avoid pathological loops on degenerate input.
• Out-of-range ticks (after the data → pixel mapping) are filtered silently so neither labels nor lines bleed past the viewport.