@nixxie-cms/fields-address 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,37 @@
+# @nixxie-cms/fields-address
+
+A structured postal-address field for Nixxie CMS. Stores
+`{ line1?, line2?, city?, region?, postalCode?, country?, lat?, lng? }` as JSON.
+
+- Unknown keys are stripped on save.
+- `country` must be an ISO-3166 alpha-2 code and is uppercased on save (`'nl'` → `'NL'`).
+- `lat`/`lng` are validated against `[-90, 90]` / `[-180, 180]` when present.
+
+```ts
+import { address } from '@nixxie-cms/fields-address'
+
+fields: {
+  shippingAddress: address({
+    validation: { isRequired: true, requireCountry: true },
+  }),
+}
+```
+
+`isRequired` accepts an address with at least `line1` + `city`, or any non-empty formatted
+result. `requireCountry` additionally rejects addresses without a country code.
+
+## Helpers
+
+```ts
+import { formatAddress, type AddressValue } from '@nixxie-cms/fields-address'
+
+const value: AddressValue = {
+  line1: 'Herengracht 1',
+  city: 'Amsterdam',
+  postalCode: '1015 BG',
+  country: 'NL',
+}
+
+formatAddress(value) // 'Herengracht 1, Amsterdam, 1015 BG, NL'
+formatAddress(value, { separator: '\n' }) // one part per line
+```

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

@@ -0,0 +1,36 @@
+import type { JsonFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+/** A structured postal address. All parts are optional; `country` is ISO-3166 alpha-2. */
+export type AddressValue = {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+    /** ISO-3166 alpha-2 country code, stored uppercased (e.g. 'NL'). */
+    country?: string;
+    lat?: number;
+    lng?: number;
+};
+export type AddressFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<JsonFieldConfig<CollectionTypeInfo>, 'defaultValue'> & {
+    validation?: {
+        /** Require an address with at least `line1` + `city`, or any non-empty formatted result. */
+        isRequired?: boolean;
+        /** Require a `country` code to be present. */
+        requireCountry?: boolean;
+    };
+};
+/**
+ * Join the non-empty parts of an address in display order
+ * (line1, line2, city, region, postalCode, country).
+ */
+export declare function formatAddress(value: AddressValue | null | undefined, options?: {
+    separator?: string;
+}): string;
+/**
+ * A structured postal-address field storing
+ * `{ line1?, line2?, city?, region?, postalCode?, country?, lat?, lng? }` as JSON.
+ * Unknown keys are stripped, the country code is uppercased, and coordinate ranges are validated.
+ */
+export declare function address<CollectionTypeInfo extends BaseCollectionTypeInfo>(config?: AddressFieldConfig<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,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAMD,MAAM,MAAM,kBAAkB,CAAC,kBAAkB,SAAS,sBAAsB,IAAI,IAAI,CACtF,eAAe,CAAC,kBAAkB,CAAC,EACnC,cAAc,CACf,GAAG;IACF,UAAU,CAAC,EAAE;QACX,4FAA4F;QAC5F,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,8CAA8C;QAC9C,cAAc,CAAC,EAAE,OAAO,CAAA;KACzB,CAAA;CACF,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,MAAM,CAOR;AAMD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,kBAAkB,SAAS,sBAAsB,EACvE,MAAM,GAAE,kBAAkB,CAAC,kBAAkB,CAAM,GAClD,aAAa,CAAC,kBAAkB,CAAC,CAwEnC"}

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

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

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

@@ -0,0 +1,109 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+/** A structured postal address. All parts are optional; `country` is ISO-3166 alpha-2. */
+
+const STRING_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'];
+const NUMBER_KEYS = ['lat', 'lng'];
+const KNOWN_KEYS = [...STRING_KEYS, ...NUMBER_KEYS];
+/**
+ * Join the non-empty parts of an address in display order
+ * (line1, line2, city, region, postalCode, country).
+ */
+function formatAddress(value, options = {}) {
+  var _options$separator;
+  if (!value || typeof value !== 'object') return '';
+  const separator = (_options$separator = options.separator) !== null && _options$separator !== void 0 ? _options$separator : ', ';
+  return STRING_KEYS.map(key => value[key]).filter(part => typeof part === 'string' && part.trim().length > 0).map(part => part.trim()).join(separator);
+}
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A structured postal-address field storing
+ * `{ line1?, line2?, city?, region?, postalCode?, country?, lat?, lng? }` as JSON.
+ * Unknown keys are stripped, the country code is uppercased, and coordinate ranges are validated.
+ */
+function address(config = {}) {
+  const {
+    validation,
+    hooks,
+    ...rest
+  } = config;
+  return fields.json({
+    ...rest,
+    defaultValue: null,
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const value = args.resolvedData[args.fieldKey];
+        if (!isPlainObject(value)) return value;
+        // Strip unknown keys and normalise the country code to uppercase.
+        const cleaned = {};
+        for (const key of KNOWN_KEYS) {
+          if (value[key] !== undefined) cleaned[key] = value[key];
+        }
+        if (typeof cleaned.country === 'string') {
+          cleaned.country = cleaned.country.toUpperCase();
+        }
+        return cleaned;
+      },
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (value === undefined) return;
+        if (value === null) {
+          if (validation !== null && validation !== void 0 && validation.isRequired) addValidationError(`${fieldKey} is required`);
+          return;
+        }
+        if (!isPlainObject(value)) {
+          addValidationError(`${fieldKey} must be an address object`);
+          return;
+        }
+        const v = value;
+        for (const key of STRING_KEYS) {
+          if (v[key] !== undefined && typeof v[key] !== 'string') {
+            addValidationError(`${fieldKey}.${key} must be a string`);
+          }
+        }
+        for (const key of NUMBER_KEYS) {
+          if (v[key] !== undefined && (typeof v[key] !== 'number' || !Number.isFinite(v[key]))) {
+            addValidationError(`${fieldKey}.${key} must be a finite number`);
+          }
+        }
+        if (typeof v.country === 'string' && !/^[A-Z]{2}$/i.test(v.country)) {
+          addValidationError(`${fieldKey}.country must be a 2-letter ISO-3166 alpha-2 code (e.g. 'NL')`);
+        }
+        if (typeof v.lat === 'number' && (v.lat < -90 || v.lat > 90)) {
+          addValidationError(`${fieldKey}.lat must be between -90 and 90`);
+        }
+        if (typeof v.lng === 'number' && (v.lng < -180 || v.lng > 180)) {
+          addValidationError(`${fieldKey}.lng must be between -180 and 180`);
+        }
+        if (validation !== null && validation !== void 0 && validation.requireCountry && !(typeof v.country === 'string' && v.country.trim())) {
+          addValidationError(`${fieldKey}.country is required`);
+        }
+        if (validation !== null && validation !== void 0 && validation.isRequired) {
+          var _v$line, _v$city;
+          const hasLine1AndCity = Boolean((_v$line = v.line1) === null || _v$line === void 0 ? void 0 : _v$line.trim()) && Boolean((_v$city = v.city) === null || _v$city === void 0 ? void 0 : _v$city.trim());
+          if (!hasLine1AndCity && formatAddress(v).length === 0) {
+            addValidationError(`${fieldKey} must have at least line1 and city, or some content`);
+          }
+        }
+      }
+    }
+  });
+}
+
+exports.address = address;
+exports.formatAddress = formatAddress;

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

@@ -0,0 +1,104 @@
+import { json } from '@nixxie-cms/core/fields';
+
+/** A structured postal address. All parts are optional; `country` is ISO-3166 alpha-2. */
+
+const STRING_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'];
+const NUMBER_KEYS = ['lat', 'lng'];
+const KNOWN_KEYS = [...STRING_KEYS, ...NUMBER_KEYS];
+/**
+ * Join the non-empty parts of an address in display order
+ * (line1, line2, city, region, postalCode, country).
+ */
+function formatAddress(value, options = {}) {
+  var _options$separator;
+  if (!value || typeof value !== 'object') return '';
+  const separator = (_options$separator = options.separator) !== null && _options$separator !== void 0 ? _options$separator : ', ';
+  return STRING_KEYS.map(key => value[key]).filter(part => typeof part === 'string' && part.trim().length > 0).map(part => part.trim()).join(separator);
+}
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A structured postal-address field storing
+ * `{ line1?, line2?, city?, region?, postalCode?, country?, lat?, lng? }` as JSON.
+ * Unknown keys are stripped, the country code is uppercased, and coordinate ranges are validated.
+ */
+function address(config = {}) {
+  const {
+    validation,
+    hooks,
+    ...rest
+  } = config;
+  return json({
+    ...rest,
+    defaultValue: null,
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const value = args.resolvedData[args.fieldKey];
+        if (!isPlainObject(value)) return value;
+        // Strip unknown keys and normalise the country code to uppercase.
+        const cleaned = {};
+        for (const key of KNOWN_KEYS) {
+          if (value[key] !== undefined) cleaned[key] = value[key];
+        }
+        if (typeof cleaned.country === 'string') {
+          cleaned.country = cleaned.country.toUpperCase();
+        }
+        return cleaned;
+      },
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (value === undefined) return;
+        if (value === null) {
+          if (validation !== null && validation !== void 0 && validation.isRequired) addValidationError(`${fieldKey} is required`);
+          return;
+        }
+        if (!isPlainObject(value)) {
+          addValidationError(`${fieldKey} must be an address object`);
+          return;
+        }
+        const v = value;
+        for (const key of STRING_KEYS) {
+          if (v[key] !== undefined && typeof v[key] !== 'string') {
+            addValidationError(`${fieldKey}.${key} must be a string`);
+          }
+        }
+        for (const key of NUMBER_KEYS) {
+          if (v[key] !== undefined && (typeof v[key] !== 'number' || !Number.isFinite(v[key]))) {
+            addValidationError(`${fieldKey}.${key} must be a finite number`);
+          }
+        }
+        if (typeof v.country === 'string' && !/^[A-Z]{2}$/i.test(v.country)) {
+          addValidationError(`${fieldKey}.country must be a 2-letter ISO-3166 alpha-2 code (e.g. 'NL')`);
+        }
+        if (typeof v.lat === 'number' && (v.lat < -90 || v.lat > 90)) {
+          addValidationError(`${fieldKey}.lat must be between -90 and 90`);
+        }
+        if (typeof v.lng === 'number' && (v.lng < -180 || v.lng > 180)) {
+          addValidationError(`${fieldKey}.lng must be between -180 and 180`);
+        }
+        if (validation !== null && validation !== void 0 && validation.requireCountry && !(typeof v.country === 'string' && v.country.trim())) {
+          addValidationError(`${fieldKey}.country is required`);
+        }
+        if (validation !== null && validation !== void 0 && validation.isRequired) {
+          var _v$line, _v$city;
+          const hasLine1AndCity = Boolean((_v$line = v.line1) === null || _v$line === void 0 ? void 0 : _v$line.trim()) && Boolean((_v$city = v.city) === null || _v$city === void 0 ? void 0 : _v$city.trim());
+          if (!hasLine1AndCity && formatAddress(v).length === 0) {
+            addValidationError(`${fieldKey} must have at least line1 and city, or some content`);
+          }
+        }
+      }
+    }
+  });
+}
+
+export { address, formatAddress };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-address",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-address.cjs.js",
+  "module": "dist/nixxie-cms-fields-address.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-address.cjs.js",
+      "module": "./dist/nixxie-cms-fields-address.esm.js",
+      "default": "./dist/nixxie-cms-fields-address.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-address"
+  }
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+import { json } from '@nixxie-cms/core/fields'
+import type { JsonFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+/** A structured postal address. All parts are optional; `country` is ISO-3166 alpha-2. */
+export type AddressValue = {
+  line1?: string
+  line2?: string
+  city?: string
+  region?: string
+  postalCode?: string
+  /** ISO-3166 alpha-2 country code, stored uppercased (e.g. 'NL'). */
+  country?: string
+  lat?: number
+  lng?: number
+}
+
+const STRING_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'] as const
+const NUMBER_KEYS = ['lat', 'lng'] as const
+const KNOWN_KEYS: readonly string[] = [...STRING_KEYS, ...NUMBER_KEYS]
+
+export type AddressFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  JsonFieldConfig<CollectionTypeInfo>,
+  'defaultValue'
+> & {
+  validation?: {
+    /** Require an address with at least `line1` + `city`, or any non-empty formatted result. */
+    isRequired?: boolean
+    /** Require a `country` code to be present. */
+    requireCountry?: boolean
+  }
+}
+
+/**
+ * Join the non-empty parts of an address in display order
+ * (line1, line2, city, region, postalCode, country).
+ */
+export function formatAddress(
+  value: AddressValue | null | undefined,
+  options: { separator?: string } = {}
+): string {
+  if (!value || typeof value !== 'object') return ''
+  const separator = options.separator ?? ', '
+  return STRING_KEYS.map(key => value[key])
+    .filter((part): part is string => typeof part === 'string' && part.trim().length > 0)
+    .map(part => part.trim())
+    .join(separator)
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+/**
+ * A structured postal-address field storing
+ * `{ line1?, line2?, city?, region?, postalCode?, country?, lat?, lng? }` as JSON.
+ * Unknown keys are stripped, the country code is uppercased, and coordinate ranges are validated.
+ */
+export function address<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: AddressFieldConfig<CollectionTypeInfo> = {}
+): FieldTypeFunc<CollectionTypeInfo> {
+  const { validation, hooks, ...rest } = config
+
+  return json<CollectionTypeInfo>({
+    ...(rest as JsonFieldConfig<CollectionTypeInfo>),
+    defaultValue: null,
+    hooks: {
+      ...hooks,
+      resolveInput: (args: any) => {
+        const value = args.resolvedData[args.fieldKey]
+        if (!isPlainObject(value)) return value
+        // Strip unknown keys and normalise the country code to uppercase.
+        const cleaned: Record<string, unknown> = {}
+        for (const key of KNOWN_KEYS) {
+          if (value[key] !== undefined) cleaned[key] = value[key]
+        }
+        if (typeof cleaned.country === 'string') {
+          cleaned.country = cleaned.country.toUpperCase()
+        }
+        return cleaned
+      },
+      validate: (args: any) => {
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (value === undefined) return
+        if (value === null) {
+          if (validation?.isRequired) addValidationError(`${fieldKey} is required`)
+          return
+        }
+        if (!isPlainObject(value)) {
+          addValidationError(`${fieldKey} must be an address object`)
+          return
+        }
+        const v = value as AddressValue
+
+        for (const key of STRING_KEYS) {
+          if (v[key] !== undefined && typeof v[key] !== 'string') {
+            addValidationError(`${fieldKey}.${key} must be a string`)
+          }
+        }
+        for (const key of NUMBER_KEYS) {
+          if (v[key] !== undefined && (typeof v[key] !== 'number' || !Number.isFinite(v[key]))) {
+            addValidationError(`${fieldKey}.${key} must be a finite number`)
+          }
+        }
+
+        if (typeof v.country === 'string' && !/^[A-Z]{2}$/i.test(v.country)) {
+          addValidationError(
+            `${fieldKey}.country must be a 2-letter ISO-3166 alpha-2 code (e.g. 'NL')`
+          )
+        }
+        if (typeof v.lat === 'number' && (v.lat < -90 || v.lat > 90)) {
+          addValidationError(`${fieldKey}.lat must be between -90 and 90`)
+        }
+        if (typeof v.lng === 'number' && (v.lng < -180 || v.lng > 180)) {
+          addValidationError(`${fieldKey}.lng must be between -180 and 180`)
+        }
+
+        if (validation?.requireCountry && !(typeof v.country === 'string' && v.country.trim())) {
+          addValidationError(`${fieldKey}.country is required`)
+        }
+
+        if (validation?.isRequired) {
+          const hasLine1AndCity = Boolean(v.line1?.trim()) && Boolean(v.city?.trim())
+          if (!hasLine1AndCity && formatAddress(v).length === 0) {
+            addValidationError(`${fieldKey} must have at least line1 and city, or some content`)
+          }
+        }
+      },
+    },
+  })
+}