@usefillo/core 0.12.1 → 0.13.0

package/dist/index.d.ts

@@ -20,7 +20,7 @@ interface JumpRule {
     /** Target page id, or "end" to finish the form. */
     to: string | "end";
 }
-type FieldKind = "short_text" | "long_text" | "email" | "url" | "phone" | "number" | "select" | "multi_select" | "dropdown" | "checkbox" | "rating" | "linear_scale" | "ranking" | "matrix" | "signature" | "date" | "file_upload" | "hidden" | "calculated" | "custom";
+type FieldKind = "short_text" | "long_text" | "email" | "url" | "phone" | "number" | "select" | "multi_select" | "dropdown" | "checkbox" | "rating" | "linear_scale" | "ranking" | "matrix" | "signature" | "date" | "file_upload" | "hidden" | "calculated" | "repeating_group" | "custom";
 type ContentKind = "heading" | "paragraph" | "divider";
 type BlockKind = FieldKind | ContentKind;
 interface SelectOption {
@@ -198,6 +198,53 @@ interface CalculatedField extends BaseField {
     prefix?: string;
     suffix?: string;
 }
+/**
+ * One repeated instance's answers: childId → that child's canonical value,
+ * the exact same shapes a top-level field would carry (trimmed strings,
+ * wire-format numerics coerced, empty answers absent — see canonical.ts). A
+ * key absent from the record means that child is unanswered in this instance,
+ * mirroring how a key absent from {@link ResponseData} means a top-level field
+ * is unanswered.
+ */
+type GroupInstanceValue = Record<string, FieldValue>;
+/**
+ * A repeated block of fields (logic depth P3) — "one row per guest/item",
+ * respondent-controlled. Bounded by construction: `maxInstances` is required
+ * (1–20); `minInstances` clamps to 0..maxInstances (default 1). The template
+ * (`fields`) is capped at 12 children, drawn from a restricted v1 allowlist
+ * (see schema-validation's GROUP_CHILD_ALLOWED_KINDS) — notably NOT
+ * `repeating_group` itself (nesting is out of scope for v1) and NOT
+ * `calculated` (no per-instance calc plumbing yet). Child ids are unique only
+ * WITHIN the group (the select-option precedent, not the global block
+ * namespace), so the same child id can recur across two different groups.
+ *
+ * Value shape (locked, roadmap decision 4):
+ * `data[groupId]: GroupInstanceValue[]`, instances in respondent order. Key
+ * absent ⇔ zero instances (unanswered iff `minInstances` is 0).
+ *
+ * Scope walls (v1, strict): a child's `visibleIf` may reference ONLY
+ * same-group sibling ids, evaluated per instance over that instance's
+ * canonical values (see logic.ts's `visibleGroupChildren`). Nothing outside
+ * the group — top-level visibility, jumps, calc operands, piping — can
+ * reference a child id; both directions are schema hard errors.
+ */
+interface RepeatingGroupField extends BaseField {
+    kind: "repeating_group";
+    /** The repeated template. Child ids are unique WITHIN the group (the
+     *  select-option precedent, not the global block namespace). */
+    fields: Field[];
+    /** Respondent-controlled instance count, clamped server-side. 0..maxInstances,
+     *  default 1. */
+    minInstances?: number;
+    /** REQUIRED, 1..20 — bounded by design (also bounds the authoring-time
+     *  worst-case payload-size estimate). */
+    maxInstances: number;
+    /** "Add another" default via strings. */
+    addLabel?: string;
+    /** Names one instance — "Guest" → headings "Guest 2 of 3", announcements,
+     *  CSV column prefixes. Defaults to the field label. */
+    itemLabel?: string;
+}
 /**
  * A field type Fillo doesn't ship. You define it in code and supply the
  * renderer via the SDK's `customComponents` map, keyed by `component`. The
@@ -212,7 +259,7 @@ interface CustomField extends BaseField {
     /** Arbitrary options handed to your component. */
     config?: Record<string, unknown>;
 }
-type Field = TextField | PhoneField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CalculatedField | CustomField;
+type Field = TextField | PhoneField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CalculatedField | RepeatingGroupField | CustomField;
 interface HeadingBlock extends BaseBlock {
     kind: "heading";
     text: string;
@@ -389,6 +436,10 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
 type FieldValue = string | number | boolean | string[] | FileValue[]
 /** Matrix answers: rowId → columnId. */
  | Record<string, string>
+/** Repeating-group answers: one record per instance, in respondent order
+ *  (roadmap decision 4). A NAMED member — never smuggled through
+ *  JsonValue — so the discriminated union stays exhaustiveness-checkable. */
+ | GroupInstanceValue[]
 /** Custom fields hold arbitrary JSON. */
  | JsonValue | null | undefined;
 type ResponseData = Record<string, FieldValue>;
@@ -491,6 +542,27 @@ declare function allFields(form: FormSchema): Field[];
 declare function responseScopeValue(settings: FormSettings, data: ResponseData): string | null;
 /** Fields currently visible given the response data. */
 declare function visibleFields(form: FormSchema, data: ResponseData): Field[];
+/**
+ * THE scoped per-instance visibility resolver for a repeating group's
+ * children (contract decisions 3 + 4): given ONE instance's values, the
+ * template children currently visible in that instance, in template order.
+ * Both renderers (which rows to draw in instance n) and validateResponse
+ * (which children to require/keep in instance n) consume THIS one helper —
+ * no second engine. It literally IS the shared engine: the children run
+ * through the same {@link resolveLogicState} fixpoint a page of top-level
+ * fields would, over the instance's values — so canonical-value discipline
+ * (trim/coerce/empty-drop before any condition reads a sibling) and
+ * hidden-sibling cascading (a hidden controller reads as unanswered) behave
+ * exactly like top level, one scope down. Scope walls are enforced at schema
+ * time: a child's visibleIf can only name same-group siblings, so the
+ * instance's own values are the complete condition universe — outer answers
+ * can never matter here, and child values never leak out (the group is one
+ * opaque field in the top-level fixpoint). No calc pass runs because
+ * `calculated` children are schema-rejected (decision 2). A logic-hidden
+ * child is unanswered for its siblings AND skipped by per-instance
+ * validation, mirroring the top-level discipline.
+ */
+declare function visibleGroupChildren(group: RepeatingGroupField, instanceValues: GroupInstanceValue): Field[];
 /** Where navigation goes when leaving a page. */
 type NextPage = {
     to: string;
@@ -637,6 +709,16 @@ declare const FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
  * applicable floors).
  */
 declare const FILLO_CALC_MIN_SDK_VERSION = "0.11.0";
+/**
+ * The floor served INSTEAD of FILLO_MIN_SDK_VERSION for forms whose live
+ * schema contains a repeating_group field: the first release that ships the
+ * kind. Stricter than the calc case (recon risk 5): an old SDK's zod enum
+ * doesn't just strip one row, it drops the WHOLE templated section silently —
+ * worse than a blank row, because there is no visual trace a question ever
+ * existed. Non-negotiable; the form GET picks the max of the applicable
+ * floors (the Turnstile/calc precedent).
+ */
+declare const FILLO_GROUP_MIN_SDK_VERSION = "0.13.0";
 declare function normalizeSettings(value: unknown): FormSettings;
 interface SchemaValidationResult {
     ok: boolean;
@@ -899,6 +981,14 @@ declare function createEmptyForm(title?: string): FormSchema;
  * first two are code-only concerns and signature is too niche to draft well)
  * and calculated (an LLM can't reliably wire a calc AST to stable field ids —
  * owners add calculations deliberately, in the builder or in code).
+ * Also excludes repeating_group (contract decision 11): the flat FieldSpec →
+ * createBlock-defaults assembly has no nested-template channel, and a group
+ * needs structural choices an LLM gets wrong in ways the assembler can't
+ * repair — per-group-unique child ids, the v1 child-kind allowlist, and a
+ * deliberate maxInstances bound (required, 1–20). A malformed group is a
+ * schema HARD error, so a hallucinated one would brick the whole draft rather
+ * than degrade a field. Owners add groups deliberately, in the builder or in
+ * code — the calculated precedent.
  */
 declare const DRAFT_KINDS: readonly BlockKind[];
 /** The LLM-friendly intermediate shape. Everything optional but `kind`. */
@@ -1814,6 +1904,16 @@ interface FilloFieldStrings {
     errorSummaryTitle: string;
     /** Live-region announcement after a ranking move: "«label», position n of m". */
     rankingPosition: (label: string, position: number, count: number) => string;
+    /** Repeating group: the Add button's default label. */
+    groupAdd: string;
+    /** Repeating group instance heading — "«item» n of m". */
+    groupInstanceLabel: (item: string, position: number, count: number) => string;
+    /** Repeating group per-instance Remove button accessible label. */
+    groupRemoveLabel: (item: string, position: number) => string;
+    /** Live-region announcement after adding an instance. */
+    groupInstanceAdded: (item: string, position: number, count: number) => string;
+    /** Live-region announcement after removing an instance. */
+    groupInstanceRemoved: (item: string, count: number) => string;
     /** Live-region announcement once a phone country-picker selection commits
      *  (focus moves straight to the national input, so nothing else announces it). */
     phoneCountrySelected: (name: string) => string;
@@ -1954,6 +2054,11 @@ interface BlockSpec {
     optionChildren?: boolean;
     /** String children become the `text` prop (heading/paragraph). */
     textChildren?: boolean;
+    /** Accepts Fillo FIELD elements as children, compiled into the `fields`
+     *  template (repeating groups). The walk's flatten/classify/buildProps trio
+     *  is reentrant, so children build through the exact same path as top-level
+     *  blocks. Child ids are per-GROUP (checked here), not global. */
+    blockChildren?: boolean;
     /** Content blocks carry no label/required/etc. */
     content?: boolean;
 }
@@ -2074,4 +2179,4 @@ declare class Sha1 {
 }
 declare const sha1Base64: (bytes: Uint8Array) => string;
 
-export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CalcExpr, type CalculatedField, type ChallengeConfig, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CALC_MIN_SDK_VERSION, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, FILLO_MIN_SDK_VERSION, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, type FilloFieldStrings, FilloJsxError, type FilloRendererStrings, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, type JumpRule, type LinearScaleField, type MatrixField, type NextPage, type NumberField, PHONE_COUNTRIES, PHONE_PICKER_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsePhoneOptions, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, type ResponseData, type ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type TrustPolicy, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, computeCalculated, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, evaluateCalc, flagEmoji, formSchemasEqual, formatAnswer, formatGroupedNumber, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, isValidPartialNumberText, localeForNotation, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parseGroupedNumber, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, radioGroupStep, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, requiredFieldMessage, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, resolveThemeAppearance, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, when };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CalcExpr, type CalculatedField, type ChallengeConfig, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CALC_MIN_SDK_VERSION, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, FILLO_GROUP_MIN_SDK_VERSION, FILLO_MIN_SDK_VERSION, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, type FilloFieldStrings, FilloJsxError, type FilloRendererStrings, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type GroupInstanceValue, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, type JumpRule, type LinearScaleField, type MatrixField, type NextPage, type NumberField, PHONE_COUNTRIES, PHONE_PICKER_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsePhoneOptions, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, type RepeatingGroupField, type ResponseData, type ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type TrustPolicy, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, computeCalculated, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, evaluateCalc, flagEmoji, formSchemasEqual, formatAnswer, formatGroupedNumber, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, isValidPartialNumberText, localeForNotation, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parseGroupedNumber, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, radioGroupStep, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, requiredFieldMessage, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, resolveThemeAppearance, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visibleGroupChildren, visiblePageBlocks, when };

package/dist/index.js

@@ -13,9 +13,38 @@ function isEmpty(value) {
   if (typeof value === "object") return Object.keys(value).length === 0;
   return false;
 }
+function normalizeGroupValue(field2, value) {
+  if (!Array.isArray(value)) return void 0;
+  const childById = new Map(field2.fields.map((child) => [child.id, child]));
+  let changed = false;
+  const instances = value.map((instance) => {
+    if (!instance || typeof instance !== "object" || Array.isArray(instance)) return instance;
+    let instanceChanged = false;
+    const out = {};
+    for (const [key, raw] of Object.entries(instance)) {
+      const child = childById.get(key);
+      if (!child) {
+        instanceChanged = true;
+        continue;
+      }
+      const canonical = canonicalValue(child, raw);
+      if (canonical === void 0) {
+        instanceChanged = true;
+        continue;
+      }
+      out[key] = canonical;
+      if (canonical !== raw) instanceChanged = true;
+    }
+    if (!instanceChanged) return instance;
+    changed = true;
+    return out;
+  });
+  return changed ? instances : value;
+}
 function normalizeValue(field2, value) {
   if (value === void 0 || value === null) return value;
   if (field2.kind === "custom") return value;
+  if (field2.kind === "repeating_group") return normalizeGroupValue(field2, value);
   if (field2.kind === "number" && typeof value === "string" && value.trim() !== "") {
     const n = Number(value);
     return Number.isNaN(n) ? value : n;
@@ -190,7 +219,12 @@ function resolveLogicState(fields, data) {
   for (const f of fields) {
     if (f.kind === "calculated") continue;
     const value = canonicalValue(f, data[f.id]);
-    if (value !== void 0) canonical[f.id] = value;
+    if (value === void 0) continue;
+    if (f.kind === "repeating_group") {
+      const count = Array.isArray(value) ? value.length : 0;
+      if (count < Math.max(1, f.minInstances ?? 1)) continue;
+    }
+    canonical[f.id] = value;
   }
   let visible = scoped;
   let calc = {};
@@ -257,6 +291,11 @@ function visibleFields(form, data) {
   const visible = visibleFieldIds(fields, data);
   return fields.filter((f) => visible.has(f.id));
 }
+function visibleGroupChildren(group, instanceValues) {
+  const values = instanceValues && typeof instanceValues === "object" && !Array.isArray(instanceValues) ? instanceValues : {};
+  const state = resolveLogicState(group.fields, values);
+  return group.fields.filter((f) => state.visible.has(f.id));
+}
 function formResolver(form, data) {
   return resolveLogicState(allFields(form), data).resolve;
 }
@@ -754,6 +793,11 @@ var DEFAULT_FIELD_STRINGS = {
   submittingAnnouncement: "Submitting your response\u2026",
   errorSummaryTitle: "Check these fields",
   rankingPosition: (label, position, count) => `${label}, position ${position} of ${count}`,
+  groupAdd: "Add another",
+  groupInstanceLabel: (item, position, count) => `${item} ${position} of ${count}`,
+  groupRemoveLabel: (item, position) => `Remove ${item} ${position}`,
+  groupInstanceAdded: (item, position, count) => `${item} ${position} added, ${position} of ${count}`,
+  groupInstanceRemoved: (item, count) => count === 0 ? `${item} removed, none left` : `${item} removed, ${count} remaining`,
   phoneCountrySelected: (name) => `${name} selected`,
   phoneResultsCount: (count) => `${count} ${count === 1 ? "result" : "results"}`,
   signatureEmpty: "No signature yet",
@@ -778,9 +822,17 @@ var fileValueSchema = z.object({
   mime: z.string(),
   url: z.optional(z.string())
 });
+function groupCountError(field2, count) {
+  const min = Math.max(0, field2.minInstances ?? 1);
+  if (count < min) return `Add at least ${min} ${min === 1 ? "entry" : "entries"}`;
+  if (Number.isFinite(field2.maxInstances) && count > field2.maxInstances)
+    return `At most ${field2.maxInstances} ${field2.maxInstances === 1 ? "entry" : "entries"}`;
+  return null;
+}
 function validateField(field2, value) {
   if (isEmpty(value)) {
     if (field2.kind === "calculated") return null;
+    if (field2.kind === "repeating_group") return groupCountError(field2, 0);
     return field2.required ? REQUIRED_FIELD_MESSAGE : null;
   }
   switch (field2.kind) {
@@ -900,6 +952,17 @@ function validateField(field2, value) {
     case "calculated": {
       return null;
     }
+    case "repeating_group": {
+      if (!Array.isArray(value)) {
+        return groupCountError(field2, 0);
+      }
+      const instances = value;
+      for (const instance of instances) {
+        if (!instance || typeof instance !== "object" || Array.isArray(instance))
+          return "Invalid value";
+      }
+      return groupCountError(field2, instances.length);
+    }
     case "custom": {
       return null;
     }
@@ -929,6 +992,10 @@ function validateResponse(form, data) {
   for (const field2 of fields) {
     if (field2.kind === "calculated") continue;
     const value = normalizeValue(field2, data[field2.id]);
+    if (field2.kind === "repeating_group") {
+      validateGroupResponse(field2, value, errors, cleaned);
+      continue;
+    }
     const error = validateField(field2, value);
     if (error) {
       errors[field2.id] = error;
@@ -938,6 +1005,29 @@ function validateResponse(form, data) {
   }
   return { ok: Object.keys(errors).length === 0, errors, data: cleaned };
 }
+function validateGroupResponse(field2, value, errors, cleaned) {
+  const groupError = validateField(field2, value);
+  if (groupError) errors[field2.id] = groupError;
+  if (!Array.isArray(value)) return;
+  const instances = value;
+  const kept = [];
+  for (let index = 0; index < instances.length; index++) {
+    const instance = instances[index];
+    if (!instance || typeof instance !== "object" || Array.isArray(instance)) continue;
+    const keptInstance = {};
+    for (const child of visibleGroupChildren(field2, instance)) {
+      const childValue = instance[child.id];
+      const childError = validateField(child, childValue);
+      if (childError) {
+        errors[`${field2.id}.${index}.${child.id}`] = childError;
+      } else if (!isEmpty(childValue)) {
+        keptInstance[child.id] = childValue;
+      }
+    }
+    kept.push(keptInstance);
+  }
+  if (!groupError && kept.length > 0) cleaned[field2.id] = kept;
+}
 
 // src/schema-validation.ts
 import * as z2 from "zod/mini";
@@ -961,6 +1051,7 @@ var FIELD_KINDS = [
   "file_upload",
   "hidden",
   "calculated",
+  "repeating_group",
   "custom"
 ];
 var CONTENT_KINDS2 = ["heading", "paragraph", "divider"];
@@ -997,10 +1088,11 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.12.1" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.13.0" : "0.0.0-dev";
 var FILLO_MIN_SDK_VERSION = "0.4.0";
 var FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
 var FILLO_CALC_MIN_SDK_VERSION = "0.11.0";
+var FILLO_GROUP_MIN_SDK_VERSION = "0.13.0";
 function str(value, max, fallback = "") {
   return typeof value === "string" ? value.trim().slice(0, max) : fallback;
 }
@@ -1170,7 +1262,7 @@ function collectCalcRefs(expr, valueRefs, whenRefs) {
       return;
   }
 }
-function validateCalculatedFields(pages) {
+function validateCalculatedFields(pages, childToGroup) {
   const kinds = /* @__PURE__ */ new Map();
   for (const page of pages) {
     for (const block of page.blocks) if (isField(block)) kinds.set(block.id, block.kind);
@@ -1190,6 +1282,10 @@ function validateCalculatedFields(pages) {
       for (const ref of valueRefs) {
         const kind = kinds.get(ref);
         if (kind === void 0) {
+          const owningGroup = childToGroup.get(ref);
+          if (owningGroup !== void 0) {
+            return `Calculated field ${block.id} references ${ref}, which is a child of repeating group ${owningGroup} \u2014 calculations can't reach inside a repeating group (calc operands must be top-level fields)`;
+          }
           return `Calculated field ${block.id} references a missing field: ${ref} \u2014 remove the reference or restore that field`;
         }
         if (!CALC_OPERAND_KINDS.includes(kind)) {
@@ -1263,6 +1359,151 @@ function calcComplexityError(pages) {
   }
   return null;
 }
+var GROUP_CHILD_ALLOWED_KINDS = [
+  "short_text",
+  "long_text",
+  "email",
+  "url",
+  "phone",
+  "number",
+  "select",
+  "multi_select",
+  "dropdown",
+  "checkbox",
+  "date",
+  "rating",
+  "linear_scale"
+];
+var MAX_GROUP_TEMPLATE_CHILDREN = 12;
+var MAX_GROUP_ESTIMATED_BYTES = 18e4;
+function worstCaseChildBytes(child) {
+  const overhead = child.id.length + 20;
+  switch (child.kind) {
+    case "short_text":
+    case "email":
+    case "url":
+      return overhead + (child.maxLength ?? 2e3);
+    case "long_text":
+      return overhead + (child.maxLength ?? 2e4);
+    case "phone":
+      return overhead + 32;
+    case "number":
+      return overhead + 32;
+    case "select":
+    case "dropdown": {
+      const longestOption = child.options.reduce((max, o) => Math.max(max, o.id.length), 0);
+      return overhead + Math.max(longestOption, child.allowOther ? 500 : 0);
+    }
+    case "multi_select": {
+      const everyOption = child.options.reduce((sum, o) => sum + o.id.length + 3, 0);
+      return overhead + everyOption + (child.allowOther ? 500 : 0);
+    }
+    case "checkbox":
+      return overhead + 8;
+    case "date":
+      return overhead + 16;
+    case "rating":
+    case "linear_scale":
+      return overhead + 8;
+    default:
+      return overhead + 64;
+  }
+}
+function groupSizeEstimate(field2) {
+  const perInstance = field2.fields.reduce((sum, child) => sum + worstCaseChildBytes(child), 24);
+  return perInstance * (Number.isFinite(field2.maxInstances) ? field2.maxInstances : 0);
+}
+function validateRepeatingGroups(pages) {
+  for (const page of pages) {
+    for (const block of page.blocks) {
+      if (block.kind !== "repeating_group") continue;
+      if (!Number.isInteger(block.maxInstances) || block.maxInstances < 1 || block.maxInstances > 20) {
+        return `Repeating group ${block.id} needs maxInstances to be a whole number between 1 and 20`;
+      }
+      const minInstances = block.minInstances ?? 1;
+      if (!Number.isInteger(minInstances) || minInstances < 0 || minInstances > block.maxInstances) {
+        return `Repeating group ${block.id} needs minInstances to be a whole number between 0 and maxInstances (${block.maxInstances})`;
+      }
+      block.minInstances = minInstances;
+      if (block.fields.length === 0) {
+        return `Repeating group ${block.id} has no template fields \u2014 add at least one field to repeat`;
+      }
+      if (block.fields.length > MAX_GROUP_TEMPLATE_CHILDREN) {
+        return `Repeating group ${block.id} has ${block.fields.length} template fields \u2014 the maximum is ${MAX_GROUP_TEMPLATE_CHILDREN}; split it into fewer fields`;
+      }
+      for (const child of block.fields) {
+        if (!GROUP_CHILD_ALLOWED_KINDS.includes(child.kind)) {
+          return `Repeating group ${block.id} has a "${child.kind}" child (${child.id}) \u2014 allowed child kinds are ${GROUP_CHILD_ALLOWED_KINDS.join(", ")}`;
+        }
+      }
+      const duplicateChild = duplicateOptionId(block.fields);
+      if (duplicateChild) {
+        return `Duplicate child id in repeating group ${block.id}: ${duplicateChild}`;
+      }
+      const siblingIds = new Set(block.fields.map((f) => f.id));
+      for (const child of block.fields) {
+        for (const cond of child.visibleIf ?? []) {
+          if (!siblingIds.has(cond.fieldId)) {
+            return `Field ${child.id} in repeating group ${block.id} has a visibleIf referencing "${cond.fieldId}" \u2014 a child's visibleIf can only reference another field in the SAME group`;
+          }
+        }
+      }
+      const estimate = groupSizeEstimate(block);
+      if (estimate > MAX_GROUP_ESTIMATED_BYTES) {
+        return `Repeating group ${block.id} could reach ~${Math.ceil(estimate / 1e3)}KB at ${block.maxInstances} instances \u2014 the maximum is ~${Math.round(MAX_GROUP_ESTIMATED_BYTES / 1e3)}KB; lower maxInstances, shorten text limits, or trim the template`;
+      }
+    }
+  }
+  return null;
+}
+function collectGroupChildIds(pages) {
+  const topLevelIds = /* @__PURE__ */ new Set();
+  for (const page of pages) {
+    for (const block of page.blocks) if (isField(block)) topLevelIds.add(block.id);
+  }
+  const childToGroup = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    for (const block of page.blocks) {
+      if (block.kind !== "repeating_group") continue;
+      for (const child of block.fields) {
+        if (!topLevelIds.has(child.id) && !childToGroup.has(child.id)) {
+          childToGroup.set(child.id, block.id);
+        }
+      }
+    }
+  }
+  return childToGroup;
+}
+function groupScopeWallError(pages, rawPages, childToGroup) {
+  for (const page of pages) {
+    for (const block of page.blocks) {
+      for (const cond of block.visibleIf ?? []) {
+        const owner = childToGroup.get(cond.fieldId);
+        if (owner !== void 0) {
+          return `Field ${block.id}'s visibleIf references "${cond.fieldId}", which is a child of repeating group ${owner} \u2014 fields outside a repeating group can't reference its children`;
+        }
+      }
+    }
+  }
+  for (const page of rawPages) {
+    if (!Array.isArray(page.next)) continue;
+    for (const rule of page.next) {
+      if (!rule || typeof rule !== "object") continue;
+      const when2 = rule.when;
+      if (!Array.isArray(when2)) continue;
+      for (const cond of when2) {
+        if (!cond || typeof cond !== "object") continue;
+        const fieldId = cond.fieldId;
+        if (typeof fieldId !== "string") continue;
+        const owner = childToGroup.get(fieldId);
+        if (owner !== void 0) {
+          return `A jump rule on page ${page.id} references "${fieldId}", which is a child of repeating group ${owner} \u2014 jumps can't reference a repeating group's children`;
+        }
+      }
+    }
+  }
+  return null;
+}
 function baseBlock(rec) {
   return {
     id: str(rec.id, 128),
@@ -1476,6 +1717,33 @@ function normalizeBlock(input) {
           return item ? [item] : [];
         }).slice(0, 50) : void 0
       });
+    case "repeating_group": {
+      const rawFields = Array.isArray(rec.fields) ? rec.fields : [];
+      const fields = rawFields.slice(0, 50).flatMap((raw) => {
+        const child = normalizeBlock(raw);
+        return child && isField(child) ? [child] : [];
+      });
+      return cleanObject({
+        ...baseField(rec, kind),
+        // A container's OWN completeness is governed by minInstances (0 is a
+        // legitimate "this group is optional"), not the generic required
+        // flag — a separately-true `required` would be redundant at best and
+        // self-contradictory at worst (the hidden/calculated precedent).
+        required: false,
+        fields,
+        // Bounds become authoritative in validateRepeatingGroups as HARD
+        // ERRORS, not silent clamps (unlike rating.max/linear_scale.min-max)
+        // — instances are respondent-controlled wire shape, not cosmetic
+        // display config. maxInstances is schema-REQUIRED, so a missing/
+        // non-finite raw value becomes NaN here (fails every bounds check on
+        // its own) rather than a fabricated fallback the post-pass would
+        // have to override anyway.
+        maxInstances: finite(rec.maxInstances) ?? Number.NaN,
+        minInstances: finite(rec.minInstances),
+        addLabel: optionalStr(rec.addLabel, 100),
+        itemLabel: optionalStr(rec.itemLabel, 100)
+      });
+    }
     case "custom":
       return cleanObject({
         ...baseField(rec, kind),
@@ -1564,7 +1832,12 @@ function normalizeFormSchema(input) {
       }
     }
   }
-  const calcError = validateCalculatedFields(pages);
+  const groupError = validateRepeatingGroups(pages);
+  if (groupError) return { ok: false, error: groupError };
+  const childToGroup = collectGroupChildIds(pages);
+  const wallError = groupScopeWallError(pages, rebuilt, childToGroup);
+  if (wallError) return { ok: false, error: wallError };
+  const calcError = validateCalculatedFields(pages, childToGroup);
   if (calcError) return { ok: false, error: calcError };
   const calcComplexity = calcComplexityError(pages);
   if (calcComplexity) return { ok: false, error: calcComplexity };
@@ -1653,6 +1926,19 @@ function formatAnswer(field2, value) {
       const text = field2.decimals === void 0 ? String(n) : n.toFixed(Math.max(0, Math.min(6, field2.decimals)));
       return `${field2.prefix ?? ""}${text}${field2.suffix ?? ""}`;
     }
+    case "repeating_group": {
+      if (!Array.isArray(value)) return String(value);
+      const instances = value;
+      if (instances.length === 0) return "";
+      const noun = field2.itemLabel ?? field2.label;
+      const summary = `${instances.length} \xD7 ${noun}`;
+      const firstChild = field2.fields[0];
+      if (!firstChild) return summary;
+      const previews = instances.map(
+        (instance) => instance && typeof instance === "object" && !Array.isArray(instance) ? formatAnswer(firstChild, instance[firstChild.id]) : ""
+      ).filter((text) => text !== "");
+      return previews.length > 0 ? `${summary}: ${previews.join(", ")}` : summary;
+    }
     case "phone": {
       const { country, national, e164 } = parsePhone(String(value));
       if (!e164) return String(value);
@@ -1815,6 +2101,7 @@ var BLOCK_KIND_META = {
   file_upload: { label: "File upload", hint: "Direct to connected storage" },
   hidden: { label: "Hidden field", hint: "Filled from the URL" },
   calculated: { label: "Calculated value", hint: "Computed from other answers" },
+  repeating_group: { label: "Repeating group", hint: "A set of fields respondents can repeat" },
   custom: { label: "Custom", hint: "Your own component (code only)" },
   heading: { label: "Heading", hint: "Section title" },
   paragraph: { label: "Paragraph", hint: "Explanatory text" },
@@ -1886,6 +2173,14 @@ function createBlock(kind) {
       return { id, kind, label: "Hidden field" };
     case "calculated":
       return { id, kind, label: "Calculated value", calc: { op: "const", value: 0 } };
+    case "repeating_group":
+      return {
+        id,
+        kind,
+        label: "Repeating group",
+        maxInstances: 5,
+        fields: [{ id: createId(6), kind: "short_text", label: "Short text" }]
+      };
     case "custom":
       return { id, kind, label: "Custom field", component: "" };
     case "file_upload":
@@ -2919,6 +3214,8 @@ function prefillFromParams(form, params) {
       case "calculated":
         break;
       // engine-computed, never prefillable — a crafted URL can't seed it
+      case "repeating_group":
+        break;
       default:
         data[field2.id] = raw;
     }
@@ -3347,8 +3644,11 @@ function createFormController(options2) {
     data = computeCalculated(form, { ...data, [fieldId]: value });
     onChange?.(data);
     submitError = void 0;
-    if (fieldId in errors) {
-      errors = Object.fromEntries(Object.entries(errors).filter(([k]) => k !== fieldId));
+    const prefix = `${fieldId}.`;
+    if (fieldId in errors || Object.keys(errors).some((k) => k.startsWith(prefix))) {
+      errors = Object.fromEntries(
+        Object.entries(errors).filter(([k]) => k !== fieldId && !k.startsWith(prefix))
+      );
     }
     notify();
     scheduleDraftSave();
@@ -3952,6 +4252,9 @@ var JSX_BLOCK_SPECS = [
   field("FileUpload", "file_upload", ["maxFiles", "maxFileSizeMb", "accept"]),
   field("Hidden", "hidden", ["paramName", "defaultValue"]),
   field("Calculated", "calculated", ["calc", "decimals", "prefix", "suffix"]),
+  field("RepeatingGroup", "repeating_group", ["minInstances", "maxInstances", "addLabel", "itemLabel"], {
+    blockChildren: true
+  }),
   field("Custom", "custom", ["component", "config"]),
   content("Heading", "heading", true),
   content("Paragraph", "paragraph", true),
@@ -4055,6 +4358,29 @@ function buildProps(spec, el) {
       );
     }
     out.__childText = parts.join("");
+  } else if (spec.blockChildren && props.children !== void 0) {
+    const childBlocks = flatten(props.children).map((child) => {
+      const childSpec = classify(child);
+      if (childSpec.kind === "__page" || childSpec.kind === "__option" || childSpec.content) {
+        throw new FilloJsxError(
+          "NON_FILLO_CHILD",
+          `Fillo.${spec.name} "${id}" children must be field elements, found Fillo.${childSpec.name} \u2014 a repeating group's template holds answerable fields only`
+        );
+      }
+      return buildProps(childSpec, child);
+    });
+    const childIds = /* @__PURE__ */ new Set();
+    for (const child of childBlocks) {
+      const childId = child.id;
+      if (childIds.has(childId)) {
+        throw new FilloJsxError(
+          "DUPLICATE_ID",
+          `Two fields in repeating group "${id}" share the id "${childId}" \u2014 child ids key instance answers and must be unique within the group`
+        );
+      }
+      childIds.add(childId);
+    }
+    out.__childBlocks = childBlocks;
   } else if (props.children !== void 0) {
     throw new FilloJsxError(
       "NON_FILLO_CHILD",
@@ -4077,6 +4403,16 @@ function buildProps(spec, el) {
   if (spec.textChildren && out.text === void 0) {
     throw new FilloJsxError("TEXT_CHILD_REQUIRED", `Fillo.${spec.name} "${id}" has no text`);
   }
+  if (spec.blockChildren) {
+    if (out.__childBlocks === void 0) {
+      throw new FilloJsxError(
+        "TEXT_CHILD_REQUIRED",
+        `Fillo.${spec.name} "${id}" has no fields \u2014 a repeating group needs at least one field element as a child (empty templates are invalid)`
+      );
+    }
+    out.fields = out.__childBlocks;
+    delete out.__childBlocks;
+  }
   if (props.visibleIf !== void 0) {
     const conditions2 = Array.isArray(props.visibleIf) ? props.visibleIf : [props.visibleIf];
     out.visibleIf = conditions2;
@@ -4184,6 +4520,11 @@ function schemaFromJsx(children, meta) {
         assertUniqueOptionIds(block.id, block.rows, "matrix rows");
         assertUniqueOptionIds(block.id, block.columns, "matrix columns");
       }
+      if (block.kind === "repeating_group") {
+        for (const child of block.fields) {
+          if ("options" in child) assertUniqueOptionIds(child.id, child.options, "options");
+        }
+      }
     }
   }
   return {
@@ -4281,6 +4622,7 @@ export {
   FILLO_CALC_MIN_SDK_VERSION,
   FILLO_CHALLENGE_MIN_SDK_VERSION,
   FILLO_DATA_ATTRS,
+  FILLO_GROUP_MIN_SDK_VERSION,
   FILLO_MIN_SDK_VERSION,
   FILLO_SCHEMA_VERSION,
   FILLO_SDK_VERSION,
@@ -4362,6 +4704,7 @@ export {
   validateResponse,
   visibleBlocks,
   visibleFields,
+  visibleGroupChildren,
   visiblePageBlocks,
   when
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [