@webx-ui/module-settings 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webx-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @webx-ui/module-settings
+
+The site's settings, as a section of a [WebX UI](https://github.com/webx-ui/webx-ui) admin
+panel. The screen itself is described by the server — `webx-ui/module-settings` ships the tree
+and the project patches it — and this package draws it and saves it.
+
+Nothing here works without the Composer half.
+
+## Install
+
+```bash
+pnpm add @webx-ui/module-settings
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { settings } from '@webx-ui/module-settings'
+import '@webx-ui/module-settings/style.css'
+
+createAdmin({
+  modules: [settings()],
+  // The project's own operations over the screen, on top of the server's.
+  screens: {
+    'settings.index': [{ op: 'set', target: 'project-name', props: { placeholder: 'Acme' } }],
+  },
+})
+```
+
+The section appears under "System" in the navigation once the server reports the module.
+
+## What it does
+
+- `settings()` — the module: a route at `/settings` and the page.
+- `WxSettingsPage` — the page: loads the values, draws `settings.index` through `WxScreen`, and
+  saves with one button. A 422 lands under the field it names.
+- `createSettingsApi(admin)` — `load()` and `save(values)`, for anything else that needs them.
+
+The guide: https://webx-ui.github.io/webx-ui/guide/settings.html.
+
+## Licence
+
+MIT.

package/dist/SettingsPage.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,10 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { SettingsValues } from './types';
+export interface SettingsApi {
+    /** Every value the screen describes, as stored. */
+    load(): Promise<SettingsValues>;
+    /** Sends the values back; answers with what the server kept. A 422 lands as `HttpError`. */
+    save(values: SettingsValues): Promise<SettingsValues>;
+}
+/** `GET` and `PUT` on `/settings`, under the panel's API path. */
+export declare function createSettingsApi(admin: AdminContext): SettingsApi;

package/dist/i18n.d.ts

@@ -0,0 +1,2 @@
+/** Puts this package's English under the panel's dictionary, once per panel. */
+export declare function useSettingsMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { settings, type SettingsOptions } from './module';
+export { createSettingsApi, type SettingsApi } from './api';
+export { settingsMessages } from './messages';
+export { default as WxSettingsPage } from './SettingsPage';
+export type { SettingsValues } from './types';

package/dist/index.js

@@ -0,0 +1,114 @@
+import { defineComponent as k, ref as l, computed as V, onMounted as W, openBlock as c, createElementBlock as C, createElementVNode as B, createVNode as M, unref as i, withCtx as m, createTextVNode as y, toDisplayString as _, createBlock as v, createCommentVNode as N } from "vue";
+import { useAdmin as x, useTranslate as P, WxScreen as A } from "@webx-ui/module-admin";
+import { toast as d, WxHeading as E, WxButton as T, WxSkeleton as D } from "@webx-ui/core";
+function H(e) {
+  const t = `${e.apiPath}/settings`;
+  return {
+    async load() {
+      return (await e.http.get(t)).data.values;
+    },
+    async save(s) {
+      return (await e.http.put(t, { values: s })).data.values;
+    }
+  };
+}
+const I = {
+  module: {
+    title: "Settings"
+  },
+  page: {
+    save: "Save",
+    saved: "Settings saved.",
+    failed: "Some values were not accepted. Check the highlighted fields."
+  }
+}, h = /* @__PURE__ */ new WeakSet();
+function O() {
+  try {
+    const { i18n: e } = x();
+    h.has(e) || (e.defaults("webx-settings", I), h.add(e));
+  } catch {
+  }
+}
+const U = { class: "wx-settings" }, $ = { class: "wx-settings__head" }, j = /* @__PURE__ */ k({
+  __name: "SettingsPage",
+  setup(e) {
+    const t = x(), s = H(t);
+    O();
+    const a = P("webx-settings"), o = l({}), u = l({}), p = l(!0), g = l(!1), f = t.can("settings.manage"), b = V(
+      () => t.state.manifest?.modules.find((r) => r.id === "settings")?.title ?? a("module.title")
+    );
+    W(async () => {
+      try {
+        o.value = await s.load();
+      } catch (r) {
+        const n = r.body;
+        d.danger(n?.message ?? String(r));
+      } finally {
+        p.value = !1;
+      }
+    });
+    async function S() {
+      g.value = !0, u.value = {};
+      try {
+        o.value = await s.save(o.value), d.success(a("page.saved"));
+      } catch (r) {
+        const n = r.body;
+        n?.errors ? (u.value = n.errors, d.danger(a("page.failed"))) : d.danger(n?.message ?? a("page.failed"));
+      } finally {
+        g.value = !1;
+      }
+    }
+    return (r, n) => (c(), C("div", U, [
+      B("div", $, [
+        M(i(E), { level: 2 }, {
+          default: m(() => [
+            y(_(b.value), 1)
+          ]),
+          _: 1
+        }),
+        i(f) ? (c(), v(i(T), {
+          key: 0,
+          type: "primary",
+          loading: g.value,
+          onClick: S
+        }, {
+          default: m(() => [
+            y(_(i(a)("page.save")), 1)
+          ]),
+          _: 1
+        }, 8, ["loading"])) : N("", !0)
+      ]),
+      p.value ? (c(), v(i(D), {
+        key: 0,
+        rows: 4
+      })) : (c(), v(i(A), {
+        key: 1,
+        modelValue: o.value,
+        "onUpdate:modelValue": n[0] || (n[0] = (w) => o.value = w),
+        name: "settings.index",
+        errors: u.value,
+        disabled: !i(f)
+      }, null, 8, ["modelValue", "errors", "disabled"]))
+    ]));
+  }
+}), q = (e, t) => {
+  const s = e.__vccOpts || e;
+  for (const [a, o] of t)
+    s[a] = o;
+  return s;
+}, z = /* @__PURE__ */ q(j, [["__scopeId", "data-v-7b2af3ae"]]);
+function K(e = {}) {
+  const t = e.path ?? "/settings";
+  return {
+    id: "settings",
+    path: t,
+    routes: [{ path: t, name: "webx.settings", component: z }]
+  };
+}
+export {
+  z as WxSettingsPage,
+  H as createSettingsApi,
+  K as settings,
+  I as settingsMessages
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/api.ts","../src/messages.ts","../src/i18n.ts","../src/SettingsPage.vue","../src/module.ts"],"sourcesContent":["import type { AdminContext } from '@webx-ui/module-admin'\nimport type { SettingsValues } from './types'\n\nexport interface SettingsApi {\n  /** Every value the screen describes, as stored. */\n  load(): Promise<SettingsValues>\n  /** Sends the values back; answers with what the server kept. A 422 lands as `HttpError`. */\n  save(values: SettingsValues): Promise<SettingsValues>\n}\n\n/** `GET` and `PUT` on `/settings`, under the panel's API path. */\nexport function createSettingsApi(admin: AdminContext): SettingsApi {\n  const base = `${admin.apiPath}/settings`\n\n  return {\n    async load() {\n      const body = await admin.http.get<{ data: { values: SettingsValues } }>(base)\n\n      return body.data.values\n    },\n    async save(values) {\n      const body = await admin.http.put<{ data: { values: SettingsValues } }>(base, { values })\n\n      return body.data.values\n    },\n  }\n}\n","import type { Messages } from '@webx-ui/module-admin'\n\n/**\n * What this package says, in English — the same keys `webx-ui/module-settings` ships as\n * `lang/en/*.php`, so a key never reaches the screen when a translation is missing.\n */\nexport const settingsMessages: Record<string, Messages> = {\n  module: {\n    title: 'Settings',\n  },\n  page: {\n    save: 'Save',\n    saved: 'Settings saved.',\n    failed: 'Some values were not accepted. Check the highlighted fields.',\n  },\n}\n","import { useAdmin } from '@webx-ui/module-admin'\nimport { settingsMessages } from './messages'\n\nconst seeded = new WeakSet<object>()\n\n/** Puts this package's English under the panel's dictionary, once per panel. */\nexport function useSettingsMessages(): void {\n  try {\n    const { i18n } = useAdmin()\n\n    if (!seeded.has(i18n)) {\n      i18n.defaults('webx-settings', settingsMessages)\n      seeded.add(i18n)\n    }\n  } catch {\n    // Outside a panel there is no dictionary to seed, and `useTranslate` falls back on its own.\n  }\n}\n","<script setup lang=\"ts\">\nimport { computed, onMounted, ref } from 'vue'\nimport { useAdmin, useTranslate, WxScreen } from '@webx-ui/module-admin'\nimport { toast, WxButton, WxHeading, WxSkeleton } from '@webx-ui/core'\nimport type { ScreenModel } from '@webx-ui/schema'\nimport { createSettingsApi } from './api'\nimport { useSettingsMessages } from './i18n'\n\n/**\n * The settings section: the screen the server describes, and the one button that is the\n * page's own. The screen does not know how it is saved; this does.\n */\nconst context = useAdmin()\nconst api = createSettingsApi(context)\nuseSettingsMessages()\n\nconst t = useTranslate('webx-settings')\n\nconst values = ref<ScreenModel>({})\nconst errors = ref<Record<string, string[]>>({})\nconst loading = ref(true)\nconst saving = ref(false)\n\nconst canManage = context.can('settings.manage')\n\n/** The section's name, as the server translated it; the built-in English until it arrives. */\nconst title = computed(\n  () =>\n    context.state.manifest?.modules.find((module) => module.id === 'settings')?.title ??\n    t('module.title'),\n)\n\nonMounted(async () => {\n  try {\n    values.value = await api.load()\n  } catch (error) {\n    const body = (error as { body?: { message?: string } }).body\n    toast.danger(body?.message ?? String(error))\n  } finally {\n    loading.value = false\n  }\n})\n\nasync function save(): Promise<void> {\n  saving.value = true\n  errors.value = {}\n\n  try {\n    values.value = await api.save(values.value)\n    toast.success(t('page.saved'))\n  } catch (error) {\n    const body = (error as { body?: { errors?: Record<string, string[]>; message?: string } }).body\n\n    if (body?.errors) {\n      errors.value = body.errors\n      toast.danger(t('page.failed'))\n    } else {\n      toast.danger(body?.message ?? t('page.failed'))\n    }\n  } finally {\n    saving.value = false\n  }\n}\n</script>\n\n<template>\n  <div class=\"wx-settings\">\n    <div class=\"wx-settings__head\">\n      <wx-heading :level=\"2\">{{ title }}</wx-heading>\n      <wx-button v-if=\"canManage\" type=\"primary\" :loading=\"saving\" @click=\"save\">\n        {{ t('page.save') }}\n      </wx-button>\n    </div>\n\n    <wx-skeleton v-if=\"loading\" :rows=\"4\" />\n    <wx-screen\n      v-else\n      v-model=\"values\"\n      name=\"settings.index\"\n      :errors=\"errors\"\n      :disabled=\"!canManage\"\n    />\n  </div>\n</template>\n\n<style scoped>\n.wx-settings {\n  display: flex;\n  flex-direction: column;\n  gap: var(--wx-space-16);\n}\n\n.wx-settings__head {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--wx-space-12);\n}\n</style>\n","import type { AdminModule } from '@webx-ui/module-admin'\nimport SettingsPage from './SettingsPage.vue'\n\nexport interface SettingsOptions {\n  /** Where the section lives inside the panel. */\n  path?: string\n}\n\n/**\n * The settings, as a section of the panel.\n *\n * The id matches the module the server reports, which is what makes the entry appear in the\n * navigation: a section shows up when both halves are installed.\n */\nexport function settings(options: SettingsOptions = {}): AdminModule {\n  const path = options.path ?? '/settings'\n\n  return {\n    id: 'settings',\n    path,\n    routes: [{ path, name: 'webx.settings', component: SettingsPage }],\n  }\n}\n"],"names":["createSettingsApi","admin","base","values","settingsMessages","seeded","useSettingsMessages","i18n","useAdmin","context","api","t","useTranslate","ref","errors","loading","saving","canManage","title","computed","module","onMounted","error","body","toast","save","_openBlock","_createElementBlock","_hoisted_1","_createElementVNode","_hoisted_2","_createVNode","_unref","WxHeading","_createBlock","WxButton","WxSkeleton","WxScreen","$event","settings","options","path","SettingsPage"],"mappings":"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"}

package/dist/messages.d.ts

@@ -0,0 +1,6 @@
+import { Messages } from '@webx-ui/module-admin';
+/**
+ * What this package says, in English — the same keys `webx-ui/module-settings` ships as
+ * `lang/en/*.php`, so a key never reaches the screen when a translation is missing.
+ */
+export declare const settingsMessages: Record<string, Messages>;

package/dist/module.d.ts

@@ -0,0 +1,12 @@
+import { AdminModule } from '@webx-ui/module-admin';
+export interface SettingsOptions {
+    /** Where the section lives inside the panel. */
+    path?: string;
+}
+/**
+ * The settings, as a section of the panel.
+ *
+ * The id matches the module the server reports, which is what makes the entry appear in the
+ * navigation: a section shows up when both halves are installed.
+ */
+export declare function settings(options?: SettingsOptions): AdminModule;

package/dist/style.css

@@ -0,0 +1 @@
+.wx-settings[data-v-7b2af3ae]{display:flex;flex-direction:column;gap:var(--wx-space-16)}.wx-settings__head[data-v-7b2af3ae]{display:flex;align-items:center;justify-content:space-between;gap:var(--wx-space-12)}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+/** Values keyed by the screen's field names, as stored: `general.project-name` is one key. */
+export type SettingsValues = Record<string, unknown>;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@webx-ui/module-settings",
+  "version": "0.1.0",
+  "description": "Site settings for the WebX UI admin panel: the section that draws the settings screen and saves it.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "keywords": [
+    "webx-ui",
+    "vue",
+    "admin",
+    "settings"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webx-ui/webx-ui.git",
+    "directory": "packages/module-settings"
+  },
+  "homepage": "https://webx-ui.github.io/webx-ui/guide/settings.html",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./dist/style.css": "./dist/style.css",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0"
+  },
+  "dependencies": {
+    "@webx-ui/core": "^0.17.0",
+    "@webx-ui/module-admin": "^0.3.1",
+    "@webx-ui/schema": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.14",
+    "vite-plugin-dts": "^4.5.4",
+    "vue": "^3.5.24",
+    "vue-router": "^4.5.1",
+    "vue-tsc": "^3.1.3"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "typecheck": "vue-tsc -p tsconfig.json --noEmit"
+  }
+}