@spring-systems/core 0.8.0

package/dist/types/index.d.ts

@@ -0,0 +1,85 @@
+import { P as Permission, b as FormStoreState } from '../form-types-D3MdGpjA.js';
+export { A as ApiErrorLike, C as ColumnLayout, c as ColumnType, d as CombinedSettingData, e as ComparisonFunction, D as DefaultFilter, f as FilterFieldValue, g as FilterNode, h as FormChangedPath, i as FormChangesApi, j as FormChangesSnapshot, k as FormCollectionActions, l as FormCollectionItem, a as FormDataValue, m as FormDetailFields, F as FormDetailRuntime, n as FormFieldCore, o as FormFieldDefinitionRuntime, p as FormFieldLifecycle, q as FormFieldMutation, r as FormFieldRuntime, s as FormFieldValidation, t as FormFieldValue, u as FormFieldVisibility, v as FormLifecycle, w as FormManagerBase, x as FormManagerRef, y as FormStoreApi, z as FormStoreInstance, B as FormStructureDef, I as Identifiable, E as Indexable, G as IndexedFormData, L as ListManagerLoadable, H as LogicOperator, R as ReadOnlyField, S as SavedLayout, J as SystemFilterRecord, V as ValidatorFn, K as getField, M as getIdentifiableId, N as getStoreValue, O as getSubState, Q as isColumnLayout, T as isCombinedSettingData, U as isFilterNode, W as isFormFieldRuntime, X as isPermission, Y as storeBoundary, Z as toFormDataValue } from '../form-types-D3MdGpjA.js';
+
+/**
+ * Branded types for nominal type safety.
+ * Prevents accidental interchange of structurally identical string types.
+ * @module branded
+ */
+declare const __brand: unique symbol;
+/** Brands a base type `T` with a nominal tag `B`. */
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/** A GUID / UUID string. */
+type Guid = Brand<string, "Guid">;
+/** A public entity identifier. */
+type IdPublic = Brand<string, "IdPublic">;
+/** A resource/translation key. */
+type ResourceKey = Brand<string, "ResourceKey">;
+/** An API route path. */
+type ApiRoute = Brand<string, "ApiRoute">;
+/** Cast a plain string to a Guid (boundary cast). */
+declare function toGuid(value: string): Guid;
+/** Cast a plain string to an IdPublic (boundary cast). */
+declare function toIdPublic(value: string): IdPublic;
+/** Cast a plain string to a ResourceKey (boundary cast). */
+declare function toResourceKey(value: string): ResourceKey;
+/** Cast a plain string to an ApiRoute (boundary cast). */
+declare function toApiRoute(value: string): ApiRoute;
+
+/**
+ * List types — pure type definitions extracted from shared/lists/lists.ts.
+ * @module list-types
+ */
+
+/** Comparison operators used in format conditions (conditional formatting). */
+type FormatOperator = "==" | "===" | "!=" | "!==" | ">" | ">=" | "<" | "<=";
+interface FormatCondition {
+    value?: string | number | boolean | null;
+    background?: string;
+    color?: string;
+    column?: string;
+    field: string;
+    operator?: FormatOperator;
+    className?: string;
+}
+declare const FormatType: {
+    readonly Badge: 1;
+    readonly Color: 2;
+    readonly Background: 3;
+    readonly RowBackground: 4;
+    readonly Icon: 5;
+    readonly Detail: 6;
+};
+type FormatType = (typeof FormatType)[keyof typeof FormatType];
+interface Pagination {
+    page?: number;
+    per_page?: number;
+    object_count: number;
+}
+interface ListResponse<T> {
+    data: T[];
+    message: string | null;
+    pagination: Pagination;
+    permissions?: Permission;
+    format_conditions: FormatCondition[];
+    params?: FormStoreState;
+}
+
+/**
+ * Shared utility types for the SPRING framework.
+ * @module utility-types
+ */
+/** Extracts the element type from an array or readonly array type. */
+type ArrayItem<T> = T extends readonly (infer U)[] ? U : T;
+/** Makes specific keys of T required while keeping the rest unchanged. */
+type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+/** Deep-readonly version of T — recursively marks all nested properties as readonly. */
+type DeepReadonly<T> = T extends Date | RegExp ? T : T extends (...args: unknown[]) => unknown ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/** Excludes null and undefined from T. */
+type Defined<T> = Exclude<T, null | undefined>;
+
+export { type ApiRoute, type ArrayItem, type Brand, type DeepReadonly, type Defined, FormStoreState, type FormatCondition, type FormatOperator, FormatType, type Guid, type IdPublic, type ListResponse, type Pagination, Permission, type RequireKeys, type ResourceKey, toApiRoute, toGuid, toIdPublic, toResourceKey };

package/dist/types/index.js

@@ -0,0 +1,72 @@
+import {
+  getField,
+  getIdentifiableId,
+  getStoreValue,
+  getSubState,
+  isFormFieldRuntime,
+  storeBoundary,
+  toFormDataValue
+} from "../chunk-QAVWXARR.js";
+
+// src/types/branded.ts
+function toGuid(value) {
+  return value;
+}
+function toIdPublic(value) {
+  return value;
+}
+function toResourceKey(value) {
+  return value;
+}
+function toApiRoute(value) {
+  return value;
+}
+
+// src/types/grid-types.ts
+function isFilterNode(val) {
+  if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+  return "logic" in val && "filters" in val || "field" in val && "operator" in val;
+}
+function isCombinedSettingData(val) {
+  if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+  return "user_filter" in val || "layout" in val;
+}
+function isPermission(val) {
+  if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+  const obj = val;
+  return typeof obj.read === "boolean" && typeof obj.list === "boolean" && typeof obj.delete === "boolean" && typeof obj.insert === "boolean" && typeof obj.update === "boolean";
+}
+function isColumnLayout(val) {
+  if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+  const obj = val;
+  return typeof obj.key === "string" && typeof obj.order === "number" && typeof obj.show === "boolean";
+}
+
+// src/types/list-types.ts
+var FormatType = {
+  Badge: 1,
+  Color: 2,
+  Background: 3,
+  RowBackground: 4,
+  Icon: 5,
+  Detail: 6
+};
+export {
+  FormatType,
+  getField,
+  getIdentifiableId,
+  getStoreValue,
+  getSubState,
+  isColumnLayout,
+  isCombinedSettingData,
+  isFilterNode,
+  isFormFieldRuntime,
+  isPermission,
+  storeBoundary,
+  toApiRoute,
+  toFormDataValue,
+  toGuid,
+  toIdPublic,
+  toResourceKey
+};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/branded.ts","../../src/types/grid-types.ts","../../src/types/list-types.ts"],"sourcesContent":["/**\n * Branded types for nominal type safety.\n * Prevents accidental interchange of structurally identical string types.\n * @module branded\n */\n\ndeclare const __brand: unique symbol;\n\n/** Brands a base type `T` with a nominal tag `B`. */\nexport type Brand<T, B extends string> = T & { readonly [__brand]: B };\n\n/** A GUID / UUID string. */\nexport type Guid = Brand<string, \"Guid\">;\n\n/** A public entity identifier. */\nexport type IdPublic = Brand<string, \"IdPublic\">;\n\n/** A resource/translation key. */\nexport type ResourceKey = Brand<string, \"ResourceKey\">;\n\n/** An API route path. */\nexport type ApiRoute = Brand<string, \"ApiRoute\">;\n\n/** Cast a plain string to a Guid (boundary cast). */\nexport function toGuid(value: string): Guid {\n    return value as Guid;\n}\n\n/** Cast a plain string to an IdPublic (boundary cast). */\nexport function toIdPublic(value: string): IdPublic {\n    return value as IdPublic;\n}\n\n/** Cast a plain string to a ResourceKey (boundary cast). */\nexport function toResourceKey(value: string): ResourceKey {\n    return value as ResourceKey;\n}\n\n/** Cast a plain string to an ApiRoute (boundary cast). */\nexport function toApiRoute(value: string): ApiRoute {\n    return value as ApiRoute;\n}\n","/**\n * Shared types used by both List and TreeList grids.\n * Single source of truth — re-exported from lists.ts and treelists.ts.\n * @module grid-types\n */\n\nexport interface Permission {\n    delete: boolean;\n    insert: boolean;\n    list: boolean;\n    read: boolean;\n    update: boolean;\n    /** Allows projects to add custom permission fields (e.g., { export: true, approve: false }) */\n    [key: string]: boolean;\n}\n\nexport type LogicOperator = \"and\" | \"or\";\n\n/** Node structure for tree-based filter. */\nexport interface FilterNode {\n    field?: string;\n    operator?: string;\n    value?: string | number | boolean | null;\n    logic?: LogicOperator;\n    filters?: FilterNode[];\n    negate?: boolean;\n}\n\n/** Simple key-value system filter (normalized into FilterNode by the engine). */\nexport interface SystemFilterRecord {\n    [key: string]: string | number | boolean | Date | null | undefined;\n}\n\nexport type ColumnType = \"string\" | \"number\" | \"date\" | \"datetime\" | \"time\" | \"boolean\" | \"object\" | \"color\";\n\n/** Column layout for saving into user settings. */\nexport interface ColumnLayout {\n    key: string;\n    order: number;\n    width?: number;\n    show: boolean;\n}\n\nexport interface DefaultFilter {\n    domain_name: string;\n    id_public: string;\n    is_default: boolean;\n    json_data: string;\n    name: string;\n    user_setting_type_code: \"user\" | \"fixed\" | \"layout\";\n    version: number;\n}\n\nexport interface SavedLayout {\n    domain_name: string;\n    id_public: string;\n    is_default: boolean;\n    json_data: string;\n    name: string;\n    user_setting_type_code: \"layout\";\n    version: number;\n}\n\n/** Combined structure for json_data in user-settings — filter + layout in one JSON. */\nexport interface CombinedSettingData {\n    user_filter?: FilterNode | null;\n    layout?: ColumnLayout[];\n}\n\n/** Type guard for FilterNode — checks for tree-filter or leaf-filter shape. */\nexport function isFilterNode(val: unknown): val is FilterNode {\n    if (typeof val !== \"object\" || val === null || Array.isArray(val)) return false;\n    return (\"logic\" in val && \"filters\" in val) || (\"field\" in val && \"operator\" in val);\n}\n\n/** Type guard for CombinedSettingData — checks for user_filter or layout property. */\nexport function isCombinedSettingData(val: unknown): val is CombinedSettingData {\n    if (typeof val !== \"object\" || val === null || Array.isArray(val)) return false;\n    return \"user_filter\" in val || \"layout\" in val;\n}\n\n/** Type guard for Permission — checks for all 5 required CRUD boolean keys. */\nexport function isPermission(val: unknown): val is Permission {\n    if (typeof val !== \"object\" || val === null || Array.isArray(val)) return false;\n    const obj = val as Record<string, unknown>;\n    return (\n        typeof obj.read === \"boolean\" &&\n        typeof obj.list === \"boolean\" &&\n        typeof obj.delete === \"boolean\" &&\n        typeof obj.insert === \"boolean\" &&\n        typeof obj.update === \"boolean\"\n    );\n}\n\n/** Type guard for ColumnLayout — checks for required key, order, show properties. */\nexport function isColumnLayout(val: unknown): val is ColumnLayout {\n    if (typeof val !== \"object\" || val === null || Array.isArray(val)) return false;\n    const obj = val as Record<string, unknown>;\n    return typeof obj.key === \"string\" && typeof obj.order === \"number\" && typeof obj.show === \"boolean\";\n}\n","/**\n * List types — pure type definitions extracted from shared/lists/lists.ts.\n * @module list-types\n */\n\nimport type { FormStoreState } from \"./form-types\";\nimport type { Permission } from \"./grid-types\";\n\n/** Comparison operators used in format conditions (conditional formatting). */\nexport type FormatOperator = \"==\" | \"===\" | \"!=\" | \"!==\" | \">\" | \">=\" | \"<\" | \"<=\";\n\nexport interface FormatCondition {\n    value?: string | number | boolean | null;\n    background?: string;\n    color?: string;\n    column?: string;\n    field: string;\n    operator?: FormatOperator;\n    className?: string;\n}\n\nexport const FormatType = {\n    Badge: 1,\n    Color: 2,\n    Background: 3,\n    RowBackground: 4,\n    Icon: 5,\n    Detail: 6,\n} as const;\nexport type FormatType = (typeof FormatType)[keyof typeof FormatType];\n\nexport interface Pagination {\n    page?: number;\n    per_page?: number;\n    object_count: number;\n}\n\nexport interface ListResponse<T> {\n    data: T[];\n    message: string | null;\n    pagination: Pagination;\n    permissions?: Permission;\n    format_conditions: FormatCondition[];\n    params?: FormStoreState;\n}\n"],"mappings":";;;;;;;;;;;AAwBO,SAAS,OAAO,OAAqB;AACxC,SAAO;AACX;AAGO,SAAS,WAAW,OAAyB;AAChD,SAAO;AACX;AAGO,SAAS,cAAc,OAA4B;AACtD,SAAO;AACX;AAGO,SAAS,WAAW,OAAyB;AAChD,SAAO;AACX;;;AC6BO,SAAS,aAAa,KAAiC;AAC1D,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,GAAG,EAAG,QAAO;AAC1E,SAAQ,WAAW,OAAO,aAAa,OAAS,WAAW,OAAO,cAAc;AACpF;AAGO,SAAS,sBAAsB,KAA0C;AAC5E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,GAAG,EAAG,QAAO;AAC1E,SAAO,iBAAiB,OAAO,YAAY;AAC/C;AAGO,SAAS,aAAa,KAAiC;AAC1D,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,GAAG,EAAG,QAAO;AAC1E,QAAM,MAAM;AACZ,SACI,OAAO,IAAI,SAAS,aACpB,OAAO,IAAI,SAAS,aACpB,OAAO,IAAI,WAAW,aACtB,OAAO,IAAI,WAAW,aACtB,OAAO,IAAI,WAAW;AAE9B;AAGO,SAAS,eAAe,KAAmC;AAC9D,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,GAAG,EAAG,QAAO;AAC1E,QAAM,MAAM;AACZ,SAAO,OAAO,IAAI,QAAQ,YAAY,OAAO,IAAI,UAAU,YAAY,OAAO,IAAI,SAAS;AAC/F;;;AC9EO,IAAM,aAAa;AAAA,EACtB,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,MAAM;AAAA,EACN,QAAQ;AACZ;","names":[]}

package/dist/utils/index.d.ts

@@ -0,0 +1,143 @@
+import { a as FormDataValue, b as FormStoreState, E as Indexable, g as FilterNode, f as FilterFieldValue, c as ColumnType } from '../form-types-D3MdGpjA.js';
+import dayjs from 'dayjs';
+export { S as SecurityLogData, a as SecurityLogScalar, b as SecurityLogValue, i as isSensitiveSecurityKey, s as sanitizeSecurityData } from '../security-sanitize-Bb0PExM6.js';
+
+interface KeyActivateEvent {
+    key: string;
+    preventDefault(): void;
+}
+declare function onKeyActivate<E extends KeyActivateEvent = KeyActivateEvent>(handler?: ((e: E) => void) | (() => void) | null): ((e: E) => void) | undefined;
+declare function prefersReducedMotion(): boolean;
+
+declare function getBrightness(r: number, g: number, b: number): number;
+declare function hexToRgb(hex: string): [number, number, number];
+declare function rgbToHex(rgb: string): string;
+declare function getContrastYIQ(hex: string): string;
+declare function getHexColorFromClass(className: string): string;
+
+declare function isValueNotEmpty(value: string | number | boolean | null | undefined | FormDataValue[]): boolean;
+/** Returns a deep copy of an object, removing unwanted references. */
+declare function deepCopy<T>(obj: T, hash?: WeakMap<WeakKey, unknown>): T;
+/**
+ * Performs deep comparison of two objects.
+ * Treats `null` and `""` as equivalent — this is intentional because the backend
+ * API returns `null` for empty fields while form inputs produce `""`.
+ */
+declare function deepEqual(a: FormDataValue | FormStoreState, b: FormDataValue | FormStoreState): boolean;
+declare function deepMerge<T extends Indexable>(target: T, source: Partial<T>): T;
+declare function getValueByPath(obj: FormStoreState, path: string): FormDataValue;
+/** Normalizes a string for comparison without diacritics, in lowercase */
+declare function normalizeString(str: string): string;
+declare function generateGUID(): string;
+declare function setDefaultStructure(data: {
+    field?: string;
+    type?: string;
+}[]): Record<string, string | number | boolean | null | undefined>;
+declare function parseJSONSafely(value: string | number | boolean | null | undefined | object): string | number | boolean | null | undefined | object;
+type ValueType = "string" | "date" | "number" | "boolean" | "object";
+declare function getValueType(value: string | number | boolean | null | undefined | object): ValueType;
+
+/**
+ * Set the dayjs locale at runtime.
+ * The locale package must be imported before calling this (e.g., `import "dayjs/locale/en"`).
+ */
+declare function setDateLocale(locale: string): void;
+declare const dateManager: {
+    formatDateCustom(value: Date | null, format: string): string;
+    formatDate(value: Date | null): string;
+    formatDateTime(value: Date | null): string;
+    formatTime(value: Date | null): string;
+    formatDateRange(dateFrom: Date, dateTo: Date, format?: string): string;
+    formatDateTimeWithSeconds(value: Date | null): string;
+    /** Formats a value as date with time, or time only if it is today */
+    formatDateTimeShort(value: Date | null): string;
+    getAgeFromDate(value: Date): number;
+    formatMonthName(value: Date, format: string): string;
+    formatMonthNumber(value: Date): number;
+    getPreviousMonth(date: Date, numberOfMonth: number): Date;
+    setTimeFromString(date: Date, time: string, onlyMinutes?: boolean): Date;
+    formatDateString(value: string): Date | null;
+    getDuration(date: Date | null, date2: Date | null, type: dayjs.ManipulateType): number | null;
+    getStartOfDate(date: Date, unitOfTime: dayjs.OpUnitType): Date;
+    getEndOfDay(date: Date): Date;
+    getDateRange(date: Date, unitOfTime: dayjs.OpUnitType): {
+        dateFrom: Date;
+        dateTo: Date;
+    };
+    isDateInRange(startDate: Date, endDate: Date, dateToCheck: Date): boolean;
+    /** Adds a number of days (or other unit) to a date */
+    add(value: Date, count: number, type?: dayjs.ManipulateType): Date;
+    substractDaysFromDate(numberOfDays: number, date: Date): Date;
+};
+
+/**
+ * Runtime deprecation warnings for the SPRING framework.
+ * Warns once per session per deprecation to avoid console spam.
+ * @module deprecation
+ */
+declare function springDeprecate(name: string, alternative: string, removeVersion?: string): void;
+/** Clear all tracked deprecation warnings. Intended for testing. */
+declare function clearDeprecationWarnings(): void;
+
+/**
+ * Dev-mode validation helpers.
+ * In development: throws errors / logs warnings for invalid usage.
+ * In production: silent (no runtime cost beyond a single boolean check).
+ * @module dev-warnings
+ */
+declare const __DEV__: boolean;
+/**
+ * Log a warning in development mode only.
+ * No-op in production.
+ */
+declare function devWarn(context: string, message: string): void;
+/**
+ * Throw an error in development mode, log a warning in production.
+ * Use for invalid API usage that should be caught during development.
+ */
+declare function devThrow(context: string, message: string): void;
+/**
+ * Assert a condition in development mode.
+ * Throws if condition is false in dev, no-op in production.
+ */
+declare function devAssert(condition: boolean, context: string, message: string): void;
+
+declare function parseFilter(value: string | number | boolean | Date | null | undefined | FilterFieldValue[] | object): string | boolean;
+/** Normalizes system filter — string/object to FilterNode. */
+declare function normalizeSystemFilter(input: Record<string, string | number | boolean | Date | null | undefined> | FilterNode | null | undefined): FilterNode | null;
+declare function getFilterFieldType(fieldKey: string, defaultListFilter: Record<string, {
+    type?: string;
+}> | null | undefined, value: string | number | boolean | null | undefined | object): string;
+
+interface FormatColumn<T> {
+    field: string & keyof T;
+    type: ColumnType;
+    decimals?: number;
+    textField?: string;
+}
+/** Strips all HTML tags from content */
+declare function sanitizeContent(content: string): string;
+/** Sanitizes HTML output from WYSIWYG editor — allows formatting tags, removes scripts */
+declare function sanitizeEditorContent(content: string): string;
+declare function truncateString(value: string, maxLength: number): string;
+declare function toNumber(value: string | number, decimals?: number): string;
+declare function setColumnBodyType<T extends FormStoreState>(item: T, obj: FormatColumn<T>): T[string & keyof T] | string | number | undefined;
+
+/**
+ * Shared utilities for tree structures (Tree and TreeList).
+ * @module tree-utils
+ */
+interface BaseTreeNode {
+    id_public: string;
+    childrenNodes?: BaseTreeNode[];
+}
+/** Safe access to node children — encapsulates dynamic property access + cast */
+declare function getChildren<T>(node: T, field: string): T[] | undefined;
+declare function findNode<T extends BaseTreeNode>(nodes: T[], id: string, childrenField?: string): T | null;
+declare function getAllIds<T extends BaseTreeNode>(nodes: T[], childrenField?: string): string[];
+declare function updateNode<T extends BaseTreeNode>(nodes: T[], id: string, updater: (node: T) => T, childrenField?: string): T[];
+declare function removeNode<T extends BaseTreeNode>(nodes: T[], id: string, childrenField?: string): T[];
+declare function addNode<T extends BaseTreeNode>(nodes: T[], parentId: string | null, newNode: T, childrenField?: string): T[];
+declare function findParentId<T extends BaseTreeNode>(nodes: T[], id: string, childrenField?: string, parentId?: string | null): string | null;
+
+export { type BaseTreeNode, type ValueType, __DEV__, addNode, clearDeprecationWarnings, dateManager, deepCopy, deepEqual, deepMerge, devAssert, devThrow, devWarn, findNode, findParentId, generateGUID, getAllIds, getBrightness, getChildren, getContrastYIQ, getFilterFieldType, getHexColorFromClass, getValueByPath, getValueType, hexToRgb, isValueNotEmpty, normalizeString, normalizeSystemFilter, onKeyActivate, parseFilter, parseJSONSafely, prefersReducedMotion, removeNode, rgbToHex, sanitizeContent, sanitizeEditorContent, setColumnBodyType, setDateLocale, setDefaultStructure, springDeprecate, toNumber, truncateString, updateNode };