config-handler

A browser-only ESM module that renders a full-screen configuration overlay from a schema object, with import/export and typed value retrieval.

Installation

npm install config-handler

Usage

import { ConfigHandler } from 'config-handler';

const schema = {
  volume: {
    inputLabel: 'Volume',
    inputType: 'number',
    dataType: 'float',
    defaultValue: 0.8,
    description: 'Master volume (0–1)',
  },
  theme: {
    inputLabel: 'Theme',
    inputType: 'select',
    dataType: null,
    defaultValue: 'dark',
    selectValues: ['Light', 'Dark', 'System'],
  },
  muted: {
    inputLabel: 'Muted',
    inputType: 'checkbox',
    dataType: null,
    defaultValue: false,
  },
};

const config = new ConfigHandler(schema);

// A gear button (⚙) is created automatically — no wiring needed to open the panel
// You can still open it programmatically if needed
config.setImportApplyFunction(() => applySettings(config.getValues()));

The overlay and a fixed-position gear button (⚙, bottom-right) are appended to document.body immediately on construction. The overlay is hidden by default; the gear button opens it. Pressing Escape closes it.

Schema

Each key in the schema object defines one input field.

| Property | Type | Required | Description | |---|---|---|---| | inputLabel | string | yes | Text displayed above the input | | inputType | string | yes | Any valid <input> type ('text', 'number', 'checkbox', 'range', …) or 'select' | | dataType | 'int' | 'float' | null | yes | Coerces getValue / getValues return type; use null for strings and booleans | | defaultValue | any | yes | Initial value; for checkboxes pass a boolean | | selectValues | string[] | when inputType === 'select' | Options rendered in the dropdown; matched case-insensitively against defaultValue | | description | string | no | Helper text rendered below the input |

API

new ConfigHandler(schema)

Creates the overlay and appends it to document.body. The overlay is hidden until openConfig() is called.

openConfig()

Shows the overlay.

closeConfig()

Hides the overlay.

getValue(key)

Returns the current value of one field, typed according to dataType. Returns undefined if the key does not exist.

const vol = config.getValue('volume'); // number

getValues()

Returns a plain object of all current values, keyed by schema field name and typed according to each field's dataType.

const { volume, theme, muted } = config.getValues();

onChange(fn, ...keys)

Attaches fn as the onchange handler for the named fields. Omit keys to target every field.

// Same callback for specific fields
config.onChange(regenerate, 'volume', 'theme', 'muted');

// Different callbacks per field — call multiple times
config.onChange(rebuildAudio, 'volume', 'muted');
config.onChange(rebuildTheme, 'theme');

// Apply to all fields
config.onChange(regenerate);

setImportApplyFunction(fn)

Registers a callback that fires after a config file is successfully imported. Use it to re-apply settings to your app.

config.setImportApplyFunction(() => {
  applySettings(config.getValues());
});

createOption(name, inputLabel, inputType, dataType, defaultValue, selectValues, description)

Dynamically adds an input field after construction. Useful when the set of options is not known at startup.

config.createOption('fps', 'Frame Rate', 'number', 'int', 60, null, 'Target FPS');

destroy()

Removes the overlay and gear button from the DOM and detaches the keyboard listener. Call when tearing down the page or component.

Import / Export

The overlay includes Import and Export buttons.

• Export — serializes all current values via getValues() to a .json file and prompts the user for a filename.
• Import — accepts a .json or .txt file and restores values. Unknown keys are skipped with a console.warn. After a successful import, the function registered with setImportApplyFunction is called.

Keyboard shortcut

Pressing Escape closes the overlay. To open it, click the gear button or call openConfig().