@aleph-alpha/settings-kit 0.0.0-stage → 1.0.0

package/dist/shell/labels.d.ts

@@ -0,0 +1,25 @@
+/** Every piece of text the shell chrome renders itself. */
+export interface SkShellLabels {
+    /** Title beside the back control; also names the top bar. */
+    title: string;
+    /** Accessible name and tooltip of the back control. */
+    back: string;
+    /** Tooltip of the sidebar toggles. */
+    toggleSidebar: string;
+    /** Accessible name of the page navigation landmark. */
+    navigation: string;
+    /** Accessible name of the layout switch. */
+    layout: string;
+    /** The layout option without the content sidebar. */
+    focusLayout: string;
+    /** The layout option with the content sidebar. */
+    sidebarLayout: string;
+    /** Appended to a page link whose page has errors. */
+    pageHasErrors: string;
+}
+/**
+ * English text of the shell chrome, from the kit wording (`shell.*`).
+ * `SkShell` uses the wording of the current locale. Pass `labels` to replace any of it.
+ */
+export declare const defaultShellLabels: SkShellLabels;
+//# sourceMappingURL=labels.d.ts.map

package/dist/shell/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/shell/labels.ts"],"names":[],"mappings":"AAKA,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAShC,CAAC"}

package/dist/shell/location.d.ts

@@ -0,0 +1,18 @@
+/** Prefix the shell owns. Empty means the site root. */
+export declare function normalizeShellBase(base: string | undefined): string;
+/** Page path (`/appearance/branding`) joined onto `base`. */
+export declare function shellPath(base: string | undefined, pagePath: string): string;
+/**
+ * Page path under `base`, or `undefined` when `fullPath` is outside it.
+ * The base matches regardless of letter case, like vue-router's own base;
+ * the base itself (`/admin/settings` and `/admin/settings/`) is `/`.
+ */
+export declare function pagePath(base: string | undefined, fullPath: string): string | undefined;
+/** History locations are already relative to their own base. */
+export declare function historyPath(location: string): string;
+/** A location split into its pathname and the `?query#hash` after it. */
+export declare function splitLocation(location: string): {
+    path: string;
+    suffix: string;
+};
+//# sourceMappingURL=location.d.ts.map

package/dist/shell/location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/shell/location.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMnE;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CASpB;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAQA"}

package/dist/shell/routes.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedLayout } from '../core/layout';
+/** One settings page as the shell routes it. */
+export interface ShellRoute {
+    /** Page id across the layout: `<category>/<page>`, segments encoded. */
+    id: string;
+    /** Path relative to the shell base: always `/<category>/<page>`. */
+    path: string;
+}
+/** One route per resolved page, in display order. */
+export declare function createShellRoutes(layout: ResolvedLayout): ShellRoute[];
+/**
+ * Route for a page path. Segments are compared decoded, without trailing
+ * slashes; an exact match wins over one that differs only in letter case,
+ * so `/Appearance/Branding/` opens `/appearance/branding`.
+ */
+export declare function findShellRoute(routes: readonly ShellRoute[], path: string): ShellRoute | undefined;
+/** Canonical form: no trailing slash, every segment decoded then re-encoded. */
+export declare function normalizeRoutePath(path: string): string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/shell/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/shell/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,UAAU,EAAE,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,SAAS,CAUxB;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvD"}

package/dist/shell/useMediaQuery.d.ts

@@ -0,0 +1,4 @@
+import { type Ref } from 'vue';
+/** Whether `query` matches; `false` where `matchMedia` is unavailable (SSR, JSDOM). */
+export declare function useMediaQuery(query: string): Ref<boolean>;
+//# sourceMappingURL=useMediaQuery.d.ts.map

package/dist/shell/useMediaQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMediaQuery.d.ts","sourceRoot":"","sources":["../../src/shell/useMediaQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAErD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAWzD"}

package/dist/shell/useShellLocation.d.ts

@@ -0,0 +1,37 @@
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import { type ShellRoute } from './routes';
+/** Options for `useShellLocation`. */
+export interface UseShellLocationOptions {
+    /** Pages the shell can show, in display order. */
+    routes: MaybeRefOrGetter<readonly ShellRoute[]>;
+    /** URL prefix of the settings pages, e.g. `/admin/settings`. */
+    base?: MaybeRefOrGetter<string | undefined>;
+}
+/** What `useShellLocation` returns. */
+export interface ShellLocation {
+    /** Id of the page on screen; the first page when the URL names none. */
+    activeId: ComputedRef<string | undefined>;
+    /** Opens a page by id and pushes its URL where the shell may. */
+    openPage: (id: string | undefined) => void;
+    /** `href` for a page link, ready for `<a>`. */
+    hrefOf: (id: string) => string;
+}
+/**
+ * Active settings page for one shell, synced with the URL through exactly
+ * one source. Nothing is registered on the app:
+ *
+ * 1. An injected history (`skShellHistoryKey`), e.g. a memory history.
+ * 2. The host router, when one is installed. The shell navigates only to
+ *    targets that still match the route record that rendered it, and leaves
+ *    the URL alone once the host has navigated elsewhere (or a `KeepAlive`
+ *    has deactivated it). An unknown page path is redirected only under an
+ *    explicit `base`.
+ * 3. Otherwise a private `createWebHistory(base)`, destroyed on unmount and
+ *    recreated when `base` changes. It never writes a URL outside `base`.
+ *
+ * A failed or blocked navigation re-reads the real location, so the shell
+ * always shows the page the URL names. Query and hash survive a canonical
+ * rewrite. Without `window` (SSR) the first page renders and no URL is read.
+ */
+export declare function useShellLocation(options: UseShellLocationOptions): ShellLocation;
+//# sourceMappingURL=useShellLocation.d.ts.map

package/dist/shell/useShellLocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShellLocation.d.ts","sourceRoot":"","sources":["../../src/shell/useShellLocation.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,KAAK,CAAC;AAiBb,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,MAAM,EAAE,gBAAgB,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IAChD,gEAAgE;IAChE,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7C;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,WAAW,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAC3C,+CAA+C;IAC/C,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,aAAa,CAyOf"}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A setting unit is the smallest self-contained description of a single
+ * user-facing setting: its identity, copy, and default value.
+ */
+export interface SettingUnit<TValue = unknown> {
+    /** Unique identifier of the setting, used as storage key and DOM id. */
+    id: string;
+    /** Human-readable label shown next to the setting control. */
+    label: string;
+    /** Optional supporting copy explaining what the setting does. */
+    description?: string;
+    /** Value used when the setting has not been changed by the user. */
+    defaultValue: TValue;
+}
+/** A boolean on/off setting rendered as a toggle switch. */
+export type ToggleSettingUnit = SettingUnit<boolean>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO;IAC3C,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,113 @@
 {
   "name": "@aleph-alpha/settings-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Turns a settings schema and layout into accessible admin screens for Vue applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./generators": {
+      "types": "./dist/generators/index.d.ts",
+      "import": "./dist/generators/index.js"
+    },
+    "./units": {
+      "types": "./dist/generators/index.d.ts",
+      "import": "./dist/generators/index.js"
+    },
+    "./shell": {
+      "types": "./dist/shell/index.d.ts",
+      "import": "./dist/shell/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "settings",
+    "vue",
+    "typescript",
+    "kit"
+  ],
+  "author": "Pharia AI",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aleph-Alpha/frontend-hub.git",
+    "directory": "packages/settings-kit"
+  },
+  "peerDependencies": {
+    "@aleph-alpha/ui-library": "^7.0.1",
+    "vue": "^3.5.27",
+    "vue-router": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vue-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aleph-alpha/ui-library": "^7.0.1",
+    "concurrently": "9.2.1",
+    "http-server": "14.1.1",
+    "jsdom": "^25.0.1",
+    "storybook": "10.2.17",
+    "@storybook/addon-a11y": "10.2.17",
+    "@storybook/addon-docs": "10.2.17",
+    "@storybook/addon-themes": "10.2.17",
+    "@storybook/vue3-vite": "10.2.17",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/vue": "8.1.0",
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3",
+    "unocss": "^66.6.2",
+    "unocss-preset-animations": "^1.3.0",
+    "unocss-preset-shadcn": "^1.0.1",
+    "@unocss/preset-wind4": "^66.6.2",
+    "@unocss/reset": "^66.6.2",
+    "vite": "^7.3.2",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "vitest": "3.2.6",
+    "vue": "^3.5.27",
+    "vue-router": "4.6.4",
+    "vue-tsc": "^3.2.4",
+    "wait-on": "9.0.3",
+    "@aleph-alpha/eslint-config-frontend": "0.7.1",
+    "@aleph-alpha/prettier-config-frontend": "2.1.1",
+    "@aleph-alpha/storybook-addon-filters": "0.0.1",
+    "@aleph-alpha/storybook-addon-sidebar": "0.0.1",
+    "@aleph-alpha/storybook-addon-theming": "0.0.1",
+    "@aleph-alpha/tsconfig-frontend": "0.7.3"
+  },
+  "scripts": {
+    "build": "vite build && vue-tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist",
+    "dev": "vite build --watch",
+    "playground": "vite playground",
+    "showcase": "vite showcase",
+    "build:showcase": "vite build showcase",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "lint": "prettier --check . && eslint --fix src",
+    "storybook": "storybook dev -p 6009",
+    "build-storybook": "storybook build",
+    "test:storybook": "pnpm concurrently -k --ks SIGKILL -s command-test -n \"storybook,test\" \"pnpm http-server ../../dist/storybook/settings-kit --port 4404 --silent\" \"wait-on tcp:4404 && test-storybook --url http://127.0.0.1:4404\"",
+    "test:storybook:local": "pnpm build-storybook && pnpm concurrently -k --ks SIGKILL -s command-test -n \"storybook,test\" \"pnpm http-server storybook-static --port 4404 --silent\" \"wait-on tcp:4404 && test-storybook --url http://127.0.0.1:4404\""
+  }
 }