@nixxie-cms/fields-phone 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @nixxie-cms/fields-phone
+
+A phone number field for Nixxie CMS. Stores E.164-normalised values (`+14155552671`): spaces,
+dashes, dots and parentheses are stripped, a leading `00` becomes `+`, and national numbers are
+promoted using `defaultCountryCode`. Invalid numbers are rejected with a validation error.
+
+```ts
+import { phone } from '@nixxie-cms/fields-phone'
+
+fields: {
+  mobile: phone({
+    defaultCountryCode: '+92', // '0300 1234567' → '+923001234567'
+    validation: { isRequired: true },
+    isIndexed: 'unique',
+  }),
+}
+```
+
+Also exports `formatPhone(e164)` for display — best-effort grouping (`+1 415 555 2671`): the
+country code is inferred from a small built-in table and the rest is split into groups of 3–4
+digits. It does not apply national formatting conventions; invalid input is returned unchanged.

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,32 @@
+import type { TextFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+/**
+ * Best-effort display formatting for an E.164 number: the country code, a space, then the
+ * remaining digits in groups of 3 (the final group absorbs a would-be lone digit, giving 3–4).
+ * E.g. `+14155552671` → `+1 415 555 2671`, `+923001234567` → `+92 300 123 4567`. The country
+ * code length is inferred from a small built-in table, not a full numbering plan, and no
+ * national conventions (area-code parentheses etc.) are applied. Input that is not valid E.164
+ * is returned unchanged.
+ */
+export declare function formatPhone(e164: string): string;
+export type PhoneFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<TextFieldConfig<CollectionTypeInfo>, 'validation'> & {
+    validation?: {
+        /** Reject saving when no value is present. */
+        isRequired?: boolean;
+    };
+    /**
+     * Country calling code (e.g. `'+92'`) prepended when the user enters a national number —
+     * one without a leading `+`. A single leading `0` (the national trunk prefix) is stripped
+     * first, so with `'+92'` both `03001234567` and `300 123 4567` become `+923001234567`.
+     */
+    defaultCountryCode?: string;
+};
+/**
+ * A phone number field storing E.164-normalised values (`+` followed by up to 15 digits). Built
+ * on the core `text` field: input is cleaned of spaces, dashes, dots and parentheses, a leading
+ * `00` becomes `+`, and national numbers are promoted via `defaultCountryCode`. Anything that
+ * still isn't valid E.164 is rejected with a validation error. Empty/null values pass through
+ * untouched. `isIndexed: 'unique'` is supported via the underlying text field.
+ */
+export declare function phone<CollectionTypeInfo extends BaseCollectionTypeInfo>(config?: PhoneFieldConfig<CollectionTypeInfo>): FieldTypeFunc<CollectionTypeInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAenF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAehD;AAgBD,MAAM,MAAM,gBAAgB,CAAC,kBAAkB,SAAS,sBAAsB,IAAI,IAAI,CACpF,eAAe,CAAC,kBAAkB,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE;QACX,8CAA8C;QAC9C,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;IACD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,kBAAkB,SAAS,sBAAsB,EACrE,MAAM,GAAE,gBAAgB,CAAC,kBAAkB,CAAM,GAChD,aAAa,CAAC,kBAAkB,CAAC,CAgCnC"}

package/dist/nixxie-cms-fields-phone.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1maWVsZHMtcGhvbmUuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/nixxie-cms-fields-phone.cjs.js

@@ -0,0 +1,105 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+/** E.164: a leading `+`, a country code starting 1–9, and 7–15 digits in total. */
+const E164 = /^\+[1-9]\d{6,14}$/;
+
+/** Country calling codes that are a single digit (NANP and Russia/Kazakhstan). */
+const ONE_DIGIT_CODES = new Set(['1', '7']);
+
+/** The ITU-assigned two-digit country calling codes — anything else is three digits. */
+const TWO_DIGIT_CODES = new Set(['20', '27', '30', '31', '32', '33', '34', '36', '39', '40', '41', '43', '44', '45', '46', '47', '48', '49', '51', '52', '53', '54', '55', '56', '57', '58', '60', '61', '62', '63', '64', '65', '66', '81', '82', '84', '86', '90', '91', '92', '93', '94', '95', '98']);
+
+/**
+ * Best-effort display formatting for an E.164 number: the country code, a space, then the
+ * remaining digits in groups of 3 (the final group absorbs a would-be lone digit, giving 3–4).
+ * E.g. `+14155552671` → `+1 415 555 2671`, `+923001234567` → `+92 300 123 4567`. The country
+ * code length is inferred from a small built-in table, not a full numbering plan, and no
+ * national conventions (area-code parentheses etc.) are applied. Input that is not valid E.164
+ * is returned unchanged.
+ */
+function formatPhone(e164) {
+  if (!E164.test(e164)) return e164;
+  const digits = e164.slice(1);
+  let ccLength = 3;
+  if (ONE_DIGIT_CODES.has(digits[0])) ccLength = 1;else if (TWO_DIGIT_CODES.has(digits.slice(0, 2))) ccLength = 2;
+  const countryCode = digits.slice(0, ccLength);
+  const rest = digits.slice(ccLength);
+  const groups = [];
+  for (let i = 0; i < rest.length; i += 3) groups.push(rest.slice(i, i + 3));
+  // Avoid a trailing single digit — merge it into the previous group (3 + 1 → 4).
+  if (groups.length > 1 && groups[groups.length - 1].length === 1) {
+    groups.splice(groups.length - 2, 2, groups[groups.length - 2] + groups[groups.length - 1]);
+  }
+  return [`+${countryCode}`, ...groups].join(' ');
+}
+
+/**
+ * Normalise user input towards E.164: strip formatting characters, convert the international
+ * `00` prefix to `+`, and — when a default country code is configured — promote a national
+ * number (no `+`, optional `0` trunk prefix) to international form.
+ */
+function normalisePhone(value, defaultCountryCode) {
+  let v = value.replace(/[\s\-.()]/g, '');
+  if (v.startsWith('00')) v = `+${v.slice(2)}`;
+  if (!v.startsWith('+') && defaultCountryCode) {
+    v = defaultCountryCode + v.replace(/^0/, '');
+  }
+  return v;
+}
+/**
+ * A phone number field storing E.164-normalised values (`+` followed by up to 15 digits). Built
+ * on the core `text` field: input is cleaned of spaces, dashes, dots and parentheses, a leading
+ * `00` becomes `+`, and national numbers are promoted via `defaultCountryCode`. Anything that
+ * still isn't valid E.164 is rejected with a validation error. Empty/null values pass through
+ * untouched. `isIndexed: 'unique'` is supported via the underlying text field.
+ */
+function phone(config = {}) {
+  const {
+    defaultCountryCode,
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return fields.text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'International phone number, e.g. +14155552671',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const value = args.resolvedData[args.fieldKey];
+        if (typeof value !== 'string' || value.length === 0) return value;
+        return normalisePhone(value, defaultCountryCode);
+      },
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !E164.test(value)) {
+          addValidationError('Must be a valid international phone number (E.164, e.g. +14155552671)');
+        }
+      }
+    }
+  });
+}
+
+exports.formatPhone = formatPhone;
+exports.phone = phone;

package/dist/nixxie-cms-fields-phone.esm.js

@@ -0,0 +1,100 @@
+import { text } from '@nixxie-cms/core/fields';
+
+/** E.164: a leading `+`, a country code starting 1–9, and 7–15 digits in total. */
+const E164 = /^\+[1-9]\d{6,14}$/;
+
+/** Country calling codes that are a single digit (NANP and Russia/Kazakhstan). */
+const ONE_DIGIT_CODES = new Set(['1', '7']);
+
+/** The ITU-assigned two-digit country calling codes — anything else is three digits. */
+const TWO_DIGIT_CODES = new Set(['20', '27', '30', '31', '32', '33', '34', '36', '39', '40', '41', '43', '44', '45', '46', '47', '48', '49', '51', '52', '53', '54', '55', '56', '57', '58', '60', '61', '62', '63', '64', '65', '66', '81', '82', '84', '86', '90', '91', '92', '93', '94', '95', '98']);
+
+/**
+ * Best-effort display formatting for an E.164 number: the country code, a space, then the
+ * remaining digits in groups of 3 (the final group absorbs a would-be lone digit, giving 3–4).
+ * E.g. `+14155552671` → `+1 415 555 2671`, `+923001234567` → `+92 300 123 4567`. The country
+ * code length is inferred from a small built-in table, not a full numbering plan, and no
+ * national conventions (area-code parentheses etc.) are applied. Input that is not valid E.164
+ * is returned unchanged.
+ */
+function formatPhone(e164) {
+  if (!E164.test(e164)) return e164;
+  const digits = e164.slice(1);
+  let ccLength = 3;
+  if (ONE_DIGIT_CODES.has(digits[0])) ccLength = 1;else if (TWO_DIGIT_CODES.has(digits.slice(0, 2))) ccLength = 2;
+  const countryCode = digits.slice(0, ccLength);
+  const rest = digits.slice(ccLength);
+  const groups = [];
+  for (let i = 0; i < rest.length; i += 3) groups.push(rest.slice(i, i + 3));
+  // Avoid a trailing single digit — merge it into the previous group (3 + 1 → 4).
+  if (groups.length > 1 && groups[groups.length - 1].length === 1) {
+    groups.splice(groups.length - 2, 2, groups[groups.length - 2] + groups[groups.length - 1]);
+  }
+  return [`+${countryCode}`, ...groups].join(' ');
+}
+
+/**
+ * Normalise user input towards E.164: strip formatting characters, convert the international
+ * `00` prefix to `+`, and — when a default country code is configured — promote a national
+ * number (no `+`, optional `0` trunk prefix) to international form.
+ */
+function normalisePhone(value, defaultCountryCode) {
+  let v = value.replace(/[\s\-.()]/g, '');
+  if (v.startsWith('00')) v = `+${v.slice(2)}`;
+  if (!v.startsWith('+') && defaultCountryCode) {
+    v = defaultCountryCode + v.replace(/^0/, '');
+  }
+  return v;
+}
+/**
+ * A phone number field storing E.164-normalised values (`+` followed by up to 15 digits). Built
+ * on the core `text` field: input is cleaned of spaces, dashes, dots and parentheses, a leading
+ * `00` becomes `+`, and national numbers are promoted via `defaultCountryCode`. Anything that
+ * still isn't valid E.164 is rejected with a validation error. Empty/null values pass through
+ * untouched. `isIndexed: 'unique'` is supported via the underlying text field.
+ */
+function phone(config = {}) {
+  const {
+    defaultCountryCode,
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'International phone number, e.g. +14155552671',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const value = args.resolvedData[args.fieldKey];
+        if (typeof value !== 'string' || value.length === 0) return value;
+        return normalisePhone(value, defaultCountryCode);
+      },
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !E164.test(value)) {
+          addValidationError('Must be a valid international phone number (E.164, e.g. +14155552671)');
+        }
+      }
+    }
+  });
+}
+
+export { formatPhone, phone };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-phone",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-phone.cjs.js",
+  "module": "dist/nixxie-cms-fields-phone.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-phone.cjs.js",
+      "module": "./dist/nixxie-cms-fields-phone.esm.js",
+      "default": "./dist/nixxie-cms-fields-phone.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/fields-phone"
+  }
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import { text } from '@nixxie-cms/core/fields'
+import type { TextFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+/** E.164: a leading `+`, a country code starting 1–9, and 7–15 digits in total. */
+const E164 = /^\+[1-9]\d{6,14}$/
+
+/** Country calling codes that are a single digit (NANP and Russia/Kazakhstan). */
+const ONE_DIGIT_CODES = new Set(['1', '7'])
+
+/** The ITU-assigned two-digit country calling codes — anything else is three digits. */
+const TWO_DIGIT_CODES = new Set([
+  '20', '27', '30', '31', '32', '33', '34', '36', '39', '40', '41', '43', '44', '45', '46', '47',
+  '48', '49', '51', '52', '53', '54', '55', '56', '57', '58', '60', '61', '62', '63', '64', '65',
+  '66', '81', '82', '84', '86', '90', '91', '92', '93', '94', '95', '98',
+])
+
+/**
+ * Best-effort display formatting for an E.164 number: the country code, a space, then the
+ * remaining digits in groups of 3 (the final group absorbs a would-be lone digit, giving 3–4).
+ * E.g. `+14155552671` → `+1 415 555 2671`, `+923001234567` → `+92 300 123 4567`. The country
+ * code length is inferred from a small built-in table, not a full numbering plan, and no
+ * national conventions (area-code parentheses etc.) are applied. Input that is not valid E.164
+ * is returned unchanged.
+ */
+export function formatPhone(e164: string): string {
+  if (!E164.test(e164)) return e164
+  const digits = e164.slice(1)
+  let ccLength = 3
+  if (ONE_DIGIT_CODES.has(digits[0])) ccLength = 1
+  else if (TWO_DIGIT_CODES.has(digits.slice(0, 2))) ccLength = 2
+  const countryCode = digits.slice(0, ccLength)
+  const rest = digits.slice(ccLength)
+  const groups: string[] = []
+  for (let i = 0; i < rest.length; i += 3) groups.push(rest.slice(i, i + 3))
+  // Avoid a trailing single digit — merge it into the previous group (3 + 1 → 4).
+  if (groups.length > 1 && groups[groups.length - 1].length === 1) {
+    groups.splice(groups.length - 2, 2, groups[groups.length - 2] + groups[groups.length - 1])
+  }
+  return [`+${countryCode}`, ...groups].join(' ')
+}
+
+/**
+ * Normalise user input towards E.164: strip formatting characters, convert the international
+ * `00` prefix to `+`, and — when a default country code is configured — promote a national
+ * number (no `+`, optional `0` trunk prefix) to international form.
+ */
+function normalisePhone(value: string, defaultCountryCode?: string): string {
+  let v = value.replace(/[\s\-.()]/g, '')
+  if (v.startsWith('00')) v = `+${v.slice(2)}`
+  if (!v.startsWith('+') && defaultCountryCode) {
+    v = defaultCountryCode + v.replace(/^0/, '')
+  }
+  return v
+}
+
+export type PhoneFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  TextFieldConfig<CollectionTypeInfo>,
+  'validation'
+> & {
+  validation?: {
+    /** Reject saving when no value is present. */
+    isRequired?: boolean
+  }
+  /**
+   * Country calling code (e.g. `'+92'`) prepended when the user enters a national number —
+   * one without a leading `+`. A single leading `0` (the national trunk prefix) is stripped
+   * first, so with `'+92'` both `03001234567` and `300 123 4567` become `+923001234567`.
+   */
+  defaultCountryCode?: string
+}
+
+/**
+ * A phone number field storing E.164-normalised values (`+` followed by up to 15 digits). Built
+ * on the core `text` field: input is cleaned of spaces, dashes, dots and parentheses, a leading
+ * `00` becomes `+`, and national numbers are promoted via `defaultCountryCode`. Anything that
+ * still isn't valid E.164 is rejected with a validation error. Empty/null values pass through
+ * untouched. `isIndexed: 'unique'` is supported via the underlying text field.
+ */
+export function phone<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: PhoneFieldConfig<CollectionTypeInfo> = {}
+): FieldTypeFunc<CollectionTypeInfo> {
+  const { defaultCountryCode, hooks, validation, ...rest } = config
+  const userValidate = hooks?.validate as
+    | ((args: any) => unknown)
+    | { create?: (args: any) => unknown; update?: (args: any) => unknown; delete?: (args: any) => unknown }
+    | undefined
+
+  return text<CollectionTypeInfo>({
+    ...(rest as TextFieldConfig<CollectionTypeInfo>),
+    validation: { isRequired: validation?.isRequired },
+    ui: { description: 'International phone number, e.g. +14155552671', ...rest.ui },
+    hooks: {
+      ...hooks,
+      resolveInput: (args: any) => {
+        const value = args.resolvedData[args.fieldKey]
+        if (typeof value !== 'string' || value.length === 0) return value
+        return normalisePhone(value, defaultCountryCode)
+      },
+      validate: async (args: any) => {
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args)
+        else await userValidate?.[args.operation as 'create' | 'update' | 'delete']?.(args)
+
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (typeof value === 'string' && value.length > 0 && !E164.test(value)) {
+          addValidationError('Must be a valid international phone number (E.164, e.g. +14155552671)')
+        }
+      },
+    },
+  })
+}