@jskit-ai/users-web 0.1.178-oldline.3 → 0.1.178

package/package.json

@@ -1,64 +1,216 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.178-oldline.3",
+  "version": "0.1.178",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
     "./client": "./src/client/index.js",
+    "./client/providers/UsersWebClientProvider": "./src/client/providers/UsersWebClientProvider.js",
     "./client/components/AccountSettingsClientElement": "./src/client/components/AccountSettingsClientElement.vue",
-    "./client/components/CrudAddEditScreen": "./src/client/components/CrudAddEditScreen.vue",
-    "./client/components/CrudListBulkActionSurface": "./src/client/components/CrudListBulkActionSurface.vue",
-    "./client/components/CrudListFilterSurface": "./src/client/components/CrudListFilterSurface.vue",
-    "./client/components/CrudListScreen": "./src/client/components/CrudListScreen.vue",
-    "./client/components/CrudViewScreen": "./src/client/components/CrudViewScreen.vue",
-    "./client/account-settings/sections": "./src/client/account-settings/sections.js",
-    "./client/bulkActions": "./src/client/bulkActions.js",
-    "./client/filters": "./src/client/filters.js",
-    "./client/rowActions": "./src/client/rowActions.js",
-    "./client/composables/useAddEdit": "./src/client/composables/records/useAddEdit.js",
-    "./client/composables/useAccess": "./src/client/composables/useAccess.js",
-    "./client/composables/useCommand": "./src/client/composables/useCommand.js",
-    "./client/composables/useCrudAddEdit": "./src/client/composables/records/useCrudAddEdit.js",
-    "./client/composables/useCrudAddEditScreen": "./src/client/composables/useCrudAddEditScreen.js",
-    "./client/composables/useCrudDeleteAction": "./src/client/composables/useCrudDeleteAction.js",
-    "./client/composables/useCrudListBulkActions": "./src/client/composables/useCrudListBulkActions.js",
-    "./client/composables/useCrudListRowActions": "./src/client/composables/useCrudListRowActions.js",
-    "./client/composables/crudLookupFieldRuntime": "./src/client/composables/crud/crudLookupFieldRuntime.js",
-    "./client/composables/useCrudListFilterLookups": "./src/client/composables/useCrudListFilterLookups.js",
-    "./client/composables/useCrudListFilters": "./src/client/composables/useCrudListFilters.js",
-    "./client/composables/useEndpointResource": "./src/client/composables/runtime/useEndpointResource.js",
-    "./client/composables/useList": "./src/client/composables/records/useList.js",
-    "./client/composables/useCrudList": "./src/client/composables/records/useCrudList.js",
-    "./client/composables/useCrudListScreen": "./src/client/composables/useCrudListScreen.js",
-    "./client/crudHttpClient": "./src/client/composables/crud/crudHttpClientSupport.js",
-    "./client/composables/useCrudListParentTitle": "./src/client/composables/useCrudListParentTitle.js",
-    "./client/composables/useRealtimeQueryInvalidation": "./src/client/composables/useRealtimeQueryInvalidation.js",
-    "./client/composables/useSurfaceRouteContext": "./src/client/composables/useSurfaceRouteContext.js",
-    "./client/composables/useView": "./src/client/composables/records/useView.js",
-    "./client/composables/useCrudView": "./src/client/composables/records/useCrudView.js",
-    "./client/composables/useCrudViewScreen": "./src/client/composables/useCrudViewScreen.js",
-    "./client/composables/usePagedCollection": "./src/client/composables/usePagedCollection.js",
-    "./client/composables/usePaths": "./src/client/composables/usePaths.js",
-    "./client/composables/runtime/useUiFeedback": "./src/client/composables/runtime/useUiFeedback.js",
-    "./client/lib/httpClient": "./src/client/lib/httpClient.js",
-    "./client/lib/permissions": "./src/client/lib/permissions.js",
-    "./client/support/contractGuards": "./src/client/support/contractGuards.js"
+    "./client/account-settings/sections": "./src/client/account-settings/sections.js"
   },
   "dependencies": {
-    "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.146",
-    "@jskit-ai/kernel": "0.1.147",
-    "@jskit-ai/realtime": "0.1.145",
-    "@jskit-ai/shell-web": "0.1.149",
-    "@jskit-ai/uploads-image-web": "0.1.123",
-    "@jskit-ai/users-core": "0.1.161"
+    "@jskit-ai/auth-web": "0.1.160",
+    "@jskit-ai/http-web": "0.1.5",
+    "@jskit-ai/http-runtime": "0.1.158",
+    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/shell-web": "0.1.164",
+    "@jskit-ai/uploads-image-web": "0.1.135",
+    "@jskit-ai/users-core": "0.1.173"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vue-router": "^5.0.4",
     "vuetify": "^4.0.0"
+  },
+  "description": "Users web module with account, profile, and user-specific shell UI.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "users.web"
+      ],
+      "requires": []
+    },
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/UsersWebClientProvider.js",
+            "export": "UsersWebClientProvider"
+          }
+        ]
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./client",
+            "summary": "Exports users-web client provider registration surface."
+          },
+          {
+            "subpath": "./client/providers/UsersWebClientProvider",
+            "summary": "Exports users-web client provider class."
+          },
+          {
+            "subpath": "./client/components/AccountSettingsClientElement",
+            "summary": "Exports the package-owned account settings host that renders placement-backed account sections."
+          },
+          {
+            "subpath": "./client/account-settings/sections",
+            "summary": "Exports placement-backed account settings section helpers."
+          }
+        ]
+      },
+      "ui": {
+        "placements": {
+          "outlets": [
+            {
+              "target": "home-cog:primary-menu",
+              "surfaces": [
+                "home"
+              ],
+              "source": "src/client/components/UsersHomeToolsWidget.vue"
+            },
+            {
+              "target": "account-settings:sections",
+              "surfaces": [
+                "account"
+              ],
+              "source": "src/client/components/AccountSettingsClientElement.vue"
+            }
+          ],
+          "topology": {
+            "placements": [
+              {
+                "id": "home.tools-menu",
+                "description": "Home surface tools menu actions.",
+                "surfaces": [
+                  "home"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "home-cog:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "medium": {
+                    "outlet": "home-cog:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  },
+                  "expanded": {
+                    "outlet": "home-cog:primary-menu",
+                    "renderers": {
+                      "link": "local.main.ui.surface-aware-menu-link-item"
+                    }
+                  }
+                }
+              },
+              {
+                "id": "settings.sections",
+                "owner": "account-settings",
+                "description": "Account settings content sections.",
+                "surfaces": [
+                  "account"
+                ],
+                "variants": {
+                  "compact": {
+                    "outlet": "account-settings:sections"
+                  },
+                  "medium": {
+                    "outlet": "account-settings:sections"
+                  },
+                  "expanded": {
+                    "outlet": "account-settings:sections"
+                  }
+                }
+              }
+            ]
+          },
+          "contributions": [
+            {
+              "id": "users.profile.menu.settings",
+              "target": "auth.profile-menu",
+              "kind": "link",
+              "surfaces": [
+                "*"
+              ],
+              "order": 500,
+              "when": "auth.authenticated === true",
+              "source": "patterns/account-settings/PATTERN.md"
+            },
+            {
+              "id": "users.home.tools.widget",
+              "target": "shell.status",
+              "kind": "component",
+              "surfaces": [
+                "home"
+              ],
+              "order": 900,
+              "componentToken": "users.web.home.tools.widget",
+              "when": "auth.authenticated === true",
+              "source": "src/client/components/UsersHomeToolsWidget.vue"
+            },
+            {
+              "id": "users.home.menu.settings",
+              "target": "home.tools-menu",
+              "kind": "link",
+              "surfaces": [
+                "home"
+              ],
+              "order": 100,
+              "when": "auth.authenticated === true",
+              "source": "patterns/account-settings/PATTERN.md"
+            },
+            {
+              "id": "users.account.settings.profile",
+              "target": "settings.sections",
+              "owner": "account-settings",
+              "kind": "component",
+              "surfaces": [
+                "account"
+              ],
+              "order": 100,
+              "componentToken": "local.main.account-settings.section.profile",
+              "source": "patterns/account-settings/example/src/components/account/settings/AccountSettingsProfileSection.vue"
+            },
+            {
+              "id": "users.account.settings.preferences",
+              "target": "settings.sections",
+              "owner": "account-settings",
+              "kind": "component",
+              "surfaces": [
+                "account"
+              ],
+              "order": 200,
+              "componentToken": "local.main.account-settings.section.preferences",
+              "source": "patterns/account-settings/example/src/components/account/settings/AccountSettingsPreferencesSection.vue"
+            },
+            {
+              "id": "users.account.settings.notifications",
+              "target": "settings.sections",
+              "owner": "account-settings",
+              "kind": "component",
+              "surfaces": [
+                "account"
+              ],
+              "order": 300,
+              "componentToken": "local.main.account-settings.section.notifications",
+              "source": "patterns/account-settings/example/src/components/account/settings/AccountSettingsNotificationsSection.vue"
+            }
+          ]
+        }
+      }
+    }
   }
 }

package/patterns/account-settings/PATTERN.md

@@ -0,0 +1,61 @@
+---
+id: users/account-settings
+title: Account settings surface
+summary: Compose an account settings route and profile, preference, and notification sections from JSKIT user web components.
+keywords: account, notifications, preferences, profile, settings, user, vue
+requires: @jskit-ai/users-core, @jskit-ai/users-web, @jskit-ai/shell-web
+---
+
+# Account settings surface
+
+## Use when
+
+Use this pattern when authenticated users need to manage their own profile and
+account preferences.
+
+## Do not use when
+
+Do not use this pattern for administrator-managed users, authentication
+credential storage, or anonymous profile editing.
+
+## Product decisions
+
+Choose editable profile fields, preference vocabulary, notification options,
+section order, and which account operations require reauthentication.
+
+## Framework APIs
+
+Use account settings elements and composables from `@jskit-ai/users-web`,
+ordinary `useCommand()` mutation behavior, and JSKIT shell placements.
+
+## Invariants
+
+- Sections use JSKIT account settings APIs rather than direct HTTP helpers.
+- Cached resource data hydrates local writable fields immediately.
+- Mutation errors use the standard toast and do not push the form down.
+- Loading uses layout-stable skeletons, never an indeterminate spinner.
+- Pending controls keep stable labels and prevent duplicate submission.
+- The route and placement owner agree.
+
+## Example files
+
+`example/` contains an account route and three concrete settings sections.
+Adapt their fields and copy while retaining the shared account runtime.
+
+## Variation points
+
+Change sections, fields, copy, order, permissions, preference choices, and
+notification vocabulary while keeping server-owned validation authoritative.
+
+## Verification
+
+Navigate away and back with warm cache, exercise browser back/forward, save and
+clear fields, verify toast errors, inspect skeleton geometry, and test keyboard
+operation at compact and expanded widths.
+
+## Avoid
+
+- page-local request clients
+- inline mutation alerts that shift content
+- lazy non-immediate watchers for initial hydration
+- copied user repositories or generator source markers

package/src/client/bootstrap/user-bootstrap-handler.js

@@ -1,7 +1,4 @@
-import {
-  registerBootstrapPayloadHandler,
-  resolveBootstrapErrorStatusCode
-} from "@jskit-ai/shell-web/client/bootstrap";
+import { resolveBootstrapErrorStatusCode } from "@jskit-ai/shell-web/client/bootstrap";
 import { resolvePlacementUserFromBootstrapPayload } from "../lib/bootstrap.js";
 
 function createUsersBootstrapUserHandler() {
@@ -43,11 +40,4 @@ function createUsersBootstrapUserHandler() {
   });
 }
 
-function registerUsersBootstrapPayloadHandlers(app) {
-  registerBootstrapPayloadHandler(app, "users.web.bootstrap.user-handler", () => createUsersBootstrapUserHandler());
-}
-
-export {
-  createUsersBootstrapUserHandler,
-  registerUsersBootstrapPayloadHandlers
-};
+export { createUsersBootstrapUserHandler };

package/src/client/composables/account-settings/accountSettingsAvatarUploadRuntime.js

@@ -1,7 +1,7 @@
 import "@jskit-ai/uploads-image-web/client/styles";
 import { createManagedImageAssetRuntime } from "@jskit-ai/uploads-image-web/client/composables/createManagedImageAssetRuntime";
 import { resolveFieldErrors } from "@jskit-ai/http-runtime/client";
-import { usersWebHttpClient } from "../../lib/httpClient.js";
+import { httpWebClient } from "@jskit-ai/http-web/client/lib/httpClient";
 
 function createAccountSettingsAvatarUploadRuntime({
   queryClient,
@@ -15,7 +15,7 @@ function createAccountSettingsAvatarUploadRuntime({
     const sessionPayload = await queryClient.fetchQuery({
       queryKey: sessionQueryKey,
       queryFn: () =>
-        usersWebHttpClient.request("/api/session", {
+        httpWebClient.request("/api/session", {
           method: "GET"
         }),
       staleTime: 60_000

package/src/client/composables/useAccountSettingsRuntime.js

@@ -10,14 +10,14 @@ import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
 import { ROUTE_VISIBILITY_PUBLIC } from "@jskit-ai/kernel/shared/support/visibility";
 import { userProfileResource } from "@jskit-ai/users-core/shared/resources/userProfileResource";
 import { userSettingsResource } from "@jskit-ai/users-core/shared/resources/userSettingsResource";
+import { useAddEdit } from "@jskit-ai/http-web/client/composables/useAddEdit";
+import { useCommand } from "@jskit-ai/http-web/client/composables/useCommand";
+import { useView } from "@jskit-ai/http-web/client/composables/useView";
 import {
   persistThemePreference,
   resolveThemeNameForPreference,
   setVuetifyThemeName
 } from "../lib/theme.js";
-import { useAddEdit } from "./records/useAddEdit.js";
-import { useCommand } from "./useCommand.js";
-import { useView } from "./records/useView.js";
 import { resolveSurfacePathFromPlacementContext } from "@jskit-ai/shell-web/client/placement";
 import {
   ACCOUNT_SETTINGS_DEFAULTS,

package/src/client/index.js

@@ -1,18 +1,2 @@
-import { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
-
 export { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
 export { default as AccountSettingsClientElement } from "./components/AccountSettingsClientElement.vue";
-export { default as CrudAddEditScreen } from "./components/CrudAddEditScreen.vue";
-export { default as CrudListBulkActionSurface } from "./components/CrudListBulkActionSurface.vue";
-export { default as CrudListFilterSurface } from "./components/CrudListFilterSurface.vue";
-export { default as CrudListScreen } from "./components/CrudListScreen.vue";
-export { default as CrudViewScreen } from "./components/CrudViewScreen.vue";
-export {
-  normalizeCrudApiAccess,
-  resolveCrudHttpClient
-} from "./composables/crud/crudHttpClientSupport.js";
-export { useCrudDeleteAction } from "./composables/useCrudDeleteAction.js";
-
-const clientProviders = Object.freeze([UsersWebClientProvider]);
-
-export { clientProviders };

package/src/client/providers/UsersWebClientProvider.js

@@ -1,20 +1,19 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import UsersHomeToolsWidget from "../components/UsersHomeToolsWidget.vue";
 import ProfileClientElement from "../components/ProfileClientElement.vue";
-import { registerUsersBootstrapPayloadHandlers } from "../bootstrap/user-bootstrap-handler.js";
+import { createUsersBootstrapUserHandler } from "../bootstrap/user-bootstrap-handler.js";
 
-class UsersWebClientProvider {
-  static id = "users.web.client";
-  static dependsOn = ["shell.web.client"];
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function" || typeof app.tag !== "function") {
-      throw new Error("UsersWebClientProvider requires application singleton()/tag().");
-    }
-
-    app.singleton("users.web.home.tools.widget", () => UsersHomeToolsWidget);
-    app.singleton("users.web.profile.element", () => ProfileClientElement);
-    registerUsersBootstrapPayloadHandlers(app);
+const UsersWebClientProvider = defineProvider({
+  id: "users.web.client",
+  requires: {
+    components: "client.components",
+    shell: "client.shell"
+  },
+  setup({ components, shell }) {
+    components.register("users.web.home.tools.widget", UsersHomeToolsWidget);
+    components.register("users.web.profile.element", ProfileClientElement);
+    shell.bootstrapHandlers.register(createUsersBootstrapUserHandler());
   }
-}
+});
 
 export { UsersWebClientProvider };

package/test/bootstrap.test.js

@@ -1,11 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { resolveBootstrapPayloadHandlers } from "@jskit-ai/shell-web/client/bootstrap";
+import { createBootstrapPayloadHandlerRegistry } from "@jskit-ai/shell-web/client/bootstrap";
 import { resolvePlacementUserFromBootstrapPayload } from "../src/client/lib/bootstrap.js";
-import {
-  createUsersBootstrapUserHandler,
-  registerUsersBootstrapPayloadHandlers
-} from "../src/client/bootstrap/user-bootstrap-handler.js";
+import { createUsersBootstrapUserHandler } from "../src/client/bootstrap/user-bootstrap-handler.js";
 
 test("resolvePlacementUserFromBootstrapPayload returns null for anonymous sessions", () => {
   assert.equal(
@@ -62,38 +59,6 @@ function createPlacementRuntimeDouble() {
   };
 }
 
-function createBootstrapRegistryAppDouble() {
-  const singletons = new Map();
-  const instances = new Map();
-  const tags = new Map();
-
-  return {
-    singleton(token, factory) {
-      singletons.set(token, factory);
-    },
-    tag(token, tagName) {
-      const current = tags.get(tagName) || [];
-      current.push(token);
-      tags.set(tagName, current);
-    },
-    resolveTag(tagName) {
-      return (tags.get(tagName) || []).map((token) => this.make(token));
-    },
-    make(token) {
-      if (instances.has(token)) {
-        return instances.get(token);
-      }
-      const factory = singletons.get(token);
-      if (typeof factory !== "function") {
-        throw new Error(`Unknown token ${String(token)}`);
-      }
-      const instance = factory(this);
-      instances.set(token, instance);
-      return instance;
-    }
-  };
-}
-
 test("users web bootstrap user handler writes placement user", async () => {
   const handler = createUsersBootstrapUserHandler();
   const placementRuntime = createPlacementRuntimeDouble();
@@ -156,11 +121,11 @@ test("users web bootstrap user handler clears placement user on bootstrap 401 on
   assert.equal(placementRuntime.getContext().user, null);
 });
 
-test("registerUsersBootstrapPayloadHandlers registers the users bootstrap user handler", () => {
-  const app = createBootstrapRegistryAppDouble();
-  registerUsersBootstrapPayloadHandlers(app);
+test("users bootstrap user handler registers with the explicit shell registry", () => {
+  const registry = createBootstrapPayloadHandlerRegistry();
+  registry.register(createUsersBootstrapUserHandler());
 
-  const handlers = resolveBootstrapPayloadHandlers(app);
+  const handlers = registry.list();
   assert.equal(handlers.length, 1);
   assert.equal(handlers[0]?.handlerId, "users.web.bootstrap.user");
   assert.equal(typeof handlers[0]?.applyBootstrapPayload, "function");

package/test/exportsContract.test.js

@@ -8,42 +8,16 @@ const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
 const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "users-web");
 
-test("users-web exports are explicit and aligned with production/template usage", () => {
+test("users-web exports only user-owned client surfaces", () => {
   const result = evaluatePackageExportsContract({
     repoRoot: REPO_ROOT,
     packageDir: PACKAGE_DIR,
     packageId: "@jskit-ai/users-web",
     requiredExports: [
       "./client",
+      "./client/providers/UsersWebClientProvider",
       "./client/components/AccountSettingsClientElement",
-      "./client/components/CrudAddEditScreen",
-      "./client/components/CrudListBulkActionSurface",
-      "./client/components/CrudListFilterSurface",
-      "./client/components/CrudListScreen",
-      "./client/components/CrudViewScreen",
-      "./client/account-settings/sections",
-      "./client/bulkActions",
-      "./client/filters",
-      "./client/rowActions",
-      "./client/composables/useAddEdit",
-      "./client/composables/useCommand",
-      "./client/composables/useEndpointResource",
-      "./client/composables/useList",
-      "./client/composables/usePaths",
-      "./client/composables/useView",
-      "./client/composables/useCrudAddEdit",
-      "./client/composables/useCrudAddEditScreen",
-      "./client/composables/useCrudDeleteAction",
-      "./client/composables/useCrudListBulkActions",
-      "./client/composables/useCrudListRowActions",
-      "./client/composables/useCrudListFilterLookups",
-      "./client/composables/useCrudListFilters",
-      "./client/composables/useCrudList",
-      "./client/composables/useCrudListScreen",
-      "./client/crudHttpClient",
-      "./client/composables/useCrudView",
-      "./client/composables/useCrudViewScreen",
-      "./client/lib/httpClient"
+      "./client/account-settings/sections"
     ]
   });
 

package/test/packageMetadataOwnership.test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import packageJson from "../package.json" with { type: "json" };
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+test("users-web publishes account examples as agent-readable patterns", async () => {
+  assert.equal(packageJson.jskit?.mutations, undefined);
+
+  const pattern = await readFile(path.join(packageRoot, "patterns", "account-settings", "PATTERN.md"), "utf8");
+  assert.match(pattern, /## Product decisions/);
+  assert.match(pattern, /## Invariants/);
+  assert.match(pattern, /Mutation errors use the standard toast/);
+  assert.match(pattern, /Loading uses layout-stable skeletons/);
+  assert.match(pattern, /## Example files/);
+});