pythonnative/src/pythonnative/components/layout.py at v0.43.1 · pythonnative/pythonnative · GitHub

Repository navigation

History

518 lines (459 loc) · 20.6 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

"""Container factories: ``View``, ``Column``, ``Row``, ``Spacer``, ``ScrollView``, and the inset-aware wrappers.

``SafeAreaView`` and ``KeyboardAvoidingView`` are thin factories over

hook-driven composites (``_SafeAreaContainer`` and

``_KeyboardAvoidingContainer``) that subscribe to the platform metrics

and re-render when the insets or keyboard height change.

"""

from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union

from ..component import component

from ..element import Element

from ..hooks import Ref, use_keyboard_height, use_safe_area_insets, use_state

from ..style import AccessibilityState, StyleProp, resolve_style

from ._base import _make_element, _refresh_control_props

def View(

*children: Element,

style: StyleProp = None,

gestures: Optional[List[Any]] = None,

hit_slop: Optional[Union[float, Dict[str, float]]] = None,

on_layout: Optional[Callable[[Dict[str, float]], None]] = None,

accessibility_label: Optional[str] = None,

accessibility_hint: Optional[str] = None,

accessibility_role: Optional[str] = None,

accessible: Optional[bool] = None,

accessibility_state: Optional[AccessibilityState] = None,

accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,

test_id: Optional[str] = None,

ref: Optional[Ref] = None,

key: Optional[str] = None,

) -> Element:

"""Universal flex container (like React Native's ``View``).

Defaults to ``flex_direction: "column"`` (override via ``style``).

Flex container properties (passed via ``style``):

- ``flex_direction``: ``"column"`` (default), ``"row"``,

``"column_reverse"``, ``"row_reverse"``.

- ``flex_wrap``: ``"nowrap"`` (default), ``"wrap"``,

``"wrap_reverse"``, with ``align_content`` controlling how

wrapped lines share leftover cross-axis space.

- ``justify_content``: main-axis distribution. Accepts

``"flex_start"`` (default), ``"center"``, ``"flex_end"``,

``"space_between"``, ``"space_around"``, ``"space_evenly"``.

- ``align_items``: cross-axis alignment. Accepts ``"stretch"``

(default), ``"flex_start"``, ``"center"``, ``"flex_end"``.

- ``direction``: ``"ltr"`` (default) or ``"rtl"``. Flips rows and

resolves ``margin_start`` / ``padding_end`` / absolute ``start``

/ ``end`` insets.

- ``overflow``: ``"visible"`` (default) or ``"hidden"``.

- ``spacing`` (alias ``gap``; per-axis ``row_gap`` /

``column_gap``), ``padding``, ``background_color``,

``border_radius``, ``border_width``, ``border_color``,

``shadow_color``, ``shadow_offset``, ``shadow_opacity``,

``shadow_radius``, ``elevation``, ``opacity``, ``transform``.

Args:

*children: Child elements rendered inside the container.

style: Style dict (or list of dicts).

gestures: Optional list of gesture descriptors from

`pythonnative.gestures` (e.g. ``[gestures.Pan(on_change=…)]``)

recognized natively on this view.

hit_slop: Extend the touch target beyond the view's bounds

without changing layout: a uniform number of points, or a

dict with any of ``top`` / ``left`` / ``bottom`` /

``right``.

on_layout: Callback invoked with

``{"x", "y", "width", "height"}`` after this view is laid

out, and again whenever its frame changes.

accessibility_label: Spoken description for screen readers.

accessibility_hint: Spoken extra detail (iOS only).

accessibility_role: Semantic role for assistive tech.

accessible: Override whether the element is exposed to AT.

accessibility_state: Current widget state for assistive tech,

e.g. ``{"disabled": True, "selected": False}``. Recognized

keys: ``disabled``, ``selected``, ``checked``, ``busy``,

``expanded``.

accessibility_live_region: How AT announces dynamic changes to

this view: ``"none"``, ``"polite"``, or ``"assertive"``

(Android only).

test_id: Stable identifier for UI tests; exposed as

``resource-id`` on Android and ``accessibilityIdentifier``

on iOS.

ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] of type ``"View"``.

"""

return _make_element(

"View",

*children,

style=style,

ref=ref,

key=key,

gestures=gestures,

hit_slop=hit_slop,

on_layout=on_layout,

accessibility_label=accessibility_label,

accessibility_hint=accessibility_hint,

accessibility_role=accessibility_role,

accessible=accessible,

accessibility_state=accessibility_state,

accessibility_live_region=accessibility_live_region,

test_id=test_id,

_defaults={"flex_direction": "column"},

)

def Column(

*children: Element,

style: StyleProp = None,

gestures: Optional[List[Any]] = None,

hit_slop: Optional[Union[float, Dict[str, float]]] = None,

on_layout: Optional[Callable[[Dict[str, float]], None]] = None,

accessibility_label: Optional[str] = None,

accessibility_hint: Optional[str] = None,

accessibility_role: Optional[str] = None,

accessible: Optional[bool] = None,

accessibility_state: Optional[AccessibilityState] = None,

accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,

test_id: Optional[str] = None,

ref: Optional[Ref] = None,

key: Optional[str] = None,

) -> Element:

"""Arrange children vertically.

Convenience wrapper around [`View`][pythonnative.View] with

``flex_direction`` locked to ``"column"``. Use ``View`` directly if

you need to switch between row and column at runtime.

Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,

accessibility, ``test_id``); only ``flex_direction`` is fixed.

Args:

*children: Child elements stacked top to bottom.

style: Style dict (or list of dicts).

gestures: Gesture descriptors recognized natively on this view.

hit_slop: Extra touch target beyond the bounds (see ``View``).

on_layout: Callback invoked with

``{"x", "y", "width", "height"}`` after layout and on

frame changes.

accessibility_label: Spoken description for screen readers.

accessibility_hint: Spoken extra detail (iOS only).

accessibility_role: Semantic role for assistive tech.

accessible: Override whether the element is exposed to AT.

accessibility_state: Current widget state for assistive tech.

accessibility_live_region: How AT announces dynamic changes

(Android only).

test_id: Stable identifier for UI tests.

ref: Optional [`Ref`][pythonnative.Ref] for native-view access.

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] of type ``"Column"``.

"""

return _make_element(

"Column",

*children,

style=style,

ref=ref,

key=key,

gestures=gestures,

hit_slop=hit_slop,

on_layout=on_layout,

accessibility_label=accessibility_label,

accessibility_hint=accessibility_hint,

accessibility_role=accessibility_role,

accessible=accessible,

accessibility_state=accessibility_state,

accessibility_live_region=accessibility_live_region,

test_id=test_id,

_forced={"flex_direction": "column"},

)

def Row(

*children: Element,

style: StyleProp = None,

gestures: Optional[List[Any]] = None,

hit_slop: Optional[Union[float, Dict[str, float]]] = None,

on_layout: Optional[Callable[[Dict[str, float]], None]] = None,

accessibility_label: Optional[str] = None,

accessibility_hint: Optional[str] = None,

accessibility_role: Optional[str] = None,

accessible: Optional[bool] = None,

accessibility_state: Optional[AccessibilityState] = None,

accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,

test_id: Optional[str] = None,

ref: Optional[Ref] = None,

key: Optional[str] = None,

) -> Element:

"""Arrange children horizontally.

Convenience wrapper around [`View`][pythonnative.View] with

``flex_direction`` locked to ``"row"``. Use ``View`` directly if you

need to switch between row and column at runtime.

Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,

accessibility, ``test_id``); only ``flex_direction`` is fixed.

Args:

*children: Child elements arranged left to right.

style: Style dict (or list of dicts).

gestures: Gesture descriptors recognized natively on this view.

hit_slop: Extra touch target beyond the bounds (see ``View``).

on_layout: Callback invoked with

``{"x", "y", "width", "height"}`` after layout and on

frame changes.

accessibility_label: Spoken description for screen readers.

accessibility_hint: Spoken extra detail (iOS only).

accessibility_role: Semantic role for assistive tech.

accessible: Override whether the element is exposed to AT.

accessibility_state: Current widget state for assistive tech.

accessibility_live_region: How AT announces dynamic changes

(Android only).

test_id: Stable identifier for UI tests.

ref: Optional [`Ref`][pythonnative.Ref] for native-view access.

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] of type ``"Row"``.

"""

return _make_element(

"Row",

*children,

style=style,

ref=ref,

key=key,

gestures=gestures,

hit_slop=hit_slop,

on_layout=on_layout,

accessibility_label=accessibility_label,

accessibility_hint=accessibility_hint,

accessibility_role=accessibility_role,

accessible=accessible,

accessibility_state=accessibility_state,

accessibility_live_region=accessibility_live_region,

test_id=test_id,

_forced={"flex_direction": "row"},

)

def Spacer(

size: Optional[float] = None,

flex: Optional[float] = None,

key: Optional[str] = None,

) -> Element:

"""Insert empty space inside a flex container.

Pass ``size`` for a fixed gap, or ``flex`` to expand and absorb

remaining space.

Args:

size: Fixed gap in dp/pt along the parent's main axis. Mirrored

on both axes: whichever axis the parent's

``flex_direction`` chooses as main becomes the actual gap.

flex: Flex-grow weight; useful for pushing siblings to the

opposite end of a [`Row`][pythonnative.Row] or

[`Column`][pythonnative.Column].

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] of type ``"Spacer"``.

"""

width = size if size is not None else None

height = size if size is not None else None

return _make_element(

"Spacer",

key=key,

size=size,

width=width,

height=height,

flex=flex,

)

def ScrollView(

*children: Element,

refresh_control: Optional[Element] = None,

scroll_axis: Optional[Literal["vertical", "horizontal"]] = None,

on_scroll: Optional[Callable[[Dict[str, float]], None]] = None,

shows_scroll_indicator: bool = True,

paging_enabled: bool = False,

bounces: bool = True,

content_container_style: StyleProp = None,

keyboard_dismiss_mode: Optional[Literal["none", "on_drag", "interactive"]] = None,

style: StyleProp = None,

ref: Optional[Ref] = None,

key: Optional[str] = None,

) -> Element:

"""Wrap children in a scrollable container.

``ScrollView`` typically takes a single child (a ``Column`` or

``Row`` aggregating the scrollable content). It accepts ``*children``

for ergonomic call sites; the underlying native scroll view stacks

them on its content axis.

Args:

*children: Child elements to scroll.

refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]

element attached to the scroll view for pull-to-refresh.

scroll_axis: ``"vertical"`` (default) or ``"horizontal"``.

on_scroll: Callback invoked with ``{"x": …, "y": …}`` content

offsets as the user scrolls.

shows_scroll_indicator: When ``False``, hides the scroll bar.

paging_enabled: When ``True``, the scroll view snaps to

multiples of its own size (carousel behavior).

bounces: When ``False``, disables the iOS rubber-band overscroll.

content_container_style: Style applied to the inner content

wrapper (padding, alignment, spacing of the scrollable

content), distinct from ``style`` (the scroll view frame).

keyboard_dismiss_mode: ``"none"`` (default), ``"on_drag"``, or

``"interactive"``. Controls whether scrolling dismisses

the keyboard.

style: Style dict (or list of dicts).

ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] of type ``"ScrollView"``.

"""

return _make_element(

"ScrollView",

*children,

style=style,

ref=ref,

key=key,

refresh_control=_refresh_control_props(refresh_control, owner="ScrollView"),

scroll_axis=scroll_axis,

on_scroll=on_scroll,

shows_scroll_indicator=False if shows_scroll_indicator is False else None,

paging_enabled=paging_enabled or None,

bounces=False if bounces is False else None,

content_container_style=resolve_style(content_container_style) or None,

keyboard_dismiss_mode=keyboard_dismiss_mode,

)

# ======================================================================

# SafeAreaView

# ======================================================================

_SAFE_AREA_EDGES: Tuple[str, ...] = ("top", "left", "bottom", "right")

def _numeric_edge_padding(style: Dict[str, Any], edge: str) -> float:

"""Return the numeric padding already declared for ``edge`` in ``style``.

Only numeric values participate; percentage strings and dict

shorthands are left alone (the inset simply overrides them for

that edge). Resolution order matches the layout engine:

``padding_{edge}`` beats the axis shorthand, which beats

``padding``.

"""

axis_key = "padding_vertical" if edge in ("top", "bottom") else "padding_horizontal"

for key in (f"padding_{edge}", axis_key, "padding"):

value = style.get(key)

if isinstance(value, (int, float)) and not isinstance(value, bool):

return float(value)

return 0.0

@component

def _SafeAreaContainer(

*children: Element,

edges: Optional[Tuple[str, ...]] = None,

style: Optional[Dict[str, Any]] = None,

) -> Element:

"""Hook-driven body of `SafeAreaView`.

Reads the live insets via

[`use_safe_area_insets`][pythonnative.use_safe_area_insets] (so the

subtree re-renders when the platform publishes new values, e.g. on

rotation) and adds each selected edge's inset on top of any padding

the user declared for that edge.

"""

insets = use_safe_area_insets()

resolved: Dict[str, Any] = dict(style or {})

selected = edges or _SAFE_AREA_EDGES

for edge in _SAFE_AREA_EDGES:

if edge not in selected:

continue

inset = float(getattr(insets, edge, 0.0) or 0.0)

if inset > 0:

resolved[f"padding_{edge}"] = _numeric_edge_padding(resolved, edge) + inset

return Element("SafeAreaView", resolved, list(children))

def SafeAreaView(

*children: Element,

edges: Optional[Tuple[Literal["top", "left", "bottom", "right"], ...]] = None,

style: StyleProp = None,

key: Optional[str] = None,

) -> Element:

"""Container that respects safe-area insets (notch, status bar, home indicator).

Applies the platform-reported insets as extra padding on the

selected edges and re-renders automatically when the insets change

(rotation, split view). User padding on an inset edge is added to

the inset, matching ``react-native-safe-area-context``.

Args:

*children: Child elements that should avoid system UI overlays.

edges: Which edges to pad; defaults to all four.

style: Style dict (or list of dicts).

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] that renders a

``"SafeAreaView"`` container.

"""

return _SafeAreaContainer(

*children,

edges=tuple(edges) if edges else None,

style=resolve_style(style),

).with_key(key)

# ======================================================================

# KeyboardAvoidingView

# ======================================================================

@component

def _KeyboardAvoidingContainer(

*children: Element,

behavior: Literal["padding", "position", "height"] = "padding",

keyboard_vertical_offset: float = 0.0,

style: Optional[Dict[str, Any]] = None,

) -> Element:

"""Hook-driven body of `KeyboardAvoidingView`.

Subscribes to the platform-reported keyboard height via

[`use_keyboard_height`][pythonnative.use_keyboard_height] and

applies the shift according to ``behavior``:

- ``"padding"``: adds the shift as bottom padding, resizing the

content area (the default, and the right choice for forms

inside a full-height container).

- ``"position"``: translates the whole container upward without

resizing it (useful for pinned footers/toolbars).

- ``"height"``: shrinks the container's own height by the shift.

The resting height is captured via ``on_layout`` while the

keyboard is hidden, so flex-sized containers work too.

"""

keyboard = use_keyboard_height()

base_height, set_base_height = use_state(0.0)

mode = behavior or "padding"

offset = float(keyboard_vertical_offset or 0.0)

shift = max(0.0, keyboard - offset) if keyboard > 0 else 0.0

resolved: Dict[str, Any] = dict(style or {})

props: Dict[str, Any] = resolved

if mode == "height":

def _record_layout(frame: Dict[str, float]) -> None:

if keyboard <= 0:

measured = float(frame.get("height", 0.0))

if measured > 0 and abs(measured - base_height) > 0.5:

set_base_height(measured)

props = dict(resolved)

props["on_layout"] = _record_layout

if shift > 0 and base_height > 0:

props["height"] = max(0.0, base_height - shift)

elif shift > 0:

if mode == "position":

transform = list(resolved.get("transform") or [])

transform.append({"translate_y": -shift})

resolved["transform"] = transform

else:

resolved["padding_bottom"] = _numeric_edge_padding(resolved, "bottom") + shift

return Element("KeyboardAvoidingView", props, list(children))

def KeyboardAvoidingView(

*children: Element,

behavior: Literal["padding", "position", "height"] = "padding",

keyboard_vertical_offset: float = 0.0,

style: StyleProp = None,

key: Optional[str] = None,

) -> Element:

"""Wrap content that should shift up when the keyboard is shown.

Subscribes to the platform-reported keyboard height (via

[`use_keyboard_height`][pythonnative.use_keyboard_height]

internally) and shifts its content so the focused text input stays

visible. On iOS the height comes from

``UIKeyboardWillShowNotification``; on Android from the window's

IME insets.

Args:

*children: Children rendered inside the avoiding container.

behavior: ``"padding"`` (adds bottom padding, resizing the

content), ``"position"`` (translates the container upward

without resizing), or ``"height"`` (shrinks the

container's height by the keyboard overlap, matching

React Native's ``"height"`` behavior).

keyboard_vertical_offset: Distance in layout units already

covered by other UI (e.g. a nav bar); subtracted from the

keyboard height before applying the shift.

style: Style dict (or list of dicts).

key: Stable identity for keyed reconciliation.

Returns:

An [`Element`][pythonnative.Element] that renders a

``"KeyboardAvoidingView"`` container.

"""

return _KeyboardAvoidingContainer(

*children,

behavior=behavior,

keyboard_vertical_offset=keyboard_vertical_offset,

style=resolve_style(style),

).with_key(key)

pythonnative/src/pythonnative/components/layout.py at v0.43.1 · pythonnative/pythonnative · GitHub

Repository navigation

Expand file tree

Breadcrumbs

layout.py

Latest commit

History

Breadcrumbs

layout.py

File metadata and controls