feat(settings): add example settings.json to public/

public/settings.json

@@ -0,0 +1,55 @@
+{
+    "contents": [
+        {
+            "name": "general",
+            "type": "section",
+            "i18n": "preferences.settings.sections.general.name",
+            "description": "preferences.settings.sections.general.description",
+            "content": [
+                {
+                    "type": "bool",
+                    "name": "darkMode",
+                    "i18n": "preferences.darkMode",
+                    "default": true
+                },
+                {
+                    "type": "selection",
+                    "name": "language",
+                    "i18n": "preferences.settings.language",
+                    "description": "preferences.settings.language.description",
+                    "default": "en",
+                    "allowMultiple": false,
+                    "options": [
+                        {
+                            "name": "en",
+                            "i18n": "preferences.locale.languages.en"
+                        },
+                        {
+                            "name": "de",
+                            "i18n": "preferences.locale.languages.de"
+                        }
+                    ]
+                },
+                {
+                    "type": "section",
+                    "name": "exampleSection",
+                    "description": "preferences.settings.sections.exampleSection.description",
+                    "content": [
+                        {
+                            "type": "number",
+                            "name": "aNumber",
+                            "i18n": "preferences.settings.sections.exampleSection.content.aNumber",
+                            "default": 42
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "name": "exampleStandaloneConfiguration",
+            "type": "bool",
+            "i18n": "preferences.settings.exampleStandalone.name",
+            "default": false
+        }
+    ]
+}

src/features/settings/composables/useSettingsConfig.js

@@ -0,0 +1,48 @@
+/*
+Copyright 2026 Seekra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { ref, readonly } from 'vue';
+import { loadSettingsConfig } from '../utils/settingsParser.js';
+
+const config  = ref(null);
+const error   = ref(null);
+const loading = ref(false);
+
+/**
+ * Provides reactive access to the parsed settings configuration.
+ * The config is loaded once and shared across all consumers.
+ */
+export function useSettingsConfig() {
+    async function load(url = '/settings.json') {
+        loading.value = true;
+        error.value   = null;
+        try {
+            config.value = await loadSettingsConfig(url);
+        } catch (e) {
+            error.value  = e.message;
+            config.value = null;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    return {
+        config:  readonly(config),
+        error:   readonly(error),
+        loading: readonly(loading),
+        load,
+    };
+}

src/features/settings/types/settingsConfig.js

@@ -0,0 +1,71 @@
+/*
+Copyright 2026 Seekra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @typedef {'bool' | 'number' | 'string' | 'selection' | 'section'} SettingType
+ */
+
+/**
+ * @typedef {Object} SelectionOption
+ * @property {string} name
+ * @property {string} i18n
+ */
+
+/**
+ * @typedef {Object} BaseSettingConfig
+ * @property {SettingType} type
+ * @property {string} name
+ * @property {string} i18n
+ * @property {string} [description]
+ */
+
+/**
+ * @typedef {BaseSettingConfig & { default: boolean }} BoolSettingConfig
+ */
+
+/**
+ * @typedef {BaseSettingConfig & { default: number }} NumberSettingConfig
+ */
+
+/**
+ * @typedef {BaseSettingConfig & { default: string }} StringSettingConfig
+ */
+
+/**
+ * @typedef {BaseSettingConfig & {
+ *   default: string | string[],
+ *   allowMultiple: boolean,
+ *   options: SelectionOption[]
+ * }} SelectionSettingConfig
+ */
+
+/**
+ * @typedef {Object} SectionSettingConfig
+ * @property {'section'} type
+ * @property {string} name
+ * @property {string} [i18n]
+ * @property {string} [description]
+ * @property {SettingConfigEntry[]} content
+ */
+
+/**
+ * @typedef {BoolSettingConfig | NumberSettingConfig | StringSettingConfig | SelectionSettingConfig | SectionSettingConfig} SettingConfigEntry
+ */
+
+/**
+ * @typedef {Object} SettingsConfig
+ * @property {SettingConfigEntry[]} contents
+ */

src/features/settings/utils/settingsParser.js

@@ -0,0 +1,43 @@
+/*
+Copyright 2026 Seekra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { validateSettingsConfig } from './settingsValidator.js';
+
+/**
+ * Loads and parses the settings configuration from a JSON file.
+ * @param {string} [url='/settings.json']
+ * @returns {Promise<import('../types/settingsConfig').SettingsConfig>}
+ */
+export async function loadSettingsConfig(url = '/settings.json') {
+    let raw;
+
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        raw = await response.json();
+    } catch (e) {
+        throw new Error(`[settings] Failed to load config from "${url}": ${e.message}`);
+    }
+
+    const result = validateSettingsConfig(raw);
+    if (!result.valid) {
+        throw new Error(result.error);
+    }
+
+    return result.config;
+}

src/features/settings/utils/settingsValidator.js

@@ -0,0 +1,101 @@
+/*
+Copyright 2026 Seekra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+const VALID_TYPES = ['bool', 'number', 'string', 'selection', 'section'];
+
+function assertString(value, path) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`[settings] "${path}" must be a non-empty string`);
+    }
+}
+
+function assertType(value, path) {
+    if (!VALID_TYPES.includes(value)) {
+        throw new Error(
+            `[settings] "${path}" has invalid type "${value}". Must be one of: ${VALID_TYPES.join(', ')}`
+        );
+    }
+}
+
+function validateSelectionOptions(options, path) {
+    if (!Array.isArray(options) || options.length === 0) {
+        throw new Error(`[settings] "${path}.options" must be a non-empty array`);
+    }
+    options.forEach((opt, i) => {
+        assertString(opt.name, `${path}.options[${i}].name`);
+        assertString(opt.i18n, `${path}.options[${i}].i18n`);
+    });
+}
+
+function validateEntry(entry, path) {
+    assertType(entry.type, `${path}.type`);
+
+    if (entry.type === 'section') {
+        assertString(entry.name, `${path}.name`);
+        if (!Array.isArray(entry.content)) {
+            throw new Error(`[settings] "${path}.content" must be an array`);
+        }
+        entry.content.forEach((child, i) =>
+            validateEntry(child, `${path}.content[${i}]`)
+        );
+        return;
+    }
+
+    assertString(entry.name, `${path}.name`);
+    assertString(entry.i18n, `${path}.i18n`);
+
+    if (entry.default === undefined) {
+        throw new Error(`[settings] "${path}.default" is required`);
+    }
+
+    if (entry.type === 'bool' && typeof entry.default !== 'boolean') {
+        throw new Error(`[settings] "${path}.default" must be a boolean`);
+    }
+    if (entry.type === 'number' && typeof entry.default !== 'number') {
+        throw new Error(`[settings] "${path}.default" must be a number`);
+    }
+    if (entry.type === 'string' && typeof entry.default !== 'string') {
+        throw new Error(`[settings] "${path}.default" must be a string`);
+    }
+    if (entry.type === 'selection') {
+        validateSelectionOptions(entry.options, path);
+        if (typeof entry.allowMultiple !== 'boolean') {
+            throw new Error(`[settings] "${path}.allowMultiple" must be a boolean`);
+        }
+    }
+}
+
+/**
+ * Validates a raw settings config object.
+ * @param {unknown} raw
+ * @returns {{ valid: true, config: import('../types/settingsConfig').SettingsConfig } | { valid: false, error: string }}
+ */
+export function validateSettingsConfig(raw) {
+    try {
+        if (!raw || typeof raw !== 'object') {
+            throw new Error('[settings] Config must be an object');
+        }
+        if (!Array.isArray(raw.contents)) {
+            throw new Error('[settings] "contents" must be an array');
+        }
+        raw.contents.forEach((entry, i) =>
+            validateEntry(entry, `contents[${i}]`)
+        );
+        return { valid: true, config: raw };
+    } catch (e) {
+        return { valid: false, error: e.message };
+    }
+}