@questpie/admin 1.1.1 → 3.0.0

package/dist/client/utils/build-field-definitions-from-schema.mjs

@@ -0,0 +1,259 @@
+import { formatLabel } from "../lib/utils.mjs";
+import { configureField } from "../builder/field/field.mjs";
+
+//#region src/client/utils/build-field-definitions-from-schema.ts
+/**
+* Build admin field definitions from server collection schema.
+*
+* Maps server field metadata to admin FieldDefinition objects:
+* - Uses `metadata.type` to look up field in registry
+* - Applies `metadata.meta.admin` overrides
+* - Handles relation type mapping (belongsTo -> single, hasMany -> multiple)
+*
+* @param schema - Collection schema from server introspection
+* @param registry - Field registry from admin config (admin.getFields())
+* @param options - Optional configuration
+*
+* @example
+* ```tsx
+* // In a component with admin context
+* const admin = useAdminStore(selectAdmin);
+* const { data: schema } = useCollectionSchema("posts");
+* const fields = buildFieldDefinitionsFromSchema(
+*   schema,
+*   admin.getFields(),
+* );
+* ```
+*/
+/**
+* Build field definitions from raw field metadata.
+* Works with metadata from any source (collection schema, global schema, block fields).
+*
+* @param fields - Record of field name to field metadata
+* @param registry - Field registry from admin config
+*
+* @example
+* ```tsx
+* const admin = useAdminStore(selectAdmin);
+* const fields = buildFieldDefinitionsFromMetadata(
+*   blockDef.fields,
+*   admin.getFields(),
+* );
+* ```
+*/
+function buildFieldDefinitionsFromMetadata(fields, registry) {
+	if (!fields) return {};
+	const result = {};
+	for (const [fieldName, fieldSchema] of Object.entries(fields)) {
+		const metadata = fieldSchema.metadata ?? fieldSchema;
+		const fieldType = resolveFieldType(metadata);
+		const fieldBuilder = registry[fieldType];
+		if (!fieldBuilder) {
+			if (process.env.NODE_ENV !== "production") console.warn(`[buildFieldDefinitionsFromMetadata] Field "${fieldName}" has type "${fieldType}" which is not registered in the field registry. Available types: ${Object.keys(registry).join(", ")}`);
+			continue;
+		}
+		result[fieldName] = configureField(fieldBuilder, buildFieldConfig(fieldSchema.name ?? fieldName, metadata, {}, registry, fieldType));
+	}
+	return result;
+}
+function buildFieldDefinitionsFromSchema(schema, registry, options = {}) {
+	if (!schema) return {};
+	const relations = "relations" in schema ? schema.relations : {};
+	const result = {};
+	for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+		if (options.exclude?.includes(fieldName)) continue;
+		if (options.include && !options.include.includes(fieldName)) continue;
+		if (isSystemField(fieldName)) continue;
+		const fieldDef = buildFieldDefinition(fieldName, fieldSchema, relations, registry, options.overrides?.[fieldName]);
+		if (fieldDef) result[fieldName] = fieldDef;
+	}
+	return result;
+}
+/**
+* Build a single field definition from schema
+*/
+function buildFieldDefinition(fieldName, fieldSchema, relations, registry, overrides) {
+	const { metadata } = fieldSchema;
+	const fieldType = resolveFieldType(metadata);
+	const fieldBuilder = registry[fieldType];
+	if (!fieldBuilder) return null;
+	const config = buildFieldConfig(fieldName, metadata, relations, registry, fieldType);
+	const adminConfig = metadata.meta?.admin;
+	if (adminConfig) applyAdminConfig(config, adminConfig);
+	if (overrides) Object.assign(config, overrides);
+	return configureField(fieldBuilder, config);
+}
+/**
+* Build field config from metadata
+*/
+function buildFieldConfig(fieldName, metadata, relations, registry, fieldType) {
+	const config = {
+		label: metadata.label ?? formatLabel(fieldName),
+		description: metadata.description,
+		required: metadata.required,
+		localized: metadata.localized,
+		readOnly: metadata.readOnly
+	};
+	if (metadata.validation) Object.assign(config, metadata.validation);
+	if (isSelectMetadata(metadata)) applySelectConfig(config, metadata);
+	else if (isRelationMetadata(metadata)) if (fieldType === "upload") applyUploadConfig(config, metadata, relations[fieldName]);
+	else applyRelationConfig(config, metadata, relations[fieldName]);
+	else if (isNestedMetadata(metadata)) applyNestedConfig(config, metadata, relations, registry);
+	else if (metadata.type === "richText") applyRichTextConfig(config, metadata);
+	applyExtraMetadata(config, metadata);
+	return config;
+}
+function isSelectMetadata(m) {
+	return m.type === "select";
+}
+function isRelationMetadata(m) {
+	return m.type === "relation";
+}
+function isNestedMetadata(m) {
+	return m.type === "object" || m.type === "array" || m.type === "blocks";
+}
+/**
+* Apply select field config
+*/
+function applySelectConfig(config, metadata) {
+	config.options = metadata.options.map((opt) => ({
+		value: opt.value,
+		label: opt.label ?? String(opt.value)
+	}));
+	if (metadata.multiple !== void 0) config.multiple = metadata.multiple;
+}
+/**
+* Apply relation field config
+*/
+function applyRelationConfig(config, metadata, relationSchema) {
+	const isSingle = ["belongsTo", "morphTo"].includes(metadata.relationType);
+	config.targetCollection = metadata.targetCollection;
+	config.type = isSingle ? "single" : "multiple";
+	config.relationType = metadata.relationType;
+	if (metadata.through ?? relationSchema?.through) config.through = metadata.through ?? relationSchema?.through;
+	if (metadata.foreignKey ?? relationSchema?.foreignKey) config.foreignKey = metadata.foreignKey ?? relationSchema?.foreignKey;
+}
+function applyUploadConfig(config, metadata, relationSchema) {
+	const isMultiple = [
+		"hasMany",
+		"manyToMany",
+		"multiple",
+		"morphMany"
+	].includes(metadata.relationType);
+	config.to = metadata.targetCollection;
+	config.multiple = isMultiple;
+	if (metadata.through ?? relationSchema?.through) config.through = metadata.through ?? relationSchema?.through;
+	if (metadata.foreignKey ?? relationSchema?.foreignKey) config.foreignKey = metadata.foreignKey ?? relationSchema?.foreignKey;
+}
+function applyNestedConfig(config, metadata, relations, registry) {
+	if (!metadata.nestedFields) return;
+	if (metadata.type === "object") {
+		const nestedDefs = buildNestedFieldDefinitions(metadata.nestedFields, relations, registry);
+		config.fields = () => nestedDefs;
+		if (metadata.form) config.form = metadata.form;
+		return;
+	}
+	if (metadata.type === "array") {
+		const itemMetadata = metadata.nestedFields.item;
+		if (!itemMetadata) return;
+		if (itemMetadata.type === "object" && itemMetadata.nestedFields) {
+			const itemFields = buildNestedFieldDefinitions(itemMetadata.nestedFields ?? {}, relations, registry);
+			config.item = () => itemFields;
+			return;
+		}
+		const itemType = mapArrayItemType(itemMetadata.type);
+		if (itemType) {
+			config.itemType = itemType;
+			if (itemMetadata.type === "select") applySelectConfig(config, itemMetadata);
+		}
+	}
+	if (metadata.type === "blocks") {
+		const blocksMetadata = metadata;
+		if (blocksMetadata.allowedBlocks) config.allowedBlocks = blocksMetadata.allowedBlocks;
+		if (blocksMetadata.minBlocks !== void 0) config.minBlocks = blocksMetadata.minBlocks;
+		if (blocksMetadata.maxBlocks !== void 0) config.maxBlocks = blocksMetadata.maxBlocks;
+	}
+}
+function applyExtraMetadata(config, metadata) {
+	const reservedKeys = new Set([
+		"type",
+		"label",
+		"description",
+		"required",
+		"localized",
+		"readOnly",
+		"writeOnly",
+		"validation",
+		"meta",
+		"nestedFields",
+		"features"
+	]);
+	for (const [key, value] of Object.entries(metadata)) {
+		if (reservedKeys.has(key)) continue;
+		if (key.startsWith("_")) continue;
+		if (value === void 0) continue;
+		config[key] = value;
+	}
+}
+function applyRichTextConfig(config, metadata) {
+	if (metadata.maxCharacters !== void 0) {
+		config.maxCharacters = metadata.maxCharacters;
+		config.showCharacterCount = true;
+	}
+	if (metadata.placeholder !== void 0) config.placeholder = metadata.placeholder;
+	if (metadata.allowImages !== void 0) config.enableImages = metadata.allowImages;
+	if (metadata.imageCollection !== void 0) config.imageCollection = metadata.imageCollection;
+}
+function buildNestedFieldDefinitions(nestedFields, relations, registry) {
+	const result = {};
+	for (const [nestedName, nestedMetadata] of Object.entries(nestedFields)) {
+		const fieldType = resolveFieldType(nestedMetadata);
+		const fieldBuilder = registry[fieldType];
+		if (!fieldBuilder) continue;
+		const config = buildFieldConfig(nestedName, nestedMetadata, relations, registry, fieldType);
+		const adminConfig = nestedMetadata.meta?.admin;
+		if (adminConfig) applyAdminConfig(config, adminConfig);
+		result[nestedName] = configureField(fieldBuilder, config);
+	}
+	return result;
+}
+function resolveFieldType(metadata) {
+	if (metadata.type === "relation") {
+		if (metadata.isUpload) return "upload";
+	}
+	return metadata.type;
+}
+function mapArrayItemType(type) {
+	return new Set([
+		"text",
+		"number",
+		"email",
+		"textarea",
+		"select"
+	]).has(type) ? type : null;
+}
+/**
+* Apply admin config overrides from server meta.admin
+*
+* Since each field type has its own admin meta with only valid properties,
+* we simply copy all defined properties from adminConfig to config.
+*/
+function applyAdminConfig(config, adminConfig) {
+	for (const [key, value] of Object.entries(adminConfig)) if (value !== void 0) config[key] = value;
+}
+/**
+* Check if a field is a system field that shouldn't be in forms
+*/
+function isSystemField(fieldName) {
+	return [
+		"id",
+		"createdAt",
+		"updatedAt",
+		"deletedAt",
+		"_title",
+		"_locale"
+	].includes(fieldName);
+}
+
+//#endregion
+export { buildFieldDefinitionsFromMetadata, buildFieldDefinitionsFromSchema };

package/dist/client/utils/dependency-tracker.mjs

@@ -0,0 +1,61 @@
+//#region src/client/utils/dependency-tracker.ts
+/**
+* Track value dependencies accessed by a resolver function.
+*/
+function trackDependencies(values, resolver) {
+	const deps = /* @__PURE__ */ new Set();
+	const createProxy = (target, prefix = "") => {
+		if (!target || typeof target !== "object") return target;
+		return new Proxy(target, {
+			get(currentTarget, prop) {
+				if (typeof prop === "symbol" || prop === "then") return Reflect.get(currentTarget, prop);
+				const path = prefix ? `${prefix}.${prop}` : prop;
+				deps.add(path);
+				const nextValue = Reflect.get(currentTarget, prop);
+				if (nextValue && typeof nextValue === "object") return createProxy(nextValue, path);
+				return nextValue;
+			},
+			has(currentTarget, prop) {
+				if (typeof prop === "symbol") return Reflect.has(currentTarget, prop);
+				const path = prefix ? `${prefix}.${prop}` : prop;
+				deps.add(path);
+				return Reflect.has(currentTarget, prop);
+			},
+			ownKeys(currentTarget) {
+				const keys = Reflect.ownKeys(currentTarget);
+				for (const key of keys) {
+					if (typeof key !== "string") continue;
+					const path = prefix ? `${prefix}.${key}` : key;
+					deps.add(path);
+				}
+				return keys;
+			},
+			getOwnPropertyDescriptor(currentTarget, prop) {
+				return Reflect.getOwnPropertyDescriptor(currentTarget, prop);
+			}
+		});
+	};
+	try {
+		return {
+			result: resolver(createProxy(values)),
+			deps: [...deps],
+			error: null
+		};
+	} catch (error) {
+		return {
+			result: void 0,
+			deps: [...deps],
+			error: error instanceof Error ? error : new Error(String(error))
+		};
+	}
+}
+/**
+* Scope dependency paths for nested field prefixes.
+*/
+function scopeDependencies(deps, fieldPrefix) {
+	if (!fieldPrefix) return deps.filter((dep) => dep.length > 0 && !dep.startsWith("$"));
+	return deps.filter((dep) => dep.length > 0 && !dep.startsWith("$")).map((dep) => `${fieldPrefix}.${dep}`);
+}
+
+//#endregion
+export { scopeDependencies, trackDependencies };

package/dist/client/utils/detect-relations.mjs

@@ -0,0 +1,45 @@
+//#region src/client/utils/detect-relations.ts
+function isMultiRelationType(relationType) {
+	return relationType === "hasMany" || relationType === "manyToMany" || relationType === "multiple" || relationType === "morphMany";
+}
+/**
+* Auto-detect M:N relation fields from config and build `with` clause.
+*
+* M:N relations need to be explicitly loaded when fetching items for editing,
+* as they are stored in junction tables and not included by default.
+*
+* @param config - Collection configuration with fields
+* @returns Object mapping relation field names to `true` for M:N relations
+*
+* @example
+* ```tsx
+* const withRelations = detectManyToManyRelations({ fields: config?.fields });
+*
+* // Use with query
+* const { data } = useCollectionItem(collection, id, {
+*   with: withRelations,
+* });
+* ```
+*/
+function detectManyToManyRelations(config) {
+	const withRelations = {};
+	if (config.schema?.fields) for (const [fieldName, fieldSchema] of Object.entries(config.schema.fields)) {
+		const metadata = fieldSchema?.metadata;
+		if (metadata?.type !== "relation") continue;
+		if (isMultiRelationType(metadata.relationType)) withRelations[fieldName] = true;
+	}
+	if (config?.fields) for (const [fieldName, fieldConfig] of Object.entries(config.fields)) {
+		const fc = fieldConfig;
+		if (fc?.name === "relation" && fc?.["~options"]?.type === "multiple") withRelations[fieldName] = true;
+	}
+	return withRelations;
+}
+/**
+* Check if there are any M:N relations to include
+*/
+function hasManyToManyRelations(withRelations) {
+	return Object.keys(withRelations).length > 0;
+}
+
+//#endregion
+export { detectManyToManyRelations, hasManyToManyRelations };

package/dist/client/utils/locale-to-flag.d.mts

@@ -0,0 +1,119 @@
+//#region src/client/utils/locale-to-flag.d.ts
+/**
+ * Locale to Flag Utility
+ *
+ * Converts locale codes to country codes for flag display.
+ * Uses flagcdn.com for PNG flags via CDN (no dependencies).
+ *
+ * ## Features
+ *
+ * - **Smart mapping**: Automatically maps locale codes to country codes (sk → SK, en → GB, en-US → US)
+ * - **Custom overrides**: Support for custom country codes via `flagCountryCode` in locale config
+ * - **Lightweight**: No dependencies, uses CDN for flags
+ * - **Fallback support**: Gracefully handles unknown locale codes
+ *
+ * ## Usage
+ *
+ * ### Basic Usage
+ *
+ * ```tsx
+ * import { getFlagUrl } from "@questpie/admin/client";
+ *
+ * function LocaleBadge({ locale }: { locale: string }) {
+ *   return (
+ *     <div>
+ *       <img src={getFlagUrl(locale, 20)} alt={locale} />
+ *       {locale}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ### Custom Country Code Mapping
+ *
+ * If the default mapping doesn't fit your needs, you can provide custom mapping:
+ *
+ * ```tsx
+ * // Show US flag for English instead of UK
+ * const flagUrl = getFlagUrl("en", 20, { en: "us" });
+ * ```
+ *
+ * ### In QUESTPIE Configuration
+ *
+ * The best way to customize flag mapping is in your app locale config:
+ *
+ * ```ts
+ * // questpie/server/locale.ts (file convention)
+ * import { locale } from "#questpie/factories";
+ *
+ * export default locale({
+ *   locales: [
+ *     {
+ *       code: "en",
+ *       label: "English",
+ *       flagCountryCode: "us", // Show US flag instead of UK
+ *     },
+ *     { code: "sk", label: "Slovenčina" },
+ *   ],
+ *   defaultLocale: "en",
+ * });
+ * ```
+ *
+ * The `flagCountryCode` will be automatically used by `LocaleSwitcher` and other locale UI components.
+ */
+interface FlagConfig {
+  /** Country code (ISO 3166-1 alpha-2) */
+  countryCode: string;
+  /** Alt text for accessibility */
+  alt: string;
+}
+/**
+ * Get country code from locale code.
+ *
+ * @param locale - Locale code (e.g., "en", "sk", "en-US")
+ * @param customMapping - Optional custom locale-to-country mapping (overrides defaults)
+ * @returns Country code (lowercase, e.g., "gb", "sk", "us")
+ *
+ * @example
+ * ```ts
+ * getCountryCode("en") // "gb" (default)
+ * getCountryCode("en-US") // "us"
+ * getCountryCode("sk") // "sk"
+ * getCountryCode("en", { en: "us" }) // "us" (custom mapping)
+ * getCountryCode("unknown") // "unknown" (fallback to input)
+ * ```
+ */
+declare function getCountryCode(locale: string, customMapping?: Record<string, string>): string;
+/**
+ * Get flag configuration for a locale.
+ *
+ * @param locale - Locale code
+ * @param customMapping - Optional custom locale-to-country mapping
+ * @returns Flag configuration with country code and alt text
+ *
+ * @example
+ * ```ts
+ * getFlagConfig("sk") // { countryCode: "sk", alt: "Slovakia" }
+ * getFlagConfig("en-US") // { countryCode: "us", alt: "United States" }
+ * getFlagConfig("en", { en: "us" }) // { countryCode: "us", alt: "EN" }
+ * ```
+ */
+declare function getFlagConfig(locale: string, customMapping?: Record<string, string>): FlagConfig;
+/**
+ * Get flag image URL from flagcdn.com.
+ *
+ * @param locale - Locale code
+ * @param size - Width in pixels (default: 20)
+ * @param customMapping - Optional custom locale-to-country mapping
+ * @returns URL to flag PNG
+ *
+ * @example
+ * ```tsx
+ * <img src={getFlagUrl("sk")} alt="SK" />
+ * <img src={getFlagUrl("en-US", 40)} alt="EN-US" />
+ * <img src={getFlagUrl("en", 20, { en: "us" })} alt="EN" />
+ * ```
+ */
+declare function getFlagUrl(locale: string, size?: number, customMapping?: Record<string, string>): string;
+//#endregion
+export { FlagConfig, getCountryCode, getFlagConfig, getFlagUrl };

package/dist/client/utils/locale-to-flag.mjs

@@ -0,0 +1,129 @@
+//#region src/client/utils/locale-to-flag.ts
+/**
+* Maps locale codes to country codes.
+* Handles both simple codes (en, sk) and region-specific (en-US, en-GB).
+*/
+const LOCALE_TO_COUNTRY = {
+	en: "gb",
+	"en-US": "us",
+	"en-GB": "gb",
+	"en-CA": "ca",
+	"en-AU": "au",
+	"en-NZ": "nz",
+	"en-IE": "ie",
+	sk: "sk",
+	cs: "cz",
+	de: "de",
+	"de-AT": "at",
+	"de-CH": "ch",
+	fr: "fr",
+	"fr-CA": "ca",
+	"fr-CH": "ch",
+	es: "es",
+	"es-MX": "mx",
+	"es-AR": "ar",
+	it: "it",
+	pt: "pt",
+	"pt-BR": "br",
+	nl: "nl",
+	pl: "pl",
+	ru: "ru",
+	uk: "ua",
+	tr: "tr",
+	sv: "se",
+	no: "no",
+	da: "dk",
+	fi: "fi",
+	hu: "hu",
+	ro: "ro",
+	bg: "bg",
+	hr: "hr",
+	sr: "rs",
+	sl: "si",
+	et: "ee",
+	lv: "lv",
+	lt: "lt",
+	zh: "cn",
+	"zh-CN": "cn",
+	"zh-TW": "tw",
+	"zh-HK": "hk",
+	ja: "jp",
+	ko: "kr",
+	th: "th",
+	vi: "vn",
+	id: "id",
+	ms: "my",
+	hi: "in",
+	ar: "sa",
+	he: "il",
+	el: "gr",
+	fa: "ir",
+	ur: "pk"
+};
+/**
+* Get country code from locale code.
+*
+* @param locale - Locale code (e.g., "en", "sk", "en-US")
+* @param customMapping - Optional custom locale-to-country mapping (overrides defaults)
+* @returns Country code (lowercase, e.g., "gb", "sk", "us")
+*
+* @example
+* ```ts
+* getCountryCode("en") // "gb" (default)
+* getCountryCode("en-US") // "us"
+* getCountryCode("sk") // "sk"
+* getCountryCode("en", { en: "us" }) // "us" (custom mapping)
+* getCountryCode("unknown") // "unknown" (fallback to input)
+* ```
+*/
+function getCountryCode(locale, customMapping) {
+	const normalized = locale.toLowerCase();
+	if (customMapping?.[normalized]) return customMapping[normalized].toLowerCase();
+	if (LOCALE_TO_COUNTRY[normalized]) return LOCALE_TO_COUNTRY[normalized];
+	const baseCode = normalized.split("-")[0];
+	if (baseCode && customMapping?.[baseCode]) return customMapping[baseCode].toLowerCase();
+	if (baseCode && LOCALE_TO_COUNTRY[baseCode]) return LOCALE_TO_COUNTRY[baseCode];
+	return normalized;
+}
+/**
+* Get flag configuration for a locale.
+*
+* @param locale - Locale code
+* @param customMapping - Optional custom locale-to-country mapping
+* @returns Flag configuration with country code and alt text
+*
+* @example
+* ```ts
+* getFlagConfig("sk") // { countryCode: "sk", alt: "Slovakia" }
+* getFlagConfig("en-US") // { countryCode: "us", alt: "United States" }
+* getFlagConfig("en", { en: "us" }) // { countryCode: "us", alt: "EN" }
+* ```
+*/
+function getFlagConfig(locale, customMapping) {
+	return {
+		countryCode: getCountryCode(locale, customMapping),
+		alt: locale.toUpperCase()
+	};
+}
+/**
+* Get flag image URL from flagcdn.com.
+*
+* @param locale - Locale code
+* @param size - Width in pixels (default: 20)
+* @param customMapping - Optional custom locale-to-country mapping
+* @returns URL to flag PNG
+*
+* @example
+* ```tsx
+* <img src={getFlagUrl("sk")} alt="SK" />
+* <img src={getFlagUrl("en-US", 40)} alt="EN-US" />
+* <img src={getFlagUrl("en", 20, { en: "us" })} alt="EN" />
+* ```
+*/
+function getFlagUrl(locale, size = 24, customMapping) {
+	const { countryCode } = getFlagConfig(locale, customMapping);
+	return `https://flagcdn.com/h${size}/${countryCode}.png`;
+}
+
+//#endregion
+export { getCountryCode, getFlagConfig, getFlagUrl };