chore: rename variable and add comments

.changeset/loud-trees-check.md

@@ -2,7 +2,7 @@
 "@logto/core-kit": patch
 ---
 
-refactor user claims type and introduce `completeUserClaims`
+refactor user claims type and introduce `userClaimsList`
 
-- Introduce a new exported variable `completeUserClaims` containing all possible user claims.
-- Utilize `completeUserClaims` to derive the `UserClaim` type, ensuring consistency and maintainability.
+- Introduce a new exported variable `userClaimsList` containing all possible user claims.
+- Utilize `userClaimsList` to derive the `UserClaim` type, ensuring consistency and maintainability.

packages/schemas/src/foundations/jsonb-types/saml-application-configs.ts

@@ -1,13 +1,12 @@
 import { type ToZodObject } from '@logto/connector-kit';
-import { completeUserClaims, type UserClaim } from '@logto/core-kit';
+import { userClaimsList, type UserClaim } from '@logto/core-kit';
 import { z } from 'zod';
 
 export type SamlAttributeMapping = Partial<Record<UserClaim | 'sub', string>>;
 
-export const samlAttributeMappingKeys = Object.freeze([
-  'sub',
-  ...completeUserClaims,
-] satisfies Array<keyof SamlAttributeMapping>);
+export const samlAttributeMappingKeys = Object.freeze(['sub', ...userClaimsList] satisfies Array<
+  keyof SamlAttributeMapping
+>);
 
 export const samlAttributeMappingGuard = z
   .object(

packages/toolkit/core-kit/src/openid.ts

@@ -18,12 +18,18 @@ export enum ReservedResource {
 
 /**
  * A comprehensive list of all available user claims that can be used in SAML applications.
- * These claims can be mapped to SAML attributes in the application configuration.
+ * This array serves two purposes:
+ * 1. Acts as a single source of truth for all possible `UserClaim` values
+ * 2. Provides a runtime accessible list of all available claims
  *
- * Note: This array must include ALL possible values from UserClaim type.
- * TypeScript will throw a compile-time error if any value is missing.
+ * Previously, `UserClaim` type was defined directly as a union type. Now, we define this array first
+ * and derive the `UserClaim` type from it using Zod. This approach maintains type safety while also
+ * making the complete list of claims available at runtime.
+ *
+ * Note: This array must include ALL possible values from `UserClaim` type.
+ * TypeScript will throw error if any value is missing.
  */
-export const completeUserClaims = [
+export const userClaimsList = [
   // OIDC standard claims
   'name',
   'given_name',
@@ -57,9 +63,9 @@ export const completeUserClaims = [
 ] as const;
 
 /**
- * Zod guard for UserClaim type, using completeUserClaims as the single source of truth
+ * Zod guard for `UserClaim` type, using `userClaimsList` as the single source of truth
  */
-export const userClaimGuard = z.enum(completeUserClaims);
+export const userClaimGuard = z.enum(userClaimsList);
 
 export type UserClaim = z.infer<typeof userClaimGuard>;