{
    "title": "State History Configuration",
    "description": "A state history timeline chart widget for visualizing discrete state changes over time. Use this widget to display how entities transition between states (e.g., machine operating states, device connectivity, task status). Each row represents an entity (asset/device) and shows colored horizontal bars indicating which state it was in at any point in time. States are mapped to colors for quick visual recognition. Supports multiple data series, pivot-based auto-generation from data columns, and zoom controls for time navigation. Ideal for production monitoring, equipment uptime tracking, process state analysis, or any scenario requiring visual representation of state durations and transitions.",
    "aiSelection": {
        "dataShape": "State-over-time rows: dataseries[].data[] entries of (tsp, state, label), where state is a discrete name matched against stateMap[] for its colour and label identifies the entity. Each entity becomes a row of coloured spans along a shared time axis. A pivot column can generate the entities.",
        "useWhen": [
            "The question is what state something was in, and for how long — machine mode, running / idle / fault, connectivity, job status.",
            "Several assets should be compared as rows on one timeline to reveal overlaps, gaps and simultaneous stoppages.",
            "Uptime, downtime reasons or shift patterns should be visible as durations rather than counted."
        ],
        "notFor": [
            "A numeric measurement over time — use widget-linechart; this widget plots state names, not quantities.",
            "How often each state occurred, or total time per state as a comparison — aggregate first, then use widget-linechart with dataseries[].type: 'bar', or widget-doughnut for shares of total time.",
            "Only the current state — use widget-signal, or widget-switch when it must be controllable.",
            "Two categorical dimensions with a numeric intensity — use widget-heatmap."
        ]
    },
    "type": "object",
    "properties": {
        "title": {
            "title": "Title",
            "description": "The main heading displayed above the chart. Use to describe what state history is being shown (e.g., 'Machine Operating States', 'Device Connectivity History').",
            "type": "string",
            "order": 1
        },
        "subTitle": {
            "title": "Subtitle",
            "description": "Secondary text displayed below the title. Use for additional context like facility name, time period, or data source.",
            "type": "string",
            "order": 2
        },
        "axis": {
            "title": "Axis Settings",
            "description": "Configuration for the time axis and legend display.",
            "type": "object",
            "order": 3,
            "properties": {
                "xAxisLabel": {
                    "title": "Time-Axis Label",
                    "description": "Label text displayed below the horizontal time axis. Typically 'Time', 'Date', or left empty.",
                    "type": "string",
                    "dataDrivenDisabled": false,
                    "order": 3
                },
                "xAxisZoom": {
                    "title": "Time Axis Zoom Tool",
                    "type": "boolean",
                    "description": "When enabled, shows a slider control below the chart for zooming into specific time ranges. Leave this DISABLED (the default) unless the user explicitly asks for a zoom, pan, or time-range slider: the slider costs vertical chart space, and dashboards usually already control the visible time range through their data query or a filter widget. Do not enable it just because the history period is long.",
                    "default": false,
                    "dataDrivenDisabled": true,
                    "order": 6
                },
                "showLegend": {
                    "title": "Show Legend",
                    "type": "boolean",
                    "description": "When enabled, displays a legend showing the mapping between colors and state names. Essential for understanding the visualization.",
                    "dataDrivenDisabled": true,
                    "order": 7
                }
            }
        },
        "stateMap": {
            "title": "State Map",
            "description": "Array defining all possible states and their display colors. Each state that appears in the data should have a corresponding entry here for proper color coding.",
            "type": "array",
            "dataDrivenDisabled": true,
            "order": 3,
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "title": "State Name",
                        "description": "The exact state value as it appears in the data (e.g., 'RUNNING', 'STOPPED', 'IDLE', 'ERROR'). Must match the data values exactly for color mapping to work.",
                        "type": "string",
                        "required": true,
                        "order": 1
                    },
                    "color": {
                        "title": "Color",
                        "description": "The color representing this state in the timeline. Use semantic colors: green for active/OK states, red for error/stopped, yellow for warning/idle, gray for unknown.",
                        "type": "color",
                        "color": true,
                        "required": true,
                        "order": 2
                    }
                }
            }
        },
        "dataseries": {
            "title": "Dataseries",
            "description": "Array of data series containing state change events. Each series can represent a group of related assets or a category of state data.",
            "type": "array",
            "dataDrivenDisabled": true,
            "order": 4,
            "items": {
                "type": "object",
                "properties": {
                    "label": {
                        "title": "Label",
                        "description": "Display name for this data series group. Used in legends and tooltips to identify the data source.",
                        "type": "string",
                        "required": true,
                        "order": 1
                    },
                    "chartName": {
                        "title": "Chart Name",
                        "description": "Groups data into separate timeline charts. Series with the same chartName share one chart; different names create separate charts. Use '#split#' to auto-create one chart per pivot value.",
                        "type": "string",
                        "dataDrivenDisabled": true,
                        "order": 3
                    },
                    "data": {
                        "title": "Data",
                        "description": "Array of state change events. Each event has a timestamp and new state. The chart draws bars from each event to the next, showing how long each state lasted.",
                        "type": "array",
                        "order": 5,
                        "items": {
                            "type": "object",
                            "properties": {
                                "label": {
                                    "title": "Asset Label",
                                    "description": "Identifier for the entity (machine, device, asset) this event belongs to. Events with the same label form one timeline row. Different labels create separate rows.",
                                    "order": 3,
                                    "type": "string"
                                },
                                "tsp": {
                                    "title": "Event Timestamp",
                                    "description": "When this state change occurred. Use ISO 8601 format (e.g., '2023-11-04T22:47:52.351152+00:00') or Unix timestamps. Events should be in chronological order.",
                                    "type": "string",
                                    "order": 1,
                                    "required": true
                                },
                                "state": {
                                    "title": "State",
                                    "description": "The new state that began at this timestamp. Must match a state name defined in the State Map for proper color coding.",
                                    "type": "string",
                                    "order": 2,
                                    "required": true
                                },
                                "pivot": {
                                    "title": "Split Data by",
                                    "description": "Column value used to split data into multiple timeline rows automatically. Each unique pivot value creates a separate row (e.g., pivot by 'machine_id' to show one row per machine).",
                                    "order": 4,
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}