@407dev/field-types 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @407dev/field-types
+
+## Purpose
+- Registry and built-in field type definitions for scalar and semantic CMS field types (`text`, `number`, `toggle`, `select`, `image`, `video`, `richtext`, `media.videoList`, `geo.area`, `address`, `address.list`).
+- Validates field constraints, default values, safe URI schemes, and ProseMirror rich text documents against node/mark whitelists.
+- Provides normalization repairs (e.g. polygon ring closure) for editor commit workflows.
+
+## Surface
+- `registry.ts`: `registerFieldType()`, `getFieldType()`, `hasFieldType()`, `listFieldTypeIds()`, `listFieldTypes()`, `fieldTypeAliases()`, `resolveTypeAlias()`, `normalizeFieldValue()`, `unknownTypeIds()`, `validateFieldValue()`, `resetRegistry()`, `registerBaseTypes()`.
+- `url.ts`: `stripUrlControlChars()`, `isSafeMediaSrc()`, `isSafeActionHref()`.
+- `richtext.ts`: `validateProseMirrorDoc()`, `isValidLinkHref()`, `isValidImageSrc()`, `RichTextConstraints`.
+- `types.ts`: `FieldTypeDefinition`, `FieldValidationError`, `FieldValidationResult`.
+- Built-in types: `textType`, `numberType`, `toggleType`, `selectType`, `imageType`, `videoType`, `richtextType`, `videoListType`, `geoAreaType`, `addressType`, `addressListType`.
+
+## Patterns
+- Pure validation functions that never throw on invalid input, returning `{ valid: boolean; errors?: FieldValidationError[] }`.
+- Safe URI sanitizer strips Unicode and ASCII control characters (`\x00`–`\x1F`, `\x7F`–`\x9F`) before evaluating scheme allowlist.
+- In-house $O(n^2)$ orientation-based self-intersection test for polygon rings without external geometry libraries.
+
+## Integrations
+- Consumed by `apps/api` for manifest field type verification and validation during entry/field writes.
+- Consumed by `packages/astro` to dynamically generate synchronous field helper methods and render components.
+- Consumed by `packages/cli` during AST extraction and manifest type checking.
+- Consumed by `apps/web` for field popovers, group modal normalization, and widget form validation.
+
+## Constraints
+- Published package: builds to ESM and `.d.ts` via `tsup`.
+- Must not depend on `apps/*` or Astro runtime packages.
+- Zero external runtime dependencies: no Turf.js, no validator packages.
+
+## Gotchas
+- `normalize?(value)` is called exclusively by the editor before save; `apps/api` stores values as received.
+- `geo.area` self-intersection algorithm validates that exterior boundary edges do not self-intersect; hole-inside-shell containment validation is explicitly out of scope.
+

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+interface FieldValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+}
+type FieldValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    errors: FieldValidationError[];
+};
+interface FieldTypeDefinition<T = unknown> {
+    id: string;
+    aliases?: string[];
+    constraintsSchema: object;
+    defaultValue?: T;
+    renderHint?: {
+        tag?: string;
+    };
+    normalize?(value: unknown, constraints?: Record<string, unknown>): unknown;
+    validate(value: unknown, constraints?: Record<string, unknown>): FieldValidationResult;
+}
+
+/**
+ * Registers a new or custom field type.
+ */
+declare function registerFieldType(def: FieldTypeDefinition): void;
+/**
+ * Retrieves a field type definition by ID.
+ */
+declare function getFieldType(id: string): FieldTypeDefinition | undefined;
+/**
+ * Checks whether a field type ID is registered.
+ */
+declare function hasFieldType(id: string): boolean;
+/**
+ * Returns all registered field type definitions.
+ */
+declare function listFieldTypes(): FieldTypeDefinition[];
+/**
+ * Returns all registered field type IDs.
+ */
+declare function listFieldTypeIds(): string[];
+/**
+ * Returns a map of all registered aliases to their canonical field type IDs.
+ */
+declare function fieldTypeAliases(): Map<string, string>;
+/**
+ * Resolves a field method/alias name to its canonical field type ID.
+ */
+declare function resolveTypeAlias(name: string): string;
+/**
+ * Normalizes a field value using the field type's normalize hook if defined.
+ * Never throws — returns input value unchanged if no normalize hook or on error.
+ */
+declare function normalizeFieldValue(typeId: string, value: unknown, constraints?: Record<string, unknown>): unknown;
+/**
+ * Given a list of field type IDs, returns any IDs that are not registered.
+ */
+declare function unknownTypeIds(ids: string[]): string[];
+/**
+ * Validates a field value against a field type's validator and constraints.
+ * Never throws — returns an unknown_type error if type is not registered.
+ */
+declare function validateFieldValue(typeId: string, value: unknown, constraints?: Record<string, unknown>): FieldValidationResult;
+/**
+ * Resets the registry (useful for test isolation).
+ */
+declare function resetRegistry(): void;
+
+interface RichTextConstraints {
+    nodes?: string[];
+    marks?: string[];
+    maxDepth?: number;
+    maxNodes?: number;
+}
+declare const DEFAULT_ALLOWED_NODES: string[];
+declare const DEFAULT_ALLOWED_MARKS: string[];
+declare function isValidLinkHref(rawHref: string): boolean;
+/**
+ * Validates a ProseMirror document structure against constraints and strict security rules.
+ */
+declare function validateProseMirrorDoc(doc: unknown, constraints?: RichTextConstraints): FieldValidationResult;
+
+/**
+ * Shared URL guards and validation routines.
+ */
+/**
+ * Strips all ASCII control characters, whitespace, and invisible Unicode control codes from a raw URL.
+ */
+declare function stripUrlControlChars(raw: string): string;
+/**
+ * Checks whether a cleaned URL string is a safe relative path or anchor.
+ * Must start with exactly one '/' not followed by '/' or '\', or start with '#'.
+ * Rejects any backslashes or percent-encoded backslashes before or at path root.
+ */
+declare function isSafeRelativeOrAnchor(cleaned: string): boolean;
+/**
+ * Validates a media src (video/image/audio).
+ * Allows relative paths, `#anchor`, UUID asset references, and `https://` URLs (with optional host allowlist).
+ */
+declare function isSafeMediaSrc(raw: string, allowedHosts?: string[]): boolean;
+/**
+ * Validates an action href (link/CTA).
+ * Default-restrictive: allows relative paths or `#anchor` only.
+ * Absolute `https://` is permitted ONLY when its host is in `allowedHosts`.
+ * Rejects `mailto:`, `tel:`, `data:`, `blob:`, `javascript:`, and non-allowed absolute URLs.
+ */
+declare function isSafeActionHref(raw: string, allowedHosts?: string[]): boolean;
+
+interface TextConstraints {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+declare const textType: FieldTypeDefinition<string>;
+
+interface NumberConstraints {
+    min?: number;
+    max?: number;
+    step?: number;
+    integer?: boolean;
+}
+declare const numberType: FieldTypeDefinition<number>;
+
+declare const toggleType: FieldTypeDefinition<boolean>;
+
+interface SelectOption {
+    label: string;
+    value: string;
+}
+interface SelectConstraints {
+    options?: Array<string | SelectOption>;
+}
+declare const selectType: FieldTypeDefinition<string>;
+
+interface ImageConstraints {
+    maxSizeBytes?: number;
+    allowedMimeTypes?: string[];
+}
+declare const imageType: FieldTypeDefinition<string | null>;
+
+declare const richtextType: FieldTypeDefinition<Record<string, unknown>>;
+
+interface VideoConstraints {
+    maxSizeBytes?: number;
+    allowedMimeTypes?: string[];
+}
+declare const videoType: FieldTypeDefinition<string | null>;
+
+type MediaRef = string | {
+    kind: 'asset';
+    id: string;
+} | {
+    kind: 'url';
+    src: string;
+};
+interface VideoItem {
+    src: MediaRef;
+    poster?: MediaRef;
+    caption?: string;
+    href?: string;
+}
+interface VideoListConstraints {
+    maxItems?: number;
+    allowedSrcHosts?: string[];
+    allowedHrefHosts?: string[];
+    maxCaptionLength?: number;
+}
+declare const videoListType: FieldTypeDefinition<VideoItem[]>;
+
+interface GeoAreaConstraints {
+    maxVertices?: number;
+    maxRings?: number;
+}
+interface GeoJsonPolygon {
+    type: 'Polygon';
+    coordinates: number[][][];
+}
+interface GeoJsonMultiPolygon {
+    type: 'MultiPolygon';
+    coordinates: number[][][][];
+}
+type GeoAreaValue = GeoJsonPolygon | GeoJsonMultiPolygon | null;
+/**
+ * Pure repair pass for GeoJSON geometry:
+ * Auto-closes rings and removes consecutive duplicate positions.
+ */
+declare function normalizeGeoArea(value: unknown): unknown;
+declare const geoAreaType: FieldTypeDefinition<GeoAreaValue>;
+
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    region: string;
+    postal: string;
+    country: string;
+    lat?: number;
+    lng?: number;
+}
+interface AddressConstraints {
+    countryFormat?: 'iso2' | 'free';
+}
+interface AddressListConstraints extends AddressConstraints {
+    minItems?: number;
+    maxItems?: number;
+}
+declare const addressType: FieldTypeDefinition<Address | null>;
+declare const addressListType: FieldTypeDefinition<Address[]>;
+
+interface StreamVideoValue {
+    uid: string;
+    durationMs?: number;
+    thumbnail?: string;
+    ready?: boolean;
+}
+interface StreamVideoConstraints {
+    maxDurationSeconds?: number;
+    allowedThumbnailHosts?: string[];
+}
+declare const streamVideoType: FieldTypeDefinition<StreamVideoValue | null>;
+
+declare function registerBaseTypes(): void;
+
+export { type Address, type AddressConstraints, type AddressListConstraints, DEFAULT_ALLOWED_MARKS, DEFAULT_ALLOWED_NODES, type FieldTypeDefinition, type FieldValidationError, type FieldValidationResult, type GeoAreaConstraints, type GeoAreaValue, type GeoJsonMultiPolygon, type GeoJsonPolygon, type ImageConstraints, type MediaRef, type NumberConstraints, type RichTextConstraints, type SelectConstraints, type SelectOption, type StreamVideoConstraints, type StreamVideoValue, type TextConstraints, type VideoConstraints, type VideoItem, type VideoListConstraints, addressListType, addressType, fieldTypeAliases, geoAreaType, getFieldType, hasFieldType, imageType, isSafeActionHref, isSafeMediaSrc, isSafeRelativeOrAnchor, isValidLinkHref, listFieldTypeIds, listFieldTypes, normalizeFieldValue, normalizeGeoArea, numberType, registerBaseTypes, registerFieldType, resetRegistry, resolveTypeAlias, richtextType, selectType, streamVideoType, stripUrlControlChars, textType, toggleType, unknownTypeIds, validateFieldValue, validateProseMirrorDoc, videoListType, videoType };