Merge branch 'main' of https://github.com/gonzalezreal/textual into syntax-extensions

Author: gonzalezreal

Examples/TextualDemo/TextualDemo/TableDemo.swift

@@ -2,6 +2,8 @@ import SwiftUI
 import Textual
 
 struct TableDemo: View {
+  @State private var relativeWidth: CGFloat = 2.1
+
   private let content = """
     Sometimes it helps to step back and *observe the situation calmly*, especially 
     when the codebase feels larger than it should. You take a breath, open the 
@@ -32,6 +34,23 @@ struct TableDemo: View {
     for future you, and walk away while things are still calm. The code will still be
     here tomorrow, probably waiting patiently :awwwblob:.
     """
+  private let overflowContent = """
+    When the status board grows beyond the comfort of the sidebar, it’s time for a wider view.
+
+    | Feature Area     | Owner            | Status       | Notes                                                                 |
+    |------------------|------------------|--------------|-----------------------------------------------------------------------|
+    | Attachments      | Casey            | In progress  | Needs caching strategy; large emoji sets are still slow to resolve.   |
+    | Selection        | Drew             | Investigating| Selection handles are jittery with nested lists and inline links.     |
+    | Rendering        | Jae              | Stable       | Layout passes are predictable, but long cells should wrap cleanly.    |
+
+    After a few iterations, priorities shift and a more detailed breakdown appears.
+
+    | Milestone            | Target Date | Dependency        | Notes                                                  |
+    |----------------------|-------------|-------------------|--------------------------------------------------------|
+    | Rendering polish     | Sep 18      | Table overlays    | Needs scrollable headers without losing alignment.     |
+    | Selection fixes      | Sep 25      | Text layout       | Requires stable geometry on fast resize changes.       |
+    | Attachment pipeline  | Oct 02      | Caching strategy  | Large emoji sets should avoid repeated decode work.    |
+    """
 
   var body: some View {
     Form {
@@ -45,6 +64,20 @@ struct TableDemo: View {
         Text("Default Style")
         Text("Text Selection Enabled")
       }
+      Section {
+        HStack {
+          Text("Relative Width")
+          Slider(value: $relativeWidth, in: 1...3)
+        }
+        StructuredText(
+          markdown: overflowContent,
+          patternOptions: .init(emoji: .mastoEmoji)
+        )
+      } header: {
+        Text("Overflow Style")
+        Text("Horizontal Scroll")
+      }
+      .textual.tableStyle(.overflow(relativeWidth: relativeWidth))
       Section("GitHub Style") {
         StructuredText(
           markdown: content,

Sources/Textual/Internal/StructuredText/Style/ResolvedTableStyle.swift

@@ -1,6 +1,6 @@
 import SwiftUI
 
-// NB: Enables environment resolution in `TableStyle` and its background / overlay hooks.
+// NB: Enables environment resolution in `TableStyle`
 
 extension StructuredText {
   struct ResolvedTableStyle<S: TableStyle>: View {
@@ -16,46 +16,10 @@ extension StructuredText {
       style.makeBody(configuration: configuration)
     }
   }
-
-  struct ResolvedTableBackground<S: TableStyle>: View {
-    private let style: S
-    private let layout: TableLayout
-
-    init(_ style: S, layout: TableLayout) {
-      self.style = style
-      self.layout = layout
-    }
-
-    var body: S.Background {
-      style.makeBackground(layout: layout)
-    }
-  }
-
-  struct ResolvedTableOverlay<S: TableStyle>: View {
-    private let style: S
-    private let layout: TableLayout
-
-    init(_ style: S, layout: TableLayout) {
-      self.style = style
-      self.layout = layout
-    }
-
-    var body: S.Overlay {
-      style.makeOverlay(layout: layout)
-    }
-  }
 }
 
 extension StructuredText.TableStyle {
   @MainActor func resolve(configuration: Configuration) -> some View {
     StructuredText.ResolvedTableStyle(self, configuration: configuration)
   }
-
-  @MainActor func resolveBackground(layout: StructuredText.TableLayout) -> some View {
-    StructuredText.ResolvedTableBackground(self, layout: layout)
-  }
-
-  @MainActor func resolveOverlay(layout: StructuredText.TableLayout) -> some View {
-    StructuredText.ResolvedTableOverlay(self, layout: layout)
-  }
 }

Sources/Textual/Internal/StructuredText/Table.swift

@@ -36,22 +36,6 @@ extension StructuredText {
         .onPreferenceChange(TableCell.SpacingKey.self) { @MainActor in
           spacing = $0
         }
-        .backgroundPreferenceValue(TableCell.BoundsKey.self) { values in
-          GeometryReader { geometry in
-            let resolvedBackground = tableStyle.resolveBackground(
-              layout: .init(values, geometry: geometry)
-            )
-            AnyView(resolvedBackground)
-          }
-        }
-        .overlayPreferenceValue(TableCell.BoundsKey.self) { values in
-          GeometryReader { geometry in
-            let resolvedOverlay = tableStyle.resolveOverlay(
-              layout: .init(values, geometry: geometry)
-            )
-            AnyView(resolvedOverlay)
-          }
-        }
 
       AnyView(resolvedStyle)
     }

Sources/Textual/StructuredText/Style/Default/DefaultTableStyle.swift

@@ -12,18 +12,17 @@ extension StructuredText {
       configuration.label
         .textual.tableCellSpacing(horizontal: Self.borderWidth, vertical: Self.borderWidth)
         .textual.blockSpacing(.fontScaled(top: 1.6, bottom: 1.6))
-        .padding(Self.borderWidth)
-    }
-
-    public func makeOverlay(layout: StructuredText.TableLayout) -> some View {
-      Canvas { context, _ in
-        for divider in layout.dividers() {
-          context.fill(
-            Path(divider),
-            with: .style(DynamicColor.grayTertiary)
-          )
+        .textual.tableOverlay { layout in
+          Canvas { context, _ in
+            for divider in layout.dividers() {
+              context.fill(
+                Path(divider),
+                with: .style(DynamicColor.grayTertiary)
+              )
+            }
+          }
         }
-      }
+        .padding(Self.borderWidth)
     }
   }
 }

Sources/Textual/StructuredText/Style/Default/OverflowTableStyle.swift

@@ -0,0 +1,78 @@
+import SwiftUI
+
+extension StructuredText {
+  /// A table style that enables horizontal scrolling with a relative max width ratio.
+  ///
+  /// Use ``TextualNamespace/overflowMode(_:)`` to switch between scrolling and wrapping.
+  public struct OverflowTableStyle: TableStyle {
+    private static let borderWidth: CGFloat = 1
+
+    private let relativeWidth: CGFloat
+
+    /// Creates an overflow table style.
+    ///
+    /// - Parameter relativeWidth: The maximum width ratio relative to the scroll container width. Defaults to `1.5`.
+    public init(relativeWidth: CGFloat = 1.5) {
+      self.relativeWidth = relativeWidth
+    }
+
+    public func makeBody(configuration: Configuration) -> some View {
+      Overflow { state in
+        let maxWidth = state.containerWidth.map {
+          $0 * relativeWidth
+        }
+        configuration.label
+          .fixedSize(horizontal: false, vertical: true)
+          .frame(maxWidth: maxWidth, alignment: .leading)
+          .textual.tableOverlay { layout in
+            Canvas { context, _ in
+              for divider in layout.dividers() {
+                context.fill(
+                  Path(divider),
+                  with: .style(DynamicColor.grayTertiary)
+                )
+              }
+            }
+          }
+          .padding(Self.borderWidth)
+      }
+      .textual.tableCellSpacing(horizontal: Self.borderWidth, vertical: Self.borderWidth)
+      .textual.blockSpacing(.fontScaled(top: 1.6, bottom: 1.6))
+    }
+  }
+}
+
+extension StructuredText.TableStyle where Self == StructuredText.OverflowTableStyle {
+  /// A table style that enables horizontal scrolling with a relative max width.
+  public static var overflow: Self {
+    .init()
+  }
+
+  /// A table style that enables horizontal scrolling with a relative max width.
+  ///
+  /// - Parameter relativeWidth: The maximum width ratio relative to the scroll container width.
+  public static func overflow(relativeWidth: CGFloat) -> Self {
+    .init(relativeWidth: relativeWidth)
+  }
+}
+
+@available(tvOS, unavailable)
+@available(watchOS, unavailable)
+#Preview {
+  StructuredText(
+    markdown: """
+      The sky above the port was the color of television, tuned to a dead channel.
+
+      Sloth speed  | Description                           | Notes
+      ------------ | ------------------------------------- | ---------------------------------------------
+      `slow`       | Moves slightly faster than a snail    | Good for sightseeing along the waterfront.
+      `medium`     | Moves at an average speed             | Balanced choice for day-to-day commuting.
+      `fast`       | Moves faster than a hare              | Best for urgent deliveries across town.
+      `supersonic` | Moves faster than the speed of sound  | Only for the bravest sloths.
+
+      It was a bright cold day in April, and the clocks were striking thirteen.
+      """
+  )
+  .padding()
+  .textual.tableStyle(.overflow)
+}

Sources/Textual/StructuredText/Style/GitHub/GitHubTableStyle.swift

@@ -12,30 +12,28 @@ extension StructuredText {
       configuration.label
         .textual.tableCellSpacing(horizontal: Self.borderWidth, vertical: Self.borderWidth)
         .textual.blockSpacing(.init(top: 0, bottom: 16))
-        .padding(Self.borderWidth)
-        .border(DynamicColor.gitHubBorder, width: Self.borderWidth)
-    }
-
-    public func makeBackground(layout: StructuredText.TableLayout) -> some View {
-      Canvas { context, _ in
-        for bounds in layout.evenRowBounds {
-          context.fill(
-            Path(bounds.integral),
-            with: .style(DynamicColor.gitHubSecondaryBackground)
-          )
+        .textual.tableBackground { layout in
+          Canvas { context, _ in
+            for bounds in layout.evenRowBounds {
+              context.fill(
+                Path(bounds.integral),
+                with: .style(DynamicColor.gitHubSecondaryBackground)
+              )
+            }
+          }
         }
-      }
-    }
-
-    public func makeOverlay(layout: StructuredText.TableLayout) -> some View {
-      Canvas { context, _ in
-        for divider in layout.dividers() {
-          context.fill(
-            Path(divider),
-            with: .style(DynamicColor.gitHubBorder)
-          )
+        .textual.tableOverlay { layout in
+          Canvas { context, _ in
+            for divider in layout.dividers() {
+              context.fill(
+                Path(divider),
+                with: .style(DynamicColor.gitHubBorder)
+              )
+            }
+          }
         }
-      }
+        .padding(Self.borderWidth)
+        .border(DynamicColor.gitHubBorder, width: Self.borderWidth)
     }
   }
 }

Sources/Textual/StructuredText/Style/Overflow.swift

@@ -8,6 +8,22 @@ public enum OverflowMode: Hashable {
   case scroll
 }
 
+/// Describes the current overflow behavior and available layout metrics.
+public enum OverflowState: Hashable {
+  /// Wraps content to fit the available width.
+  case wrap
+  /// Scrolls horizontally. The container width is provided when available.
+  case scroll(containerWidth: CGFloat?)
+
+  /// The scroll container width when available; otherwise `nil`.
+  public var containerWidth: CGFloat? {
+    guard case .scroll(let containerWidth) = self else {
+      return nil
+    }
+    return containerWidth
+  }
+}
+
 /// A container that adapts to the current ``OverflowMode``.
 ///
 /// `Overflow` handles content that overflows horizontally. It can switch
@@ -20,28 +36,48 @@ public enum OverflowMode: Hashable {
 ///   Using a horizontal `ScrollView` directly will interfere with text selection gestures.
 public struct Overflow<Content: View>: View {
   @Environment(\.overflowMode) private var mode
+  @State private var containerWidth: CGFloat?
+  @State private var contentHeight: CGFloat?
 
-  private let content: () -> Content
+  private let content: (OverflowState) -> Content
 
   /// Creates an overflow container.
   public init(@ViewBuilder content: @escaping () -> Content) {
+    self.init { _ in
+      content()
+    }
+  }
+
+  /// Creates an overflow container that exposes the current overflow state.
+  public init(@ViewBuilder content: @escaping (_ state: OverflowState) -> Content) {
     self.content = content
   }
 
   public var body: some View {
     switch mode {
     case .wrap:
-      content()
+      content(.wrap)
         .frame(maxWidth: .infinity, alignment: .leading)
 
     case .scroll:
       ScrollView(.horizontal) {
-        content()
-          // Make text selection local in scrollable regions
-          .modifier(TextSelectionInteraction())
-          .transformPreference(Text.LayoutKey.self) { value in
-            value = []
-          }
+        ZStack {
+          // Update the scroll view height when the content height changes
+          Color.clear
+            .frame(minHeight: contentHeight)
+          content(.scroll(containerWidth: containerWidth))
+            .onGeometryChange(for: CGFloat.self, of: \.size.height) {
+              contentHeight = $0
+            }
+            // Make text selection local in scrollable regions
+            .modifier(TextSelectionInteraction())
+            .transformPreference(Text.LayoutKey.self) { value in
+              value = []
+            }
+        }
+      }
+      .onScrollGeometryChange(for: CGFloat.self, of: \.containerSize.width) {
+        containerWidth = $1
       }
       // Propagate gesture exclusion area
       .background(