Skip to content
cinpeCanPublic

About

Multiplatform force-directed physics UI SDK for Compose Multiplatform (Android, iOS, Desktop, Web/Wasm) & Android Views — interactive graphs & spring links.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Repository files navigation

Deponder

Maven Central

中文说明

A Multiplatform Physics Interaction SDK for Android Views and Compose Multiplatform (Android, iOS, Desktop, Web/Wasm).

Decouple force-directed physics from layout containers via lightweight Compose Modifiers and Android View extensions. Add attraction-repulsion fields, spring links, and smooth dragging directly to standard UI components without wrapper layouts or view-tree mutations — ideal for knowledge graphs, topology views, interactive tag clouds, and floating cards.

Deponder demo

Key Features

  • Unified Cross-Stack API: Identical 5-part mental model and dp-based physics configuration across Compose Multiplatform and Android Views, with full Java interop.
  • Low-Intrusive & Gesture-Safe: Preserves standard .clickable {}, OnClickListener, and ripple feedback via touchSlop gating and root-space coordinate projection; elevates dragged items via zIndex / translationZ without reordering child views or mutating clipChildren / clipToBounds.
  • Content-Adaptive Spring Length & WindowInsets-Style Safe Areas: RubberPhysics() automatically adapts spring natural length to measured label/badge width by default (RubberPhysics.auto(...) to customize padding & min/max bounds, or RubberPhysics(naturalLengthDp = 120f) / XML app:deponderNaturalLength="wrap_content | 120dp" for fixed rest lengths), while DeponderRubberInsets orthogonally controls UI endpoint clearance (Default contour estimation, fixed(dp), None center-to-center spans, startOnly / endOnly); includes ready-to-use DeponderDefaultRubber (Compose) and DeponderRubberView (Android View / XML) with floating labels and directional arrowheads (automatically omitted on center-anchored endpoints).
  • Opt-In Sparse Topological Unfolding (0.6.0, RootPhysics.withUnfold(true)): Disabled by default (false) to preserve strictly local point-mass physics; when enabled, a deterministic O(K * (|V| + |E|)) solver (degree-1 tree peeling, Farthest-First PivotMDS, bounded Sparse Stress Majorization, radial subtree fanning, and Procrustes alignment) smoothly untangles knotted cycles, trees, grids, and disconnected islands during topology changes or reheat() before fading out completely into pure Newtonian springs and 0% CPU sleep.
  • Frame-Rate-Independent Physics Kernel (deponder-core):
    • Consistent Motion Across 60Hz–240Hz: Adaptive 1/120s sub-stepping keeps simulation speed consistent across display refresh rates, paired with deterministic symmetry breaking for stacked or collinear nodes.
    • Idle 0% CPU & 3-Tier Hybrid Quadtree: Dual velocity/acceleration sleep thresholds drop CPU usage to 0% at rest with instant drag wakeup, scaling automatically across node counts (< 64 direct array, 64–255 single-thread quadtree, 256+ parallel snapshot evaluation on Dispatchers.Default).
    • Layer-Only Frame Updates: Drives displacement and deformation via Compose Modifier.Node graphics layers and Android View layer transforms without triggering per-frame relayout or recomposition.
  • Minimal Transitive Footprint: deponder-core depends only on kotlin-stdlib and kotlinx-coroutines-core; deponder-compose depends strictly on deponder-core, compose-runtime, and compose-ui (zero compose-foundation or Material dependency); deponder exposes only deponder-core and lifecycle-common.

Core Concepts at a Glance

Role Compose API Android View API Purpose
Root Field Modifier.deponderRoot viewGroup.deponderRoot Establishes the physics coordinate space and frame loop on a container
Node (Planet) Modifier.deponderPlanet view.deponderPlanet Registers a UI component as a physics body with mass, repulsion radius, or pinning
Spring Link (Rubber) Modifier.deponderRubber view.deponderRubber Connects two node IDs with configurable spring attraction (or use built-in default rubbers)
Link Transform (Stretch) Modifier.deponderStretch view.deponderStretch Stretches and rotates a custom link component dynamically between two nodes
Drag Gesture (Drag) Modifier.deponderDrag view.deponderDrag Adds opt-in, click-safe physics dragging to a node

Artifacts & Setup

Artifact Target UI Stack Platforms
io.github.cinpecan:deponder-compose:0.6.0 Jetpack Compose & Compose Multiplatform Android, iOS, Desktop (JVM 17), Web (wasmJs)
io.github.cinpecan:deponder:0.6.0 Traditional Android View / ViewGroup Android (minSdk 23, JVM 17)
io.github.cinpecan:deponder-core:0.6.0 UI-agnostic KMP physics kernel (custom Canvas / headless graphs) Android, iOS, Desktop (JVM 17), Web (wasmJs)
io.github.cinpecan:deponder-bom:0.6.0 Version alignment BOM (optional for hybrid projects) All

Compose Multiplatform (commonMain) or Pure Jetpack Compose:

dependencies {
    implementation("io.github.cinpecan:deponder-compose:0.6.0")
}

Traditional Android View:

dependencies {
    implementation("io.github.cinpecan:deponder:0.6.0")
}

Hybrid Android View + Compose Project (with BOM):

dependencies {
    implementation(platform("io.github.cinpecan:deponder-bom:0.6.0"))
    implementation("io.github.cinpecan:deponder")
    implementation("io.github.cinpecan:deponder-compose")
}

Quick Start: Compose Multiplatform

Host Modifier.deponderRoot on an unconstrained container such as Box. In Compose, deponderPlanet and deponderRubber can be declared at any static nesting depth inside deponderRoot.

val state = rememberDeponderState(
    RootPhysics.fromPreset(DeponderDefaults.Presets.Balanced)
        .withUnfold(true) // Optional (default false): smoothly untangle cycles, trees, and meshes
)

Box(modifier = Modifier.fillMaxSize().deponderRoot(state)) {
    // 1. Ready-to-use default spring link (for custom link UIs, combine Modifier.deponderRubber + Modifier.deponderStretch)
    links.forEach { link ->
        DeponderDefaultRubber(
            startId = link.fromId,
            endId = link.toId,
            label = link.relation,
            arrowMode = DeponderArrowMode.BOTH,
            physics = RubberPhysics(), // Auto-adapts to label length by default; pass naturalLengthDp = 120f or RubberPhysics.auto(...) to customize
            insets = DeponderRubberInsets.Default, // or DeponderRubberInsets.None for center-to-center lines
        )
    }

    // 2. Any standard Composable — layer-only updates with zero recomposition during physics frames
    nodes.forEach { node ->
        NodeCardComposable(
            node = node,
            modifier = Modifier
                .deponderPlanet(
                    id = node.id,
                    physics = PlanetPhysics(repulsionRadiusDp = 90f, pinned = node.isAnchor),
                )
                .deponderDrag()
                .clickable { onNodeClicked(node) },
        )
    }
}

// Runtime control: state.submitScale(1.2f), state.submitRubberElasticity(2.4f), state.setPinned(id, true)

Quick Start: Android View (Kotlin & Java)

Host deponderRoot on an unconstrained ViewGroup such as FrameLayout, ConstraintLayout, or CoordinatorLayout (deponderPlanet and deponderRubber views must be direct children of deponderRoot).

val controller = rootFrameLayout.deponderRoot(
    lifecycleOwner = this,
    physics = RootPhysics.fromPreset(DeponderDefaults.Presets.Balanced)
        .withUnfold(true), // Optional (default false): smoothly untangle cycles, trees, and meshes
)

// Ready-to-use default spring View (also supports XML <com.cinpe.deponder.DeponderRubberView>;
// for custom compound link Views, combine view.deponderRubber(...) with view.deponderStretch() or @string/deponder_stretch)
val rubberView = DeponderRubberView(this)
    .withLabel("depends on")
    .withArrowMode(DeponderArrowMode.END)
rootFrameLayout.addView(rubberView)
rubberView.deponderRubber("core", "ui") // Auto-adapts to label length by default; pass RubberPhysics(naturalLengthDp = 120f) to lock fixed length

// Configure force fields and dragging on direct-child Views while keeping setOnClickListener intact
cardCore.deponderPlanet("core", PlanetPhysics(pinned = true))
cardUi.deponderPlanet("ui")
cardUi.deponderDrag()
cardUi.setOnClickListener { showDetail("ui") }

// Runtime control: controller.submitScale(1.2f), controller.submitRubberElasticity(2.4f), controller.cancel()

Java callers can use static & fluent helpers on DeponderViews (deponderRoot, deponderPlanet, deponderRubber, deponderStretch, deponderDrag) and new DeponderRubberView(context).withLabel(...).

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Copyright (c) 2022-present, Cinpecan and Deponder Contributors.
Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0

About

Multiplatform force-directed physics UI SDK for Compose Multiplatform (Android, iOS, Desktop, Web/Wasm) & Android Views — interactive graphs & spring links.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages