transform.go

package jsonstat

import (
	"strconv"
	"strings"
)

// This file implements the two non-deprecated conversion methods of the JS
// Toolkit on [Dataset]: Unflatten() and Transform(). It is a faithful port of
// the JS Toolkit's behaviour, documented in
// https://json-stat.org/wiki/api-methods/#unflatten and
// https://json-stat.org/wiki/api-methods/#transform. The deprecated toTable()
// is NOT emulated — neither as toTable nor as ToTable — because jsonstat-go
// ships only the non-deprecated surface.
//
// Both methods consume the same per-cell data that [Dataset.cellAt] produces
// (value, status, missing flag, flat index, per-dimension category index);
// they diverge only in how that per-cell data is reshaped for the caller.
//
// Conventions shared with the JS Toolkit:
//
//   - Coordinates are exposed as dimension-ID → category-ID maps. Category
//     IDs are always strings (even for time dimensions whose categories are
//     numeric-looking years).
//   - category labels fall back to the category ID when the source omitted
//     category.label; the helper [labelFor] centralises that fallback.
//   - missing cells: in Unflatten the datapoint is still surfaced (with Value
//     = 0 and Status = ""); in Transform the canonical samples render null
//     for the value, so the array/objarr/object types emit nil for missing
//     values, while arrobj omits the value key for missing cells.
//   - the comma option formats numbers as strings using a comma decimal
//     mark, matching the JS Toolkit's locale-style formatting.

// ---------------------------------------------------------------------------
// Unflatten
// ---------------------------------------------------------------------------

// Coordinates is the dimension-ID → category-ID map exposed to the
// [UnflattenFunc] callback for the current cell. It is freshly allocated per
// cell so the callback may retain references safely. Category IDs are always
// strings (e.g. the "year" dimension exposes {"year": "2012"}, not 2012).
type Coordinates map[string]string

// Datapoint is the value/status pair exposed to the [UnflattenFunc] callback
// for the current cell. When the cell carries no status, Status is the empty
// string (matching the JS Toolkit, which exposes null but uses "" here to
// stay Go-friendly). When the cell is missing (JSON null in a dense value
// array, or absent key in a sparse object), Value is 0 and Missing is true.
type Datapoint struct {
	Value   float64
	Status  string
	Missing bool
}

// UnflattenFunc mirrors the JS Toolkit's Unflatten callback. It is invoked
// once per cell in row-major order. The arguments are:
//
//   - coords: the [Coordinates] of the cell (dimension ID → category ID).
//   - dp:     the cell's value/status pair ([Datapoint]).
//   - n:      the 0-based cell counter (the flat row-major index).
//   - row:    the accumulator slice being built; the value returned by the
//     callback is appended to it after the callback returns.
//
// Returning nil skips the cell (it is not appended), matching the JS Toolkit's
// treatment of a callback that returns undefined.
type UnflattenFunc func(coords Coordinates, dp Datapoint, n int, row []any) any

// Unflatten walks every cell of the cube, invoking fn for each, and returns
// the slice of non-nil results. It is the Go counterpart of the JS Toolkit's
// `Dataset.Unflatten(cb)`.
//
//	fn returns any → appended to the result; nil → cell dropped.
//
// An empty (nil) dataset or a nil callback returns (nil, nil).
//
// Usage (mirrors the JS example that returns {coordinates, datapoint}):
//
//	out, err := ds.Unflatten(func(coords jsonstat.Coordinates, dp jsonstat.Datapoint, n int, row []any) any {
//	    return map[string]any{"coordinates": coords, "datapoint": dp}
//	})
func (d *Dataset) Unflatten(fn UnflattenFunc) ([]any, error) {
	if d == nil || d.total == 0 || fn == nil {
		return nil, nil
	}
	// Pre-size to the upper bound; the actual slice may be shorter if the
	// callback drops cells.
	row := make([]any, 0, d.total)
	for flat := 0; flat < d.total; flat++ {
		coords, dp := d.flatToUnflatten(flat)
		v := fn(coords, dp, flat, row)
		if v != nil {
			row = append(row, v)
		}
	}
	return row, nil
}

// flatToUnflatten builds the Coordinates and Datapoint for a given flat index.
// It mirrors what the JS Toolkit exposes to the Unflatten callback.
func (d *Dataset) flatToUnflatten(flat int) (Coordinates, Datapoint) {
	coords := make(Coordinates, len(d.ID))
	coordIdx, _ := coordsForFlat(d, flat)
	for pos, dimID := range d.ID {
		dim := d.Dimensions[dimID]
		if dim == nil || pos >= len(coordIdx) {
			coords[dimID] = ""
			continue
		}
		catIdx := coordIdx[pos]
		if catIdx < 0 || catIdx >= len(dim.Categories) {
			coords[dimID] = ""
			continue
		}
		coords[dimID] = dim.Categories[catIdx].ID
	}
	val, present := d.values.at(flat)
	status := d.status.at(flat)
	return coords, Datapoint{Value: val, Status: status, Missing: !present}
}

// coordsForFlat returns the per-dimension category index for a flat index. It
// is a thin wrapper around the cached strides so transform.go does not have to
// depend on the internal/stride package directly.
func coordsForFlat(d *Dataset, flat int) ([]int, error) {
	if d == nil {
		return nil, nil
	}
	if len(d.strides) == 0 {
		// Should not happen on a reindexed dataset, but compute on the fly to
		// be safe.
		return coordsFromSize(d.Size, flat)
	}
	coords := make([]int, len(d.Size))
	rem := flat
	for i, s := range d.Size {
		if i == len(d.strides) {
			break
		}
		stride := d.strides[i]
		if stride <= 0 {
			coords[i] = 0
			continue
		}
		coords[i] = rem / stride
		rem -= coords[i] * stride
		if s > 0 {
			_ = s
		}
	}
	return coords, nil
}

// coordsFromSize computes coordinates from Size + a flat index without using
// the cached strides. Used only as a fallback when strides are unset.
func coordsFromSize(size []int, flat int) ([]int, error) {
	if len(size) == 0 {
		return nil, nil
	}
	strides := make([]int, len(size))
	s := 1
	for i := len(size) - 1; i >= 0; i-- {
		strides[i] = s
		s *= size[i]
	}
	coords := make([]int, len(size))
	rem := flat
	for i, stride := range strides {
		if stride > 0 {
			coords[i] = rem / stride
			rem -= coords[i] * stride
		}
	}
	return coords, nil
}

// ---------------------------------------------------------------------------
// Transform — options
// ---------------------------------------------------------------------------

// TransformType selects the output shape of [Dataset.Transform]. It mirrors
// the JS Toolkit's opts.type string values.
type TransformType string

const (
	// TransformArray is the default type: an array of arrays whose first
	// element is a header row. Mirrors JS type "array".
	TransformArray TransformType = "array"

	// TransformArrObj produces an array of per-cell objects keyed by dimension
	// ID, "value" and "status". Mirrors JS type "arrobj". Supports the `by`
	// (pivot) and `meta` options.
	TransformArrObj TransformType = "arrobj"

	// TransformObjArr produces a columnar object: each property is a parallel
	// array. Mirrors JS type "objarr". Supports the `by` (pivot) and `meta`
	// options.
	TransformObjArr TransformType = "objarr"

	// TransformObject produces a Google DataTable {cols, rows}. Mirrors JS
	// type "object". Infers column type ("number" or "string") from the first
	// value.
	TransformObject TransformType = "object"
)

// Content controls whether categories are identified by label or by ID in the
// Transform output. Mirrors the JS Toolkit's opts.content.
type Content string

const (
	// ContentLabel (the default) identifies categories by their human-readable
	// label.
	ContentLabel Content = "label"
	// ContentID identifies categories by their ID.
	ContentID Content = "id"
)

// Field controls whether the dimension, value and status column keys are IDs
// or labels. Mirrors the JS Toolkit's opts.field. The default is FieldID,
// except for the "array" type whose default is FieldLabel (matching JS).
type Field string

const (
	// FieldID keys columns by dimension/value/status IDs.
	FieldID Field = "id"
	// FieldLabel keys columns by dimension/value/status labels.
	FieldLabel Field = "label"

	// fieldUnset is an internal sentinel used to detect that the caller did
	// not pass [WithField], so that the type-specific default (FieldLabel for
	// array, FieldID otherwise) can be applied at resolve time. It is never
	// visible to callers.
	fieldUnset Field = ""
)

// TransformOption configures [Dataset.Transform]. The functional-options
// pattern keeps the call sites self-documenting.
type TransformOption func(*transformConfig)

// transformConfig is the resolved configuration after applying every option.
// Defaults match the JS Toolkit's documented defaults.
type transformConfig struct {
	ttype   TransformType
	status  bool
	content Content
	field   Field
	vlabel  string
	slabel  string
	meta    bool
	by      string
	prefix  string
	drop    map[string]struct{}
	comma   bool
	byValid bool // resolved: does `by` name a real dimension?
	byPos   int  // resolved: position of the `by` dimension in ID
}

func newTransformConfig(opts []TransformOption) *transformConfig {
	c := &transformConfig{
		ttype:   TransformArray,
		status:  false,
		content: ContentLabel,
		field:   fieldUnset, // resolved to FieldID (or FieldLabel for array) in resolve()
		vlabel:  "Value",
		slabel:  "Status",
		meta:    false,
		by:      "",
		prefix:  "",
		drop:    nil,
		comma:   false,
	}
	for _, opt := range opts {
		if opt != nil {
			opt(c)
		}
	}
	return c
}

// WithTransformType sets the output shape. Default [TransformArray].
func WithTransformType(t TransformType) TransformOption {
	return func(c *transformConfig) { c.ttype = t }
}

// WithStatus includes the status column in the output. Default false. Ignored
// when [WithBy] is also set (matching JS behaviour).
func WithStatus(b bool) TransformOption {
	return func(c *transformConfig) { c.status = b }
}

// WithContent controls whether categories are identified by label or by ID.
// Default [ContentLabel].
func WithContent(ct Content) TransformOption {
	return func(c *transformConfig) { c.content = ct }
}

// WithField controls whether dimension, value and status keys are IDs or
// labels. Default [FieldID] (the array type overrides this to [FieldLabel]).
func WithField(f Field) TransformOption {
	return func(c *transformConfig) { c.field = f }
}

// WithValueLabel sets the label of the value column. Default "Value".
func WithValueLabel(s string) TransformOption {
	return func(c *transformConfig) { c.vlabel = s }
}

// WithStatusLabel sets the label of the status column. Default "Status".
// Only relevant when [WithStatus] is true.
func WithStatusLabel(s string) TransformOption {
	return func(c *transformConfig) { c.slabel = s }
}

// WithMeta attaches dataset metadata to the output, wrapping it as
// *TableWithMeta. Default false. Not available with the object type.
func WithMeta(b bool) TransformOption {
	return func(c *transformConfig) { c.meta = b }
}

// WithBy pivots the value column on the given dimension (one output column
// per category of that dimension). Only supported by the arrobj and objarr
// types (silently ignored for the array and object types, matching JS).
// When `by` names a non-existent dimension, it is ignored.
func WithBy(dimID string) TransformOption {
	return func(c *transformConfig) { c.by = dimID }
}

// WithPrefix sets a prefix prepended to the pivoted category columns when
// [WithBy] is in effect. Default "".
func WithPrefix(s string) TransformOption {
	return func(c *transformConfig) { c.prefix = s }
}

// WithDrop excludes the listed dimension IDs from the output. Invalid
// dimension IDs and multi-category dimensions are ignored (single-category
// dimensions are the only ones droppable, matching the JS rule).
func WithDrop(dimIDs ...string) TransformOption {
	return func(c *transformConfig) {
		if c.drop == nil {
			c.drop = make(map[string]struct{}, len(dimIDs))
		}
		for _, id := range dimIDs {
			c.drop[id] = struct{}{}
		}
	}
}

// WithComma formats numbers as strings with a comma decimal mark. Default
// false. Not available with the object type.
func WithComma(b bool) TransformOption {
	return func(c *transformConfig) { c.comma = b }
}

// ---------------------------------------------------------------------------
// Transform — public entry point
// ---------------------------------------------------------------------------

// Transform converts the dataset to tabular form. It is the Go counterpart of
// the JS Toolkit's `Dataset.Transform(opts)`, built on top of [Dataset.Unflatten]
// and using the same options vocabulary. It returns one of:
//
//   - `[][]any`               for [TransformArray]   (header row + data rows)
//   - `[]map[string]any`      for [TransformArrObj]  (one object per cell)
//   - `map[string][]any`      for [TransformObjArr]  (columnar)
//   - `*DataTable`            for [TransformObject]  (Google DataTable)
//
// When [WithMeta] is true the array/objarr shapes are wrapped in
// [*TableWithMeta] carrying the dataset metadata block, matching the JS
// Toolkit's `{meta, data}` shape. The object type never emits metadata.
//
// An empty (nil) dataset returns (nil, nil).
func (d *Dataset) Transform(opts ...TransformOption) (any, error) {
	if d == nil || d.total == 0 {
		return nil, nil
	}
	c := newTransformConfig(opts)
	c.resolve(d)

	switch c.ttype {
	case TransformArray:
		out := d.transformArray(c)
		if c.meta {
			return &TableWithMeta{Meta: d.metaFor(c), Data: out}, nil
		}
		return out, nil
	case TransformArrObj:
		out := d.transformArrObj(c)
		if c.meta {
			return &TableWithMeta{Meta: d.metaFor(c), Data: out}, nil
		}
		return out, nil
	case TransformObjArr:
		out := d.transformObjArr(c)
		if c.meta {
			return &TableWithMeta{Meta: d.metaFor(c), Data: out}, nil
		}
		return out, nil
	case TransformObject:
		return d.transformObject(c), nil
	default:
		// Unknown type falls back to the JS Toolkit's behaviour of treating
		// it as the default ("array").
		c.ttype = TransformArray
		out := d.transformArray(c)
		if c.meta {
			return &TableWithMeta{Meta: d.metaFor(c), Data: out}, nil
		}
		return out, nil
	}
}

// resolve finalises derived state: defaults that depend on the type (field
// defaults to label for array), and validation of `by` against the dataset's
// dimensions.
func (c *transformConfig) resolve(d *Dataset) {
	// Apply the type-specific field default. JS Toolkit rule:
	//   "field defaults to id except when type is array."
	// We only intervene when the caller did not pass [WithField], detected by
	// the fieldUnset sentinel. An explicit FieldID for the array type is
	// preserved.
	if c.field == fieldUnset {
		if c.ttype == TransformArray {
			c.field = FieldLabel
		} else {
			c.field = FieldID
		}
	}
	// Resolve `by`.
	c.byValid = false
	c.byPos = -1
	if c.by != "" && (c.ttype == TransformArrObj || c.ttype == TransformObjArr) {
		for pos, dimID := range d.ID {
			if dimID == c.by {
				c.byValid = true
				c.byPos = pos
				break
			}
		}
	}
}

// ---------------------------------------------------------------------------
// Transform — array type
// ---------------------------------------------------------------------------

// transformArray produces the array-of-arrays form: first row is the header
// (column labels/IDs per `field`), subsequent rows are data (category
// labels/IDs per `content`). Status precedes value when status is requested,
// matching the JS Toolkit.
func (d *Dataset) transformArray(c *transformConfig) [][]any {
	header := make([]any, 0, len(d.ID)+2)
	for _, dimID := range d.ID {
		header = append(header, d.columnKey(dimID, c.field))
	}
	if c.status {
		header = append(header, d.statusKey(c))
	}
	header = append(header, d.valueKey(c))

	out := make([][]any, 0, d.total+1)
	out = append(out, header)

	for flat := 0; flat < d.total; flat++ {
		row := make([]any, 0, len(d.ID)+2)
		coords, _ := coordsForFlat(d, flat)
		for pos, dimID := range d.ID {
			dim := d.Dimensions[dimID]
			if dim == nil {
				row = append(row, "")
				continue
			}
			idx := 0
			if pos < len(coords) {
				idx = coords[pos]
			}
			row = append(row, d.categoryValue(dim, idx, c.content))
		}
		val, present := d.values.at(flat)
		if c.status {
			status := d.status.at(flat)
			row = append(row, status)
		}
		row = append(row, d.valueOrMissing(val, present, c))
		out = append(out, row)
	}
	return out
}

// ---------------------------------------------------------------------------
// Transform — arrobj type
// ---------------------------------------------------------------------------

// transformArrObj produces the array-of-objects form, optionally pivoted by
// the `by` dimension.
func (d *Dataset) transformArrObj(c *transformConfig) []map[string]any {
	if !c.byValid {
		return d.transformArrObjFlat(c)
	}
	return d.transformArrObjPivoted(c)
}

func (d *Dataset) transformArrObjFlat(c *transformConfig) []map[string]any {
	out := make([]map[string]any, 0, d.total)
	droppable := d.droppableSet(c)
	for flat := 0; flat < d.total; flat++ {
		coords, _ := coordsForFlat(d, flat)
		obj := make(map[string]any, len(d.ID)+2)
		for pos, dimID := range d.ID {
			if _, drop := droppable[dimID]; drop {
				continue
			}
			dim := d.Dimensions[dimID]
			if dim == nil {
				continue
			}
			idx := 0
			if pos < len(coords) {
				idx = coords[pos]
			}
			obj[d.columnKey(dimID, c.field)] = d.categoryValue(dim, idx, c.content)
		}
		val, present := d.values.at(flat)
		if present {
			obj[d.valueKey(c)] = d.numericOrString(val, c)
		} else {
			obj[d.valueKey(c)] = nil
		}
		if c.status {
			obj[d.statusKey(c)] = d.status.at(flat)
		}
		out = append(out, obj)
	}
	return out
}

func (d *Dataset) transformArrObjPivoted(c *transformConfig) []map[string]any {
	// Pivot by the `by` dimension: group rows by every other dimension's
	// coordinate, and emit one column per category of the `by` dimension.
	byPos := c.byPos
	byDim := d.Dimensions[d.ID[byPos]]
	if byDim == nil {
		return d.transformArrObjFlat(c)
	}
	// Column order for the pivoted categories: in category index order.
	// When content is label, the pivoted column keys come from the category
	// label; when content is id, from the category ID. Either way they are
	// strings here, so we cast defensively.
	pivotedCols := make([]string, 0, byDim.Size)
	for i := 0; i < byDim.Size; i++ {
		colKey := c.prefix + asString(d.categoryValue(byDim, i, c.content))
		pivotedCols = append(pivotedCols, colKey)
	}
	// Group key positions = every dimension position except byPos.
	groupPos := make([]int, 0, len(d.ID))
	for pos := range d.ID {
		if pos == byPos {
			continue
		}
		groupPos = append(groupPos, pos)
	}
	droppable := d.droppableSet(c)
	// Iterate every cell, computing its group signature.
	type groupEntry struct {
		obj map[string]any
	}
	groups := make(map[string]*groupEntry)
	order := make([]string, 0, d.total) // preserve first-seen order

	for flat := 0; flat < d.total; flat++ {
		coords, _ := coordsForFlat(d, flat)
		if byPos >= len(coords) {
			continue
		}
		byCatIdx := coords[byPos]
		// Build the group signature from the non-by positions.
		var sb strings.Builder
		keyParts := make([]string, 0, len(groupPos))
		for _, pos := range groupPos {
			keyParts = append(keyParts, strconv.Itoa(coords[pos]))
		}
		sb.WriteString(strings.Join(keyParts, "|"))
		sig := sb.String()

		entry, ok := groups[sig]
		if !ok {
			obj := make(map[string]any, len(groupPos)+byDim.Size)
			for _, pos := range groupPos {
				dimID := d.ID[pos]
				if _, drop := droppable[dimID]; drop {
					continue
				}
				dim := d.Dimensions[dimID]
				if dim == nil {
					continue
				}
				obj[d.columnKey(dimID, c.field)] = d.categoryValue(dim, coords[pos], c.content)
			}
			entry = &groupEntry{obj: obj}
			groups[sig] = entry
			order = append(order, sig)
		}
		// Place the value in the right pivoted column.
		colKey := pivotedCols[byCatIdx]
		val, present := d.values.at(flat)
		if present {
			entry.obj[colKey] = d.numericOrString(val, c)
		} else {
			entry.obj[colKey] = nil
		}
	}

	out := make([]map[string]any, 0, len(order))
	for _, sig := range order {
		out = append(out, groups[sig].obj)
	}
	return out
}

// ---------------------------------------------------------------------------
// Transform — objarr type
// ---------------------------------------------------------------------------

// transformObjArr produces the columnar form: each property is a parallel
// array of length N.
func (d *Dataset) transformObjArr(c *transformConfig) map[string][]any {
	if !c.byValid {
		return d.transformObjArrFlat(c)
	}
	return d.transformObjArrPivoted(c)
}

func (d *Dataset) transformObjArrFlat(c *transformConfig) map[string][]any {
	cols := make(map[string][]any, len(d.ID)+2)
	droppable := d.droppableSet(c)
	for _, dimID := range d.ID {
		if _, drop := droppable[dimID]; drop {
			continue
		}
		key := d.columnKey(dimID, c.field)
		cols[key] = make([]any, 0, d.total)
	}
	valKey := d.valueKey(c)
	cols[valKey] = make([]any, 0, d.total)
	if c.status {
		statKey := d.statusKey(c)
		cols[statKey] = make([]any, 0, d.total)
	}

	for flat := 0; flat < d.total; flat++ {
		coords, _ := coordsForFlat(d, flat)
		for _, dimID := range d.ID {
			if _, drop := droppable[dimID]; drop {
				continue
			}
			dim := d.Dimensions[dimID]
			pos := d.dimPos[dimID]
			if dim == nil {
				continue
			}
			idx := 0
			if pos < len(coords) {
				idx = coords[pos]
			}
			cols[d.columnKey(dimID, c.field)] = append(cols[d.columnKey(dimID, c.field)], d.categoryValue(dim, idx, c.content))
		}
		val, present := d.values.at(flat)
		if present {
			cols[valKey] = append(cols[valKey], d.numericOrString(val, c))
		} else {
			cols[valKey] = append(cols[valKey], nil)
		}
		if c.status {
			statKey := d.statusKey(c)
			cols[statKey] = append(cols[statKey], d.status.at(flat))
		}
	}
	return cols
}

func (d *Dataset) transformObjArrPivoted(c *transformConfig) map[string][]any {
	byPos := c.byPos
	byDim := d.Dimensions[d.ID[byPos]]
	if byDim == nil {
		return d.transformObjArrFlat(c)
	}
	// Build the pivoted output by reusing the arrobj-pivoted logic and
	// transposing it into columns.
	arrobj := d.transformArrObjPivoted(c)
	if len(arrobj) == 0 {
		return map[string][]any{}
	}
	// Discover columns from the first object (every row shares the same keys
	// because they all came from the same group template).
	cols := make(map[string][]any, len(arrobj[0]))
	for k := range arrobj[0] {
		cols[k] = make([]any, 0, len(arrobj))
	}
	for _, obj := range arrobj {
		for k, v := range obj {
			cols[k] = append(cols[k], v)
		}
	}
	return cols
}

// ---------------------------------------------------------------------------
// Transform — object type (Google DataTable)
// ---------------------------------------------------------------------------

// DataTable is the Google DataTable {cols, rows} shape produced by Transform
// with the [TransformObject] type. See
// https://developers.google.com/chart/interactive/docs/reference#DataTable.
type DataTable struct {
	Cols []DataTableCol `json:"cols"`
	Rows []DataTableRow `json:"rows"`
}

// DataTableCol is one column descriptor in a [DataTable].
type DataTableCol struct {
	ID    string `json:"id,omitempty"`
	Type  string `json:"type"`
	Label string `json:"label,omitempty"`
}

// DataTableRow is one row of a [DataTable]. Cells carry the value in `v` and
// an optional `f` (formatted) — here only `v` is populated, matching the JS
// Toolkit's behaviour.
type DataTableRow struct {
	C map[string]any `json:"c"`
}

func (d *Dataset) transformObject(c *transformConfig) *DataTable {
	// Header columns: dimensions then value, with status preceding value when
	// requested.
	cols := make([]DataTableCol, 0, len(d.ID)+2)
	for _, dimID := range d.ID {
		cols = append(cols, DataTableCol{
			ID:    dimID,
			Type:  "string",
			Label: d.columnKey(dimID, c.field),
		})
	}
	// Infer the value column type from the first present value.
	valType := "string"
	for flat := 0; flat < d.total; flat++ {
		if _, present := d.values.at(flat); present {
			valType = "number"
			break
		}
	}
	if c.status {
		cols = append(cols, DataTableCol{
			ID:    c.slabel,
			Type:  "string",
			Label: d.statusKey(c),
		})
	}
	cols = append(cols, DataTableCol{
		ID:    c.vlabel,
		Type:  valType,
		Label: d.valueKey(c),
	})

	rows := make([]DataTableRow, 0, d.total)
	for flat := 0; flat < d.total; flat++ {
		coords, _ := coordsForFlat(d, flat)
		cell := make(map[string]any, len(cols))
		for pos, dimID := range d.ID {
			dim := d.Dimensions[dimID]
			if dim == nil {
				cell[dimID] = map[string]any{"v": ""}
				continue
			}
			idx := 0
			if pos < len(coords) {
				idx = coords[pos]
			}
			cell[dimID] = map[string]any{"v": d.categoryValue(dim, idx, c.content)}
		}
		val, present := d.values.at(flat)
		statKey := d.statusKey(c)
		valKey := d.valueKey(c)
		if c.status {
			cell[statKey] = map[string]any{"v": d.status.at(flat)}
		}
		if present {
			cell[valKey] = map[string]any{"v": d.numericOrString(val, c)}
		} else {
			cell[valKey] = map[string]any{"v": nil}
		}
		rows = append(rows, DataTableRow{C: cell})
	}
	return &DataTable{Cols: cols, Rows: rows}
}

// ---------------------------------------------------------------------------
// Transform — meta wrapper
// ---------------------------------------------------------------------------

// TableWithMeta wraps a Transform result with the dataset metadata block,
// emitted when [WithMeta] is true. It mirrors the JS Toolkit's {meta, data}
// shape exactly so that JSON serialisation is byte-compatible.
type TableWithMeta struct {
	Meta TableMeta `json:"meta"`
	Data any       `json:"data"`
}

// TableMeta is the metadata block attached by [WithMeta]. Only the fields the
// JS Toolkit includes are populated; provider-specific extension is left to
// callers via the [Dataset.Extension] map (not auto-copied here).
type TableMeta struct {
	Type       string                  `json:"type"`
	Label      string                  `json:"label,omitempty"`
	Source     string                  `json:"source,omitempty"`
	Updated    string                  `json:"updated,omitempty"`
	ID         []string                `json:"id"`
	Status     bool                    `json:"status"`
	By         string                  `json:"by,omitempty"`
	Drop       []string                `json:"drop,omitempty"`
	Prefix     string                  `json:"prefix,omitempty"`
	Comma      bool                    `json:"comma"`
	Dimensions map[string]TableDimMeta `json:"dimensions,omitempty"`
}

// TableDimMeta is the per-dimension metadata attached under TableMeta.
type TableDimMeta struct {
	Label      string             `json:"label"`
	Role       string             `json:"role,omitempty"`
	Categories TableDimCategories `json:"categories"`
}

// TableDimCategories holds the parallel category ID/label arrays.
type TableDimCategories struct {
	ID    []string `json:"id"`
	Label []string `json:"label"`
}

func (d *Dataset) metaFor(c *transformConfig) TableMeta {
	m := TableMeta{
		Type:    string(c.ttype),
		Label:   d.Label,
		Source:  d.Source,
		Updated: d.Updated,
		ID:      append([]string(nil), d.ID...),
		Status:  c.status,
		Comma:   c.comma,
	}
	if c.byValid {
		m.By = c.by
	}
	if c.prefix != "" {
		m.Prefix = c.prefix
	}
	if len(c.drop) > 0 {
		dropList := make([]string, 0, len(c.drop))
		for id := range c.drop {
			dropList = append(dropList, id)
		}
		m.Drop = dropList
	}
	// Dimensions block is not affected by `by`/`drop` (JS rule).
	m.Dimensions = make(map[string]TableDimMeta, len(d.ID))
	for _, dimID := range d.ID {
		dim := d.Dimensions[dimID]
		if dim == nil {
			continue
		}
		labels := dim.CategoryLabels()
		ids := dim.CategoryIDs()
		m.Dimensions[dimID] = TableDimMeta{
			Label:      dim.Label,
			Role:       string(dim.Role),
			Categories: TableDimCategories{ID: ids, Label: labels},
		}
	}
	return m
}

// ---------------------------------------------------------------------------
// Helpers shared by every type
// ---------------------------------------------------------------------------

// columnKey resolves a *dimension* column key (ID or label) according to the
// `field` setting. It is intentionally only used for dimensions: the built-in
// value/status columns have their own resolution rules (see valueKey/statusKey).
func (d *Dataset) columnKey(idOrLabel string, field Field) string {
	if field == FieldLabel {
		if dim, ok := d.Dimensions[idOrLabel]; ok && dim.Label != "" {
			return dim.Label
		}
	}
	return idOrLabel
}

// valueKey returns the column key for the value column. When field is label it
// is the configured vlabel (default "Value"); when field is id it is the
// canonical lowercase "value", matching the JS Toolkit's documented behaviour
// (see raw/api.md lines 601-602: field:"id" yields lowercase "value").
func (d *Dataset) valueKey(c *transformConfig) string {
	if c.field == FieldLabel {
		return c.vlabel
	}
	return "value"
}

// statusKey returns the column key for the status column. Mirrors valueKey:
// vlabel-style slabel ("Status") when field is label, canonical lowercase
// "status" when field is id.
func (d *Dataset) statusKey(c *transformConfig) string {
	if c.field == FieldLabel {
		return c.slabel
	}
	return "status"
}

// categoryValue returns the ID or the Label of the category at the given
// index, according to the `content` setting. The label falls back to the ID
// when the source omitted category.label.
func (d *Dataset) categoryValue(dim *Dimension, idx int, content Content) any {
	if dim == nil || idx < 0 || idx >= len(dim.Categories) {
		return ""
	}
	cat := dim.Categories[idx]
	if content == ContentID {
		return cat.ID
	}
	return labelFor(cat)
}

// labelFor returns the category's label, falling back to the ID when the
// label is empty. This matches the JS Toolkit's category label resolution.
func labelFor(c Category) string {
	if c.Label != "" {
		return c.Label
	}
	return c.ID
}

// valueOrMissing formats the cell value for the array/object types. Missing
// cells emit nil; present cells honour the `comma` flag.
func (d *Dataset) valueOrMissing(val float64, present bool, c *transformConfig) any {
	if !present {
		return nil
	}
	return d.numericOrString(val, c)
}

// numericOrString formats a present value as a number, or as a comma-decimal
// string when the `comma` flag is set.
func (d *Dataset) numericOrString(val float64, c *transformConfig) any {
	if c.comma {
		return commaDecimal(val)
	}
	return val
}

// commaDecimal renders a float64 with a comma decimal mark. The JS Toolkit
// uses the provider's locale, but its only documented behaviour is
// "comma replaces the dot", so we honour that literally.
func commaDecimal(v float64) string {
	// strconv.FormatFloat with -1 precision matches JS's default number
	// formatting closely enough for the canonical samples.
	s := strconv.FormatFloat(v, 'f', -1, 64)
	return strings.Replace(s, ".", ",", 1)
}

// droppableSet resolves the set of dimensions that are actually droppable:
// those named in `drop` that exist in the dataset AND have exactly one
// category. Invalid IDs and multi-category dimensions are ignored, matching
// the JS Toolkit's documented behaviour.
func (d *Dataset) droppableSet(c *transformConfig) map[string]struct{} {
	if len(c.drop) == 0 {
		return nil
	}
	out := make(map[string]struct{}, len(c.drop))
	for id := range c.drop {
		dim, ok := d.Dimensions[id]
		if !ok {
			continue
		}
		if dim.Size != 1 {
			continue
		}
		out[id] = struct{}{}
	}
	if len(out) == 0 {
		return nil
	}
	return out
}

// asString coerces an any returned by categoryValue back to its string form.
// categoryValue always returns a string for valid categories (the ID or the
// label); this helper exists only so the pivot logic can do string
// concatenation without a cast at every call site.
func asString(v any) string {
	if s, ok := v.(string); ok {
		return s
	}
	return ""
}