@structured-id/ui-core 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -62,6 +62,7 @@ export {
   refusalMessage,
   REFUSAL_TEXTS,
   SID_ERROR_DOMAIN,
+  type FieldViolation,
   type RpcRefusal,
 } from "./utils/rpcRefusal";
 

package/src/profile/components/SidLoginForm.test.ts

@@ -80,6 +80,20 @@ describe("SidLoginForm", () => {
     expect(w.text()).toContain("Your password never leaves this device");
   });
 
+  // The default subtitle names only the types the field accepts: a form
+  // restricted to email must not invite a phone or a username.
+  it("names the accepted types in the default subtitle", () => {
+    expect(mountLogin().text()).toContain(
+      "Enter your email, phone, or username to continue",
+    );
+    expect(mountLogin({ principalTypes: ["email"] }).text()).toContain(
+      "Enter your email to continue",
+    );
+    expect(
+      mountLogin({ principalTypes: ["email"], subtitle: "Hello" }).text(),
+    ).toContain("Hello");
+  });
+
   // Regression: the password turned red on the first keystroke and its empty
   // error read "Required" beside the identifier's "This field is required".
   it("validates the password once left, with the shared required text", () => {

package/src/profile/components/SidLoginForm.vue

@@ -3,7 +3,7 @@
     <q-card-section>
       <slot name="header">
         <div class="text-h6">{{ title }}</div>
-        <div class="text-caption text-grey">{{ subtitle }}</div>
+        <div class="text-caption text-grey">{{ shownSubtitle }}</div>
       </slot>
     </q-card-section>
 
@@ -38,6 +38,8 @@
           v-model="identifier"
           :disable="loading"
           :label="identifierLabel"
+          :types="principalTypes"
+          :texts="principalTexts"
           data-test="principal"
           @update:principal-type="principalType = $event"
         />
@@ -116,9 +118,17 @@
 </template>
 
 <script setup lang="ts">
-import { ref } from "vue";
-import { SidPrincipalInput } from "../../quasar";
-import type { PrincipalType } from "../../quasar";
+import { computed, ref } from "vue";
+import {
+  ALL_PRINCIPAL_TYPES,
+  DEFAULT_PRINCIPAL_INPUT_TEXTS,
+  SidPrincipalInput,
+} from "../../quasar";
+import type {
+  AcceptedPrincipalType,
+  PrincipalInputTexts,
+  PrincipalType,
+} from "../../quasar";
 import { normalizePrincipal, refusalMessage } from "../../index";
 import { REQUIRED_FIELD_TEXT } from "../../utils/validators";
 
@@ -154,6 +164,10 @@ const props = withDefaults(
     registerUrl?: string;
     /** OPAQUE step labels (step 1-3) */
     opaqueStepLabels?: Record<number, string>;
+    /** The principal types this instance signs in with. Default: every type. */
+    principalTypes?: AcceptedPrincipalType[];
+    /** Replacements for the identifier field's texts. */
+    principalTexts?: Partial<PrincipalInputTexts>;
     /** External login function — receives (identifier, password, stepCallback) */
     loginFn: (
       identifier: string,
@@ -167,9 +181,13 @@ const props = withDefaults(
   }>(),
   {
     title: "Sign in",
-    subtitle: "Enter your email, phone, or username to continue",
+    // Without one the subtitle names the accepted types.
+    subtitle: undefined,
     submitLabel: "Sign in",
-    identifierLabel: "Email, phone, or username",
+    // Without one the field names the accepted types.
+    identifierLabel: undefined,
+    principalTypes: () => ["email", "phone", "username"],
+    principalTexts: () => ({}),
     passwordLabel: "Password",
     passwordRequiredText: REQUIRED_FIELD_TEXT,
     showForgotPassword: true,
@@ -195,6 +213,14 @@ const emit = defineEmits<{
   "forgot-password": [];
 }>();
 
+const shownSubtitle = computed(
+  () =>
+    props.subtitle ??
+    { ...DEFAULT_PRINCIPAL_INPUT_TEXTS, ...props.principalTexts }.loginSubtitle(
+      ALL_PRINCIPAL_TYPES.filter((t) => props.principalTypes.includes(t)),
+    ),
+);
+
 const identifier = ref("");
 const principalType = ref<PrincipalType>("unknown");
 const password = ref("");

package/src/profile/components/SidRegistrationForm.test.ts

@@ -1,5 +1,13 @@
 import { describe, it, expect, vi } from "vitest";
 import { flushPromises, mount } from "@vue/test-utils";
+import { RpcError } from "@protobuf-ts/runtime-rpc";
+import { base64encode } from "@protobuf-ts/runtime";
+import { Any } from "@structured-id/proto/google/protobuf/any";
+import { Status } from "@structured-id/proto/google/rpc/status";
+import {
+  BadRequest,
+  ErrorInfo,
+} from "@structured-id/proto/google/rpc/error_details";
 import SidRegistrationForm from "./SidRegistrationForm.vue";
 
 const quasarStubs = {
@@ -16,10 +24,12 @@ const quasarStubs = {
     emits: ["submit"],
   },
   "q-input": {
-    props: ["modelValue"],
+    props: ["modelValue", "error", "errorMessage"],
     emits: ["update:modelValue"],
+    // The form re-validates the confirmation through the QInput API.
+    methods: { validate: () => true },
     template:
-      '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />',
+      '<input :value="modelValue" :data-error="error ? errorMessage : undefined" @input="$emit(\'update:modelValue\', $event.target.value)" />',
   },
   "q-btn": { template: '<button type="submit"><slot /></button>' },
   "sid-password-ceremony": {
@@ -30,13 +40,49 @@ const quasarStubs = {
       '<div class="ceremony" :data-outcome="outcome" :data-refused="refusedText" :data-length="length" :data-fields="fields" />',
   },
   "sid-principal-input": {
-    props: ["modelValue", "disable", "label"],
+    name: "SidPrincipalInput",
+    props: [
+      "modelValue",
+      "disable",
+      "label",
+      "types",
+      "minUsernameLength",
+      "fieldError",
+    ],
     emits: ["update:modelValue", "update:principal-type"],
     template:
-      '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />',
+      '<input :value="modelValue" :data-error="fieldError || undefined" @input="$emit(\'update:modelValue\', $event.target.value)" />',
   },
 };
 
+/** A refusal as the gRPC-Web transport raises it, with field violations. */
+function refusedFields(
+  violations: { field: string; description: string }[],
+): RpcError {
+  const bad = Any.pack(
+    BadRequest.create({
+      fieldViolations: violations.map((v) => ({ ...v, reason: "" })),
+    }),
+    BadRequest,
+  );
+  const info = Any.pack(
+    ErrorInfo.create({
+      reason: "INVALID_FIELD_VALUE",
+      domain: "structured.id",
+      metadata: {},
+    }),
+    ErrorInfo,
+  );
+  const status = Status.create({
+    code: 3,
+    message: "invalid",
+    details: [info, bad],
+  });
+  return new RpcError("invalid", "INVALID_ARGUMENT", {
+    "grpc-status-details-bin": base64encode(Status.toBinary(status)),
+  });
+}
+
 const registerFn = vi.fn().mockResolvedValue(undefined);
 
 function mountForm(props = {}) {
@@ -383,6 +429,126 @@ describe("SidRegistrationForm", () => {
     });
   });
 
+  describe("principal", () => {
+    function principalInput(props = {}) {
+      return mountForm(props).findComponent({ name: "SidPrincipalInput" });
+    }
+
+    // The field takes only the types the instance or the scenario admits.
+    it("passes the admitted principal types to the field", () => {
+      expect(
+        principalInput({ principalTypes: ["email"] }).props("types"),
+      ).toEqual(["email"]);
+      expect(principalInput().props("types")).toEqual([
+        "email",
+        "phone",
+        "username",
+      ]);
+    });
+
+    // A short username is admitted only in the registration that presents
+    // the installation's claim token (its first administrator); an ordinary
+    // registration keeps the registration minimum.
+    it("admits a short username only with the claim token", () => {
+      expect(principalInput().props("minUsernameLength")).toBe(6);
+      expect(
+        principalInput({ claimRequired: true }).props("minUsernameLength"),
+      ).toBe(3);
+    });
+
+    // Regression: a refusal that named the identifier field reached the
+    // user only as an undecoded banner. It is shown under the field it
+    // concerns, and the claim token's under the token.
+    it("shows each field violation under its field", async () => {
+      registerFn.mockRejectedValueOnce(
+        refusedFields([
+          { field: "principal", description: "Registration here takes email" },
+          {
+            field: "claim_token",
+            description: "Not this installation's token",
+          },
+        ]),
+      );
+      const w = mountForm({ claimRequired: true });
+      const [claim, principal, password, confirm] = w.findAll("input");
+      await claim.setValue("sidclaim_x");
+      await principal.setValue("sid");
+      await password.setValue("Secret-Pass-123");
+      await confirm.setValue("Secret-Pass-123");
+      await w.find("form").trigger("submit");
+      await flushPromises();
+      w.findComponent({ name: "SidPasswordCeremony" }).vm.$emit(
+        "settled",
+        "refused",
+      );
+      await flushPromises();
+
+      const [claimAfter, principalAfter] = w.findAll("input");
+      expect(principalAfter.attributes("data-error")).toBe(
+        "Registration here takes email",
+      );
+      expect(claimAfter.attributes("data-error")).toBe(
+        "Not this installation's token",
+      );
+      expect(w.text()).not.toContain("invalid");
+
+      // Editing the field clears what the server said about it.
+      await principalAfter.setValue("owner@sid.example.com");
+      expect(w.findAll("input")[1].attributes("data-error")).toBeUndefined();
+    });
+
+    async function refuse(
+      violations: { field: string; description: string }[],
+      props = {},
+    ) {
+      registerFn.mockRejectedValueOnce(refusedFields(violations));
+      const w = mountForm(props);
+      const [principal, password, confirm] = w.findAll("input");
+      await principal.setValue("user@sid.example.com");
+      await password.setValue("Secret-Pass-123");
+      await confirm.setValue("Secret-Pass-123");
+      await w.find("form").trigger("submit");
+      await flushPromises();
+      w.findComponent({ name: "SidPasswordCeremony" }).vm.$emit(
+        "settled",
+        "refused",
+      );
+      await flushPromises();
+      return w;
+    }
+
+    // Several requirements of one field are all shown at once, not only the
+    // last one the server listed.
+    it("keeps every violation of one field", async () => {
+      const w = await refuse([
+        { field: "password", description: "At least 1 digit" },
+        { field: "password", description: "At least 1 symbol" },
+      ]);
+      expect(w.findAll("input")[1].attributes("data-error")).toBe(
+        "At least 1 digit; At least 1 symbol",
+      );
+    });
+
+    // Regression: a refusal bound to the password stayed under it after the
+    // password was edited.
+    it("clears the password's refusal when the password changes", async () => {
+      const w = await refuse([
+        { field: "password", description: "Not accepted" },
+      ]);
+      await w.findAll("input")[1].setValue("Another-Pass-456");
+      expect(w.findAll("input")[1].attributes("data-error")).toBeUndefined();
+    });
+
+    // A violation of a field the form does not show (the invite code while
+    // no invite is asked for) stays in the banner instead of disappearing.
+    it("keeps a hidden field's violation in the banner", async () => {
+      const w = await refuse([
+        { field: "invite_code", description: "This invite has expired" },
+      ]);
+      expect(w.text()).toContain("This invite has expired");
+    });
+  });
+
   it("renders footer slot", () => {
     const w = mount(SidRegistrationForm, {
       props: { registerFn },

package/src/profile/components/SidRegistrationForm.vue

@@ -80,7 +80,10 @@
           spellcheck="false"
           :disable="loading"
           :rules="[(v: string) => !!v.trim() || claimTokenRequiredText]"
+          :error="!!fieldErrors.claimToken"
+          :error-message="fieldErrors.claimToken"
           data-test="claim-token"
+          @update:model-value="fieldErrors.claimToken = undefined"
         >
           <template v-slot:prepend>
             <q-icon name="sym_o_key" />
@@ -108,6 +111,9 @@
             inviteRequired ? [(v: string) => !!v || inviteCodeRequiredText] : []
           "
           :hint="inviteCodeHint"
+          :error="!!fieldErrors.inviteCode"
+          :error-message="fieldErrors.inviteCode"
+          @update:model-value="fieldErrors.inviteCode = undefined"
         >
           <template v-slot:prepend>
             <q-icon name="sym_o_vpn_key" />
@@ -129,9 +135,13 @@
           v-model="identifier"
           :disable="loading"
           :label="identifierLabel"
+          :types="principalTypes"
+          :texts="principalTexts"
           :lazy-rules="false"
-          :min-username-length="usernameMinLength"
+          :min-username-length="effectiveUsernameMinLength"
+          :field-error="fieldErrors.principal"
           data-test="principal"
+          @update:model-value="fieldErrors.principal = undefined"
           @update:principal-type="principalType = $event"
         />
 
@@ -146,6 +156,8 @@
           :disable="loading"
           :lazy-rules="false"
           :rules="passwordRules"
+          :error="!!fieldErrors.password"
+          :error-message="fieldErrors.password"
           data-test="password"
           @update:model-value="onPasswordInput"
         >
@@ -231,8 +243,12 @@ import {
 interface ValidatableInput {
   validate: () => boolean | Promise<boolean>;
 }
-import type { PrincipalType } from "../../quasar";
-import { normalizePrincipal, refusalMessage } from "../../index";
+import type {
+  AcceptedPrincipalType,
+  PrincipalInputTexts,
+  PrincipalType,
+} from "../../quasar";
+import { normalizePrincipal, refusalMessage, rpcRefusal } from "../../index";
 import { REQUIRED_FIELD_TEXT } from "../../utils/validators";
 
 /** What the form collected besides the identifier and password. */
@@ -315,15 +331,31 @@ const props = withDefaults(
     acceptedText?: string;
     /** Show confirm-password field with match validation. Default true. */
     showConfirmPassword?: boolean;
-    /** Min username length. Registration default 6 (premium feature gating);
-     *  login flow can pass 3 since short usernames are valid post-registration. */
+    /**
+     * The shortest username an ordinary registration admits; the instance's
+     * registration settings give it (6 on the global namespace).
+     */
     usernameMinLength?: number;
+    /**
+     * The shortest username the claim registration admits: the
+     * installation's first administrator may take a short name, nobody else.
+     */
+    claimUsernameMinLength?: number;
+    /**
+     * The principal types this registration admits, from the instance's
+     * registration settings or the scenario (the platform claim at SaaS
+     * central takes email only). Default: every type.
+     */
+    principalTypes?: AcceptedPrincipalType[];
+    /** Replacements for the identifier field's texts. */
+    principalTexts?: Partial<PrincipalInputTexts>;
   }>(),
   {
     title: "Create account",
     subtitle: "Set up your StructuredID account",
     submitLabel: "Create account",
-    identifierLabel: "Email, phone, or username",
+    // Without one the field names the admitted types.
+    identifierLabel: undefined,
     passwordLabel: "Password",
     confirmPasswordLabel: "Confirm password",
     passwordRequiredText: REQUIRED_FIELD_TEXT,
@@ -350,10 +382,38 @@ const props = withDefaults(
       "This installation has no administrator yet. Enter the claim token from the service log; the account you create becomes its administrator.",
     showConfirmPassword: true,
     usernameMinLength: 6,
+    claimUsernameMinLength: 3,
+    principalTypes: () => ["email", "phone", "username"],
+    principalTexts: () => ({}),
     acceptedText: "Account created",
   },
 );
 
+// The claim registration is a scenario of its own: its admission rules are
+// fixed here until the instance's flow configuration can set them.
+const effectiveUsernameMinLength = computed(() =>
+  props.claimRequired ? props.claimUsernameMinLength : props.usernameMinLength,
+);
+
+/**
+ * What the server said about each field of the request, shown under it until
+ * the field is edited. The request fields are the registration Start's.
+ */
+const fieldErrors = ref<{
+  principal?: string;
+  claimToken?: string;
+  inviteCode?: string;
+  password?: string;
+}>({});
+
+/** Request field → form field. */
+const FIELD_OF: Record<string, keyof typeof fieldErrors.value> = {
+  principal: "principal",
+  claim_token: "claimToken",
+  invite_code: "inviteCode",
+  password: "password",
+};
+
 const emit = defineEmits<{
   success: [data: { identifier: string; principalType: string }];
   error: [error: Error];
@@ -404,6 +464,8 @@ watch(password, () => {
 });
 
 function onPasswordInput() {
+  // What the server said about the password was about its earlier value.
+  fieldErrors.value.password = undefined;
   // Trigger downstream confirm re-validation immediately (don't wait for blur).
   if (confirmPassword.value) confirmRef.value?.validate();
 }
@@ -426,6 +488,7 @@ async function onSubmit() {
 
   loading.value = true;
   error.value = null;
+  fieldErrors.value = {};
   progress.value = null;
   ceremony.value = "running";
   // A phone's keyboard would cover the ceremony.
@@ -434,7 +497,7 @@ async function onSubmit() {
   try {
     const normalized = normalizePrincipal(
       identifier.value,
-      props.usernameMinLength,
+      effectiveUsernameMinLength.value,
     );
     const extras: RegistrationExtras = props.claimRequired
       ? { claimToken: claimToken.value.trim() }
@@ -453,7 +516,31 @@ async function onSubmit() {
   } catch (e) {
     success.value = false;
     const err = e instanceof Error ? e : new Error("Registration failed");
-    error.value = refusalMessage(e, "Registration failed");
+    // A violation of a field the form shows goes under that field, all of a
+    // field's together; the banner keeps the rest (a field not shown now
+    // included), or the general reason when nothing is left.
+    const shown: Record<keyof typeof fieldErrors.value, boolean> = {
+      principal: true,
+      password: true,
+      claimToken: props.claimRequired,
+      inviteCode: showInviteField.value,
+    };
+    const rest: string[] = [];
+    for (const v of rpcRefusal(e)?.fieldViolations ?? []) {
+      const field = FIELD_OF[v.field];
+      if (field && shown[field]) {
+        const before = fieldErrors.value[field];
+        fieldErrors.value[field] = before ? `${before}; ${v.text}` : v.text;
+      } else {
+        rest.push(v.text);
+      }
+    }
+    const bound = Object.keys(fieldErrors.value).length > 0;
+    error.value = rest.length
+      ? rest.join("; ")
+      : bound
+        ? null
+        : refusalMessage(e, "Registration failed");
     announce = () => emit("error", err);
     ceremony.value = "refused";
   } finally {

package/src/quasar/SidPrincipalInput.test.ts

@@ -7,7 +7,14 @@ import { REQUIRED_FIELD_TEXT } from "../utils/validators";
 const stubs = {
   "q-input": defineComponent({
     name: "QInputStub",
-    props: ["modelValue", "rules", "lazyRules"],
+    props: [
+      "modelValue",
+      "rules",
+      "lazyRules",
+      "label",
+      "error",
+      "errorMessage",
+    ],
     template: "<div><slot name='prepend' /><slot name='append' /></div>",
   }),
   "q-icon": { template: "<span />" },
@@ -46,4 +53,68 @@ describe("SidPrincipalInput", () => {
     const [required] = input({ required: false }).props("rules") as Rule[];
     expect(required("")).toBe(true);
   });
+
+  // A field that accepts only some principal types refuses the others before
+  // any call, naming what it accepts: a registration that takes email only
+  // must not let a username reach the server.
+  it("refuses a principal type it does not accept", () => {
+    const [, type] = input({ types: ["email"] }).props("rules") as Rule[];
+    expect(type("alice_wonder")).toBe("Enter an email address");
+    expect(type("+380501234567")).toBe("Enter an email address");
+    expect(type("alice@sid.example.com")).toBe(true);
+    const [, two] = input({ types: ["email", "username"] }).props(
+      "rules",
+    ) as Rule[];
+    expect(two("+380501234567")).toBe("Enter an email address or a username");
+    expect(two("alice_wonder")).toBe(true);
+  });
+
+  // Regression: a username shorter than the minimum was not recognized as a
+  // username and the field asked for "email, phone, or username" instead of
+  // saying the minimum.
+  it("tells a too-short username the minimum length", () => {
+    const [, type] = input({ minUsernameLength: 6 }).props("rules") as Rule[];
+    expect(type("sid")).toBe("A username has at least 6 characters");
+    expect(type("sidsid")).toBe(true);
+    const [, login] = input().props("rules") as Rule[];
+    expect(login("sid")).toBe(true);
+    expect(login("si")).toBe("A username has at least 3 characters");
+  });
+
+  // The label names the accepted types unless the form gives its own.
+  it("labels the field by the types it accepts", () => {
+    expect(input().props("label")).toBe("Email, phone, or username");
+    expect(input({ types: ["email"] }).props("label")).toBe("Email");
+    expect(input({ types: ["email", "username"] }).props("label")).toBe(
+      "Email or username",
+    );
+    expect(
+      input({ types: ["email"], label: "Your email" }).props("label"),
+    ).toBe("Your email");
+  });
+
+  // The chip naming the detected type is a text like the others: a
+  // translated form does not switch back to English when a type is found.
+  it("takes the type chip's text from the texts", () => {
+    const w = mount(SidPrincipalInput, {
+      props: {
+        modelValue: "alice@sid.example.com",
+        texts: { typeChip: (t: string) => `chip:${t}` },
+      },
+      global: { stubs },
+    });
+    expect(w.text()).toContain("chip:email");
+  });
+
+  // A refusal the server bound to this field is shown on it.
+  it("shows an error given from outside", () => {
+    const shown = input({
+      fieldError: "Registration here takes an email address",
+    });
+    expect(shown.props("error")).toBe(true);
+    expect(shown.props("errorMessage")).toBe(
+      "Registration here takes an email address",
+    );
+    expect(input().props("error")).toBe(false);
+  });
 });

package/src/quasar/SidPrincipalInput.vue

@@ -2,8 +2,10 @@
   <q-input
     ref="inputRef"
     v-model="model"
-    :label="label"
+    :label="fieldLabel"
     :rules="[requiredRule, typeRule]"
+    :error="!!fieldError"
+    :error-message="fieldError ?? undefined"
     outlined
     type="text"
     :inputmode="inputMode"
@@ -35,13 +37,32 @@ import { ref, computed, watch } from "vue";
 import { isValidPhoneNumber } from "libphonenumber-js";
 import { REQUIRED_FIELD_TEXT, isValidEmail } from "../utils/validators";
 
-export type PrincipalType = "email" | "phone" | "username" | "unknown";
+import {
+  ALL_PRINCIPAL_TYPES,
+  DEFAULT_PRINCIPAL_INPUT_TEXTS,
+  type AcceptedPrincipalType,
+  type PrincipalInputTexts,
+  type PrincipalType,
+} from "./principalInputTexts";
+
+export type { PrincipalType };
 
 interface Props {
   modelValue: string;
+  /**
+   * The principal types this field accepts; the others are refused before
+   * any call, with a text naming the accepted ones. The instance's settings
+   * or the scenario decide it (a registration may take email only).
+   */
+  types?: AcceptedPrincipalType[];
   minUsernameLength?: number;
   required?: boolean;
+  /** The label; without one the field names the accepted types. */
   label?: string;
+  /** A refusal the server bound to this field, shown on it until edited. */
+  fieldError?: string | null;
+  /** Replacements for the field's texts. */
+  texts?: Partial<PrincipalInputTexts>;
   /** What an empty required field says. */
   requiredText?: string;
   /**
@@ -54,14 +75,31 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   modelValue: "",
+  types: () => [...ALL_PRINCIPAL_TYPES],
   // Username rule: ^[a-z0-9_]{3,32}$ (display form ^[a-zA-Z0-9_]{3,32}$).
   minUsernameLength: 3,
   required: true,
-  label: "Email, phone, or username",
+  label: undefined,
+  fieldError: null,
+  texts: () => ({}),
   requiredText: REQUIRED_FIELD_TEXT,
   lazyRules: true,
 });
 
+const text = computed<PrincipalInputTexts>(() => ({
+  ...DEFAULT_PRINCIPAL_INPUT_TEXTS,
+  ...props.texts,
+}));
+
+/** The accepted types in their fixed order. */
+const accepted = computed(() =>
+  ALL_PRINCIPAL_TYPES.filter((t) => props.types.includes(t)),
+);
+
+const fieldLabel = computed(
+  () => props.label ?? text.value.label(accepted.value),
+);
+
 const emit = defineEmits<{
   "update:modelValue": [value: string];
   "update:principalType": [type: PrincipalType];
@@ -87,16 +125,11 @@ function detectType(value: string): PrincipalType {
   // Email: contains @ (checked after phone to exclude edge cases)
   if (trimmed.includes("@")) return "email";
 
-  // Username: ^[a-z0-9_]{3,32}$, no leading/trailing _, no __
-  // Detection is relaxed: accepts uppercase (will normalize), checks min length
-  const re = new RegExp(
-    `^[a-zA-Z0-9_]{${props.minUsernameLength},${USERNAME_MAX_LENGTH}}$`,
-  );
-  if (re.test(trimmed) && !trimmed.startsWith("_") && !trimmed.endsWith("_")) {
-    return "username";
-  }
+  // Username by its shape at any length, so that a short one is told the
+  // minimum instead of being taken for no type at all. Uppercase is accepted
+  // (the server derives the key); length and underscores are the rule's.
+  if (/^[a-zA-Z0-9_]+$/.test(trimmed)) return "username";
 
-  // Still typing — not enough chars to determine
   return "unknown";
 }
 
@@ -119,26 +152,26 @@ const requiredRule = (val: string) =>
 const typeRule = (val: string): string | true => {
   if (!val) return true; // required rule handles empty
   const type = detectType(val);
+  if (type === "unknown" || !accepted.value.includes(type)) {
+    return text.value.enterAccepted(accepted.value);
+  }
 
   switch (type) {
     case "email":
-      return isValidEmail(val.trim()) || "Invalid email address";
+      return isValidEmail(val.trim()) || text.value.invalidEmail;
     case "phone":
-      return isValidPhoneNumber(val) || "Invalid phone number";
+      return isValidPhoneNumber(val) || text.value.invalidPhone;
     case "username": {
-      const lower = val.toLowerCase();
-      const re = new RegExp(
-        `^[a-z0-9_]{${props.minUsernameLength},${USERNAME_MAX_LENGTH}}$`,
-      );
-      if (!re.test(lower)) return "Invalid username";
-      if (lower.startsWith("_") || lower.endsWith("_"))
-        return "Username cannot start or end with underscore";
-      if (lower.includes("__"))
-        return "Username cannot contain consecutive underscores";
+      const name = val.trim();
+      if (name.length < props.minUsernameLength)
+        return text.value.usernameTooShort(props.minUsernameLength);
+      if (name.length > USERNAME_MAX_LENGTH)
+        return text.value.usernameTooLong(USERNAME_MAX_LENGTH);
+      if (name.startsWith("_") || name.endsWith("_"))
+        return text.value.usernameUnderscoreEdge;
+      if (name.includes("__")) return text.value.usernameDoubleUnderscore;
       return true;
     }
-    default:
-      return "Enter email, phone (+...), or username";
   }
 };
 
@@ -177,18 +210,11 @@ const inputMode = computed(() => {
   }
 });
 
-const chipLabel = computed(() => {
-  switch (detectedType.value) {
-    case "email":
-      return "email";
-    case "phone":
-      return "phone";
-    case "username":
-      return "username";
-    default:
-      return "";
-  }
-});
+const chipLabel = computed(() =>
+  detectedType.value === "unknown"
+    ? ""
+    : text.value.typeChip(detectedType.value),
+);
 
 const chipColor = computed(() => {
   switch (detectedType.value) {

package/src/quasar/index.ts

@@ -5,6 +5,14 @@
  * Import as: import { SidPrincipalInput } from '@structured-id/ui-core/quasar'
  */
 export { default as SidPrincipalInput } from "./SidPrincipalInput.vue";
-export type { PrincipalType } from "./SidPrincipalInput.vue";
+export type {
+  AcceptedPrincipalType,
+  PrincipalInputTexts,
+  PrincipalType,
+} from "./principalInputTexts";
+export {
+  ALL_PRINCIPAL_TYPES,
+  DEFAULT_PRINCIPAL_INPUT_TEXTS,
+} from "./principalInputTexts";
 export { default as SidPasswordCeremony } from "./SidPasswordCeremony.vue";
 export type { CeremonyOutcome } from "./SidPasswordCeremony.vue";

package/src/quasar/principalInputTexts.ts

@@ -0,0 +1,68 @@
+/** The principal types and texts of `SidPrincipalInput`. */
+
+export type PrincipalType = "email" | "phone" | "username" | "unknown";
+
+/** A principal type a field can accept. */
+export type AcceptedPrincipalType = Exclude<PrincipalType, "unknown">;
+
+/** Every type, in the order the label and the texts name them. */
+export const ALL_PRINCIPAL_TYPES: readonly AcceptedPrincipalType[] = [
+  "email",
+  "phone",
+  "username",
+];
+
+/** What the field says; each text can be replaced (translated) by the form. */
+export interface PrincipalInputTexts {
+  /** The label for the accepted types, when the form gives none. */
+  label: (types: AcceptedPrincipalType[]) => string;
+  /** A value of a type the field does not accept, or of no type at all. */
+  enterAccepted: (types: AcceptedPrincipalType[]) => string;
+  /** The chip naming the type the value was recognized as. */
+  typeChip: (type: AcceptedPrincipalType) => string;
+  /** The login form's default subtitle for the accepted types. */
+  loginSubtitle: (types: AcceptedPrincipalType[]) => string;
+  invalidEmail: string;
+  invalidPhone: string;
+  usernameTooShort: (min: number) => string;
+  usernameTooLong: (max: number) => string;
+  usernameUnderscoreEdge: string;
+  usernameDoubleUnderscore: string;
+}
+
+/** `a`, `a or b`, `a, b, or c`. */
+function list(words: string[]): string {
+  if (words.length <= 1) return words.join("");
+  if (words.length === 2) return `${words[0]} or ${words[1]}`;
+  return `${words.slice(0, -1).join(", ")}, or ${words[words.length - 1]}`;
+}
+
+const LABEL_WORDS: Record<AcceptedPrincipalType, string> = {
+  email: "email",
+  phone: "phone",
+  username: "username",
+};
+
+const ENTER_WORDS: Record<AcceptedPrincipalType, string> = {
+  email: "an email address",
+  phone: "a phone number (+...)",
+  username: "a username",
+};
+
+export const DEFAULT_PRINCIPAL_INPUT_TEXTS: PrincipalInputTexts = {
+  label: (types) => {
+    const text = list(types.map((t) => LABEL_WORDS[t]));
+    return text.charAt(0).toUpperCase() + text.slice(1);
+  },
+  enterAccepted: (types) => `Enter ${list(types.map((t) => ENTER_WORDS[t]))}`,
+  typeChip: (type) => LABEL_WORDS[type],
+  loginSubtitle: (types) =>
+    `Enter your ${list(types.map((t) => LABEL_WORDS[t]))} to continue`,
+  invalidEmail: "Invalid email address",
+  invalidPhone: "Invalid phone number",
+  usernameTooShort: (min) => `A username has at least ${min} characters`,
+  usernameTooLong: (max) => `A username has at most ${max} characters`,
+  usernameUnderscoreEdge: "A username cannot start or end with an underscore",
+  usernameDoubleUnderscore:
+    "A username cannot contain two underscores in a row",
+};

package/src/utils/rpcRefusal.test.ts

@@ -4,6 +4,7 @@ import { base64encode } from "@protobuf-ts/runtime";
 import { Any } from "@structured-id/proto/google/protobuf/any";
 import { Status } from "@structured-id/proto/google/rpc/status";
 import {
+  BadRequest,
   ErrorInfo,
   LocalizedMessage,
 } from "@structured-id/proto/google/rpc/error_details";
@@ -142,6 +143,47 @@ describe("rpcRefusal", () => {
     );
   });
 
+  // A refusal that names the fields it concerns lets the form show each
+  // text under its field: the server's text for people when it sent one,
+  // else its description.
+  it("reads the field violations", () => {
+    const bad = Any.pack(
+      BadRequest.create({
+        fieldViolations: [
+          {
+            field: "principal",
+            description: "registration here accepts: email",
+            reason: "PRINCIPAL_TYPE_NOT_ACCEPTED",
+          },
+          {
+            field: "claim_token",
+            description: "not the installation's token",
+            reason: "",
+            localizedMessage: LocalizedMessage.create({
+              locale: "en",
+              message: "This claim token is not valid.",
+            }),
+          },
+        ],
+      }),
+      BadRequest,
+    );
+    const refusal = rpcRefusal(refused([info, bad]));
+    expect(refusal?.fieldViolations).toEqual([
+      {
+        field: "principal",
+        reason: "PRINCIPAL_TYPE_NOT_ACCEPTED",
+        text: "registration here accepts: email",
+      },
+      {
+        field: "claim_token",
+        reason: null,
+        text: "This claim token is not valid.",
+      },
+    ]);
+    expect(rpcRefusal(refused([info]))?.fieldViolations).toEqual([]);
+  });
+
   it("survives an unreadable trailer", () => {
     const err = new RpcError("m", "INTERNAL", {
       "grpc-status-details-bin": "!!!",

package/src/utils/rpcRefusal.ts

@@ -8,6 +8,7 @@ import { base64decode } from "@protobuf-ts/runtime";
 import { Any } from "@structured-id/proto/google/protobuf/any";
 import { Status } from "@structured-id/proto/google/rpc/status";
 import {
+  BadRequest,
   ErrorInfo,
   LocalizedMessage,
 } from "@structured-id/proto/google/rpc/error_details";
@@ -28,6 +29,18 @@ export interface RpcRefusal {
   message: string;
   /** The server's text for people (`LocalizedMessage`), when it sent one. */
   localized: string | null;
+  /** The request fields the refusal names (`BadRequest`), in the server's order. */
+  fieldViolations: FieldViolation[];
+}
+
+/** One request field a refusal names. */
+export interface FieldViolation {
+  /** The field's path in the request, as the proto names it (`principal`). */
+  field: string;
+  /** The field-level reason, when the server gave one. */
+  reason: string | null;
+  /** What to show under the field: the server's text for people, else its description. */
+  text: string;
 }
 
 /**
@@ -50,6 +63,7 @@ export function rpcRefusal(err: unknown): RpcRefusal | null {
     metadata: {},
     message: decodeStatusMessage(err.message),
     localized: null,
+    fieldViolations: [],
   };
   for (const detail of statusDetails(err.meta[DETAILS_KEY])) {
     if (Any.contains(detail, ErrorInfo)) {
@@ -61,6 +75,14 @@ export function rpcRefusal(err: unknown): RpcRefusal | null {
         info.domain === SID_ERROR_DOMAIN ? sidReason(info.reason) : null;
     } else if (Any.contains(detail, LocalizedMessage)) {
       refusal.localized = Any.unpack(detail, LocalizedMessage).message;
+    } else if (Any.contains(detail, BadRequest)) {
+      for (const v of Any.unpack(detail, BadRequest).fieldViolations) {
+        refusal.fieldViolations.push({
+          field: v.field,
+          reason: v.reason || null,
+          text: v.localizedMessage?.message || v.description,
+        });
+      }
     }
   }
   return refusal;