Custom activity toolbars

1
/*
2
 *   Copyright © 2026 PSPDFKit GmbH. All rights reserved.
3
 *
4
 *   The PSPDFKit Sample applications are licensed with a modified BSD license.
5
 *   Please see License for details. This notice may not be removed from this file.
6
 */
7
@file:OptIn(ExperimentalLayoutApi::class)
8

9
package com.pspdfkit.catalog.examples.kotlin
10

11
import android.content.Context
12
import android.content.Intent
13
import android.net.Uri
14
import android.os.Bundle
15
import android.view.View
16
import android.view.ViewGroup
17
import android.widget.FrameLayout
18
import androidx.activity.compose.setContent
19
import androidx.appcompat.app.AppCompatActivity
20
import androidx.compose.animation.AnimatedVisibility
21
import androidx.compose.animation.core.tween
22
import androidx.compose.animation.fadeIn
23
import androidx.compose.animation.fadeOut
24
import androidx.compose.foundation.ScrollState
25
import androidx.compose.foundation.background
26
import androidx.compose.foundation.horizontalScroll
27
import androidx.compose.foundation.layout.Arrangement
28
import androidx.compose.foundation.layout.Box
29
import androidx.compose.foundation.layout.BoxScope
30
import androidx.compose.foundation.layout.ExperimentalLayoutApi
31
import androidx.compose.foundation.layout.Row
32
import androidx.compose.foundation.layout.WindowInsets
33
import androidx.compose.foundation.layout.WindowInsetsSides
34
import androidx.compose.foundation.layout.displayCutout
35
import androidx.compose.foundation.layout.fillMaxSize
36
import androidx.compose.foundation.layout.fillMaxWidth
37
import androidx.compose.foundation.layout.ime
38
import androidx.compose.foundation.layout.only
39
import androidx.compose.foundation.layout.padding
40
import androidx.compose.foundation.layout.systemBarsIgnoringVisibility
41
import androidx.compose.foundation.layout.union
42
import androidx.compose.foundation.layout.windowInsetsPadding
43
import androidx.compose.foundation.rememberScrollState
44
import androidx.compose.foundation.shape.RoundedCornerShape
45
import androidx.compose.material3.MaterialTheme
46
import androidx.compose.material3.Surface
47
import androidx.compose.runtime.Composable
48
import androidx.compose.runtime.LaunchedEffect
49
import androidx.compose.runtime.collectAsState
50
import androidx.compose.runtime.getValue
51
import androidx.compose.runtime.mutableStateOf
52
import androidx.compose.runtime.remember
53
import androidx.compose.runtime.setValue
54
import androidx.compose.runtime.snapshotFlow
55
import androidx.compose.ui.Alignment
56
import androidx.compose.ui.Modifier
57
import androidx.compose.ui.draw.drawWithContent
58
import androidx.compose.ui.draw.shadow
59
import androidx.compose.ui.geometry.Offset
60
import androidx.compose.ui.geometry.Size
61
import androidx.compose.ui.graphics.Brush
62
import androidx.compose.ui.graphics.Color
63
import androidx.compose.ui.graphics.Path
64
import androidx.compose.ui.graphics.StrokeCap
65
import androidx.compose.ui.graphics.StrokeJoin
66
import androidx.compose.ui.graphics.drawscope.Stroke
67
import androidx.compose.ui.platform.ComposeView
68
import androidx.compose.ui.platform.LocalDensity
69
import androidx.compose.ui.platform.LocalLayoutDirection
70
import androidx.compose.ui.unit.Dp
71
import androidx.compose.ui.unit.LayoutDirection
72
import androidx.compose.ui.unit.dp
73
import androidx.compose.ui.viewinterop.AndroidView
74
import androidx.fragment.app.Fragment
75
import androidx.fragment.app.FragmentContainerView
76
import androidx.fragment.app.FragmentManager
77
import androidx.fragment.app.commit
78
import androidx.lifecycle.lifecycleScope
79
import com.pspdfkit.catalog.R
80
import com.pspdfkit.catalog.SdkExample
81
import com.pspdfkit.catalog.tasks.ExtractAssetTask
82
import com.pspdfkit.catalog.ui.theming.CatalogTheme
83
import com.pspdfkit.catalog.ui.theming.applyConfigurationTheme
84
import com.pspdfkit.catalog.ui.theming.enableConfigurationEdgeToEdge
85
import com.pspdfkit.catalog.ui.theming.hasDarkMainToolbar
86
import com.pspdfkit.catalog.ui.theming.isNightTheme
87
import com.pspdfkit.compose.theme.MainToolbarColors
88
import com.pspdfkit.compose.theme.NutrientTheme
89
import com.pspdfkit.compose.theme.ToolbarPopupColors
90
import com.pspdfkit.compose.theme.UiColorScheme
91
import com.pspdfkit.compose.theme.UiTheme
92
import com.pspdfkit.compose.theme.getUiColors
93
import com.pspdfkit.compose.toolbar.adapter.ToolbarCoordinator
94
import com.pspdfkit.compose.toolbar.adapter.ToolbarSubscription
95
import com.pspdfkit.compose.toolbar.composables.LocalToolbarContentInset
96
import com.pspdfkit.compose.toolbar.composables.NutrientContextualToolbar
97
import com.pspdfkit.compose.toolbar.composables.NutrientMainToolbar
98
import com.pspdfkit.compose.toolbar.composables.NutrientMainToolbarDefaults
99
import com.pspdfkit.compose.toolbar.composables.NutrientToolbarItemButton
100
import com.pspdfkit.compose.toolbar.composables.NutrientToolbarItems
101
import com.pspdfkit.compose.toolbar.composables.NutrientToolbars
102
import com.pspdfkit.compose.toolbar.state.ContextualToolbarKind
103
import com.pspdfkit.compose.toolbar.state.ContextualToolbarState
104
import com.pspdfkit.compose.toolbar.state.ToolbarAction
105
import com.pspdfkit.compose.toolbar.state.ToolbarIcon
106
import com.pspdfkit.compose.toolbar.state.ToolbarItem
107
import com.pspdfkit.compose.toolbar.state.ToolbarItems
108
import com.pspdfkit.compose.toolbar.state.withContextualKind
109
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
110
import com.pspdfkit.jetpack.compose.interactors.rememberDocumentState
111
import com.pspdfkit.jetpack.compose.toolbar.AnnotationToolbarBinder
112
import com.pspdfkit.jetpack.compose.toolbar.PdfFragmentToolbarBinder
113
import com.pspdfkit.jetpack.compose.toolbar.nutrientToolbarCoordinator
114
import com.pspdfkit.jetpack.compose.toolbar.nutrientToolbarsComposeView
115
import com.pspdfkit.jetpack.compose.views.DocumentView
116
import com.pspdfkit.ui.PdfActivity
117
import com.pspdfkit.ui.PdfActivityIntentBuilder
118
import com.pspdfkit.ui.PdfFragment
119
import com.pspdfkit.ui.annotations.OnAnnotatingModeChangeListener
120
import com.pspdfkit.ui.inspector.PropertyInspectorCoordinatorLayout
121
import com.pspdfkit.ui.inspector.annotation.AnnotatingInspectorController
122
import com.pspdfkit.ui.inspector.annotation.DefaultAnnotationCreationInspectorController
123
import com.pspdfkit.ui.inspector.annotation.DefaultAnnotationEditingInspectorController
124
import com.pspdfkit.ui.special_mode.controller.AnnotatingController
125
import com.pspdfkit.utils.getSupportParcelableExtra
126
import kotlinx.collections.immutable.persistentListOf
127
import kotlinx.coroutines.delay
128
import kotlinx.coroutines.flow.first
129
import kotlinx.coroutines.launch
130
import kotlin.time.Duration.Companion.milliseconds
131

132
/*
133
 * Four catalog entries covering the toolbar hosting shapes the SDK supports beyond the stock
134
 * `PdfActivity`, all sharing **one inset scheme** ([HostInsetScheme]) and one set of custom
135
 * chrome composables ([HostedMainToolbar], [HostedContextualBar]) — proving the chrome and its
136
 * inset handling are host-independent:
137
 *
138
 * - [CustomToolbarsPdfActivityExample]: `PdfActivity` with both SDK bars disabled and custom
139
 *   Compose chrome overlaid on the activity-scoped [ToolbarCoordinator].
140
 * - [CustomToolbarsPdfFragmentExample]: a bare [PdfFragment] with the SDK bars mounted by the
141
 *   host through [NutrientToolbars], plus the annotation property inspector.
142
 * - [CustomToolbarsPdfFragmentViewExample]: the same integration for classic View layouts, mounting
143
 *   the SDK toolbar stack as a `ComposeView` via [nutrientToolbarsComposeView].
144
 * - [CustomToolbarsDocumentViewExample]: the Compose [DocumentView] wrapper with both SDK bars
145
 *   disabled and the same custom chrome rendered from [ToolbarCoordinator.contextualToolbar].
146
 */
147

148
/**
149
 * `PdfActivity` with fully custom toolbars: `defaultToolbarEnabled(false)` +
150
 * `defaultContextualToolbarEnabled(false)` on a [PdfActivity] subclass. The SDK keeps
151
 * populating the activity-scoped [ToolbarCoordinator] (default items, contextual state on mode
152
 * changes), and the subclass overlays its own Compose bars on the same coordinator — search,
153
 * outline, annotation tools, and undo/redo stay fully functional.
154
 *
155
 * Known limits: overlay views (thumbnail grid, outline) keep their built-in ~56dp top inset,
156
 * and the popup toolbars stay SDK-rendered (see `PopupToolbarCustomItemsExample`).
157
 *
158
 * For a production-styled custom main toolbar see [MainToolbarCustomizationExample]; for
159
 * user-customizable contextual tools see `AnnotationToolbarUserEditableExample`.
160
 */
161
class CustomToolbarsPdfActivityExample(context: Context) :
162
    SdkExample(context, R.string.customToolbarsPdfActivityExampleTitle, R.string.customToolbarsPdfActivityExampleDescription) {
163
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
164
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
165
            val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile))
166
                .configuration(
167
                    configuration
168
                        .defaultToolbarEnabled(false)
169
                        .defaultContextualToolbarEnabled(false)
170
                        .documentTitleOverlayEnabled(false)
171
                        // Flip the main-toolbar frame off while ANY contextual bar is shown —
172
                        // including side-docked ones (a top-docked bar always takes the frame
173
                        // over). The host-rendered pill follows the frame, so it hides while
174
                        // the document/content editing bars are up.
175
                        .hideMainToolbarWhenContextualToolbarIsDocked(true)
176
                        .build(),
177
                )
178
                .activityClass(CustomChromePdfActivity::class.java)
179
                .build()
180
            context.startActivity(intent)
181
        }
182
    }
183
}
184

185
/**
186
 * A bare [PdfFragment] hosted inside [NutrientToolbars] — the same single-tree scaffold
187
 * `PdfActivity` uses internally, self-hosted, plus the annotation property inspector.
188
 *
189
 * Known limit: only the annotation bar has a public binder — the document/content editing bars
190
 * can't be driven from a bare fragment.
191
 */
192
class CustomToolbarsPdfFragmentExample(context: Context) :
193
    SdkExample(context, R.string.customToolbarsPdfFragmentExampleTitle, R.string.customToolbarsPdfFragmentExampleDescription) {
194
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
195
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
196
            val intent = Intent(context, ScaffoldHostedFragmentActivity::class.java)
197
                .putExtra(ScaffoldHostedFragmentActivity.EXTRA_URI, Uri.fromFile(documentFile))
198
                // The full catalog-prepared configuration: the host applies its theme itself
199
                // (a bare fragment gets no PdfActivity theme handling) and hands the
200
                // fragment-level slice to the PdfFragment.
201
                .putExtra(ScaffoldHostedFragmentActivity.EXTRA_CONFIGURATION, configuration.build())
202
            context.startActivity(intent)
203
        }
204
    }
205
}
206

207
/**
208
 * The same bare-[PdfFragment] integration for classic View layouts: the SDK toolbar stack
209
 * mounts as a `ComposeView` via [nutrientToolbarsComposeView], with the full docking contract
210
 * `PdfActivity` has — drag handle, drop-zone chrome, dock persistence.
211
 */
212
class CustomToolbarsPdfFragmentViewExample(context: Context) :
213
    SdkExample(context, R.string.customToolbarsPdfFragmentViewExampleTitle, R.string.customToolbarsPdfFragmentViewExampleDescription) {
214
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
215
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
216
            val intent = Intent(context, ScaffoldHostedFragmentActivity::class.java)
217
                .putExtra(ScaffoldHostedFragmentActivity.EXTRA_URI, Uri.fromFile(documentFile))
218
                .putExtra(ScaffoldHostedFragmentActivity.EXTRA_CONFIGURATION, configuration.build())
219
                .putExtra(ScaffoldHostedFragmentActivity.EXTRA_VIEW_INTEROP, true)
220
            context.startActivity(intent)
221
        }
222
    }
223
}
224

225
/**
226
 * The Compose [DocumentView] wrapper with both SDK bars disabled: the host renders the main
227
 * toolbar *and* a bottom-docked contextual bar (a dock the SDK itself doesn't offer) from
228
 * [ToolbarCoordinator.contextualToolbar] — the same chrome composables
229
 * [CustomToolbarsPdfActivityExample] overlays on `PdfActivity`.
230
 */
231
class CustomToolbarsDocumentViewExample(context: Context) :
232
    SdkExample(context, R.string.customToolbarsDocumentViewExampleTitle, R.string.customToolbarsDocumentViewExampleDescription) {
233
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
234
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
235
            val intent = Intent(context, CustomToolbarsDocumentViewActivity::class.java)
236
                .putExtra(CustomToolbarsDocumentViewActivity.EXTRA_URI, Uri.fromFile(documentFile))
237
                // The catalog-prepared configuration carries the catalog theme and the user's
238
                // preference toggles — pass it through instead of rebuilding.
239
                .putExtra(CustomToolbarsDocumentViewActivity.EXTRA_CONFIG, configuration.build())
240
            context.startActivity(intent)
241
        }
242
    }
243
}
244

245
// region The shared inset scheme
246

247
/**
248
 * The single inset policy every toolbar and toolbar container in these examples uses, at every
249
 * integration level:
250
 *
251
 * - **Placement insets are the *stable* system bars united with the display cutout.** Stable
252
 *   (ignoring-visibility) values keep the bars from jumping when the SDK hides the system UI
253
 *   (immersive mode, hide-UI-when-creating-annotations) — the same policy the SDK's own
254
 *   toolbar scaffold uses. Including the cutout keeps chrome out of camera notches in
255
 *   landscape.
256
 * - **Top-anchored chrome** consumes the top and horizontal sides of the placement insets.
257
 * - **Bottom-anchored chrome** consumes the bottom and horizontal sides, and additionally
258
 *   yields to the IME so the keyboard never covers it.
259
 * - **Containers, not bars, consume the insets.** Each toolbar composable is rendered with
260
 *   zero insets of its own ([NutrientMainToolbar]'s `windowInsets = WindowInsets(0,0,0,0)`),
261
 *   and its wrapping container applies the scheme exactly once — so no inset is ever
262
 *   double-counted no matter which host the chrome moves to.
263
 */
264
private object HostInsetScheme {
265
    /** Stable system bars ∪ display cutout — the placement basis for every bar. */
266
    val placement: WindowInsets
267
        @Composable get() = WindowInsets.systemBarsIgnoringVisibility.union(WindowInsets.displayCutout)
268

269
    /** What a top-anchored toolbar container consumes. */
270
    val topBar: WindowInsets
271
        @Composable get() = placement.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
272

273
    /** What a bottom-anchored toolbar container consumes — additionally yields to the IME. */
274
    val bottomBar: WindowInsets
275
        @Composable get() = placement.only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal).union(WindowInsets.ime)
276

277
    /** The scheme's top placement inset as a scalar, for [NutrientToolbars]. */
278
    @Composable
279
    fun topPlacementInset(): Dp = with(LocalDensity.current) { placement.getTop(this).toDp() }
280

281
    /** The scheme's bottom placement inset as a scalar, for [NutrientToolbars]. */
282
    @Composable
283
    fun bottomPlacementInset(): Dp = with(LocalDensity.current) { placement.getBottom(this).toDp() }
284

285
    /** The scheme's physical-left placement inset, for [NutrientToolbars]. */
286
    @Composable
287
    fun leftPlacementInset(): Dp = with(LocalDensity.current) {
288
        placement.getLeft(this, LocalLayoutDirection.current).toDp()
289
    }
290

291
    /** The scheme's physical-right placement inset, for [NutrientToolbars]. */
292
    @Composable
293
    fun rightPlacementInset(): Dp = with(LocalDensity.current) {
294
        placement.getRight(this, LocalLayoutDirection.current).toDp()
295
    }
296

297
    /** One margin for every floating chrome piece, so the bars keep consistent clearances. */
298
    val chromeMarginHorizontal: Dp = 16.dp
299

300
    /** The chrome's clearance from the inset edge it anchors to, shared by both bars. */
301
    val chromeMarginVertical: Dp = 12.dp
302

303
    /** Corner radius of every floating chrome piece (the main pill and the contextual bar). */
304
    val chromeCornerRadius: Dp = 28.dp
305
}
306

307
// endregion
308

309
// region The shared custom chrome
310

311
/**
312
 * The host-rendered main toolbar: a rounded pill docked to the top end corner, exactly as wide as
313
 * its icons, that expands to the full width while inline search is open and collapses again
314
 * afterwards. The container consumes [HostInsetScheme.topBar]; the toolbar itself opts out of
315
 * insets entirely, per the scheme.
316
 *
317
 * Nothing here sizes or animates the toolbar: it wraps its content, its default search bar fills
318
 * the width while search is open, and the toolbar animates that width change itself. (Don't add
319
 * `animateContentSize()` for it — that clips to the toolbar's bounds and cuts the pill's shadow.)
320
 */
321
@Composable
322
private fun BoxScope.HostedMainToolbar(coordinator: ToolbarCoordinator) {
323
    // The pill is the toolbar's own chrome, drawn inside its visibility animation, so chrome and
324
    // bar leave together. Its background must be opaque — an elevated transparent surface shows
325
    // its own shadow's silhouette straight through itself — which is what hostedToolbarColors()
326
    // sets on the theme below.
327
    NutrientTheme(colorScheme = hostedToolbarColors()) {
328
        NutrientMainToolbar(
329
            coordinator = coordinator,
330
            shape = RoundedCornerShape(HostInsetScheme.chromeCornerRadius),
331
            shadowElevation = NutrientMainToolbarDefaults.FloatingShadowElevation,
332
            // The container below already consumed the scheme insets — the bar adds none.
333
            windowInsets = NutrientMainToolbarDefaults.NoWindowInsets,
334
            // align is parent data: it reaches this Box only from the toolbar's outermost node.
335
            modifier = Modifier
336
                .align(Alignment.TopEnd)
337
                // The scheme's single inset consumption point for top-anchored chrome.
338
                .windowInsetsPadding(HostInsetScheme.topBar)
339
                .padding(NutrientMainToolbarDefaults.FloatingMargin),
340
            actions = { NutrientToolbarItems(coordinator, Modifier.weight(1f).padding(horizontal = 12.dp)) },
341
        )
342
    }
343
}
344

345
/**
346
 * The host-rendered contextual bar. Two treatments by kind, both free to ignore the main pill
347
 * because both hosts set `hideMainToolbarWhenContextualToolbarIsDocked(true)`:
348
 *
349
 * - The **document- and content-editing** bars are short, so they are the SDK's own
350
 *   [NutrientContextualToolbar] tucked into the top end corner. Nothing is hand-rolled: the pill
351
 *   shape, elevation and colors are parameters, the bar is as wide as its items, and its close
352
 *   button and kind-stamped dispatch come with it.
353
 * - The **annotation** bar carries a long tool run and docks to the **bottom** edge — a dock the
354
 *   SDK bar does not offer — so it stays a hand-rolled, flat, scrollable row
355
 *   ([HostedAnnotationBar]).
356
 */
357
@Composable
358
private fun BoxScope.HostedContextualBar(coordinator: ToolbarCoordinator) {
359
    val contextual by coordinator.contextualToolbar.collectAsState()
360
    // The bars keep composing during their exit fade after the flow flipped to null — latch the
361
    // last non-null state so the fade-out still draws the bar it dismisses.
362
    var lastShown by remember { mutableStateOf<ContextualToolbarState?>(null) }
363
    contextual?.let { lastShown = it }
364
    val shown = contextual ?: lastShown
365
    if (shown?.kind == ContextualToolbarKind.Annotation) {
366
        HostedAnnotationBar(coordinator, visible = contextual != null, bar = shown)
367
    } else {
368
        NutrientTheme {
369
            NutrientContextualToolbar(
370
                coordinator = coordinator,
371
                modifier = Modifier
372
                    .align(Alignment.TopEnd)
373
                    // The scheme's single inset consumption point for top-anchored chrome.
374
                    .windowInsetsPadding(HostInsetScheme.topBar)
375
                    .padding(
376
                        horizontal = HostInsetScheme.chromeMarginHorizontal,
377
                        vertical = HostInsetScheme.chromeMarginVertical,
378
                    ),
379
                shape = RoundedCornerShape(HostInsetScheme.chromeCornerRadius),
380
                shadowElevation = 8.dp,
381
                colors = hostedToolbarColors().mainToolbar,
382
            )
383
        }
384
    }
385
}
386

387
/**
388
 * The annotation bar, docked to the bottom edge as a flat, scrollable row of every tool. The
389
 * container consumes [HostInsetScheme.bottomBar] (which includes the IME), per the scheme.
390
 */
391
@Composable
392
private fun BoxScope.HostedAnnotationBar(coordinator: ToolbarCoordinator, visible: Boolean, bar: ContextualToolbarState) {
393
    AnimatedVisibility(
394
        visible = visible,
395
        enter = fadeIn(),
396
        exit = fadeOut(),
397
        modifier = Modifier
398
            .align(Alignment.BottomCenter)
399
            // The scheme's single inset consumption point for bottom-anchored chrome.
400
            .windowInsetsPadding(HostInsetScheme.bottomBar)
401
            .padding(
402
                horizontal = HostInsetScheme.chromeMarginHorizontal,
403
                vertical = HostInsetScheme.chromeMarginVertical,
404
            ),
405
    ) {
406
        // Clicks from a host-rendered contextual bar must carry the shown bar's kind — each SDK
407
        // mode binder only handles clicks stamped with its own kind.
408
        val dispatch: (ToolbarAction) -> Unit = { action ->
409
            coordinator.dispatch(action.withContextualKind(bar.kind))
410
        }
411
        // Flatten pre-grouped submenus so every tool renders as its own button; long runs scroll.
412
        val flatItems = bar.items
413
            .flatMap { item -> if (item is ToolbarItem.Submenu) item.children else listOf(item) }
414
            .filter { it.state.isVisible }
415
        NutrientTheme(colorScheme = hostedToolbarColors()) {
416
            val barColor = UiTheme.colors.mainToolbar.backgroundColor
417
            val toolScrollState = rememberScrollState()
418
            // One-time peek when a scrollable bar appears: scroll a few tools in and settle
419
            // back, so the user SEES the row move before ever touching it. A user gesture
420
            // during the peek cancels it (animateScrollTo yields to touch input).
421
            ScrollPeekEffect(toolScrollState)
422
            Surface(
423
                shape = RoundedCornerShape(HostInsetScheme.chromeCornerRadius),
424
                color = barColor,
425
                shadowElevation = 8.dp,
426
            ) {
427
                Row(
428
                    verticalAlignment = Alignment.CenterVertically,
429
                    horizontalArrangement = Arrangement.spacedBy(2.dp),
430
                    modifier = Modifier.padding(horizontal = 8.dp, vertical = 5.dp),
431
                ) {
432
                    Row(
433
                        verticalAlignment = Alignment.CenterVertically,
434
                        horizontalArrangement = Arrangement.spacedBy(2.dp),
435
                        modifier = Modifier
436
                            .weight(1f, fill = false)
437
                            // The scroll affordance: tools fade into the bar edge and a chevron
438
                            // points at the hidden ones while more content exists there.
439
                            .horizontalScrollEdgeFade(
440
                                toolScrollState,
441
                                color = barColor,
442
                                chevronColor = UiTheme.colors.mainToolbar.textColor,
443
                            )
444
                            .horizontalScroll(toolScrollState),
445
                    ) {
446
                        flatItems.filter { it.position == ToolbarItem.ItemEdge.Start }.forEach { item ->
447
                            NutrientToolbarItemButton(item = item, onAction = dispatch, invertedSelection = true)
448
                        }
449
                    }
450
                    flatItems.filter { it.position == ToolbarItem.ItemEdge.End }.forEach { item ->
451
                        NutrientToolbarItemButton(item = item, onAction = dispatch, invertedSelection = true)
452
                    }
453
                    NutrientToolbarItemButton(
454
                        item = ToolbarItem.Button(
455
                            actionId = "catalog.hosted_bar.close",
456
                            id = com.pspdfkit.R.id.pspdf__toolbar_close_button,
457
                            contentDescription = "Close toolbar",
458
                            icon = ToolbarIcon.Resource(com.pspdfkit.R.drawable.pspdf__ic_close_circled),
459
                        ),
460
                        onAction = dispatch,
461
                    )
462
                }
463
            }
464
        }
465
    }
466
}
467

468
/**
469
 * Plays the one-time scroll peek on [state]: once the row is measured and turns out to
470
 * overflow, it glides a couple of tool widths toward the end and settles back — the motion
471
 * itself demonstrates that the row scrolls.
472
 */
473
@Composable
474
private fun ScrollPeekEffect(state: ScrollState) {
475
    val peekPx = with(LocalDensity.current) { 72.dp.roundToPx() }
476
    LaunchedEffect(state) {
477
        // maxValue is Int.MAX_VALUE until the first measure pass reports the real overflow.
478
        val max = snapshotFlow { state.maxValue }.first { it != Int.MAX_VALUE }
479
        if (max > 0) {
480
            delay(SCROLL_PEEK_START_DELAY_MS.milliseconds)
481
            state.animateScrollTo(minOf(peekPx, max), tween(SCROLL_PEEK_LEG_MS))
482
            state.animateScrollTo(0, tween(SCROLL_PEEK_LEG_MS))
483
        }
484
    }
485
}
486

487
/** Pause before the peek, so the bar's own entrance animation finishes first. */
488
private const val SCROLL_PEEK_START_DELAY_MS = 450L
489

490
/** Duration of each leg of the peek (out and back). */
491
private const val SCROLL_PEEK_LEG_MS = 500
492

493
/**
494
 * The scroll affordance for a tool run: at whichever edge still has more content to scroll to,
495
 * the tools fade into [color] and a small chevron points toward the hidden ones. Without it a
496
 * full row just cuts off at the bar edge and nothing suggests the row scrolls at all.
497
 */
498
private fun Modifier.horizontalScrollEdgeFade(state: ScrollState, color: Color, chevronColor: Color, width: Dp = 36.dp): Modifier =
499
    drawWithContent {
500
        drawContent()
501
        val fadePx = width.toPx()
502
        // canScrollForward/Backward are logical (toward the end/start); map them to physical edges.
503
        val ltr = layoutDirection == LayoutDirection.Ltr
504
        val fadeRight = if (ltr) state.canScrollForward else state.canScrollBackward
505
        val fadeLeft = if (ltr) state.canScrollBackward else state.canScrollForward
506
        val chevron = 4.dp.toPx()
507
        val stroke = Stroke(width = 2.dp.toPx(), cap = StrokeCap.Round, join = StrokeJoin.Round)
508
        if (fadeRight) {
509
            drawRect(
510
                brush = Brush.horizontalGradient(
511
                    0f to Color.Transparent,
512
                    1f to color,
513
                    startX = size.width - fadePx,
514
                    endX = size.width,
515
                ),
516
                topLeft = Offset(size.width - fadePx, 0f),
517
                size = Size(fadePx, size.height),
518
            )
519
            val x = size.width - chevron * 1.5f
520
            drawPath(
521
                path = Path().apply {
522
                    moveTo(x, center.y - chevron)
523
                    lineTo(x + chevron, center.y)
524
                    lineTo(x, center.y + chevron)
525
                },
526
                color = chevronColor,
527
                style = stroke,
528
            )
529
        }
530
        if (fadeLeft) {
531
            drawRect(
532
                brush = Brush.horizontalGradient(0f to color, 1f to Color.Transparent, startX = 0f, endX = fadePx),
533
                topLeft = Offset.Zero,
534
                size = Size(fadePx, size.height),
535
            )
536
            val x = chevron * 1.5f
537
            drawPath(
538
                path = Path().apply {
539
                    moveTo(x, center.y - chevron)
540
                    lineTo(x - chevron, center.y)
541
                    lineTo(x, center.y + chevron)
542
                },
543
                color = chevronColor,
544
                style = stroke,
545
            )
546
        }
547
    }
548

549
/** The custom chrome's color scheme, layered on the XML-derived defaults. */
550
@Composable
551
private fun hostedToolbarColors(): UiColorScheme {
552
    val background = MaterialTheme.colorScheme.primary
553
    return getUiColors().copy(
554
        mainToolbar = MainToolbarColors(
555
            backgroundColor = background,
556
            textColor = Color.White,
557
            popup = ToolbarPopupColors(backgroundColor = background),
558
            titleTextColor = Color.White,
559
        ),
560
    )
561
}
562

563
// endregion
564

565
// region PdfActivity with fully custom chrome
566

567
/**
568
 * A [PdfActivity] whose toolbars are entirely host-rendered. The configuration (passed by
569
 * [CustomToolbarsPdfActivityExample]) disables both SDK-mounted bars; the SDK still populates
570
 * the **activity-scoped** [ToolbarCoordinator] with the default items and the contextual state
571
 * on mode changes, so the overlay chrome below stays fully functional.
572
 */
573
class CustomChromePdfActivity : PdfActivity() {
574
    override fun onCreate(savedInstanceState: Bundle?) {
575
        // PdfActivity themes itself from its configuration, so the system bar icons have to
576
        // follow the same answer. Both SDK bars are off here and the host chrome floats below the
577
        // strip, so the icons land on the document — left to the platform they would follow the
578
        // device's night mode and turn white over this light page.
579
        //
580
        // Before super.onCreate, like every other host here: PdfActivity.getConfiguration() falls
581
        // back to the intent extra until its implementation exists, so it already answers here.
582
        enableConfigurationEdgeToEdge(configuration)
583
        super.onCreate(savedInstanceState)
584
        // The same coordinator instance PdfUiImpl populates for this activity.
585
        val coordinator = nutrientToolbarCoordinator()
586
        val overlay = ComposeView(this).apply {
587
            setContent {
588
                CatalogTheme(darkTheme = configuration.isNightTheme) {
589
                    Box(Modifier.fillMaxSize()) {
590
                        HostedMainToolbar(coordinator)
591
                        HostedContextualBar(coordinator)
592
                    }
593
                }
594
            }
595
        }
596
        // Overlay the custom chrome above the SDK content. Touches outside the bars fall
597
        // through to the document.
598
        addContentView(overlay, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
599
    }
600
}
601

602
// endregion
603

604
// region Bare PdfFragment with SDK toolbars (Compose scaffold or View interop)
605

606
/**
607
 * Hosts a plain [PdfFragment] with the SDK toolbars, in one of two shapes:
608
 *
609
 * **Compose scaffold (default):** the host mounts [NutrientToolbars] — the same single-tree
610
 * scaffold `PdfActivity` uses internally:
611
 * - The host reads [HostInsetScheme] once and passes it as the scaffold's placement-inset
612
 *   scalars; the scaffold derives everything from them (top dock strip, side-dock bounds,
613
 *   drop zones, vertical-fit correction, content inset).
614
 * - The document container pads itself by [LocalToolbarContentInset] — the scaffold's contract
615
 *   for keeping content clear of a top-docked bar.
616
 *
617
 * **View interop ([EXTRA_VIEW_INTEROP]):** a classic View layout mounts the same toolbar stack
618
 * as a `ComposeView` via [nutrientToolbarsComposeView], with the full docking contract
619
 * `PdfActivity` has — drag handle, drop-zone chrome while dragging, dock placement and
620
 * persistence. The view paints nothing while no contextual toolbar is shown, and touches pass
621
 * through empty areas to the fragment below.
622
 *
623
 * Both shapes share every other piece, wired against the activity-scoped [ToolbarCoordinator]:
624
 * - [PdfFragmentToolbarBinder] keeps the host's undo/redo items and tool selection in sync;
625
 *   [AnnotationToolbarBinder] shows the SDK annotation bar when annotating starts (the
626
 *   fragment's [OnAnnotatingModeChangeListener] tells us when to attach and detach).
627
 * - [DefaultAnnotationCreationInspectorController] / [DefaultAnnotationEditingInspectorController]
628
 *   provide the annotation property inspector on a [PropertyInspectorCoordinatorLayout].
629
 */
630
class ScaffoldHostedFragmentActivity :
631
    AppCompatActivity(),
632
    OnAnnotatingModeChangeListener {
633
    private var fragment: PdfFragment? = null
634
    private lateinit var annotationToolbarBinder: AnnotationToolbarBinder
635
    private lateinit var fragmentBinder: PdfFragmentToolbarBinder
636
    private lateinit var inspectorCoordinatorLayout: PropertyInspectorCoordinatorLayout
637
    private lateinit var annotationCreationInspectorController: AnnotatingInspectorController
638
    private lateinit var annotationEditingInspectorController: AnnotatingInspectorController
639
    private val subscriptions = mutableListOf<ToolbarSubscription>()
640
    private var creationToolbarShown = false
641
    private var editingInspectorBound = false
642
    private var fragmentBinderAttached = false
643

644
    /** The resolved theme of the hosted configuration — see `CatalogTheme` in [mountComposeScaffold]. */
645
    private var isNightTheme = false
646

647
    /** Attaches/detaches the fragment binder at its documented lifecycle points. */
648
    private val lifecycleCallbacks = object : FragmentManager.FragmentLifecycleCallbacks() {
649
        override fun onFragmentViewCreated(fm: FragmentManager, f: Fragment, v: View, savedInstanceState: Bundle?) {
650
            if (f === fragment && !fragmentBinderAttached) {
651
                fragmentBinder.attach(f)
652
                fragmentBinderAttached = true
653
            }
654
        }
655

656
        override fun onFragmentViewDestroyed(fm: FragmentManager, f: Fragment) {
657
            if (f === fragment && fragmentBinderAttached) {
658
                fragmentBinder.detach()
659
                fragmentBinderAttached = false
660
            }
661
        }
662
    }
663

664
    override fun onCreate(savedInstanceState: Bundle?) {
665
        val activityConfiguration = intent.getSupportParcelableExtra(EXTRA_CONFIGURATION, PdfActivityConfiguration::class.java)
666
            ?: PdfActivityConfiguration.Builder(this).build()
667
        // A bare-fragment host gets no PdfActivity theme handling — apply the configured theme
668
        // ourselves, so the SDK toolbars, the inspector, and the fragment pick up the catalog
669
        // styling instead of the application theme.
670
        isNightTheme = activityConfiguration.isNightTheme
671
        applyConfigurationTheme(activityConfiguration)
672
        enableConfigurationEdgeToEdge(activityConfiguration, statusBarIsDark = hasDarkMainToolbar())
673
        super.onCreate(savedInstanceState)
674
        val uri = intent.getSupportParcelableExtra(EXTRA_URI, Uri::class.java)!!
675
        val viewInterop = intent.getBooleanExtra(EXTRA_VIEW_INTEROP, false)
676
        val pdfConfiguration = activityConfiguration.configuration
677

678
        val coordinator = nutrientToolbarCoordinator()
679
        annotationToolbarBinder = AnnotationToolbarBinder(coordinator)
680
        fragmentBinder = PdfFragmentToolbarBinder(coordinator)
681
        supportFragmentManager.registerFragmentLifecycleCallbacks(lifecycleCallbacks, false)
682

683
        // The annotation property inspector: controllers bind to the AnnotatingController when
684
        // annotating starts (see the OnAnnotatingModeChangeListener callbacks below) and render
685
        // into this coordinator layout, overlaid above the document.
686
        inspectorCoordinatorLayout = PropertyInspectorCoordinatorLayout(this).apply {
687
            elevation = 16.dp.value * resources.displayMetrics.density
688
        }
689
        annotationCreationInspectorController = DefaultAnnotationCreationInspectorController(this, inspectorCoordinatorLayout)
690
        annotationEditingInspectorController = DefaultAnnotationEditingInspectorController(this, inspectorCoordinatorLayout)
691

692
        val fragment = (supportFragmentManager.findFragmentById(R.id.fragmentContainer) as? PdfFragment)
693
            ?: PdfFragment.newInstance(uri, pdfConfiguration)
694
        this.fragment = fragment
695
        fragment.addOnAnnotatingModeChangeListener(this)
696

697
        // The host owns the main-toolbar contents in a bare-fragment integration: title plus
698
        // annotate / undo / redo. The undo and redo items reuse the binder's stable action IDs
699
        // so PdfFragmentToolbarBinder keeps their enabled state in sync automatically.
700
        // One activity backs both catalog entries, so name the shape it was launched for — in the
701
        // toolbar and in the task label the recents screen shows (the manifest can only carry one).
702
        val exampleTitle = getString(
703
            if (viewInterop) R.string.customToolbarsPdfFragmentViewExampleTitle else R.string.customToolbarsPdfFragmentExampleTitle,
704
        )
705
        setTitle(exampleTitle)
706
        coordinator.setMainToolbarTitle(
707
            getString(
708
                if (viewInterop) {
709
                    R.string.customToolbarsPdfFragmentViewMainToolbarTitle
710
                } else {
711
                    R.string.customToolbarsPdfFragmentMainToolbarTitle
712
                },
713
            ),
714
        )
715
        coordinator.setMainToolbarItems(
716
            ToolbarItems(
717
                visible = persistentListOf(
718
                    ToolbarItem.Button(
719
                        actionId = "catalog.hosted_fragment.annotate",
720
                        id = R.id.custom_action1,
721
                        contentDescription = "Toggle annotation mode",
722
                        icon = ToolbarIcon.Resource(com.pspdfkit.R.drawable.pspdf__ic_edit_annotations),
723
                        overflowBehavior = ToolbarItem.OverflowBehavior.AlwaysShow,
724
                    ),
725
                    ToolbarItem.Button(
726
                        actionId = PdfFragmentToolbarBinder.ACTION_UNDO,
727
                        id = R.id.custom_action2,
728
                        contentDescription = "Undo",
729
                        icon = ToolbarIcon.Resource(com.pspdfkit.R.drawable.pspdf__ic_undo),
730
                        overflowBehavior = ToolbarItem.OverflowBehavior.AlwaysShow,
731
                    ),
732
                    ToolbarItem.Button(
733
                        actionId = PdfFragmentToolbarBinder.ACTION_REDO,
734
                        id = R.id.custom_action3,
735
                        contentDescription = "Redo",
736
                        icon = ToolbarIcon.Resource(com.pspdfkit.R.drawable.pspdf__ic_redo),
737
                        overflowBehavior = ToolbarItem.OverflowBehavior.AlwaysShow,
738
                    ),
739
                ),
740
            ),
741
        )
742
        subscriptions += coordinator.addItemClickHandler { id ->
743
            val f = this.fragment ?: return@addItemClickHandler
744
            when (id) {
745
                R.id.custom_action1 -> if (creationToolbarShown) f.exitCurrentlyActiveMode() else f.enterAnnotatingMode()
746
                R.id.custom_action2 -> lifecycleScope.launch { f.undoManager.undo() }
747
                R.id.custom_action3 -> lifecycleScope.launch { f.undoManager.redo() }
748
            }
749
        }
750

751
        if (viewInterop) {
752
            mountViewInterop(coordinator, fragment)
753
        } else {
754
            mountComposeScaffold(coordinator, fragment)
755
        }
756
    }
757

758
    /** The Compose-scaffold shape: [NutrientToolbars] owns placement; content pads itself. */
759
    private fun mountComposeScaffold(coordinator: ToolbarCoordinator, fragment: PdfFragment) {
760
        setContent {
761
            CatalogTheme(darkTheme = isNightTheme) {
762
                NutrientToolbars(
763
                    coordinator = coordinator,
764
                    // The shared scheme, applied once at the scaffold seam — every slot inside
765
                    // (main toolbar, top/side contextual docks, drop zones, fit correction)
766
                    // derives from these scalars.
767
                    topWindowInset = HostInsetScheme.topPlacementInset(),
768
                    bottomWindowInset = HostInsetScheme.bottomPlacementInset(),
769
                    leftWindowInset = HostInsetScheme.leftPlacementInset(),
770
                    rightWindowInset = HostInsetScheme.rightPlacementInset(),
771
                    modifier = Modifier.fillMaxSize(),
772
                ) {
773
                    // The scaffold's content contract: consume LocalToolbarContentInset so the
774
                    // document clears a top-docked bar; the document view itself adds nothing.
775
                    AndroidView(
776
                        factory = { context ->
777
                            FrameLayout(context).apply {
778
                                addView(
779
                                    FragmentContainerView(context).apply { id = R.id.fragmentContainer },
780
                                    matchParentParams(),
781
                                )
782
                                addView(inspectorCoordinatorLayout, matchParentParams())
783
                            }
784
                        },
785
                        modifier = Modifier
786
                            .fillMaxSize()
787
                            .padding(top = LocalToolbarContentInset.current),
788
                    )
789
                    LaunchedEffect(Unit) {
790
                        if (supportFragmentManager.findFragmentById(R.id.fragmentContainer) == null) {
791
                            supportFragmentManager.commit { add(R.id.fragmentContainer, fragment) }
792
                        }
793
                    }
794
                }
795
            }
796
        }
797
    }
798

799
    /** The View-interop shape: the toolbar stack is a `ComposeView` in a classic View tree. */
800
    private fun mountViewInterop(coordinator: ToolbarCoordinator, fragment: PdfFragment) {
801
        val root = FrameLayout(this)
802
        root.addView(FragmentContainerView(this).apply { id = R.id.fragmentContainer }, matchParentParams())
803
        // Mount the SDK toolbar stack over the document: docking wiring follows the view's
804
        // window-attach lifecycle, so there is nothing to release on teardown.
805
        root.addView(nutrientToolbarsComposeView(this, coordinator, showMainToolbar = true), matchParentParams())
806
        root.addView(inspectorCoordinatorLayout, matchParentParams())
807
        setContentView(root)
808
        if (supportFragmentManager.findFragmentById(R.id.fragmentContainer) == null) {
809
            supportFragmentManager.commit { add(R.id.fragmentContainer, fragment) }
810
        }
811
    }
812

813
    private fun matchParentParams() = FrameLayout.LayoutParams(
814
        FrameLayout.LayoutParams.MATCH_PARENT,
815
        FrameLayout.LayoutParams.MATCH_PARENT,
816
    )
817

818
    override fun onDestroy() {
819
        // Release everything we bound before handing off to the framework teardown.
820
        fragment?.removeOnAnnotatingModeChangeListener(this)
821
        if (creationToolbarShown) annotationToolbarBinder.detach()
822
        supportFragmentManager.unregisterFragmentLifecycleCallbacks(lifecycleCallbacks)
823
        subscriptions.forEach { it.close() }
824
        subscriptions.clear()
825
        fragment = null
826
        super.onDestroy()
827
    }
828

829
    override fun onEnterAnnotatingMode(controller: AnnotatingController) {
830
        // An annotation tool is active: show the creation toolbar and bind its inspector.
831
        if (controller.activeAnnotationTool != null && !creationToolbarShown) {
832
            annotationCreationInspectorController.bindController(controller)
833
            annotationToolbarBinder.attach(controller)
834
            creationToolbarShown = true
835
        }
836
        // Annotations are selected: bind the editing inspector.
837
        if (controller.hasCurrentlySelectedAnnotations() && !editingInspectorBound) {
838
            annotationEditingInspectorController.bindController(controller)
839
            editingInspectorBound = true
840
        }
841
    }
842

843
    override fun onChangeAnnotatingMode(controller: AnnotatingController) {
844
        if (controller.hasCurrentlySelectedAnnotations() && !editingInspectorBound) {
845
            annotationEditingInspectorController.bindController(controller)
846
            editingInspectorBound = true
847
        } else if (!controller.hasCurrentlySelectedAnnotations() && editingInspectorBound) {
848
            annotationEditingInspectorController.unbindController()
849
            editingInspectorBound = false
850
        }
851
    }
852

853
    override fun onExitAnnotatingMode(controller: AnnotatingController) {
854
        if (controller.activeAnnotationTool == null && creationToolbarShown) {
855
            annotationToolbarBinder.detach()
856
            annotationCreationInspectorController.unbindController()
857
            creationToolbarShown = false
858
        }
859
        if (!controller.hasCurrentlySelectedAnnotations() && editingInspectorBound) {
860
            annotationEditingInspectorController.unbindController()
861
            editingInspectorBound = false
862
        }
863
    }
864

865
    companion object {
866
        const val EXTRA_URI = "ScaffoldHostedFragmentActivity.DocumentUri"
867
        const val EXTRA_CONFIGURATION = "ScaffoldHostedFragmentActivity.ActivityConfiguration"
868
        const val EXTRA_VIEW_INTEROP = "ScaffoldHostedFragmentActivity.ViewInterop"
869
    }
870
}
871

872
// endregion
873

874
// region DocumentView with fully custom toolbars
875

876
/**
877
 * The Compose [DocumentView] with both SDK bars disabled and everything host-rendered. The
878
 * fragment-scoped [ToolbarCoordinator] is published through
879
 * `documentState.toolbarCoordinator` once the SDK UI initializes; the SDK keeps populating it
880
 * (items, contextual state) with the defaults disabled.
881
 */
882
class CustomToolbarsDocumentViewActivity : AppCompatActivity() {
883
    override fun onCreate(savedInstanceState: Bundle?) {
884
        val baseConfiguration = intent.getSupportParcelableExtra(EXTRA_CONFIG, PdfActivityConfiguration::class.java)
885
        // Both SDK toolbars are off here, but the fragment behind the DocumentView still renders
886
        // SDK UI that reads the *activity's* XML theme — the annotation inspector, the popup
887
        // toolbars, the page chrome. Apply the configured catalog theme before anything inflates.
888
        applyConfigurationTheme(baseConfiguration)
889
        enableConfigurationEdgeToEdge(baseConfiguration)
890
        super.onCreate(savedInstanceState)
891
        val uri = intent.getSupportParcelableExtra(EXTRA_URI, Uri::class.java)!!
892

893
        // Layer the example's needs on top of the catalog-prepared configuration.
894
        val configuration = (baseConfiguration?.let { PdfActivityConfiguration.Builder(it) } ?: PdfActivityConfiguration.Builder(this))
895
            .defaultToolbarEnabled(false)
896
            .defaultContextualToolbarEnabled(false)
897
            .documentTitleOverlayEnabled(false)
898
            // The host-rendered pill follows the frame: hide it while any contextual bar shows.
899
            .hideMainToolbarWhenContextualToolbarIsDocked(true)
900
            .build()
901

902
        setContent {
903
            CatalogTheme(darkTheme = baseConfiguration.isNightTheme) {
904
                val documentState = rememberDocumentState(uri, configuration)
905
                Box(Modifier.fillMaxSize()) {
906
                    DocumentView(
907
                        documentState = documentState,
908
                        modifier = Modifier.fillMaxSize(),
909
                    )
910
                    val coordinator by documentState.toolbarCoordinator.collectAsState()
911
                    coordinator?.let { c ->
912
                        HostedMainToolbar(c)
913
                        HostedContextualBar(c)
914
                    }
915
                }
916
            }
917
        }
918
    }
919

920
    companion object {
921
        const val EXTRA_URI = "CustomToolbarsDocumentViewActivity.DocumentUri"
922
        const val EXTRA_CONFIG = "CustomToolbarsDocumentViewActivity.Configuration"
923
    }
924
}
925

926
// endregion