@logixjs/form 0.0.1

package/dist/impl-Ccdm5eDF.d.cts

@@ -0,0 +1,225 @@
+import * as Logix from '@logixjs/core';
+import { Schema, Effect } from 'effect';
+import { e as RulesDecl, f as RuleInput, L as ListIdentityPolicy, g as RootDecl, c as CanonicalListPath, C as CanonicalPath, d as CanonicalListItem, h as ListDecl, b as CanonicalValue, E as ErrorTarget, i as FieldDecl, A as AutoValidateOn } from './Rule-BOAiSVz9.cjs';
+import { D as DerivedSpec } from './Trait-Bu794ROY.cjs';
+
+/**
+ * RulesSpec: the input shape of `Form.make({ rules })`.
+ *
+ * - Task 028 compiles `rules` into an equivalent `StateTraitSpec`; `rules` itself does not introduce a second runtime.
+ */
+type RulesSpec<TValues extends object> = Readonly<{
+    readonly _tag: 'FormRulesSpec';
+    readonly decls: ReadonlyArray<RulesDecl<TValues>>;
+}>;
+type RulesFieldNode = Readonly<{
+    readonly _tag: 'FormRulesNodeField';
+    readonly rule: RuleInput<any, any>;
+}>;
+type RulesObjectNode = Readonly<{
+    readonly _tag: 'FormRulesNodeObject';
+    readonly shape: Readonly<Record<string, RulesNode>>;
+    readonly refineRule?: RuleInput<any, any>;
+    readonly superRefineRule?: RuleInput<any, any>;
+    readonly refine: (rule: RuleInput<any, any>) => RulesObjectNode;
+    readonly superRefine: (rule: RuleInput<any, any>) => RulesObjectNode;
+}>;
+type RulesArrayNode = Readonly<{
+    readonly _tag: 'FormRulesNodeArray';
+    readonly item: RulesNode;
+    readonly identity: ListIdentityPolicy;
+    readonly refineRule?: RuleInput<any, any>;
+    readonly superRefineRule?: RuleInput<any, any>;
+    readonly refine: (rule: RuleInput<any, any>) => RulesArrayNode;
+    readonly superRefine: (rule: RuleInput<any, any>) => RulesArrayNode;
+}>;
+type RulesNode = RulesFieldNode | RulesObjectNode | RulesArrayNode;
+type TrackByKey<Item> = Item extends object ? CanonicalPath<Item> extends never ? string : CanonicalPath<Item> : string;
+type RulesDsl<TValues extends object> = {
+    (...decls: ReadonlyArray<RulesDecl<TValues>>): RulesSpec<TValues>;
+    (...decls: ReadonlyArray<RulesDecl<TValues> | ReadonlyArray<RulesDecl<TValues>>>): RulesSpec<TValues>;
+    readonly schema: (node: RulesNode) => RulesSpec<TValues>;
+    readonly at: (prefix: string) => RulesDsl<TValues>;
+    readonly root: <Ctx = unknown>(rule: RuleInput<TValues, Ctx>) => RootDecl<TValues, Ctx>;
+    readonly list: <P extends CanonicalListPath<TValues>, Ctx = unknown>(listPath: P, spec: {
+        readonly identity: Readonly<{
+            readonly mode: 'trackBy';
+            readonly trackBy: TrackByKey<CanonicalListItem<TValues, P>>;
+        }> | Readonly<{
+            readonly mode: 'store';
+        }> | Readonly<{
+            readonly mode: 'index';
+        }>;
+        readonly item?: RuleInput<CanonicalListItem<TValues, P>, Ctx>;
+        readonly list?: RuleInput<ReadonlyArray<CanonicalListItem<TValues, P>>, Ctx>;
+    }) => ListDecl<CanonicalListItem<TValues, P>, Ctx>;
+    readonly field: {
+        <P extends CanonicalPath<TValues>, Ctx = unknown>(valuePath: P, rule: RuleInput<CanonicalValue<TValues, P>, Ctx>, options?: {
+            readonly errorTarget?: ErrorTarget;
+        }): FieldDecl<CanonicalValue<TValues, P>, Ctx>;
+        (schema: Schema.Schema<any, any, never>): RulesFieldNode;
+        (rule: RuleInput<any, any>): RulesFieldNode;
+    };
+    readonly object: (shape: Readonly<Record<string, RulesNode>>) => RulesObjectNode;
+    readonly array: (item: RulesNode, options: {
+        readonly identity: ListIdentityPolicy;
+    }) => RulesArrayNode;
+};
+/**
+ * Form.rules：
+ * - `$.rules(...decls)`：decl list（`Form.Rule.field/list/root`）
+ * - `$.rules.schema(node)`: zod-like rules authoring (Phase 3 will be filled in gradually)
+ * - `$.rules.at(prefix)`: write relative paths under `prefix`
+ */
+declare const rules: <TValues extends object, I>(_valuesSchema: Schema.Schema<TValues, I>) => RulesDsl<TValues>;
+
+type RulesManifest = Readonly<{
+    readonly moduleId: string;
+    readonly lists: ReadonlyArray<Readonly<{
+        readonly path: ReadonlyArray<string>;
+        readonly identity: ListIdentityPolicy;
+    }>>;
+    readonly rules: ReadonlyArray<RuleDescriptor>;
+}>;
+type RuleScope = Readonly<{
+    readonly kind: 'root' | 'field' | 'list' | 'item';
+    readonly fieldPath: ReadonlyArray<string>;
+    readonly errorTarget?: ErrorTarget;
+}>;
+type RuleDescriptor = Readonly<{
+    readonly ruleId: string;
+    readonly scope: RuleScope;
+    readonly deps: ReadonlyArray<string>;
+    readonly validateOn?: ReadonlyArray<AutoValidateOn>;
+    readonly meta?: Logix.Observability.JsonValue;
+}>;
+
+type FormErrors = unknown;
+type FormUiState = unknown;
+type FormMeta = {
+    readonly submitCount: number;
+    readonly isSubmitting: boolean;
+    readonly isDirty: boolean;
+    /**
+     * errorCount：
+     * - Used for O(1) reads in `FormView.isValid/canSubmit`.
+     * - Semantics: the number of ErrorValue leaf nodes in the errors tree (including `$manual/$schema`).
+     */
+    readonly errorCount: number;
+};
+type FormState<TValues extends object> = TValues & {
+    readonly errors: FormErrors;
+    readonly ui: FormUiState;
+    readonly $form: FormMeta;
+};
+declare const FormActions: {
+    readonly setValue: Schema.Struct<{
+        path: typeof Schema.String;
+        value: typeof Schema.Unknown;
+    }>;
+    readonly blur: Schema.Struct<{
+        path: typeof Schema.String;
+    }>;
+    readonly submit: typeof Schema.Void;
+    readonly validate: typeof Schema.Void;
+    readonly validatePaths: Schema.Array$<typeof Schema.String>;
+    readonly submitAttempt: typeof Schema.Void;
+    readonly setSubmitting: typeof Schema.Boolean;
+    readonly reset: Schema.UndefinedOr<typeof Schema.Unknown>;
+    readonly setError: Schema.Struct<{
+        path: typeof Schema.String;
+        error: typeof Schema.Unknown;
+    }>;
+    readonly clearErrors: Schema.UndefinedOr<Schema.Array$<typeof Schema.String>>;
+    readonly arrayAppend: Schema.Struct<{
+        path: typeof Schema.String;
+        value: typeof Schema.Unknown;
+    }>;
+    readonly arrayPrepend: Schema.Struct<{
+        path: typeof Schema.String;
+        value: typeof Schema.Unknown;
+    }>;
+    readonly arrayRemove: Schema.Struct<{
+        path: typeof Schema.String;
+        index: typeof Schema.Number;
+    }>;
+    readonly arraySwap: Schema.Struct<{
+        path: typeof Schema.String;
+        indexA: typeof Schema.Number;
+        indexB: typeof Schema.Number;
+    }>;
+    readonly arrayMove: Schema.Struct<{
+        path: typeof Schema.String;
+        from: typeof Schema.Number;
+        to: typeof Schema.Number;
+    }>;
+};
+type FormShapeForActions = FormShape<Record<string, never>>;
+type FormAction = Logix.ActionOf<FormShapeForActions>;
+type FormShape<TValues extends object> = Logix.Shape<Schema.Schema<FormState<TValues>, any>, typeof FormActions>;
+interface FormMakeConfig<TValues extends object> {
+    readonly values: Schema.Schema<TValues, any>;
+    readonly initialValues: TValues;
+    readonly validateOn?: ReadonlyArray<'onSubmit' | 'onChange' | 'onBlur'>;
+    readonly reValidateOn?: ReadonlyArray<'onSubmit' | 'onChange' | 'onBlur'>;
+    readonly debounceMs?: number;
+    /**
+     * rules：
+     * - Recommended: express validations using rules only (field/list/root rules).
+     * - The result will be compiled into an equivalent StateTraitSpec (does not introduce a second runtime).
+     */
+    readonly rules?: RulesSpec<TValues>;
+    readonly traits?: Logix.StateTrait.StateTraitSpec<TValues>;
+    /**
+     * derived：
+     * - The entry point for domain-level linkage/derivation (by default, only writes back to values/ui are allowed).
+     * - The result must be fully reducible to StateTraitSpec/IR (computed/link/source).
+     */
+    readonly derived?: DerivedSpec<TValues>;
+}
+type FormExtendDef<TValues extends object> = Omit<Logix.Module.MakeExtendDef<Schema.Schema<FormState<TValues>, any>, typeof FormActions, {}>, 'actions'> & {
+    readonly actions?: never;
+};
+interface FormController<TValues extends object> {
+    readonly runtime: Logix.ModuleRuntime<FormState<TValues>, FormAction>;
+    readonly getState: Effect.Effect<FormState<TValues>>;
+    readonly dispatch: (action: FormAction) => Effect.Effect<void>;
+    readonly submit: () => Effect.Effect<void>;
+    readonly controller: {
+        readonly validate: () => Effect.Effect<void, never, any>;
+        readonly validatePaths: (paths: ReadonlyArray<string> | string) => Effect.Effect<void, never, any>;
+        readonly reset: (values?: TValues) => Effect.Effect<void>;
+        readonly setError: (path: string, error: unknown) => Effect.Effect<void>;
+        readonly clearErrors: (paths?: ReadonlyArray<string> | string) => Effect.Effect<void>;
+        readonly handleSubmit: (handlers: {
+            readonly onValid: (values: TValues) => Effect.Effect<void, any, any>;
+            readonly onInvalid?: (errors: unknown) => Effect.Effect<void, any, any>;
+        }) => Effect.Effect<void, any, any>;
+    };
+    readonly field: (path: string) => {
+        readonly get: Effect.Effect<unknown>;
+        readonly set: (value: unknown) => Effect.Effect<void>;
+        readonly blur: () => Effect.Effect<void>;
+    };
+    readonly fieldArray: (path: string) => {
+        readonly get: Effect.Effect<ReadonlyArray<unknown>>;
+        readonly append: (value: unknown) => Effect.Effect<void>;
+        readonly prepend: (value: unknown) => Effect.Effect<void>;
+        readonly remove: (index: number) => Effect.Effect<void>;
+        readonly swap: (indexA: number, indexB: number) => Effect.Effect<void>;
+        readonly move: (from: number, to: number) => Effect.Effect<void>;
+    };
+}
+type FormHandleExt<TValues extends object> = {
+    readonly controller: FormController<TValues>['controller'];
+    readonly rulesManifest: () => RulesManifest;
+    readonly rulesManifestWarnings: () => ReadonlyArray<string>;
+};
+type FormModule<Id extends string, TValues extends object> = Logix.Module.Module<Id, FormShape<TValues>, FormHandleExt<TValues>, any> & {
+    readonly controller: {
+        readonly make: (runtime: Logix.ModuleRuntime<FormState<TValues>, FormAction>) => FormController<TValues>;
+    };
+};
+declare const make: <Id extends string, TValues extends object>(id: Id, config: FormMakeConfig<TValues>, extend?: FormExtendDef<TValues>) => FormModule<Id, TValues>;
+
+export { type FormErrors as F, type RulesDsl as R, type RulesNode as a, type RulesSpec as b, type FormUiState as c, type FormMeta as d, type FormState as e, type FormAction as f, type FormShape as g, type FormMakeConfig as h, type FormExtendDef as i, type FormController as j, type FormHandleExt as k, type FormModule as l, make as m, type RuleDescriptor as n, type RuleScope as o, type RulesManifest as p, rules as r };