react-luna-form 0.0.85 → 0.0.87

package/dist/types/luna-react/src/client/hook/use-entry-atom.d.ts

@@ -0,0 +1,18 @@
+import type { PrimitiveAtom } from 'jotai';
+/**
+ * One entry of a record the whole form shares, as an atom of the component that
+ * reads it.
+ *
+ * A family did this before: one atom per name, kept in a module-level cache for
+ * the life of the page. That cache never let go on its own, so it had to be
+ * emptied by hand -- release atoms, a call in `useStore`, and a comment on the
+ * loop to avoid -- and two of the three families grew anyway, a key per row ever
+ * added and a key per name ever shown. Made here, the atom goes when the
+ * component does, and there is nothing left to release.
+ */
+export declare function useEntryAtom<T>(base: PrimitiveAtom<Record<string, T>>, name: string): import("jotai").WritableAtom<NonNullable<T> | undefined, [next: T | undefined], void>;
+/** The same for a record of contributions. See `createContributionAtom`. */
+export declare function useContributionAtom<T>(base: PrimitiveAtom<Record<string, Record<string, T>>>, name: string, options: Readonly<{
+    merge: (values: T[]) => T | undefined;
+    validateTarget: (target: string) => boolean;
+}>): import("jotai").WritableAtom<T | undefined, [target: string, value: T | undefined], void>;

package/dist/types/luna-react/src/client/hook/use-form-action.d.ts

@@ -1,3 +1,4 @@
+import { type FormEvent } from 'react';
 import { type Field, type FormStateError, type Nullable, type Schemas, type ZodSchema } from '../../../../luna-core/index';
 export type FormState<T> = {
     data: Nullable<T>;
@@ -10,4 +11,4 @@ export type FormActionOptions<T> = {
     translations?: Record<string, string>;
     validation?: boolean;
 };
-export declare function useFormState<T, F = Record<string, unknown>>(getSchema: () => readonly [Schemas, Field[]], action?: (formData: F, schema?: ZodSchema) => Promise<FormState<T>>, options?: FormActionOptions<T>): readonly [(payload: FormData) => void, FormState<T>, boolean];
+export declare function useFormState<T, F = Record<string, unknown>>(getSchema: () => readonly [Schemas, Field[]], action?: (formData: F, schema?: ZodSchema) => Promise<FormState<T>>, options?: FormActionOptions<T>): readonly [(payload: FormData) => void, FormState<T>, boolean, (event: FormEvent<HTMLFormElement>) => void];

package/dist/types/luna-react/src/client/hook/use-host-entry.d.ts

@@ -0,0 +1,17 @@
+import { type HostEntry } from '../lib/host-value-store';
+/**
+ * What the host says about one field. Re-renders this field when its own entry
+ * changes, and only then.
+ */
+export declare function useHostEntry(name: string): HostEntry;
+/**
+ * The same answer, read at the moment it is asked rather than at the moment the
+ * component rendered.
+ *
+ * For a reader that decides once and marks itself done. The store is written
+ * from the form's effect, and a parent's effects run after its children's, so a
+ * child asking during its own effect is always one commit behind. Asking from
+ * the microtask that follows the commit is not: every effect in that commit has
+ * run by then, the form's write included.
+ */
+export declare function useHostEntryReader(name: string): () => HostEntry;

package/dist/types/luna-react/src/client/hook/use-input-core.d.ts

@@ -1,4 +1,4 @@
-import { type AriaAttributes, type CommonProps, type DataAttributes, type DataSource, type Field, type Nullable, type Schema, type Schemas, type Value } from '../../../../luna-core/index';
+import { type AriaAttributes, type CommonProps, type DataAttributes, type DataSource, type Field, type Schema, type Value } from '../../../../luna-core/index';
 import type { Config, InputChange } from '../../type';
 export type InputCoreProps = Readonly<{
     ariaAttributes?: AriaAttributes;
@@ -7,23 +7,22 @@ export type InputCoreProps = Readonly<{
     context?: Record<string, unknown>;
     dataAttributes?: DataAttributes;
     field: Field;
-    getSchema: () => readonly [Schemas, Field[]];
+    getField: (name: string) => Field | undefined;
     horizontal?: boolean;
-    onMount: (name: string, schema: Schema, field: Field) => void;
+    onRegister: (name: string, schema: Schema, field: Field) => void;
     onUnmount: (name: string, options?: {
         keepValue?: boolean;
     }) => void;
     onValueChange?: (input: InputChange) => void;
+    readOnly?: boolean;
     translations?: Record<string, string>;
-    value?: Nullable<Record<string, unknown>>;
 }>;
 export declare function useInputCore(props: InputCoreProps, deps: Readonly<{
     setSource: (target: string, source?: DataSource) => void;
     setValue: (value: unknown) => void;
-    shouldSkipOnChange: () => boolean;
     value: unknown;
 }>): {
-    readonly applyChangeEventsRef: import("react").RefObject<((selected: unknown) => void) | null>;
+    readonly applyChangeEventsRef: import("react").RefObject<(selected: unknown) => void>;
     readonly commonProps: {
         placeholder: string;
         disabled?: boolean;
@@ -34,9 +33,8 @@ export declare function useInputCore(props: InputCoreProps, deps: Readonly<{
     readonly entity: string | undefined;
     readonly hasClickable: boolean;
     readonly onBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
-    readonly onValueChangeRef: import("react").RefObject<((value: Value) => void) | null>;
+    readonly onValueChangeRef: import("react").RefObject<(value: Value) => void>;
     readonly setTimeoutRef: (callback: () => void, delay: number) => void;
-    readonly shouldSkipOnChange: () => boolean;
     readonly validated: (value: Value) => void;
     readonly valueRef: import("react").RefObject<unknown>;
 };

package/dist/types/luna-react/src/client/hook/use-input.d.ts

@@ -1,4 +1,4 @@
 import type { Field, Schema } from '../../../../luna-core/index';
-export declare function useInput(field: Field, onMount: (name: string, schema: Schema, field: Field) => void, onUnmount: (name: string, options?: {
+export declare function useInput(field: Field, onRegister: (name: string, schema: Schema, field: Field) => void, onUnmount: (name: string, options?: {
     keepValue?: boolean;
 }) => void, translations?: Record<string, string>): import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;

package/dist/types/luna-react/src/client/hook/use-latest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The latest value a commit left, for the code that runs after it: an event
+ * handler, an effect, a callback whose identity has to stay steady across
+ * renders.
+ *
+ * Written from a layout effect and not from the render body, which is the whole
+ * point. A render is not a promise that anything reached the screen -- React
+ * throws one away when a transition is interrupted or a boundary retries -- and
+ * a ref assigned while rendering keeps whatever that discarded render held,
+ * which is props nobody ever saw. A commit is the moment a value becomes real,
+ * so that is when this writes it. It is also what the React Compiler asks of a
+ * component before it will optimize it.
+ *
+ * Layout and not `useEffect`: every effect of a commit runs after every layout
+ * effect of that same commit, so an effect reading this ref reads the value of
+ * the render it belongs to, whatever order the hooks were declared in.
+ *
+ * Reading it while rendering is still wrong, and still reported by
+ * `react-hooks/refs`: there the value is one commit old. What a render needs is
+ * the value itself.
+ */
+export declare function useLatest<T>(value: T): import("react").RefObject<T>;

package/dist/types/luna-react/src/client/hook/use-live-item-value.d.ts

@@ -1,6 +1,20 @@
 /**
- * Returns the live value of a list item or field path, merging the current
- * Jotai form state on top of the initial value tree. Used by previews to
- * evaluate `when` conditions reactively against user edits.
+ * What a row holds right now: the form's own state over the initial value tree,
+ * for a `when` that has to follow what the user types.
+ *
+ * Subscribed to the row's keys and not to the record. Every field in the form
+ * writes into that one record, so a row that read it woke up on every keystroke
+ * anywhere and walked every key in the form to find its own. The selection is
+ * compared shallowly, so a keystroke outside the row recomputes the pick, finds
+ * the same keys, and renders nothing.
+ *
+ * Only a condition needs this, and only a condition asks for it: the components
+ * that own one render the child that calls this hook, so a row with no
+ * condition to answer never subscribes at all.
+ *
+ * The atom is made with the component that reads it and goes with it: jotai
+ * caches a selection under the selector function, `pickRow` makes a new one per
+ * row, and both are held weakly, so nothing is kept by name for the life of the
+ * page.
  */
 export declare function useLiveItemValue(name: string, initialValue?: Record<string, unknown> | unknown[] | null): unknown;

package/dist/types/luna-react/src/client/hook/use-schema.d.ts

@@ -1,4 +1,6 @@
-import type { Field, Schema, Schemas } from '../../../../luna-core/index';
-export declare function useSchema(): readonly [() => readonly [Schemas, Field[]], (name: string, schema: Schema, field: Field) => void, (name: string, options?: {
+import type { Field, Schema } from '../../../../luna-core/index';
+export declare function useSchema(): readonly [() => readonly [{
+    [k: string]: Schema;
+}, Field[]], (name: string) => Field | undefined, (name: string, schema: Schema, field: Field) => void, (name: string, options?: {
     keepValue?: boolean;
 }) => void];

package/dist/types/luna-react/src/client/hook/use-value.d.ts

@@ -1,6 +1,6 @@
-import { type Field, type Nullable } from '../../../../luna-core/index';
-export declare function useValue(field: Field, currentValue?: Nullable<Record<string, unknown>>): {
-    readonly setValue: (newValue: unknown) => void;
+import { type Field } from '../../../../luna-core/index';
+export declare function useValue(field: Field): {
+    readonly setValue: (next: unknown) => void;
     readonly shouldSkipOnChange: () => boolean;
     readonly value: {} | undefined;
 };

package/dist/types/luna-react/src/client/lib/compose-list-value.d.ts

@@ -1,5 +1,7 @@
+import { type Nullable } from '../../../../luna-core/index';
 import type { MountedList } from './list-store';
-import type { Nullable } from '../../../../luna-core/index';
+/** A list's rows as a consumer is given them, in order. */
+export type ListRows = Array<Record<string, unknown>>;
 export declare function itemKey(listName: string, stableId: number, leafName: string): string;
 /**
  * The three places a leaf can be found, declared in the order they are tried.
@@ -38,4 +40,29 @@ export type ValueSources = {
  * @param listName - The list's name, already carrying its ancestors' stable
  *   ids (`rules.0.rule`), which is what makes the keys unambiguous.
  */
-export declare function composeListValue(listName: string, { items, leafNames }: MountedList, sources: ValueSources): Array<Record<string, unknown>>;
+export declare function composeListValue(listName: string, { items, leafNames }: MountedList, sources: ValueSources): ListRows;
+/**
+ * Every positional name a change to a list's rows can have left out of date,
+ * each with what it holds now.
+ *
+ * A consumer that keeps each report in one record -- the way the docs suggest
+ * keeping values -- holds a row's leaves there twice: inside the list's array,
+ * and under their own positional names, `items.0.value`, from the reports the
+ * leaves made as they were typed in. Removing a row moves every row after it
+ * up one position; assigning rows rewrites what every position holds. The
+ * array is reported again either way, but the names would go on holding what
+ * the rows used to hold, and `resolveEntry` tries a flat name before the path
+ * into the array: the next row to read one of them gets a row that is gone.
+ *
+ * So every name from `from` to the end of the longer of the two lists comes
+ * back, with what its position holds now, or `undefined` where no row is left
+ * -- whether or not that differs from before, because what the consumer holds
+ * is not necessarily what the list last said.
+ *
+ * @param base - The list's positional name, as the consumer addresses it.
+ * @param from - The first position the change can have touched.
+ */
+export declare function positionalEntries(base: string, from: number, previous: ListRows, next: ListRows): Array<{
+    name: string;
+    value: unknown;
+}>;

package/dist/types/luna-react/src/client/lib/error-store.d.ts

@@ -1,7 +1,9 @@
+export declare const inputErrorAtom: import("jotai").PrimitiveAtom<Record<string, string[]>> & {
+    init: Record<string, string[]>;
+};
 export declare const clearInputErrorAtom: import("jotai").WritableAtom<null, [names: string[]], void> & {
     init: null;
 };
 export declare const reportErrorAtom: import("jotai").WritableAtom<null, [newValue: Record<string, string[]>], void> & {
     init: null;
 };
-export declare const reportInputErrorAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<string[] | undefined, [newValue: string[] | undefined], void>>;

package/dist/types/luna-react/src/client/lib/host-value-store.d.ts

@@ -0,0 +1,28 @@
+import type { Nullable } from '../../../../luna-core/index';
+export declare const hostValueAtom: import("jotai").PrimitiveAtom<Nullable<Record<string, unknown>>> & {
+    init: Nullable<Record<string, unknown>>;
+};
+/** What the host says about one field, with the sentinel already read. */
+export type HostEntry = {
+    /** The host names this field. A field it does not name reads `undefined`. */
+    found: boolean;
+    value: unknown;
+};
+export declare function readHostEntry(entry: unknown): HostEntry;
+/**
+ * One field's entry in that record.
+ *
+ * Keyed by the name the record actually uses -- the POSITIONAL one. A leaf
+ * inside a list is named after its row's stable id, and the two diverge the
+ * moment a non-tail row is removed, so the caller translates before it
+ * subscribes. That translation lives in a React context, which an atom cannot
+ * read; doing it at the call site is what keeps this correct where a memo
+ * comparator could not be. See `ListPathContext`.
+ *
+ * Made by whoever subscribes rather than cached by name, so it goes with the
+ * component that asked: a family kept one per name for the life of the page,
+ * and this one was never released at all -- 110 keys after ten definitions of
+ * ten fields. See `useEntryAtom` for the same move on the records a field
+ * writes into.
+ */
+export declare function hostEntryAtom(name: string): import("jotai").Atom<unknown>;

package/dist/types/luna-react/src/client/lib/list-store.d.ts

@@ -1,7 +1,6 @@
 export declare const pendingListRowsAtom: import("jotai").PrimitiveAtom<Record<string, Record<string, unknown>[]>> & {
     init: Record<string, Record<string, unknown>[]>;
 };
-export declare const reportPendingListRowsAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<Record<string, unknown>[] | undefined, [newValue: Record<string, unknown>[] | undefined], void>>;
 /**
  * What a list on screen is holding: the stable ids of its live rows, in the
  * order they are shown, and the name of every leaf a row owns.
@@ -16,7 +15,7 @@ export type MountedList = {
      * The list's own `hidden`, as its definition declares it.
      *
      * Here rather than looked up, because there is nowhere to look it up: the
-     * schema registry `getSchema` answers from is filled by `onMount` on the
+     * schema registry `getField` answers from is filled by `onRegister` on the
      * input path, and a container never goes through it. That gap is what let a
      * list keep its values through a hide -- the branch that clears a target
      * reverting to its static hidden asked only that registry, found nothing,
@@ -27,10 +26,13 @@ export type MountedList = {
      * rather than a gap: the only target worth clearing is one that was showing.
      */
     hidden?: boolean;
-    /** The list's own `keepValue`, published for the same reason as `hidden`. */
+    /**
+     * The list's own `advanced.keepValue`, published for the same reason as
+     * `hidden` and flattened on the way in: this registry answers about a list
+     * that is on screen, not about the JSON that declared it.
+     */
     keepValue?: boolean;
 };
 export declare const mountedListsAtom: import("jotai").PrimitiveAtom<Record<string, MountedList>> & {
     init: Record<string, MountedList>;
 };
-export declare const reportMountedListAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<MountedList | undefined, [newValue: MountedList | undefined], void>>;

package/dist/types/luna-react/src/client/lib/resolve-value.d.ts

@@ -1,6 +1 @@
-export type Entry = {
-    found: boolean;
-    value: unknown;
-};
-export declare function resolveEntry(name: string, currentValue: Record<string, unknown> | unknown[]): Entry;
 export declare function resolveValue(name: string, currentValue: Record<string, unknown> | unknown[]): unknown;

package/dist/types/luna-react/src/client/lib/source-store.d.ts

@@ -1,5 +1,11 @@
 import { type DataSource } from '../../../../luna-core/index';
-export declare const reportSourceAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<DataSource | undefined, [target: string, value: DataSource | undefined], void>>;
+export declare const sourceAtom: import("jotai").PrimitiveAtom<Record<string, Record<string, DataSource>>> & {
+    init: Record<string, Record<string, DataSource>>;
+};
+export declare const SOURCE_OPTIONS: {
+    readonly merge: (values: DataSource[]) => DataSource | undefined;
+    readonly validateTarget: (target: string) => boolean;
+};
 export declare const clearInputSourceAtom: import("jotai").WritableAtom<null, [contributorNames: string[]], void> & {
     init: null;
 };

package/dist/types/luna-react/src/client/lib/state-store.d.ts

@@ -2,4 +2,3 @@ import type { FieldState } from '../../../../luna-core/index';
 export declare const fieldStateAtom: import("jotai").PrimitiveAtom<Record<string, FieldState>> & {
     init: Record<string, FieldState>;
 };
-export declare const reportFieldStateAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<FieldState | undefined, [newValue: FieldState | undefined], void>>;

package/dist/types/luna-react/src/client/lib/store-helper.d.ts

@@ -1,10 +1,10 @@
 import { type PrimitiveAtom } from 'jotai';
-type NestedAtomFamilyOptions<TInner> = {
-    merge?: (values: TInner[]) => TInner | undefined;
-    validateTarget?: (target: string) => boolean;
-};
 export declare function omitKey<T extends Record<string, unknown>>(obj: T, key: string): T;
-export declare function createNestedRecordAtomFamily<TInner, TRecord extends Record<string, Record<string, TInner>> = Record<string, Record<string, TInner>>>(baseAtom: PrimitiveAtom<TRecord>, options?: NestedAtomFamilyOptions<TInner>): import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<TInner | undefined, [target: string, value: TInner | undefined], void>>;
+export declare function createEntryAtom<T>(base: PrimitiveAtom<Record<string, T>>, name: string): import("jotai").WritableAtom<NonNullable<T> | undefined, [next: T | undefined], void>;
+export declare function createContributionAtom<T>(base: PrimitiveAtom<Record<string, Record<string, T>>>, name: string, options: Readonly<{
+    merge: (values: T[]) => T | undefined;
+    validateTarget: (target: string) => boolean;
+}>): import("jotai").WritableAtom<T | undefined, [target: string, value: T | undefined], void>;
 export declare function createNestedClearAtom<TInner>(baseAtom: PrimitiveAtom<Record<string, Record<string, TInner>>>): import("jotai").WritableAtom<null, [contributorNames: string[]], void> & {
     init: null;
 };
@@ -21,6 +21,4 @@ export declare function createAtomStore<T>(initialValue?: Record<string, T>): {
     bulkReport: import("jotai").WritableAtom<null, [newValue: Record<string, T>], void> & {
         init: null;
     };
-    report: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<NonNullable<T> | undefined, [newValue: T | undefined], void>>;
 };
-export {};

package/dist/types/luna-react/src/client/lib/value-store.d.ts

@@ -7,7 +7,6 @@ export declare const clearAllValueAtom: import("jotai").WritableAtom<null, [], v
 export declare const clearInputValueAtom: import("jotai").WritableAtom<null, [names: string[]], void> & {
     init: null;
 };
-export declare const reportValueAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<{} | undefined, [newValue: unknown], void>>;
 export declare const appliedAutoFillAtom: import("jotai").PrimitiveAtom<Record<string, unknown>> & {
     init: Record<string, unknown>;
 };

package/dist/types/luna-react/src/component/collapsible.d.ts

@@ -1,4 +1,5 @@
-export declare function Collapsible({ children, visible, }: Readonly<{
+export declare function Collapsible({ children, onReveal, visible, }: Readonly<{
     children: React.ReactNode;
+    onReveal?: () => void;
     visible?: boolean;
 }>): import("react").JSX.Element;

package/dist/types/luna-react/src/component/column.d.ts

@@ -1,3 +1,4 @@
+import { type DescriptionTextProps } from './description';
 import { type Column } from '../../../luna-core/index';
 import type { Config } from '../type';
 export declare function Column(props: Readonly<{
@@ -5,5 +6,6 @@ export declare function Column(props: Readonly<{
     column?: Column;
     config?: Config;
     context?: Record<string, unknown>;
+    description?: React.ComponentType<DescriptionTextProps>;
     translations?: Record<string, string>;
 }>): import("react").JSX.Element;

package/dist/types/luna-react/src/component/description.d.ts

@@ -1,4 +1,13 @@
+import { type Description as DescriptionType } from '../../../luna-core/index';
+import type { Config } from '../type';
 export declare function Description(props: Readonly<{
     children: string | React.ReactNode;
     title?: string;
 }>): import("react").JSX.Element;
+export type DescriptionTextProps = Readonly<{
+    config?: Config;
+    context?: Record<string, unknown>;
+    text?: DescriptionType;
+    translations?: Record<string, string>;
+}>;
+export declare function DescriptionText(props: DescriptionTextProps): import("react").JSX.Element | null;

package/dist/types/luna-react/src/component/field/{field-set.d.ts → field-set-static.d.ts}

@@ -1,5 +1,5 @@
 import { type Section, type Style } from '../../../../luna-core/index';
-export declare function FieldSet(props: Readonly<{
+export declare function StaticFieldSet(props: Readonly<{
     advanced?: {
         step?: boolean;
     };

package/dist/types/luna-react/src/component/field/field.d.ts

@@ -3,7 +3,7 @@ import type { Children } from '../../type';
 export type FieldProps = Readonly<{
     children: Children;
     disabled?: boolean;
-    errors?: Record<string, string[]>;
+    errors?: string[];
     field: Field;
     lang?: string;
     style?: Style;

package/dist/types/luna-react/src/component/field-description.d.ts

@@ -1,8 +1,9 @@
 import type { Config } from '../type';
 import type { Field } from '../../../luna-core/index';
-export declare function FieldDescription(props: Readonly<{
+export type DescriptionProps = Readonly<{
     config?: Config;
     context?: Record<string, unknown>;
     field: Field;
     translations?: Record<string, string>;
-}>): import("react").JSX.Element;
+}>;
+export declare function StaticDescription(props: DescriptionProps): import("react").JSX.Element;

package/dist/types/luna-react/src/component/form.d.ts

@@ -1,5 +1,13 @@
+import { StaticFieldSet } from './field/field-set-static';
 import { type Definition, type Sections } from '../../../luna-core/index';
 import type { Config, Control, Slot } from '../type';
+import type { Fields } from '../../../luna-core/index';
+import type { FormEvent } from 'react';
+export type GuardProps = Readonly<{
+    children: React.ReactNode;
+    fields: Fields;
+}>;
+export declare function StaticGuard(props: GuardProps): import("react").ReactNode;
 export declare function Form(props: Readonly<{
     advanced?: {
         step?: boolean;
@@ -9,8 +17,11 @@ export declare function Form(props: Readonly<{
     config: Config;
     control?: Control;
     definition?: Definition;
+    fieldSet?: React.ComponentType<React.ComponentProps<typeof StaticFieldSet>>;
+    guard?: React.ComponentType<GuardProps>;
     isPending?: boolean;
     noValidate?: boolean;
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
     readOnly?: boolean;
     sections: Sections;
     translations?: Record<string, string>;

package/dist/types/luna-react/src/component/input/input-base.d.ts

@@ -7,5 +7,6 @@ export declare function InputBase(props: Readonly<{
     field: Field;
     horizontal?: boolean;
     lang?: string;
+    readOnly?: boolean;
     translations?: Record<string, string>;
 }>): import("react").ReactNode;

package/dist/types/luna-react/src/component/input-group.d.ts

@@ -1,9 +1,11 @@
+import { type DescriptionProps } from './field-description';
 import type { Config } from '../type';
 import type { Field } from '../../../luna-core/index';
 export declare function InputGroup(props: Readonly<{
     children: React.ReactNode;
     config?: Config;
     context?: Record<string, unknown>;
+    description?: React.ComponentType<DescriptionProps>;
     field: Field;
     horizontal?: boolean;
     translations?: Record<string, string>;

package/dist/types/luna-react/src/component/input-label.d.ts

@@ -1,8 +1,10 @@
+import { type DescriptionProps } from './field-description';
 import { type Field } from '../../../luna-core/index';
 import type { Config } from '../type';
 export declare function InputLabel(props: Readonly<{
     config?: Config;
     context?: Record<string, unknown>;
+    description?: React.ComponentType<DescriptionProps>;
     field: Field;
     horizontal?: boolean;
     translations?: Record<string, string>;

package/dist/types/luna-react/src/component/slot/slot-base.d.ts

@@ -1,8 +1,10 @@
 import { type Fields, type Nullable, type Style } from '../../../../luna-core/index';
+import type { DescriptionTextProps } from '../description';
 import type { Children, Config } from '../../type';
 import type { FieldProps } from '../field/field';
 import type { ListProps } from '../field/field-list';
 export type SlotComponents = {
+    description?: React.ComponentType<DescriptionTextProps>;
     field: React.ComponentType<FieldProps>;
     list: React.ComponentType<ListProps>;
 };

package/dist/types/luna-react/src/lib/visibility.d.ts

@@ -0,0 +1,3 @@
+import type { Field, FieldState, Fields, List } from '../../../luna-core/index';
+export declare function isEntryHidden(entry: Fields[number], states: Record<string, FieldState>): boolean;
+export declare function isGuardHidden(states: Record<string, FieldState>, fields: Fields, container?: Field | List): boolean;

package/dist/types/luna-react/src/server/component/field.d.ts

@@ -0,0 +1,2 @@
+import type { FieldProps } from '../../component/field/field';
+export declare function Field(props: FieldProps): import("react").JSX.Element;

package/dist/types/luna-react/src/server/component/list-slot.d.ts

@@ -0,0 +1,2 @@
+import type { ListProps } from '../../component/field/field-list';
+export declare function ListSlot(props: ListProps): import("react").JSX.Element;

package/dist/types/luna-react/src/server/component/slot.d.ts

@@ -0,0 +1,15 @@
+export declare const Slot: (props: Readonly<{
+    children: import("../../type").Children;
+    config: import("../../type").Config;
+    context?: Record<string, unknown>;
+    disabled?: boolean;
+    fields?: import('../../../../luna-core/index').Fields;
+    lang?: string;
+    onValueChange?: (input: {
+        name: string;
+        value: unknown;
+    }) => void;
+    style?: import('../../../../luna-core/index').Style;
+    translations?: Record<string, string>;
+    value?: import('../../../../luna-core/index').Nullable<Record<string, unknown>>;
+}>) => import("react").JSX.Element;

package/dist/types/luna-react/src/type.d.ts

@@ -12,6 +12,7 @@ export type Children = (props: {
     dataAttributes?: DataAttributes;
     field: Field;
     horizontal?: boolean;
+    readOnly?: boolean;
 }) => React.ReactNode;
 export type InputConfig<T extends React.ElementType> = {
     types: string | string[];

package/docs/events/change.md

@@ -159,7 +159,7 @@ A row's key can name a field that is itself a `list`, in which case its value is
 Every rule above holds one level down as well: an inner list assigns rather than adds, honours its own `advanced.length`, and keeps the identity of the rows that survive. Two more only come up here:
 
 - **A row that names an inner list without giving it rows empties it.** `"checks": []`, a `checks` key holding something that is not rows, and no `checks` key at all all mean the same thing — none — rather than leaving behind what the row in that position had.
-- **The consumer is told once for the whole tree**, under the outer list's name, with the inner rows already in it. The inner lists then report their own paths (`groups.0.checks`) as they take their rows, the same way they do when a row is added or removed by hand.
+- **The consumer is told the whole tree at once**, under the outer list's name, with the inner rows already in it, and then every positional name the assignment rewrote (`groups.0.label`, `groups.1.checks.0.v`) with what that position holds now, or nothing where no row is left. A consumer that keeps each report in one record would otherwise go on holding the values of the rows that went away under those names. The inner lists then report their own paths (`groups.0.checks`) as they take their rows, the same way they do when a row is added or removed by hand.
 
 This is what the relative syntax cannot do. `"groups/checks"` reaches the inner list of the row the sender is sitting in, and `"groups.0.checks"` reaches the first one; neither can say "every group", so a control that appends a group has to assign the outer list and carry the inner rows along with it.
 
@@ -237,11 +237,19 @@ It does not matter how the form phrases the hiding. A rule whose state is
 so the field falls back to its own `hidden`, are the same act and clear the
 same values -- containers included.
 
+What the cleared target decided goes with it. A target with `state` rules of its
+own asserted them on the strength of its value, and that value is gone, so its
+rules are undone as if it held nothing: a field it revealed is hidden again --
+and cleared, if it too falls back to `hidden` -- and so on down the chain.
+Showing the first target again brings it back empty, and nothing it had revealed
+comes back with it. A target that keeps its value through the hide keeps what
+its rules decided as well; see below.
+
 #### Keeping a value through a hide
 
-A field that declares `keepValue: true` is put away rather than dropped: hiding
-it leaves what it held, showing it again gives it back, and the consumer is
-told nothing because nothing was taken.
+A field that declares `advanced.keepValue: true` is put away rather than
+dropped: hiding it leaves what it held, showing it again gives it back, and the
+consumer is told nothing because nothing was taken.
 
 ```json
 {
@@ -249,15 +257,21 @@ told nothing because nothing was taken.
   "name": "raw",
   "type": "textarea",
   "hidden": true,
-  "keepValue": true
+  "advanced": { "keepValue": true }
 }
 ```
 
+It sits in `advanced` beside [`transient`](#transient-controls), which is the
+other key that decides what ends up stored, rather than beside `hidden`: the
+two read as a pair, but `hidden` is what the form does to the field and this is
+what the field is.
+
 It is declared on the FIELD and not on the rule, for the same reason the clear
 does not care how the hiding was phrased: a field either survives being put
 away or it does not, and which of several rules happened to hide it this time
-says nothing about that. A `list` may declare it too, and then it covers every
-value its rows hold.
+says nothing about that. A
+[`list`](../fields/list.md#advanced-configuration-advanced-object) may declare
+it too, and then it covers every value its rows hold.
 
 Reach for it where two fields are two views of the same thing and the form
 swaps between them -- there, hiding one is a change of scenery, not a change of

package/docs/fields/custom-inputs.md

@@ -60,6 +60,10 @@ its own handlers must call the ones it received, or the form never learns the
 value changed: validation will not run, and neither will any `change` event the
 field declares.
 
+A `readonly` field arrives `disabled` and without a `name`. Its value is still
+submitted, but by the form, in hidden inputs of its own: nothing your component
+renders for it is sent, so it is sent once, whatever your component renders.
+
 ## Forwarding `id` is what gives the field its name
 
 The label is rendered by this library, outside your component, as