@jskit-ai/users-web 0.2.9 → 0.2.11

package/src/client/lib/profileElementPresentation.js

@@ -0,0 +1,85 @@
+import {
+  normalizeObject,
+  normalizeOneOf
+} from "@jskit-ai/kernel/shared/support/normalize";
+
+// Default copy, by copy prop key; the copy prop overrides it.
+const DEFAULT_COPY_KEYS = Object.freeze({
+  title: "jskit.users.accountSettings.profile.title",
+  previewSizePrefix: "jskit.users.accountSettings.profile.previewSizePrefix",
+  previewSizeSuffix: "jskit.users.accountSettings.profile.previewSizeSuffix",
+  replaceAvatar: "jskit.users.accountSettings.profile.replaceAvatar",
+  removeAvatar: "jskit.users.accountSettings.profile.removeAvatar",
+  selectedFilePrefix: "jskit.users.accountSettings.profile.selectedFilePrefix",
+  displayName: "jskit.users.accountSettings.profile.displayName",
+  email: "jskit.users.accountSettings.profile.email",
+  emailHint: "jskit.users.accountSettings.profile.emailHint",
+  saveProfile: "jskit.users.accountSettings.profile.save"
+});
+
+function resolveProfileCopy(copy, t) {
+  return {
+    ...Object.fromEntries(Object.entries(DEFAULT_COPY_KEYS).map(([name, key]) => [name, t(key)])),
+    ...normalizeObject(copy)
+  };
+}
+
+function resolveProfileVariant(value) {
+  const variant = normalizeObject(value);
+  return {
+    layout: normalizeOneOf(variant.layout, ["compact", "comfortable"], "comfortable"),
+    surface: normalizeOneOf(variant.surface, ["plain", "carded"], "carded"),
+    density: normalizeOneOf(variant.density, ["compact", "comfortable"], "comfortable"),
+    tone: normalizeOneOf(variant.tone, ["neutral", "emphasized"], "neutral")
+  };
+}
+
+function resolveProfileFeatures(value) {
+  const features = normalizeObject(value);
+  return {
+    header: features.header !== false,
+    removeAvatar: features.removeAvatar !== false
+  };
+}
+
+function resolveProfileUiClasses(ui) {
+  const classes = normalizeObject(normalizeObject(ui).classes);
+  return {
+    root: String(classes.root || "").trim(),
+    card: String(classes.card || "").trim()
+  };
+}
+
+function resolveProfileUiTestIds(ui) {
+  const testIds = normalizeObject(normalizeObject(ui).testIds);
+  return {
+    root: String(testIds.root || "profile-client-element"),
+    card: String(testIds.card || "profile-client-card"),
+    submitButton: String(testIds.submitButton || "profile-submit-button"),
+    avatarReplaceButton: String(testIds.avatarReplaceButton || "profile-avatar-replace-button"),
+    avatarRemoveButton: String(testIds.avatarRemoveButton || "profile-avatar-remove-button")
+  };
+}
+
+function resolveProfileRootClasses(variant, uiClasses) {
+  const classes = [
+    "profile-client-element",
+    `profile-client-element--layout-${variant.layout}`,
+    `profile-client-element--surface-${variant.surface}`,
+    `profile-client-element--density-${variant.density}`,
+    `profile-client-element--tone-${variant.tone}`
+  ];
+  if (uiClasses.root) {
+    classes.push(uiClasses.root);
+  }
+  return classes;
+}
+
+export {
+  resolveProfileCopy,
+  resolveProfileFeatures,
+  resolveProfileRootClasses,
+  resolveProfileUiClasses,
+  resolveProfileUiTestIds,
+  resolveProfileVariant
+};

package/src/client/lib/theme.js

@@ -12,18 +12,20 @@ function normalizeThemePreference(value) {
   return THEME_PREFERENCE_SYSTEM;
 }
 
-function resolveSystemThemeName({ prefersDark } = {}) {
-  if (typeof prefersDark === "boolean") {
-    return prefersDark ? THEME_PREFERENCE_DARK : THEME_PREFERENCE_LIGHT;
-  }
+/** The page's window; null outside a browser. */
+function pageWindow() {
+  return typeof window === "undefined" ? null : window;
+}
 
-  if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
-    return window.matchMedia("(prefers-color-scheme: dark)").matches
-      ? THEME_PREFERENCE_DARK
-      : THEME_PREFERENCE_LIGHT;
-  }
+/** Whether the system asks for a dark theme; false where it cannot say. */
+function systemPrefersDark() {
+  const page = pageWindow();
+  // readable-check: allow method-probe - platform object: matchMedia exists only in a browser
+  return typeof page?.matchMedia === "function" && page.matchMedia("(prefers-color-scheme: dark)").matches;
+}
 
-  return THEME_PREFERENCE_LIGHT;
+function resolveSystemThemeName({ prefersDark = systemPrefersDark() } = {}) {
+  return prefersDark ? THEME_PREFERENCE_DARK : THEME_PREFERENCE_LIGHT;
 }
 
 function resolveThemeNameForPreference(themePreference, options = {}) {
@@ -44,12 +46,8 @@ function resolveThemePreferenceStorage(options = {}) {
     return customStorage;
   }
 
-  if (typeof window !== "object" || !window) {
-    return null;
-  }
-
   try {
-    return window.localStorage;
+    return pageWindow()?.localStorage || null;
   } catch {
     return null;
   }
@@ -57,7 +55,7 @@ function resolveThemePreferenceStorage(options = {}) {
 
 function readPersistedThemePreference(options = {}) {
   const storage = resolveThemePreferenceStorage(options);
-  if (!storage || typeof storage.getItem !== "function") {
+  if (!storage) {
     return THEME_PREFERENCE_SYSTEM;
   }
 
@@ -70,7 +68,7 @@ function readPersistedThemePreference(options = {}) {
 
 function persistThemePreference(themePreference, options = {}) {
   const storage = resolveThemePreferenceStorage(options);
-  if (!storage || typeof storage.setItem !== "function") {
+  if (!storage) {
     return false;
   }
 
@@ -108,38 +106,14 @@ function persistBootstrapThemePreference(payload = {}, options = {}) {
 }
 
 function resolveVuetifyThemeController(vueApp) {
-  if (!vueApp || typeof vueApp !== "object") {
-    return null;
-  }
-
-  const provides = vueApp._context?.provides;
-  if (!provides || typeof provides !== "object") {
-    return null;
-  }
-
-  const themeController = provides[ThemeSymbol];
-  if (
-    !themeController ||
-    typeof themeController !== "object" ||
-    typeof themeController.change !== "function" ||
-    !themeController.name
-  ) {
-    return null;
-  }
-
-  return themeController;
+  return vueApp._context.provides[ThemeSymbol] || null;
 }
 
+/**
+ * @param {import("vuetify").ThemeInstance} themeController
+ * @param {string} themeName
+ */
 function setVuetifyThemeName(themeController, themeName) {
-  if (
-    !themeController ||
-    typeof themeController !== "object" ||
-    typeof themeController.change !== "function" ||
-    !themeController.name
-  ) {
-    return false;
-  }
-
   const normalizedThemeName = themeName === THEME_PREFERENCE_DARK ? THEME_PREFERENCE_DARK : THEME_PREFERENCE_LIGHT;
   if (themeController.name.value === normalizedThemeName) {
     return false;

package/src/client/providers/UsersWebClientProvider.js

@@ -9,6 +9,12 @@ const UsersWebClientProvider = defineProvider({
     components: "client.components",
     shell: "client.shell"
   },
+  /**
+   * @param {{
+   *   components: import("@jskit-ai/kernel/client/types").ClientComponents,
+   *   shell: import("../types.js").UsersShell
+   * }} capabilities
+   */
   setup({ components, shell }) {
     components.register("users.web.home.tools.widget", UsersHomeToolsWidget);
     components.register("users.web.profile.element", ProfileClientElement);

package/src/client/types.js

@@ -0,0 +1,65 @@
+// The values users-web's client hands out and receives across files.
+
+/**
+ * The part of shell-web's placement runtime the bootstrap handler writes the signed-in user into.
+ * @typedef {object} UsersPlacementRuntime
+ * @property {() => Record<string, any>} getContext
+ * @property {(patch: Record<string, any>, options?: { source?: string }) => void} setContext
+ */
+
+/**
+ * The part of shell-web's placement runtime the account settings sections read.
+ * @typedef {object} AccountSectionsPlacementRuntime
+ * @property {() => number} getRevision
+ * @property {(listener: (event?: { revision?: number }) => void) => () => void} subscribe
+ * @property {(query: { surface: string, target: string, context: unknown }) => readonly Record<string, any>[]} getPlacements
+ */
+
+/**
+ * What shell-web's bootstrap hands a payload handler.
+ * @typedef {object} UsersBootstrapContext
+ * @property {Record<string, any>} [payload]
+ * @property {unknown} [error]
+ * @property {UsersPlacementRuntime} placementRuntime
+ * @property {string} [source]
+ */
+
+/**
+ * The part of the `client.shell` capability users-web uses.
+ * @typedef {object} UsersShell
+ * @property {{ register: (handler: ReturnType<typeof import("./bootstrap/user-bootstrap-handler.js").createUsersBootstrapUserHandler>) => void }} bootstrapHandlers
+ */
+
+/**
+ * One line of feedback about an account action.
+ * @typedef {object} AccountFeedback
+ * @property {string} message
+ * @property {string} [severity]
+ * @property {string} [channel]
+ * @property {string} [dedupeKey]
+ */
+
+/**
+ * What `ProfileClientElement` shows and edits.
+ * @typedef {object} ProfileElementState
+ * @property {{ displayName: string, email: string }} profileForm
+ * @property {{ avatarSize: number }} preferencesForm
+ * @property {{ effectiveUrl: string, hasUploadedAvatar: boolean }} profileAvatar
+ * @property {string} profileInitials
+ * @property {string} selectedAvatarFileName
+ * @property {{ displayName?: string }} profileFieldErrors
+ * @property {{ isPending: import("vue").Ref<boolean> }} profileMutation
+ * @property {{ isPending: import("vue").Ref<boolean> }} avatarDeleteMutation
+ */
+
+/**
+ * What `ProfileClientElement` calls.
+ * @typedef {object} ProfileElementActions
+ * @property {(payload: { displayName: string }) => unknown} submitProfile
+ * @property {() => unknown} openAvatarEditor
+ * @property {() => unknown} submitAvatarDelete
+ */
+
+/** @typedef {ReturnType<typeof import("./composables/useAccountSettingsRuntime.js").useAccountSettingsRuntime>} AccountSettingsRuntime */
+
+export {};

package/test/accountLocale.test.js

@@ -78,19 +78,26 @@ test("preference option labels follow the app's vue-i18n locale", () => {
 test("useAccountLocale follows the bootstrap payload's saved locale", async () => {
   const handler = createUsersBootstrapUserHandler();
   const accountLocale = useAccountLocale();
+  const placementRuntime = {
+    getContext() {
+      return {};
+    },
+    setContext() {}
+  };
 
   await handler.applyBootstrapPayload({
-    payload: { session: { authenticated: true, userId: "7" }, userSettings: { locale: "it-it" } }
+    payload: { session: { authenticated: true, userId: "7" }, userSettings: { locale: "it-it" } },
+    placementRuntime
   });
   assert.equal(accountLocale.value, "it-IT");
 
-  await handler.handleBootstrapError({ error: { statusCode: 500 } });
+  await handler.handleBootstrapError({ error: { statusCode: 500 }, placementRuntime });
   assert.equal(accountLocale.value, "it-IT");
 
-  await handler.handleBootstrapError({ error: { statusCode: 401 } });
+  await handler.handleBootstrapError({ error: { statusCode: 401 }, placementRuntime });
   assert.equal(accountLocale.value, "");
 
-  await handler.applyBootstrapPayload({ payload: { session: { authenticated: true }, userSettings: { locale: "en" } } });
-  await handler.applyBootstrapPayload({ payload: { session: { authenticated: false }, userSettings: null } });
+  await handler.applyBootstrapPayload({ payload: { session: { authenticated: true }, userSettings: { locale: "en" } }, placementRuntime });
+  await handler.applyBootstrapPayload({ payload: { session: { authenticated: false }, userSettings: null }, placementRuntime });
   assert.equal(accountLocale.value, "");
 });