Documentation Index

Fetch the complete documentation index at: https://docs.joyfill.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Migration guide for v1.x.x to v2.x.x

​

What changed at a glance

• Dependencies: use standard io.joyfill:* artifacts for v2, or io.joyfill:legacy-* to remain on v1 (details, stay on v1)
• Package names: v2-beta code under joyfill2 moved to joyfill in v2 — rename imports from joyfill2 → joyfill (details)
• Event API: legacy FieldEvent has been replaced by ComponentEvent.* — use ComponentEvent.FieldEvent (standalone fields) and ComponentEvent.CellEvent (table cells) (details)
• Behavior notes: most imports remain identical for v1→v2 because the package is still joyfill; some v1 UI components may not exist in v2 — check v2 docs for alternatives (details)

​

Dependencies changes

• Replace legacy artifacts with the standard ones:
  • io.joyfill:legacy-compose → io.joyfill:compose
  • io.joyfill:legacy-models → io.joyfill:models
  • io.joyfill:legacy-builder → io.joyfill:builder
  • io.joyfill:legacy-api → io.joyfill:api

// BEFORE (v1)
dependencies {
    implementation("io.joyfill:legacy-compose:<version>")
    implementation("io.joyfill:legacy-models:<version>")
    implementation("io.joyfill:legacy-builder:<version>")
    implementation("io.joyfill:legacy-api:<version>")
}

// AFTER (v2)
dependencies {
    implementation("io.joyfill:compose:<version>")
    implementation("io.joyfill:models:<version>")
    implementation("io.joyfill:builder:<version>")
    implementation("io.joyfill:api:<version>")
}

• Keep using joyfill.* imports.
• Example usage:

Form(
    editor = rememberEditor(document = doc),
    mode = Mode.fill,
)

​

FieldEvent → ComponentEvent.* (events)

• v1 used a single FieldEvent for all field callbacks.
• v2 unifies events under ComponentEvent.* with two concrete types:
  • ComponentEvent.FieldEvent<E> for standalone fields (text, number, image, signature, etc.)
  • ComponentEvent.CellEvent<E> for table cells (row-aware events)
• Handler parameter types changed accordingly in Form/components.

• The v2 architecture standardizes how components emit and consume events and makes table events first-class by including row/column context.

• v1 (legacy): joyfill.FieldEvent
• v2: joyfill.ComponentEvent.FieldEvent and joyfill.ComponentEvent.CellEvent

• Common in both versions:
  • fieldId, fieldIdentifier, pageId, id (document id), identifier (document identifier), fileId, fieldPositionId
• v2 additions/notes:
  • source: the typed editor instance (e.g., ImageEditor, TextEditor)
  • multi: available when the underlying component is a file component (e.g., image with multi-upload)
  • Cell-only: rowIds, columnId, schemaId, parentPath

1. General field handlers (change/focus/blur)

• v1 (legacy Form):

Form(
    // ...
    onFieldChange = { e: FieldEvent -> /* use e.fieldId, e.pageId, ... */ },
    onFocus = { e: FieldEvent -> /* ... */ },
    onBlur = { e: FieldEvent -> /* ... */ },
)

• v2 (Form/components):

Form(
    // ...
    onFieldChange = { e: ComponentEvent<*> ->
        when (e) {
            is ComponentEvent.FieldEvent<*> -> { /* standalone field */ }
            is ComponentEvent.CellEvent<*>  -> { /* table cell */ }
        }
    },
    onFocus = { e: ComponentEvent<*> -> /* same pattern as above */ },
    onBlur  = { e: ComponentEvent<*> -> /* same pattern as above */ },
)

2. File upload/capture handlers (image/signature/barcode)

• v1:

Form(
    onUpload = { e: FieldEvent -> listOf("https://.../file1") },
    onCapture = { e: FieldEvent -> "barcode-or-text" },
)

• v2:

Form(
    onUpload = { e: ComponentEvent<joyfill.editors.file.AbstractFileEditor> ->
        // Optional: narrow by editor type
        when (val src = e.source) {
            is joyfill.editors.image.ImageEditor -> listOf("https://.../img1")
            is joyfill.editors.signature.SignatureEditor -> listOf("https://.../sig1")
            else -> emptyList()
        }
    },
    onCapture = { e: ComponentEvent<joyfill.editors.components.AbstractCompStringEditor> ->
        // Example for barcode/text-capable components
        when (e.source) {
            is joyfill.editors.barcode.BarcodeEditor -> "scanned-barcode"
            else -> null
        }
    },
)

3. Table cell events

• v2 introduces CellEvent for row-aware callbacks used by table components and their editors:

val handler: (ComponentEvent.CellEvent<*>) -> Unit = { e ->
    val rowIds = e.rowIds  // one or more row ids affected
    val columnId = e.columnId
    val fieldId = e.fieldId
    // handle per-row updates, analytics, etc.
}

• Replace callback parameter types:
  • FieldEvent → ComponentEvent<*> when used at the Form level
  • For table-specific handlers: prefer ComponentEvent.CellEvent<*>
  • For single-field components: prefer ComponentEvent.FieldEvent<*>
• Update when branches to handle both FieldEvent and CellEvent where applicable.
• If you previously relied on attachments in events: v2 surfaces file uploads through file editors and returns should come from your handler; attachments on events is not required in typical flows.

• ComponentEvent is generic on the editor type (E : ComponentEditor). When you need editor-specific behavior, check e.source with is ImageEditor etc.

• v2 event system overview: architecture/v2/event-system.md

​

FAQ

• Ensure you’re using the standard artifacts (no legacy- prefix).
• Confirm your imports are joyfill.* and that you do NOT have joyfill2.* anywhere.

• Some components may be missing in v2 compared to v1, but v2 offers many new features and improved architecture. See the v2 docs for details.

​

Related Documentation

• Architecture Overview: architecture/README.md
• V2 Overview: architecture/v2/README.md
• V2 UI Components: architecture/v2/ui-components.md
• V2 Editor Pattern: architecture/v2/editor-pattern.md
• V2 API Integration: architecture/v2/api-integration.md

​

Important context

• Prior to v2 release, we had:
  • v1 under the joyfill package
  • v2-beta under the joyfill2 package
• With the v2 release:
  • v2 now lives under the joyfill package
  • Legacy v1 classes were moved into separate legacy modules, but kept the same joyfill package names for source compatibility
  • Practically, both legacy and v2 expose symbols like joyfill.Form. Which one you use depends on the dependency you add.

• V1 → V2: swap your dependencies from legacy modules to v2 modules. Most imports remain identical because the package is still joyfill.
• V2-beta → V2: rename your imports from joyfill2 to joyfill. No other code changes should be required.

​

Stay on v1 (Legacy Modules)

[!CAUTION] This is not RECOMMENDED. This is a temporary path for those who want to continue using v1 for a short period of time.

• If you want to continue using the legacy v1 implementation for a period, switch your dependencies to the legacy-* artifacts.
• Imports remain joyfill.* because legacy modules preserve the same package names.

• Replace standard artifacts with legacy ones if you were previously on the standard artifacts but wish to remain on v1:
  • io.joyfill:compose → io.joyfill:legacy-compose
  • io.joyfill:models → io.joyfill:legacy-models
  • io.joyfill:builder → io.joyfill:legacy-builder
  • io.joyfill:api → io.joyfill:legacy-api

// BEFORE (standard artifacts)
dependencies {
    implementation("io.joyfill:compose:<version>")
    implementation("io.joyfill:models:<version>")
    implementation("io.joyfill:builder:<version>")
    implementation("io.joyfill:api:<version>")
}

// AFTER (stay on v1 legacy)
dependencies {
    implementation("io.joyfill:legacy-compose:<version>")
    implementation("io.joyfill:legacy-models:<version>")
    implementation("io.joyfill:legacy-builder:<version>")
    implementation("io.joyfill:legacy-api:<version>")
}

• Ensure your imports remain joyfill.* and not joyfill2.*.
• Confirm you’re pulling legacy-* artifacts in your dependency tree.

• This path is intended for temporary continuity. Plan to migrate to v2 soon.