SaveButton

A save button for persisting datasource changes with explicit workflow feedback and update handling.

Import

import { SaveButton } from "@schukai/monster/source/components/datatable/save-button.mjs";

Source

View source code

Package

@schukai/monster

Since

1.0.0

Introduction

The Monster SaveButton persists pending datasource changes through one explicit commit action. Use it when edits should remain local until users deliberately save them.

When to use SaveButton

Use it for staged editing flows: Datatables and editing panels often gather changes before persistence.
Use it when users need a clear commit point: The button signals that local changes are not yet final.
Do not use it for autosave workflows: If changes are persisted immediately, the extra button adds noise.

Typical mistakes

Make unsaved state visible. A save button is most useful when users can tell that changes exist and understand what will be written once they confirm.

Simple Example

In this example, a simple data source is used and the value is adjusted after loading.

Javascript

import '@schukai/monster/source/components/datatable/save-button.mjs';

// simulate a data change
setTimeout(() => {
    const ds = document.querySelector('#myDataSource');
    ds.data = [];
}, 5000);<script type="module">//import '@schukai/monster/source/components/datatable/change-button.mjs';


setTimeout(() => {
    const ds = document.querySelector('#IeNg10');
    ds.data = [];
}, 5000);</script>

HTML

<monster-datasource-save-button data-monster-option-datasource-selector="#myDataSource"></monster-datasource-save-button>

<monster-datasource-rest id="myDataSource"
                         data-monster-option-features-autoInit="true"
                         data-monster-option-write-url="/assets/examples/countries.json"
                         data-monster-option-read-url="/assets/examples/countries.json?page=${page}"
></monster-datasource-rest>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Draft Changes Workflow

This example documents a realistic draft workflow: local datasource changes increase the badge count and the save action persists the new snapshot.

Increase price

Decrease stock

Log: ready

Javascript

import "@schukai/monster/source/components/datatable/datasource/dom.mjs";
import "@schukai/monster/source/components/datatable/save-button.mjs";
import "@schukai/monster/source/components/form/button.mjs";

const datasource = document.getElementById("save-button-workflow-source");
const priceButton = document.getElementById("save-button-workflow-price");
const stockButton = document.getElementById("save-button-workflow-stock");
const draft = document.getElementById("save-button-workflow-draft");
const saved = document.getElementById("save-button-workflow-saved");
const log = document.getElementById("save-button-workflow-log");

let savedSnapshot = null;

const cloneValue = (value) => JSON.parse(JSON.stringify(value));

const render = () => {
  const item = datasource.data?.dataset?.[0];
  if (!item) {
    return;
  }

  draft.textContent = "Draft: " + item.name + ", " + item.price + " EUR, " + item.stock + " units.";

  const persisted = savedSnapshot?.dataset?.[0];
  if (persisted) {
    saved.textContent = "Saved: " + persisted.name + ", " + persisted.price + " EUR, " + persisted.stock + " units.";
  }
};

datasource.write = async () => {
  await new Promise((resolve) => window.setTimeout(resolve, 400));
  savedSnapshot = cloneValue(datasource.data);
  log.textContent = "Log: changes stored in the datasource mock";
  render();
  return savedSnapshot;
};

window.setTimeout(() => {
  savedSnapshot = cloneValue(datasource.data);
  render();
}, 0);

priceButton.setOption("actions.click", () => {
  const next = cloneValue(datasource.data);
  next.dataset[0].price += 5;
  datasource.data = next;
  log.textContent = "Log: draft price increased";
  render();
});

stockButton.setOption("actions.click", () => {
  const next = cloneValue(datasource.data);
  next.dataset[0].stock = Math.max(0, next.dataset[0].stock - 1);
  datasource.data = next;
  log.textContent = "Log: draft stock decreased";
  render();
});<script type="module">import "@schukai/monster/source/components/datatable/datasource/dom.mjs";
import "@schukai/monster/source/components/datatable/save-button.mjs";
import "@schukai/monster/source/components/form/button.mjs";

const datasource = document.getElementById("save-button-workflow-source-run");
const priceButton = document.getElementById("save-button-workflow-price-run");
const stockButton = document.getElementById("save-button-workflow-stock-run");
const draft = document.getElementById("save-button-workflow-draft-run");
const saved = document.getElementById("save-button-workflow-saved-run");
const log = document.getElementById("save-button-workflow-log-run");

let savedSnapshot = null;

const cloneValue = (value) => JSON.parse(JSON.stringify(value));

const render = () => {
  const item = datasource.data?.dataset?.[0];
  if (!item) {
    return;
  }

  draft.textContent = "Draft: " + item.name + ", " + item.price + " EUR, " + item.stock + " units.";

  const persisted = savedSnapshot?.dataset?.[0];
  if (persisted) {
    saved.textContent = "Saved: " + persisted.name + ", " + persisted.price + " EUR, " + persisted.stock + " units.";
  }
};

datasource.write = async () => {
  await new Promise((resolve) => window.setTimeout(resolve, 400));
  savedSnapshot = cloneValue(datasource.data);
  log.textContent = "Log: changes stored in the datasource mock";
  render();
  return savedSnapshot;
};

window.setTimeout(() => {
  savedSnapshot = cloneValue(datasource.data);
  render();
}, 0);

priceButton.setOption("actions.click", () => {
  const next = cloneValue(datasource.data);
  next.dataset[0].price += 5;
  datasource.data = next;
  log.textContent = "Log: draft price increased";
  render();
});

stockButton.setOption("actions.click", () => {
  const next = cloneValue(datasource.data);
  next.dataset[0].stock = Math.max(0, next.dataset[0].stock - 1);
  datasource.data = next;
  log.textContent = "Log: draft stock decreased";
  render();
});</script>

HTML

<div style="display:grid;gap:1rem;max-inline-size:36rem;">
  <monster-datasource-save-button
    id="save-button-workflow-demo"
    data-monster-option-datasource-selector="#save-button-workflow-source"
    data-monster-options='{"disableWhenNoChanges": true}'
  ></monster-datasource-save-button>

  <div style="display:flex;flex-wrap:wrap;gap:0.75rem;">
    <monster-button id="save-button-workflow-price">Increase price</monster-button>
    <monster-button id="save-button-workflow-stock">Decrease stock</monster-button>
  </div>

  <p id="save-button-workflow-draft" style="margin:0;"></p>
  <p id="save-button-workflow-saved" style="margin:0;"></p>
  <div id="save-button-workflow-log">Log: ready</div>

  <monster-datasource-dom id="save-button-workflow-source">
    <script type="application/json">
      {
        "dataset": [
          {
            "id": 1,
            "name": "Monster Hoodie",
            "price": 69,
            "stock": 14
          }
        ]
      }
    </script>
  </monster-datasource-dom>
</div>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

This component is built using the Shadow DOM, which allows it to encapsulate its internal structure and styling. By using a shadow root, the component's internal elements are isolated from the rest of the webpage, ensuring that external styles or scripts cannot accidentally modify its internal layout or behavior.

Shadow DOM and Accessibility

Since the component is encapsulated within a shadow root, direct access to its internal elements is restricted. This means that developers cannot manipulate or style these elements from outside the component. The Shadow DOM helps maintain consistency in the design and behavior of the component by preventing external interference.

Customizing Through Exported Parts

While the Shadow DOM restricts direct access to the component's internal structure, customization is still possible through exported parts. Specific parts of the component are made accessible for styling by being explicitly marked for export. These exported parts can be targeted and customized using CSS, allowing you to modify the appearance of the component without compromising its encapsulation.

Available Part Attributes

control: This part represents the entire control area of the save button, including the button and the badge. Use this to style the general layout and background of the control panel.
state-button: Represents the save button, allowing styling for various states such as "changed" or "disabled".
badge: Represents the badge indicating the number of unsaved changes.

Below is an example of how to use CSS part attributes to customize different parts of the component.


monster-datasource-save-button::part(state-button) {
    background-color: #4CAF50;
    color: white;
}
monster-datasource-save-button::part(badge) {
    background-color: red;
    color: white;
    border-radius: 50%;
}

Accessibility

Accessibility is a key consideration in the design of this component. By following best practices for web accessibility, the component ensures that users of all abilities can interact with it effectively. This includes support for keyboard navigation, screen readers, and other assistive technologies to provide an inclusive user experience.

HTML Structure

<monster-save-button></monster-save-button>

JavaScript Initialization

const element = document.createElement('monster-save-button');
document.body.appendChild(element);

Exported

SaveButton

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option

Type

Default

Description

templates

object

undefined

Template definitions

templates.main

string

undefined

Main template

datasource

object

undefined

The datasource

datasource.selector

string

undefined

The selector of the datasource

labels.button

string

undefined

The button label

classes

object

undefined

The classes

classes.bar

string

undefined

The bar class

classes.badge

string

undefined

The badge class

ignoreChanges

array

undefined

The ignore changes (regex)

data

array

undefined

The data

disabled

boolean

undefined

The disabled state

disableWhenNoChanges

boolean

undefined

Disable button when there are no changes

logLevel

string

undefined

The log level (off, debug)

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

[CSSStyleSheet]

getTag()

Returns

{string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

This method is responsible for assembling the component. It calls the parent's assemble method first, then initializes control references and event handlers. If the datasource.selector option is provided and is a string, it searches for the corresponding element in the DOM using that selector. If the selector matches exactly one element, it checks if the element is an instance of the Datasource class. If it is, the component's datasourceLinkedElementSymbol property is set to the element, and the component attaches an observer to the datasource's changes. The observer is a function that calls the handleDataSourceChanges method in the context of the component. Additionally, the component attaches an observer to itself, which also calls the handleDataSourceChanges method in the component's context.

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.