Introduce parley_flow

This introduces a small, flow‑first layer on top of Parley that treats
a document as an ordered set of text blocks, with explicit container
rectangles defining where each block lives. The flow owns geometry
and the “join” between neighboring blocks (e.g., space vs newline),
while blocks only supply layout and text. On top of this, the crate
provides hit‑testing, selection geometry, and cross‑block text
extraction, so you can drag through multiple paragraphs/labels and
get predictable results.

Motivation

- Borrow from proven platform models (e.g., TextKit containers):
  separate shaping/layout from flow/regions, keep APIs small and durable.
- Reduce ambiguity and API surface: one explicit flow path for
  hit‑testing, selection, and copy, instead of guessing based
  on per‑layout state.
- Keep integration simple: a convenience builder stacks blocks
  vertically when you don’t want to hand author rects; otherwise,
  supply rectangles you already have in your UI.

Author: waywardmonkeys

Cargo.lock

@@ -7,6 +7,7 @@ members = [
     "parley_bench",
     "parley_core",
     "parley_dev",
+    "parley_flow",
     "examples/tiny_skia_render",
     "examples/swash_render",
     "examples/vello_editor",

Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "parley_flow"
+description = "High-level text surfaces, multi-selection, and document aggregation on top of parley"
+keywords = ["text", "layout", "flow"]
+categories = ["gui", "graphics"]
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+exclude = ["/tests"]
+readme = "README.md"
+
+[package.metadata.docs.rs]
+all-features = true
+
+[lints]
+workspace = true
+
+[features]
+default = ["std"]
+std = ["parley/std"]
+libm = ["parley/libm"]
+
+[dependencies]
+parley = { workspace = true }

parley_flow/Cargo.toml

@@ -0,0 +1,14 @@
+parley_flow (TextBlock + TextFlow)
+=====================================
+
+A small, flow-first layer on top of Parley that introduces:
+
+- TextBlock: a minimal trait for blocks of laid-out text (paragraphs, labels)
+- LayoutBlock: adapter for a `parley::layout::Layout` + `&str`
+- TextFlow: explicit ordered containers (rect + join policy) for deterministic hit-testing,
+  cross-block navigation, and text concatenation
+- Flow-based helpers: `hit_test`, `selection_geometry`, `copy_text`
+
+Status: experimental. Names and APIs may change as this evolves.
+
+See `src/design.rs` for comparisons to TextKit/DirectWrite/Android and long-term goals.

parley_flow/README.md

@@ -0,0 +1,71 @@
+//! Minimal example showing surfaces, multi-selection geometry, and copy.
+
+use parley::{Alignment, AlignmentOptions, FontContext, Layout, LayoutContext, StyleProperty};
+use parley_flow::{
+    BoundaryPolicy, LayoutBlock, SelectionSegment, SelectionSet, copy_text, flow::TextFlow,
+    hit_test, selection_geometry,
+};
+
+fn build_layout<'a>(
+    font_cx: &mut FontContext,
+    layout_cx: &mut LayoutContext<()>,
+    text: &'a str,
+) -> Layout<()> {
+    let mut builder = layout_cx.ranged_builder(font_cx, text, 1.0, true);
+    builder.push_default(StyleProperty::FontSize(16.0));
+    let mut layout: Layout<()> = builder.build(text);
+    let width = Some(200.0);
+    layout.break_all_lines(width);
+    layout.align(width, Alignment::Start, AlignmentOptions::default());
+    layout
+}
+
+fn main() {
+    // Build two simple paragraph layouts with Parley
+    let mut font_cx = FontContext::new();
+    let mut layout_cx = LayoutContext::new();
+
+    let text1 = "Hello world";
+    let text2 = "Second line";
+    let layout1 = build_layout(&mut font_cx, &mut layout_cx, text1);
+    let layout2 = build_layout(&mut font_cx, &mut layout_cx, text2);
+
+    // Wrap them as surfaces with y-offsets stacked vertically
+    let surfaces = vec![
+        LayoutBlock {
+            id: 0u32,
+            layout: &layout1,
+            text: text1,
+        },
+        LayoutBlock {
+            id: 1u32,
+            layout: &layout2,
+            text: text2,
+        },
+    ];
+    let flow = TextFlow::<u32>::from_vertical_stack::<(), _>(&surfaces, BoundaryPolicy::Newline);
+
+    // Hit-test near the start of the first paragraph to get a caret
+    let caret = hit_test::<(), _>(&flow, &surfaces, 2.0, 2.0).expect("caret");
+    println!("Caret: {:?}", caret);
+
+    // Build a multi-selection spanning both surfaces
+    let mut set = SelectionSet::collapsed(caret);
+    set.add_segment(SelectionSegment::new(0, 0..5)); // "Hello"
+    set.add_segment(SelectionSegment::new(1, 0..6)); // "Second"
+
+    // Compute geometry (global coordinates)
+    let mut rects = Vec::new();
+    selection_geometry::<(), _, _>(&flow, &surfaces, &set, |bb, _| rects.push((bb, 0)));
+    println!("Selection rects (count={}):", rects.len());
+    for (bb, surface_ix) in &rects {
+        println!(
+            "  surface={} rect=({},{})->({},{}))",
+            surface_ix, bb.x0, bb.y0, bb.x1, bb.y1
+        );
+    }
+
+    // Extract text across surfaces
+    let copied = copy_text::<(), _>(&flow, &surfaces, &set);
+    println!("Copied text:\n{}", copied);
+}

parley_flow/examples/basic.rs

@@ -0,0 +1,105 @@
+//! Text blocks and a simple adapter for Parley [`parley::layout::Layout`].
+
+use alloc::string::String;
+use core::ops::Range;
+
+use parley::layout::Layout;
+use parley::style::Brush;
+
+/// A uniform facade for anything that behaves like a text layout block.
+///
+/// Implementers must provide:
+/// - A stable identifier (`id`).
+/// - A layout reference for geometry and hit-testing.
+/// - Text access for extraction via [`TextBlock::text_slice`] and/or
+///   [`TextBlock::read_text`].
+///
+/// Geometry and ordering are defined by `FlowItem` rectangles in a `TextFlow`; this
+/// trait does not carry positional information.
+pub trait TextBlock<B: Brush> {
+    /// Identifier type used by this surface set.
+    type Id: Copy + Ord + Eq + core::fmt::Debug;
+
+    /// Stable identifier for the surface.
+    fn id(&self) -> Self::Id;
+
+    /// The underlying Parley layout for this surface.
+    ///
+    /// This is typically a [`parley::layout::Layout`] built by your code.
+    fn layout(&self) -> &Layout<B>;
+
+    /// Return a borrowed text slice for a local byte `range`, if valid and contiguous.
+    ///
+    /// This is the fast path used when the underlying storage is contiguous. Implementers that
+    /// do not have contiguous storage (e.g., ropes) can return `None` and instead implement
+    /// [`TextBlock::read_text`]. The `range` must be on UTF‑8 character boundaries.
+    fn text_slice(&self, _range: Range<usize>) -> Option<&str> {
+        None
+    }
+
+    /// Append the text in the local byte `range` into `out` and return `true` if successful.
+    ///
+    /// This is the fallback used by helpers like [`crate::copy_text`] to support non‑contiguous
+    /// storage. The default implementation tries [`TextBlock::text_slice`] and, if present,
+    /// pushes it into `out`.
+    fn read_text(&self, range: Range<usize>, out: &mut String) -> bool {
+        if let Some(s) = self.text_slice(range) {
+            out.push_str(s);
+            true
+        } else {
+            false
+        }
+    }
+}
+
+/// A simple adapter turning a Parley [`parley::layout::Layout`] and source text into a
+/// [`TextBlock`].
+///
+/// Construct this when you already have a `Layout` and the `&str` it was built from, then
+/// pass it to helpers like [`crate::hit_test`], [`crate::selection_geometry`], and
+/// [`crate::copy_text`].
+#[derive(Copy, Clone)]
+pub struct LayoutBlock<'a, B: Brush, Id> {
+    /// Stable identifier for the surface.
+    pub id: Id,
+    /// The layout to expose.
+    pub layout: &'a Layout<B>,
+    /// The source text used to build `layout`.
+    pub text: &'a str,
+}
+
+impl<'a, B: Brush, Id: Copy + Ord + Eq + core::fmt::Debug> TextBlock<B> for LayoutBlock<'a, B, Id> {
+    type Id = Id;
+
+    fn id(&self) -> Self::Id {
+        self.id
+    }
+
+    fn layout(&self) -> &Layout<B> {
+        self.layout
+    }
+
+    fn text_slice(&self, range: Range<usize>) -> Option<&str> {
+        self.text.get(range)
+    }
+
+    fn read_text(&self, range: Range<usize>, out: &mut String) -> bool {
+        if let Some(slice) = self.text.get(range) {
+            out.push_str(slice);
+            true
+        } else {
+            false
+        }
+    }
+}
+
+impl<'a, B: Brush, Id: Copy + Ord + Eq + core::fmt::Debug> core::fmt::Debug
+    for LayoutBlock<'a, B, Id>
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.debug_struct("LayoutBlock")
+            .field("id", &self.id)
+            .field("text_len", &self.text.len())
+            .finish_non_exhaustive()
+    }
+}

parley_flow/src/block.rs

@@ -0,0 +1,151 @@
+//! Design notes, comparisons, and long-term considerations.
+//!
+//! Parley’s core (`parley`) is intentionally paragraph-focused and pure: it owns shaping,
+//! line breaking, bidi, and alignment. This crate builds a higher-level layer for composing
+//! many paragraphs/surfaces and for modeling multi-selection/navigation.
+//!
+//! ## Inspiration and Comparisons
+//!
+//! ### Apple TextKit 1/2
+//!
+//! - Layering: `NSTextStorage` (attributed storage) → `NSLayoutManager`/`NSTextLayoutManager`
+//!   (shaping/line breaking) → `NSTextContainer` (geometry/regions). Storage can flow through
+//!   multiple containers for columns/pages.
+//! - Selection/navigation: First-class objects (`NSTextSelection`, `NSTextSelectionNavigation`)
+//!   with anchor/focus, affinity, and granularity (character/word/line/paragraph).
+//! - Attachments: `NSTextAttachment` uses object-replacement semantics, which maps to Parley
+//!   inline boxes and helps serialization (U+FFFC placeholder).
+//! - Takeaways for us:
+//!   - Preserve a strict separation: storage vs. layout vs. region.
+//!   - Model selection/navigation as reusable services that operate over regions/surfaces.
+//!   - Treat inline objects as real selection units and serialization boundaries.
+//!
+//! ### Windows DirectWrite + TSF
+//!
+//! - DirectWrite: paragraph-centric layouts (`IDWriteTextLayout`) composed by host toolkits
+//!   into documents. Justification, trimming, and typographic knobs exposed as explicit options.
+//! - TSF (Text Services Framework): composition (IME) modeled as ranges; selection kept in sync;
+//!   UTF‑16 code unit indexing as lingua franca.
+//! - Takeaways:
+//!   - Keep layout per-paragraph; composition/selection are ranges in storage.
+//!   - Provide explicit UTF‑8↔UTF‑16 conversions at the edges for platform interoperability.
+//!   - Don’t bake editing into layout; keep layout pure and reusable.
+//!
+//! ### Android (Spannable, MovementMethod, InputConnection)
+//!
+//! - Ranges: Spans with inclusive/exclusive flags survive edits; replacement spans for attachments.
+//! - Navigation: MovementMethod separates navigation from widgets, enabling reuse across views.
+//! - IME: InputConnection is an explicit bridge for composition, commit, and selection updates.
+//! - Precompute: Precomputed/Measured text validates doing shaping/measurement off the UI thread
+//!   and reusing results (like `LayoutContext`).
+//! - Cautions: span proliferation and watchers can become hot paths; cross-widget selection is
+//!   not first-class.
+//! - Takeaways:
+//!   - Favor compact range tables over callback-heavy span objects.
+//!   - Keep navigation and IME bridges separate, explicit, and host-driven.
+//!   - Make async/precomputed layout a supported pattern via caches + generations.
+//!
+//! ### WPF/Web (brief)
+//!
+//! - WPF: `TextContainer`/`TextPointer`/`TextSelection` abstractions, flow across regions.
+//! - Web: `Range` across nodes, selection APIs that treat node boundaries as hard breaks; rich
+//!   serialization policies matter.
+//! - Takeaways:
+//!   - Encapsulate positions as abstract pointers, not raw indices.
+//!   - Provide serialization policies (logical/visual order, boundary separators).
+//!
+//! ## Key Choices for a 10+ Year Horizon
+//!
+//! - Keep editor/navigation policies out of `Layout`; implement them in this crate.
+//! - Favor explicit types for locations/ranges across surfaces, with conversions to platform units.
+//! - Treat surface boundaries as hard boundaries for movement/word/line granularity.
+//! - Provide read-only aggregation (copy/search/AX) across surfaces by default; editing across
+//!   multiple surfaces is opt-in and typically limited to a single active caret.
+//!
+//! ## Future Work
+//!
+//! ### Surface Flow and Ordering
+//!
+//! Parley surfaces are intentionally minimal. Explicit flow is modeled by `flow::TextFlow`:
+//! - Each `FlowItem` encodes a `block_id`, a `rect` (for hit-testing/geometry), and a `join`
+//!   policy for serialization.
+//! - Order in the `TextFlow` defines cross-block navigation and concatenation semantics.
+//! - This mirrors TextKit’s ordered container array.
+//!
+//! Guidance:
+//! - Provide non-overlapping `rect`s in the flow for deterministic hit-testing.
+//! - Use large widths/heights when you don’t care about precise bounds; the flow determines order.
+//! - For multi-column/page or virtualized layouts, build the `TextFlow` with the intended reading
+//!   order and rects for each visible block.
+//! - Concatenation: use a uniform `join` via [`crate::flow::TextFlow::from_vertical_stack`] or assign
+//!   per-item `join` policies (e.g., `Space` for inline, `Newline` for block boundaries).
+//!
+//! ### 1) TextLocation and TextRange (positions across surfaces)
+//!
+//! - Purpose: decouple pointer/range representations from raw indices; enable safe conversions to
+//!   platform units and stable identity across edits.
+//! - Shape:
+//!   - `TextLocation { surface_id, utf8: usize }` with helpers: `to_utf16()`, `from_utf16()`.
+//!   - `TextRange { start: TextLocation, end: TextLocation }`, normalized with methods for
+//!     granularity expansion (to cluster/word/line/paragraph) using the surface’s layout.
+//! - Invariants:
+//!   - Always at character boundaries in UTF‑8; conversion to UTF‑16 is lossy only in units, not
+//!     in meaning.
+//!   - Stable `surface_id` and monotonic ordering within a surface.
+//! - Interop:
+//!   - Map to TSF/AppKit APIs that require UTF‑16 indices; provide zero‑allocation conversions.
+//!   - Serialize as absolute (surface_id, byte_offset) to avoid ambiguity when text changes.
+//! - Integration:
+//!   - Backed by the same hit-testing code as current `Cursor`/`Selection`.
+//!   - Acts as the wire type for accessibility and IME bridges.
+//!
+//! ### 2) SelectionNavigation (surface‑crossing caret movement)
+//!
+//! - Purpose: unify navigation semantics (move/extend by cluster/word/line/paragraph) across
+//!   multiple surfaces in visual order, mirroring Apple’s `NSTextSelectionNavigation`.
+//! - Current scaffold:
+//!   - Implemented in `crate::selection_navigation` with `move_left`/`move_right` that cross
+//!     surface boundaries by jumping to the end/start of adjacent surfaces.
+//!   - Inside a surface, movement delegates to Parley’s `Cursor` logic.
+//!   - Tests cover crossing from the end of one surface to the start of the next, and vice versa.
+//! - Next steps:
+//!   - Vertical movement preserving `h_pos`: `move_line_up`/`move_line_down`.
+//!   - Word/paragraph granularity: `move_word_left/right`, `hard_line_start/end`.
+//!   - Extend variants (Shift-modify): introduce an anchor caret in `SelectionSet` or pass a
+//!     transient anchor so movement can grow/shrink the nearest segment or add cross-surface
+//!     segments.
+//!   - Surface ordering predicates: allow clients to supply ordering beyond y-offset (e.g., columns).
+//! - Semantics to retain:
+//!   - Affinity and bidi: respect `Cursor` affinity at line ends; treat surface edges as hard
+//!     boundaries; never span a cluster across surfaces.
+//!   - Vertical movement: maintain a sticky `h_pos` in global coordinates; when moving across
+//!     surfaces, compute target y in the next surface via its `y_offset` and line metrics.
+//!   - Word/line boundaries: use per-surface rules; when crossing a surface, land at the first/last
+//!     selectable boundary inside the target surface.
+//! - Testing:
+//!   - Golden tests for bidi line ends, RTL/LTR boundaries, mixed metrics; property tests for
+//!     inverse moves where appropriate.
+//!
+//! ### 3) Document Storage and Incremental Relayout
+//!
+//! - Purpose: provide a concrete “document” built from paragraphs with efficient editing,
+//!   invalidation, and relayout, while still exposing each paragraph as a `TextBlock`.
+//! - Storage:
+//!   - Use a rope or gap buffer for large texts; maintain paragraph boundaries as a side table of
+//!     byte ranges with stable paragraph IDs.
+//!   - Inclusive/exclusive range flags for styles, composition, and annotations that survive edits.
+//! - Invalidation:
+//!   - When editing, detect impacted paragraphs (splits/merges on newlines) and only rebuild
+//!     affected layouts; reuse shaped results when attributes allow.
+//!   - Employ generations to coordinate caches (fonts, shaping, line breaking) and async rebuilds.
+//! - Layout:
+//!   - Build each paragraph’s `Layout` via `LayoutContext`; cache glyph/cluster data.
+//!   - Support async layout: produce placeholder metrics/geometry, swap in final results when ready.
+//! - Regions:
+//!   - Flow paragraphs into regions (columns/pages) by assigning `y_offset`s; each paragraph is a
+//!     `TextBlock` with its own layout and text slice.
+//! - Attachments:
+//!   - Represent as inline boxes using object‑replacement semantics (U+FFFC) for selection and
+//!     serialization; geometry carried by the inline box.
+//!
+//! This module contains only documentation.