Vue Embedded AnalyticsUndo & Redo

Version 3.0.0

Studio records each change made to a report, and can step back and forward through them.

Undo and redo cover the durable document: widgets, layout, filters and schema. View state such as the selected page and the current selection is left where it is, then brought back into view for the restored change.

main.ts

import type {
  AgFieldDefinition,
  AgReportHistory,
  AgReportState,
  AgStudioApi,
  AgStudioApiReadyEvent,
  AgStudioMode,
} from "ag-studio";
import { enableStudioDevValidations } from "ag-studio";
import { AgStudio } from "ag-studio-vue3";
import { createApp, defineComponent, ref, shallowRef } from "vue";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const INITIAL_STATE: AgReportState = {
  selectedPageId: "main",
  pages: [
    {
      id: "main",
      widgets: {
        "kpi-revenue": {
          type: "value",
          dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }] },
          format: { caption: { enabled: true, text: "Total Revenue" } },
        },
        "by-region": {
          type: "bar-chart-grouped",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
          },
          format: { title: { enabled: true, text: "Revenue by Region" } },
        },
        "sales-grid": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "sales.region" },
              { id: "sales.product" },
              { id: "sales.revenue", aggregation: "sum" },
              { id: "sales.units", aggregation: "sum" },
            ],
          },
          format: { title: { enabled: true, text: "Sales" } },
        },
      },
      widgetLayout: {
        "kpi-revenue": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 6 },
        "by-region": { xTrack: 0, yTrack: 6, xSpan: 24, ySpan: 16 },
        "sales-grid": { xTrack: 0, yTrack: 22, xSpan: 24, ySpan: 16 },
      },
    },
  ],
};

const SALES_DATA = [
  { region: "North", product: "Widget", revenue: 4200, units: 120 },
  { region: "North", product: "Gadget", revenue: 3100, units: 80 },
  { region: "South", product: "Widget", revenue: 2600, units: 70 },
  { region: "South", product: "Gadget", revenue: 5400, units: 150 },
  { region: "East", product: "Widget", revenue: 1800, units: 45 },
  { region: "East", product: "Gadget", revenue: 3900, units: 110 },
  { region: "West", product: "Widget", revenue: 4700, units: 130 },
  { region: "West", product: "Gadget", revenue: 2200, units: 60 },
];

const SALES_FIELDS: AgFieldDefinition[] = [
  { id: "region", name: "Region", format: "textFormat" },
  { id: "product", name: "Product", format: "textFormat" },
  { id: "revenue", name: "Revenue", format: "currencyFormat" },
  { id: "units", name: "Units", format: "integerFormat" },
];

const INITIAL_WIDGET_IDS = ["kpi-revenue", "by-region", "sales-grid"];

function selectedPage(state: AgReportState) {
  return state.pages.find((page) => page.id === state.selectedPageId)!;
}

// Read the added charts back from live state, so add and remove stay in step with undo and redo
// rather than tracking a private list that drifts once state is restored.
function addedChartIds(state: AgReportState): string[] {
  const widgets = selectedPage(state).widgets ?? {};
  return Object.keys(widgets).filter((id) => !INITIAL_WIDGET_IDS.includes(id));
}

function describeNext(history: AgReportHistory): string {
  const nextUndo = history.undo.at(-1);
  const nextRedo = history.redo.at(-1);
  const undoText = nextUndo
    ? `${nextUndo.label} (${history.undo.length})`
    : "nothing";
  const redoText = nextRedo
    ? `${nextRedo.label} (${history.redo.length})`
    : "nothing";
  return `undo: ${undoText}   redo: ${redoText}`;
}

const VueExample = defineComponent({
  template: `
        <div style="display: flex; flex-direction: column; height: 100%">
            <div class="example-controls">
                <div class="controls-row">
                    <button v-on:click="doUndo()" :disabled="!canUndo">Undo</button>
                    <button v-on:click="doRedo()" :disabled="!canRedo">Redo</button>
                    <button v-on:click="undoAll()" :disabled="!canUndo">Undo All</button>
                    <button v-on:click="addChart()">Add chart</button>
                    <button v-on:click="removeLast()">Remove last</button>
                    <button v-on:click="toggleMode()">
                        {{ mode === 'edit' ? 'Switch to View Mode' : 'Switch to Edit Mode' }}
                    </button>
                    <span class="history-status">{{ status }}</span>
                </div>
            </div>
            <ag-studio
                style="width: 100%; height: 100%;"
                class="my-studio-container"
                @api-ready="onApiReady"
                :initialState="initialState"
                :mode="mode"
                :data="data"
                @state-updated="onStateUpdated"></ag-studio>
        </div>
    `,
  components: {
    "ag-studio": AgStudio,
  },
  setup() {
    const studioApi = shallowRef<AgStudioApi | null>(null);
    const initialState = ref<AgReportState>(INITIAL_STATE);
    const mode = ref<AgStudioMode>("edit");
    const data = ref({
      sources: [
        { id: "sales", name: "Sales", data: SALES_DATA, fields: SALES_FIELDS },
      ],
    });
    const canUndo = ref(false);
    const canRedo = ref(false);
    const status = ref("");

    const onStateUpdated = () => {
      const history = studioApi.value!.getHistory();
      canUndo.value = history.undo.length > 0;
      canRedo.value = history.redo.length > 0;
      status.value = describeNext(history);
    };
    const onApiReady = (params: AgStudioApiReadyEvent) => {
      studioApi.value = params.api;
      onStateUpdated();
    };
    const doUndo = () => {
      studioApi.value!.undo();
    };
    const doRedo = () => {
      studioApi.value!.redo();
    };
    const undoAll = () => {
      const oldest = studioApi.value!.getHistory().undo[0];
      if (oldest) studioApi.value!.undo(oldest.id);
    };
    const addChart = () => {
      const api = studioApi.value!;
      const state = api.getState();
      const page = selectedPage(state);
      const added = addedChartIds(state);
      const nextNum =
        added.reduce(
          (max, id) => Math.max(max, Number(id.slice("chart-".length)) || 0),
          0,
        ) + 1;
      const id = `chart-${nextNum}`;
      const yTrack = 38 + (added.length + 1) * 16;

      api.setState({
        ...state,
        pages: state.pages.map((p) =>
          p.id !== page.id
            ? p
            : {
                ...p,
                widgets: {
                  ...p.widgets,
                  [id]: {
                    type: "bar-chart-grouped",
                    dataMapping: {
                      categoryKey: [{ id: "sales.product" }],
                      valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
                    },
                    format: {
                      title: {
                        enabled: true,
                        text: `Revenue by Product (${id})`,
                      },
                    },
                  },
                },
                widgetLayout: {
                  ...p.widgetLayout,
                  [id]: { xTrack: 0, yTrack, xSpan: 24, ySpan: 16 },
                },
              },
        ),
      });
    };
    const removeLast = () => {
      const api = studioApi.value!;
      const state = api.getState();
      const added = addedChartIds(state);
      const id = added[added.length - 1];
      if (id == null) return;

      api.setState({
        ...state,
        pages: state.pages.map((p) => {
          const { [id]: _removedWidget, ...widgets } = p.widgets ?? {};
          const { [id]: _removedLayout, ...widgetLayout } =
            p.widgetLayout ?? {};
          return { ...p, widgets, widgetLayout };
        }),
      });
    };
    const toggleMode = () => {
      mode.value = mode.value === "edit" ? "view" : "edit";
    };

    return {
      studioApi,
      initialState,
      mode,
      data,
      canUndo,
      canRedo,
      status,
      onApiReady,
      onStateUpdated,
      doUndo,
      doRedo,
      undoAll,
      addChart,
      removeLast,
      toggleMode,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

styles.css

.history-status {
    font: 12px/1.4 monospace;
    margin-left: auto;
    opacity: 0.75;
    white-space: pre;
}

Keyboard Shortcuts Copy Link

While focus is inside Studio:

⌃ Ctrl/⌘ Cmd + Z - Undo the last change.
⌃ Ctrl/⌘ Cmd + ⇧ Shift + Z - Redo.

The shortcuts are bound to Studio's own element, so they work only while focus is inside it. Studio listens nowhere else: with focus in one of your application's inputs or controls, the key press is yours, and a text field inside Studio keeps the shortcut for its own editing history. See Keyboard Shortcuts for Studio's other shortcuts.

Undoing From Outside Studio Copy Link

To undo while focus is elsewhere in your application, bind the shortcut yourself and call undo() or redo():

document.addEventListener('keydown', (event) => {
    if (!(event.ctrlKey || event.metaKey) || event.code !== 'KeyZ') return;

    event.preventDefault();
    if (event.shiftKey) {
        api.redo();
    } else {
        api.undo();
    }
});

How far that binding reaches, and which of your own components it should leave alone, is yours to decide. Studio makes no assumptions about the page around it.

A binding on the document also fires for a press made inside Studio, because Studio does not stop the event propagating. Suppress the shortcut in Studio, as below, so one press does not undo twice.

Suppressing the Shortcuts Copy Link

suppressKeyboard stops Studio handling a shortcut, leaving the key press for the application to bind:

<ag-studio
    :suppressKeyboard="suppressKeyboard"
    /* other studio properties ... */>
</ag-studio>

this.suppressKeyboard = {
    undo: true,
    redo: true,
};

Each is independent, so { redo: true } keeps undo on ⌃ Ctrl/⌘ Cmd + Z. A suppressed shortcut is left untouched rather than swallowed, so a handler of your own still receives the event.

Undoing and Redoing in Code Copy Link

undo() and redo() each step one change, and do nothing at the end of their stack:

api.undo();
api.redo();

Making a new change discards whatever was waiting to be redone.

Reading the History Copy Link

Studio ships no undo controls of its own, so an application that wants them builds them from getHistory(). It returns the live state alongside the changes each action would step through:

const { undo, redo } = api.getHistory();
undoButton.disabled = undo.length === 0;
redoButton.disabled = redo.length === 0;

Refresh the controls from the stateUpdated event, which fires after every committed change - undo and redo included - and also when the history is discarded, whether or not the live state itself changed. A host persisting on this event sees one write per clearHistory() call, and one per mode switch once it opts into history.onModeChange: 'clear'.

The last entry of each stack is the one that action takes next, and its label names the change. Labels come from the locale, so they follow the configured language:

const next = api.getHistory().undo.at(-1);
undoButton.title = next ? `Undo ${next.label}` : 'Nothing to undo';

Each entry also carries an id. Passing one to undo() or redo() steps through every change up to that entry as a single step, which is what a history list needs:

const { undo } = api.getHistory();
api.undo(undo[0].id); // back to the start of the history

The history holds the last 100 changes by default, and is cleared when Studio loads initialState. A later setState() is recorded as a change like any other, so it can be undone. It can also be cleared explicitly with api.clearHistory(), or automatically on a mode change with history.onModeChange: 'clear', both covered below.

Limiting the History Copy Link

Each entry holds the whole state either side of its change, so a long history on a large dashboard costs memory. Set history.maxEntries to trade how far back a user can undo against what that retention costs:

<ag-studio
    :history="history"
    /* other studio properties ... */>
</ag-studio>

this.history = {
    maxEntries: 20,
};

Once the history holds that many changes, recording a new one discards the oldest, which can no longer be undone. Undone changes do not add to the count: undoing moves a change from the undo side to the redo side rather than creating another one, so the two stacks together never exceed the limit.

A value below one keeps no history, leaving undo() and redo() with nothing to do. Changes still apply as normal; only the ability to reverse them is given up.

Clearing the History Copy Link

Call clearHistory() to discard the undo and redo stacks without touching the live state:

api.clearHistory();

getHistory() then returns empty stacks, and undo()/redo() are no-ops until the next change. The live state is untouched, so the changes themselves remain - only the ability to step back over them goes.

Set history.onModeChange to have this happen automatically whenever mode changes:

<ag-studio
    :history="history"
    /* other studio properties ... */>
</ag-studio>

this.history = {
    onModeChange: 'clear',
};

The default, 'preserve', carries the history across a mode switch. 'clear' discards it on a switch in either direction, so a change made while in view mode (possible when filter editing is enabled there) is discarded too on the way back to edit mode. Mode does not otherwise gate undo or redo - both work in either mode.

Add a chart or two below, then clear the history explicitly or switch mode with onModeChange set to 'clear'. The counts show both stacks emptying while the charts stay where they are:

main.ts

import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgStudio } from "ag-studio-vue3";
import {
  AgDataEngine,
  AgDataSourcesDefinition,
  AgFieldDefinition,
  AgHistoryOptions,
  AgReportState,
  AgStudioApi,
  AgStudioApiReadyEvent,
  AgStudioMode,
  AgStudioProperties,
  enableStudioDevValidations,
} from "ag-studio";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const salesData = [
  { region: "North", product: "Widget", revenue: 4200 },
  { region: "North", product: "Gadget", revenue: 3100 },
  { region: "South", product: "Widget", revenue: 2600 },
  { region: "South", product: "Gadget", revenue: 5400 },
  { region: "East", product: "Widget", revenue: 1800 },
  { region: "East", product: "Gadget", revenue: 3900 },
  { region: "West", product: "Widget", revenue: 4700 },
  { region: "West", product: "Gadget", revenue: 2200 },
];

const salesFields: AgFieldDefinition[] = [
  { id: "region", name: "Region", format: "textFormat" },
  { id: "product", name: "Product", format: "textFormat" },
  { id: "revenue", name: "Revenue", format: "currencyFormat" },
];

const INITIAL_WIDGET_IDS = ["by-region"];

// Held here rather than read back through `getProperty('history')`: a framework wrapper may model
// the property as its own component state, which does not settle until after this handler returns.
let onModeChange: "preserve" | "clear" = "preserve";

function selectedPage(state: AgReportState) {
  return state.pages.find((page) => page.id === state.selectedPageId)!;
}

// Read the added charts back from live state, so the count stays in step with undo and redo rather
// than tracking a private list that drifts once state is restored.
function addedChartIds(state: AgReportState): string[] {
  const widgets = selectedPage(state).widgets ?? {};
  return Object.keys(widgets).filter((id) => !INITIAL_WIDGET_IDS.includes(id));
}

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <div style="display: flex; flex-direction: column; height: 100%">
      <div class="example-controls">
        <div class="controls-row">
          <button v-on:click="addChart()">Add chart</button>
          <button id="undoBtn" v-on:click="doUndo()">Undo</button>
          <button id="redoBtn" v-on:click="doRedo()">Redo</button>
          <button id="clearBtn" v-on:click="clearHistory()">Clear history</button>
          <button id="onModeChangeBtn" v-on:click="toggleOnModeChange()">onModeChange: preserve</button>
          <button id="modeBtn" v-on:click="toggleMode()">Switch to View Mode</button>
          <span class="history-status">
            undo: <span id="undoCount">0</span>, redo: <span id="redoCount">0</span>
          </span>
        </div>
      </div>
      <ag-studio
        style="width: 100%; height: 100%;"
        class="my-studio-container"
        @api-ready="onApiReady"
        :initialState="initialState"
        :mode="mode"
        :history="history"
        :data="data"
        @state-updated="onStateUpdated"></ag-studio>
      </div>
        </div>
    `,
  components: {
    "ag-studio": AgStudio,
  },
  setup(props) {
    const studioApi = shallowRef<AgStudioApi | null>(null);
    const initialState = ref<AgReportState>({
      selectedPageId: "main",
      pages: [
        {
          id: "main",
          widgets: {
            "by-region": {
              type: "bar-chart-grouped",
              dataMapping: {
                categoryKey: [{ id: "sales.region" }],
                valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
              },
              format: { title: { enabled: true, text: "Revenue by Region" } },
            },
          },
          widgetLayout: {
            "by-region": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 18 },
          },
        },
      ],
    });
    const mode = ref<AgStudioMode>("edit");
    const history = ref<AgHistoryOptions>({ onModeChange: "preserve" });
    const data = ref<AgDataSourcesDefinition | AgDataEngine>({
      sources: [
        { id: "sales", name: "Sales", data: salesData, fields: salesFields },
      ],
    });

    function onStateUpdated() {
      refreshControls();
    }
    function addChart() {
      const state = studioApi.value.getState();
      const page = selectedPage(state);
      const added = addedChartIds(state);
      // Past the largest suffix in use, not the count: a chart deleted through Studio's own widget
      // menu would otherwise free a number that is still on a surviving chart, and adding would
      // overwrite it instead of adding one.
      const nextNum =
        added.reduce(
          (max, chartId) =>
            Math.max(max, Number(chartId.slice("chart-".length)) || 0),
          0,
        ) + 1;
      const id = `chart-${nextNum}`;
      studioApi.value.setState({
        ...state,
        pages: state.pages.map((p) =>
          p.id !== page.id
            ? p
            : {
                ...p,
                widgets: {
                  ...p.widgets,
                  [id]: {
                    type: "bar-chart-grouped",
                    dataMapping: {
                      categoryKey: [{ id: "sales.product" }],
                      valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
                    },
                    format: {
                      title: {
                        enabled: true,
                        text: `Revenue by Product (${id})`,
                      },
                    },
                  },
                },
                widgetLayout: {
                  ...p.widgetLayout,
                  [id]: {
                    xTrack: 0,
                    yTrack: 18 + (nextNum - 1) * 14,
                    xSpan: 24,
                    ySpan: 14,
                  },
                },
              },
        ),
      });
    }
    function doUndo() {
      studioApi.value.undo();
    }
    function doRedo() {
      studioApi.value.redo();
    }
    // The live state is untouched: the charts stay, only the ability to step back over them goes.
    function clearHistory() {
      studioApi.value.clearHistory();
    }
    function toggleOnModeChange() {
      onModeChange = onModeChange === "clear" ? "preserve" : "clear";
      studioApi.value.setProperty("history", { onModeChange: onModeChange });
      refreshControls();
    }
    function toggleMode() {
      const next =
        studioApi.value.getProperty("mode") === "edit" ? "view" : "edit";
      studioApi.value.setProperty("mode", next);
      refreshControls();
    }
    const onApiReady = (params: AgStudioApiReadyEvent) => {
      studioApi.value = params.api;
    };
    function refreshControls() {
      const { undo, redo } = studioApi.value.getHistory();
      const mode = studioApi.value.getProperty("mode");
      (document.getElementById("undoBtn") as HTMLButtonElement).disabled =
        undo.length === 0;
      (document.getElementById("redoBtn") as HTMLButtonElement).disabled =
        redo.length === 0;
      (document.getElementById("clearBtn") as HTMLButtonElement).disabled =
        undo.length === 0 && redo.length === 0;
      document.getElementById("modeBtn")!.textContent =
        mode === "edit" ? "Switch to View Mode" : "Switch to Edit Mode";
      document.getElementById("onModeChangeBtn")!.textContent =
        `onModeChange: ${onModeChange}`;
      document.getElementById("undoCount")!.textContent = String(undo.length);
      document.getElementById("redoCount")!.textContent = String(redo.length);
    }

    return {
      studioApi,
      initialState,
      mode,
      history,
      data,
      onApiReady,
      onStateUpdated,
      addChart,
      doUndo,
      doRedo,
      clearHistory,
      toggleOnModeChange,
      toggleMode,
      refreshControls,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");

styles.css

.history-status {
    font: 12px/1.4 monospace;
    margin-left: auto;
    opacity: 0.75;
    white-space: nowrap;
}

Undo & Redo API Copy Link

Properties Copy Link

AgSuppressKeyboard

Keyboard shortcuts Studio should not handle, so an application can bind them itself. Each shortcut is suppressed independently, e.g. { redo: true } keeps undo on ctrl/cmd+Z and leaves ctrl/cmd+shift+Z to the application.

AgHistoryOptions

How Studio's undo and redo history behaves.

API Methods Copy Link

Function

Undo the last change to the durable document state (widgets, layout, filters, schema). View state such as the selected page or selection is left as it is, then brought back into view for the restored change. No-op when there is nothing to undo (getHistory().undo is empty). Pass a getHistory().undo entry's id to undo every change back through that entry in a single step; an unknown id is a no-op.

Function

Redo the change most recently undone. No-op when there is nothing to redo (getHistory().redo is empty). Making a fresh change discards the redo branch. Pass a getHistory().redo entry's id to redo every change forward through that entry in a single step; an unknown id is a no-op.

Function

The editing history: the live state plus what undo() and redo() would step through, each entry labelled and timestamped. Drives control enablement (an empty undo stack means there is nothing to undo) and a history list. History does not survive loading new state.

Function

Discard the undo and redo history, so getHistory() returns empty stacks and undo()/redo() become no-ops until the next change. The live state is untouched.

Getting Started

Connecting Data

Agent Framework

Fields & Formatting

Appearance & Behaviour

Widgets

Server-Side Data

User Guide

Vue Embedded AnalyticsUndo & Redo

Keyboard Shortcuts Copy Link

Undoing From Outside Studio Copy Link

Suppressing the Shortcuts Copy Link

Undoing and Redoing in Code Copy Link

Reading the History Copy Link

Limiting the History Copy Link

Clearing the History Copy Link

Undo & Redo API Copy Link

Properties Copy Link

API Methods Copy Link