Textual Documentation

Textual uses three distinct coordinate systems to manage navigation, logic, and rendering:

• Structural Navigation (TextPosition): Uses a hierarchical IndexPath structure ([layout, line, run, runSlice]) to navigate the layout and track selection state.
• Text Operations: Uses character indices (integer offsets into attributed strings) for operations like word navigation.
• Visual Geometry: Uses CGRect and CGPoint derived from Text.Layout to provide bounds and origins for overlay rendering (e.g., positioning an image attachment).

Textual provides a .fontScaled() measurement system to ensure layouts scale harmoniously with text size and accessibility settings. You can use these values for padding, block spacing, frame sizes, and insets. A value of .fontScaled(0.5) creates a measurement equal to half of the current font size.

.textual.padding(.fontScaled(1.0))
.textual.blockSpacing(.fontScaled(top: 0.8, bottom: 1.2))

Attachments (like images via run.imageURL) are handled in two phases:

1. Parsing Phase: The parser identifies the attachment reference and stores it as an attribute within the AttributedString.
2. Resolution Phase: WithAttachments asynchronously resolves these references using environment-provided attachment loaders. Once loaded, the attribute is updated to a Textual.Attachment type, allowing the rest of the pipeline to treat it as a standard run.

To implement custom attachment loading, ensure you provide the appropriate loaders via the SwiftUI environment.

Block styling is handled at the view level rather than the attribute level.

1. Grouping: BlockContent groups runs by their PresentationIntent.
2. View Creation: It creates specific views for different types, such as Paragraph, Heading, OrderedList, etc.
3. Customization: You can customize these blocks by implementing style protocols that receive the content and associated metadata.
4. Spacing: BlockVStack manages the reconciliation of spacing between adjacent blocks using SwiftUI preferences.

To use Textual in a SwiftPM project, add the package dependency to your Package.swift file and include the Textual product in your target's dependencies.

dependencies: [
  .package(url: "https://github.com/gonzalezreal/textual", from: "0.1.0")
]

// In your target definition:
.product(name: "Textual", package: "textual")

You can customize InlineText using standard SwiftUI modifiers (like .font() and .foregroundStyle()) or Textual's specific .textual.inlineStyle(_:) modifier to define styles for code, emphasis, and more.

InlineText(
  markdown: "Use `git status` to check _uncommitted changes_"
)
.font(.custom("Avenir Next", size: 18))
.textual.inlineStyle(
  InlineStyle()
    .code(
      .monospaced,
      .fontScale(0.85),
      .backgroundColor(.purple),
      .foregroundColor(.white)
    )
    .emphasis(.italic, .underlineStyle(.single))
)

Use StructuredText for documents containing structured elements like headings, paragraphs, lists, blockquotes, and tables. Each block type can be customized independently.

StructuredText(
  markdown: """
    ## The Problem

    > After merging PR #347, users reported that tapping "Back" from the detail view would sometimes
    > navigate to a completely random screen.

    Here's what we knew going in:

    - The issue only appeared **after** the state restoration changes
    - It happened _inconsistently_—maybe 1 in 5 back navigations
    """
)

Use InlineText for content that requires inline formatting (like bold, italics, or code), images, and links. It acts as a drop-in replacement for SwiftUI's Text but with attachment support and comprehensive styling. It flows naturally within its container.

InlineText(
  markdown: """
    This is a *lighthearted* but **perfectly serious** paragraph where `inline code` lives \"happily alongside ~~a terrible idea~~ a better one, a [useful link](https://example.com), \"and a bit of _extra emphasis_ just for style. To keep things interesting without overdoing \"it, here’s a completely random image that adapts to the container width:\n\n    ![Random image](https://picsum.photos/seed/textual/400/250)\n    """
)

Textual supports syntax extensions via the syntaxExtensions parameter.

• Emoji: Define custom emoji using Emoji objects with a shortcode and a URL.
• Math: Enable math expression rendering by including .math in the extensions.

// Custom Emoji
let emoji: Set<Emoji> = [
  Emoji(shortcode: "rocket", url: URL(string: "https://example.com/rocket.png")!),
  Emoji(shortcode: "sparkles", url: URL(string: "https://example.com/sparkles.gif")!),
]

InlineText(
  markdown: "Shipped the new feature :rocket: and it's working :sparkles:",
  syntaxExtensions: [.emoji(emoji)]
)

// Math
StructuredText(
  markdown: "The area is $A = \\pi r^2$.",
  syntaxExtensions: [.math]
)

For full control over the entire document's appearance, implement the StructuredText.Style protocol. This allows you to define a cohesive theme by providing implementations for inlineStyle, headingStyle, paragraphStyle, and list markers.

struct CompactStyle: StructuredText.Style {
  var inlineStyle: InlineStyle {
    InlineStyle()
      .code(.monospaced, .fontScale(0.9))
      .strong(.fontWeight(.semibold))
  }

  var headingStyle: some StructuredText.HeadingStyle { ... }
  var paragraphStyle: some StructuredText.ParagraphStyle { ... }

  var unorderedListMarker: StructuredText.UnorderedListMarker {
    .hierarchical(.disc, .circle, .square)
  }

  var orderedListMarker: StructuredText.OrderedListMarker {
    .decimal
  }
}

// Apply the custom style
StructuredText(markdown: content)
  .textual.structuredTextStyle(CompactStyle())