@xcwds/plugin-settings

The settings page for an @xcwds app, generalised from xcwds.github.io's /settings. It shows:

every plugin's settings, grouped by section, with built-in controls;
whole sections other plugins add, such as Install and What's new;
Your data: download, share or import a backup, and clear data per group or all at once;
Privacy: the servers the app contacts and why, from each plugin's network metadata and privacy.allowOrigins (or that it contacts none), and every plugin's declared network use;
About.

// xcwds.config.ts
import settings from '@xcwds/plugin-settings';

export default defineConfig({
	brand,
	plugins: [
		shell({ sections: [/* … */ { path: '/settings', label: 'Settings', emoji: '⚙️' }] }),
		settings({ source: 'https://github.com/me/my-app', backupName: 'my-app-backup' })
	]
});

/* src/app.css, after Tailwind and the shell's styles */
@import '@xcwds/plugin-settings/styles.css';

<!-- src/routes/settings/+page.svelte -->
<script>
	import SettingsPage from '@xcwds/plugin-settings/SettingsPage.svelte';
</script>

<main class="page-narrow">
	<SettingsPage>
		{#snippet about()}<p>Anything else for About.</p>{/snippet}
	</SettingsPage>
</main>

Options

Option	Default	What it does
`path`	`/settings`	The page (added to the route registry with `title` and `emoji`).
`title`	`Settings`	Its title.
`emoji`	`⚙️`	Its emoji; `''` shows none.
`width`	`narrow`	`narrow`, or `split` for a page laid out in two columns on wide screens.
`sections`	`{}`	Titles by section id, in the order they show (`{ tools: 'Tool defaults' }`).
`source`	none	An `https://` link to the app's source, under About.
`backupName`	`backup`	The backup file's name before its date.

Settings fields

A field shows when it has a control (plain data, so the kernel stays framework-free):

app.settings.field('alarm', {
	default: { sound: true },
	parse,
	label: 'Timer alarm',
	section: 'timers',
	control: {
		type: 'switches',
		options: [{ key: 'sound', label: 'Alarm sound', hint: 'Beep when done.' }]
	}
});

Control	Shape	Shows
`choice`	`options: [{ value, label }]`	A segmented control (radio buttons).
`switch`	(none)	A switch for a boolean field.
`number`	`min`, `max`, `step?`, `unit?`	A − / + stepper.
`switches`	`options: [{ key, label, hint? }]`	One switch per boolean in an object.

hint adds a line under the field's label. Sections are ordered as in sections, then Appearance, General and Timers, then the rest in the order their fields were added.

For plugins

app.settingsPage.control(name, Component) shows a field with your component (it gets the field's name). @xcwds/plugin-shell shows its nav setting with NavPicker this way.
app.settingsPage.add(Component, { props?, order? }) adds a whole section. Fields sit at order 0, Your data at 100, Privacy at 150 and About at 200; @xcwds/plugin-install adds its card at -100.

Both are usually called on boot, with the component imported dynamically (the component imports @xcwds/sveltekit, which imports your page entry).

Your data

Backups: the JSON from app.storage.exportData(), downloaded (or shared, where the browser can share files). Importing shows what it holds first, then merges or replaces.
Clearing: one button per storage group, labelled by its entries (e.g. "Clear Home shortcuts"), and Clear all data, each confirmed first. Clears and imports reach every component on this tab through app.storage.onChange, so what's showing updates without a reload.
A warning shows when the browser won't let the app save.
Toasts (app.toast) confirm what happened; an invalid backup shows an inline error.

API

From the package's types and doc comments.

Options (SettingsOptions)

path? string: The settings page. Defaults to /settings.
title? string
emoji? string: Shown before the title in the header. Defaults to ⚙️; '' shows none.
width? 'narrow' | 'split': The page's width (@xcwds/sveltekit's route widths): narrow (the default), or split, narrow until wide screens, where an app's own settings page can lay out two columns.
sections? Record<string, string>: Titles for settings sections by id (fields' section), in the order they show.
source? string: A link to the app's source code, shown under About.
backupName? string: The backup file's name before the date, e.g. xcwds-backup. Defaults to backup.

Decorators

app.settingsPage? AppSettingsPage

From @xcwds/plugin-settings.

app.settingsPage.options ResolvedSettingsOptions
app.settingsPage.add (component: PageSection['component'], options?: { props?: Record<string, unknown>; order?: number }) => () => void: Adds a section; returns a function that removes it.
app.settingsPage.control (name: string, component: FieldComponent) => () => void: Shows the field name with component instead of its control.
app.settingsPage.sections () => readonly PageSection[]
app.settingsPage.controls () => ReadonlyMap<string, FieldComponent>
app.settingsPage.subscribe (listener: () => void) => () => void: Calls listener now and whenever sections or controls change.

Edit this page on GitHub