ChartTime

ChartTime manifests describe time-based charts. They share many fields with ChartStructure but add date-axis-specific options.

Spec outline

apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_time_chart
spec:
  dataset: revenue_daily
  chartTitle: "Daily revenue"
  chartMode: bar             # bar | line | auto
  maxBars: 28                # threshold for auto mode
  lineFullWidth: true         # stretch line charts to full width
  axisLabelsMode: smart      # smart | long | short
  dateInterval: auto         # year | quarter | month | week | day | hour | minute | second | millisecond | auto
  filter: "region_group = 'EMEA'"
  level: auto                # rowcategory | category | subcategory | auto
  order: auto                # category | categoryindex | rowgroup | rowgroupindex | ac1-4 | fc1-4 | pp1-4 | pl1-4 | auto
  orderDirection: asc
  measureScale: M
  measureUnit: "EUR"
  internationalisation: "_system"
  internationalisationMode: "default"
  translation: "chart.revenue.time"
  showCategories: true
  showMeasureScale: true
  showOverlayAvg: true
  showOverlayMedian: false
  limit: 0
  intervalSpanLimit: 50
  percentageScaling: "default"
  unitScaling: "default"
  syncSpaceLeft: 0
  scenarios: ["ac1", "fc1"]   # ac1-4 | fc1-4 | pp1-4 | pl1-4 | auto
  variances: ["dfc1_ac1_pos"]
  scale: auto                    # "" | none | auto | 0.5 | 1.2 | …
  stack:                       # optional stacked chart config
    by: scenarioss              # scenarios | dimensions
    mode: absolute             # absolute | relative | absolute-relative
    order: dataset             # asc | desc | dataset

Fields

• dataset – required dataset name or array.
• chartTitle – optional title.
• chartMode – rendering mode: bar (default), line, or auto. When set to auto, the chart automatically switches to line mode when data points exceed maxBars.
• maxBars – threshold for auto-switching to line mode (default: 28). Only applies when chartMode is auto.
• lineFullWidth – when true (default in the renderer), line charts stretch to fill the full parent width instead of using fixed per-data-point spacing. Has no effect in bar mode.
• axisLabelsMode – smart (context-aware labels), long, or short.
• dateInterval – desired time granularity; auto lets the renderer choose based on dataset meta.
• filter – optional filter expression.
• level – aggregation level: rowcategory, category, subcategory, or auto. When set to auto, the level is detected from the dataset silently. When left blank, it is detected with a warning.
• order – sort key; if you use a scenario, it must appear in scenarios. Set to auto to detect from the dataset silently. When left blank, it is detected with a warning.
• orderDirection – sort direction (asc or desc).
• measureScale, measureUnit – SI prefix and unit string.
• showCategories, showMeasureScale – visibility flags.
• showOverlayAvg, showOverlayMedian – enables overlay lines.
• limit – column stack limit; 0 means unlimited.
• intervalSpanLimit – controls how many columns drive automatic date interval selection.
• percentageScaling, unitScaling, syncSpaceLeft – scaling and sync options. When unitScaling is set to a numeric value and bars exceed the available container height, an overdrive bar is rendered: the bar is visually split into a base section, a zigzag break indicator, and a proportionally scaled overdrive section above it. This preserves value labels and relative comparisons between overflowing bars instead of clipping them. AC scenario bars break at a higher point than non-AC scenarios (PP, FC, PL) to maintain visual hierarchy.
• scenarios – list of scenarios (up to 4); values like ac1–ac4, fc1–fc4, pp1–pp4, pl1–pl4, or auto. When set to auto, scenarios are detected from the dataset silently. When left blank, they are detected with a warning.
• variances – list of variance definitions of the form d<scenarioB>_<scenarioA>_[pos|neg|neu].
• scale – proportional scaling of the chart (font size, spacings, and bar/column dimensions all scale together). Scaling triggers on width overflow (horizontal axis labels cut off).
  • not set or "" – auto-scale to fit the parent width; emits an AUTO_scale warning with the applied factor.
  • "none" – no scaling; render at the base font size regardless of available space.
  • "auto" – auto-scale to fit the parent width silently (no warning).
  • "0.5", "1.2", … – fixed factor applied to the base font size. All dimensions scale proportionally.
• stack – optional object to enable stacked rendering:
  • by – (required) stacking dimension: scenarios stacks scenario slots end-to-end; dimensions auto-derives the stack column from the level prop (rowGroup→category, category→subCategory). When using dimensions, only the first scenario is used; additional scenarios are discarded with a warning.
  • mode – stacking mode: absolute (additive, default), relative (100% stacked), or absolute-relative (absolute height with percentage labels).
  • order – segment order within each stack: asc, desc, or dataset (default).
  • When chartMode is bar, produces stacked columns. When chartMode is line, produces a stacked area chart.

Example: Monthly revenue line chart

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_monthly_chart
spec:
  dataset: revenue_monthly
  chartTitle: "Monthly revenue"
  axisLabelsMode: smart
  dateInterval: month
  level: category
  order: category
  orderDirection: asc
  measureScale: M
  measureUnit: "EUR"
  showMeasureScale: true
  showOverlayAvg: true
  scenarios: ["ac1"]

Example: Line chart mode

Force line chart rendering with square markers at each data point:

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_line_chart
spec:
  dataset: revenue_daily
  chartTitle: "Daily revenue trend"
  chartMode: line
  dateInterval: day
  measureScale: M
  measureUnit: "EUR"
  scenarios: ["ac1", "pp1"]

Example: Auto-switching mode

Automatically switch to line chart when data points exceed the threshold:

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_auto_chart
spec:
  dataset: revenue_weekly
  chartTitle: "Weekly revenue"
  chartMode: auto
  maxBars: 15
  dateInterval: week
  measureScale: M
  measureUnit: "EUR"
  scenarios: ["ac1", "fc1"]

Line chart features

When rendered in line mode:

• Square markers (8×8px) at each data point
• Data values displayed above each marker
• Scenario labels positioned to the right of the last data point
• Smart X-axis labels showing start, end, and year boundaries
• Vertical dashed separator lines at year transitions
• IBCS color schema:
  • AC (Actual): Black fill, black stroke, solid line
  • PP (Previous Period): Gray fill, gray stroke, solid line
  • FC (Forecast): White fill, black stroke, dashed line
  • PL (Plan): White fill, black stroke, solid line

Overdrive bars (overflow handling)

When unitScaling is set to a fixed numeric value (not auto), bars may exceed the available container height. Instead of silently clipping the bars, the renderer applies overdrive rendering:

1. Base section – the bar is drawn up to a computed cut height that fits within the container.
2. Break indicator – a zigzag line across the bar width signals the axis break.
3. Overdrive section – a proportionally scaled continuation above the break shows how much the bar exceeds the cut point.

Bars that fit within the available space render normally. Among overflowing bars, the overdrive height is proportional to the overflow amount, so a bar overflowing by 200 px gets twice the overdrive of one overflowing by 100 px.

AC scenario bars break at a higher point than PP, FC, and PL bars. This staggered break position maintains the IBCS visual hierarchy between scenario types.

Overdrive bars apply to bar mode only and do not affect line charts, stacked charts, or auto-fit scaling. The existing overflow warning is still emitted alongside the visual treatment.

Example: Stacked columns by scenario

Stack AC and PP values as additive columns:

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_stacked_chart
spec:
  dataset: revenue_monthly
  chartTitle: "Revenue stacked by scenario"
  dateInterval: month
  unitScaling: 0.05
  scenarios: ["ac1", "pp1"]
  stack:
    by: scenarios
    mode: absolute

Example: 100% stacked columns

Show the relative contribution of each scenario:

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_relative_stacked
spec:
  dataset: revenue_monthly
  chartTitle: "Revenue share by scenario"
  dateInterval: month
  unitScaling: 100
  scenarios: ["ac1", "pp1", "fc1"]
  stack:
    by: scenarios
    mode: relative

Example: Stacked area chart

Combine chartMode: line with stack to render stacked area fills:

---
apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: revenue_stacked_area
spec:
  dataset: revenue_monthly
  chartTitle: "Revenue trend (stacked area)"
  chartMode: line
  dateInterval: month
  unitScaling: 0.05
  scenarios: ["ac1", "pp1", "fc1"]
  stack:
    by: scenarios
    mode: absolute

Attribute Reference

Common Metadata

Attribute	Type	Required	Default	Description
apiVersion	string	yes	—	Must be bino.bi/v1alpha1.
kind	string	yes	—	Must be ChartTime.
metadata.name	string	yes	—	Unique identifier.
metadata.labels	object	no	—	Key-value pairs for categorization and constraint matching.
metadata.annotations	object	no	—	Arbitrary key-value metadata, not used by the system.
metadata.description	string	no	—	Free-form description.
metadata.constraints	array	no	—	Conditional inclusion rules. See Constraints.

Spec Attributes

Attribute	Type	Required	Default	Description	Sample
spec.dataset	string or object	yes	—	Dataset reference (name or inline definition). Provided by the withDataset mixin in the template engine.	dataset: revenue_daily
spec.chartTitle	string	no	""	Custom chart title.	chartTitle: "Daily revenue"
spec.chartMode	string	no	bar	Rendering mode. Values: bar, line, auto. When auto, switches to line when data points exceed maxBars.	chartMode: line
spec.maxBars	integer	no	28	Threshold for auto-switching to line mode. Only applies when chartMode is auto. Minimum: 1.	maxBars: 15
spec.lineFullWidth	boolean	no	true	Stretch line charts to fill full parent width. Has no effect in bar mode.	lineFullWidth: true
spec.axisLabelsMode	string	no	—	Axis label rendering. Values: smart (context-aware), long, short.	axisLabelsMode: smart
spec.dateInterval	string	no	auto-detect	Time granularity. Values: year, quarter, month, week, day, hour, minute, second, millisecond, auto.	dateInterval: month
spec.filter	string	no	""	AlaSQL WHERE clause fragment to filter rows.	filter: "region_group = 'EMEA'"
spec.level	string	no	auto-detect with warning	Aggregation level. Values: rowcategory, category, subcategory, auto.	level: category
spec.order	string	no	auto-detect with warning	Sort key. Values: category, categoryindex, rowgroup, rowgroupindex, ac1–ac4, fc1–fc4, pp1–pp4, pl1–pl4, auto.	order: ac1
spec.orderDirection	string	no	asc	Sort direction. Values: asc, desc.	orderDirection: desc
spec.measureScale	string	no	greatest	SI prefix for measure scaling. Values: _, k, M, G, T, P, E, Z, Y, m, μ, n, p, f, a, z, y, GREATEST, LEAST.	measureScale: M
spec.measureUnit	string	no	""	Unit string for the chart axis.	measureUnit: "EUR"
spec.unitScaling	string or number	no	—	Name of a scaling group or numeric pixels-per-unit factor. Numeric values enable overdrive bars on overflow.	unitScaling: 0.05
spec.percentageScaling	string or number	no	—	Name of a scaling group or numeric pixels-per-percentage factor.	percentageScaling: 50
spec.syncSpaceLeft	number	no	-1	Synchronize left axis space across charts (pixels). -1 disables.	syncSpaceLeft: 80
spec.showCategories	boolean	no	true	Show category labels.	showCategories: false
spec.showMeasureScale	boolean	no	false	Show measure unit in chart header.	showMeasureScale: true
spec.showOverlayAvg	boolean	no	true	Show average overlay line.	showOverlayAvg: true
spec.showOverlayMedian	boolean	no	false	Show median overlay line.	showOverlayMedian: true
spec.limit	integer	no	0	Column stack limit. 0 means unlimited.	limit: 12
spec.intervalSpanLimit	integer	no	28	Controls how many columns drive automatic date interval selection.	intervalSpanLimit: 50
spec.scenarios	string or array	no	—	Scenario measures (up to 4). Values: ac1–ac4, fc1–fc4, pp1–pp4, pl1–pl4, or auto.	scenarios: ["ac1", "fc1"]
spec.variances	string or array	no	—	Variance definitions. Pattern: d<scenarioB>_<scenarioA>_[pos|neg|neu].	variances: ["dfc1_ac1_pos"]
spec.scale	string or number	no	auto-scale with warning	Proportional scaling. "" or omitted: auto-scale to fit parent width with warning. "none": no scaling. "auto": auto-scale silently. Positive number: fixed factor.	scale: auto
spec.internationalisation	string	no	—	i18n namespace. Maps to the internationalisation HTML attribute.	internationalisation: "_system"
spec.internationalisationMode	string	no	—	i18n mode.	internationalisationMode: "default"
spec.translation	string	no	—	Translation key prefix.	translation: "chart.revenue.time"
spec.stack	object	no	—	Stacked rendering configuration. When chartMode is bar, produces stacked columns. When chartMode is line, produces stacked area chart.	see below

Stack configuration

spec:
  stack:
    by: scenarios       # scenarios | dimensions
    mode: absolute      # absolute | relative | absolute-relative
    order: dataset      # asc | desc | dataset

Property	Type	Required	Default	Description
stack.by	string	yes	—	Stacking dimension. scenarios: stacks scenario slots end-to-end. dimensions: auto-derives from level prop.
stack.mode	string	no	absolute	Stacking mode. absolute: additive. relative: 100% stacked. absolute-relative: absolute height with percentage labels.
stack.order	string	no	dataset	Segment order within each stack. Values: asc, desc, dataset.