[Primitives] - Create a Text widget

[matthew-carroll]

Create a widget that matches Swift UI's Text view.

Swift UI Docs: https://developer.apple.com/documentation/swiftui/text

[matthew-carroll]

@Maatteogekko @vincevargadev - Can you two take a look at the API design at the bottom of the Wiki for Text?

I've described an API that I think should cover the bases for Accessibility and Localization. Can you look for any holes in that API?

[Maatteogekko]

The Localization part seems fine. Just a couple of considerations.
I don't understand why LocalizedStringResource has locale required.
I think bundle won't be useful in the context of flutter apps, but better to keep it and remove it later, when more thought has gone into it.

Another thing. I noticed there is no property for LocalizedStringKey. In swiftUI it is needed to make string variables discoverable to Xcode's automatic localizable strings discovery. Were you aware of this?
Proper support for this mechanism may be outside the scope of the swift_ui package though. What do you think?

[matthew-carroll]

@Maatteogekko

I don't understand why LocalizedStringResource has locale required.

Is there a purpose for a LocalizedStringResource if it doesn't have a locale? Isn't the locale what makes it "localized"?

Another thing. I noticed there is no property for LocalizedStringKey

Can you specify where exactly you expected that to appear in the API?

[Maatteogekko]

Is there a purpose for a LocalizedStringResource if it doesn't have a locale...

Sure, but I expect it to be optional. If not provided it should be resolved at runtime, from the context of the Text widget.

LocalizedStringKey makes sense to include only if we plan on implementing an automatic way to extract localizable strings from code, like Xcode does.

[matthew-carroll]

@Maatteogekko - But what's the purpose of a LocalizedStringResource without a locale? Why wouldn't you just pass a regular String if you don't want to specify a Locale? In other words, what's the actual use-case for a LocalizedStringResource without a Locale?

[Maatteogekko]

To bundle all the localization parameters for the Text widget in a single object. This is a use case that the SwiftUI API allows, so I think it's important to include.

[matthew-carroll]

The locale property doesn't seem to be nullable: https://developer.apple.com/documentation/foundation/localizedstringresource/3988424-locale

[Maatteogekko]

please see https://developer.apple.com/documentation/foundation/localizedstringresource/3988421-init

[matthew-carroll]

Ok, so .current is a Locale and that's set as the locale when none is provided. Does Flutter have a definition for the "current locale"?

[Maatteogekko]

There is WidgetsBinding.instance.platformDispatcher.locale

[vincevargadev]

The proposed text accessibility configuration looks good, the only thing I might do differently are the nullability of the TextAccessibility and its fields. I'll write up a proposal this weekend.

[matthew-carroll]

@vincevargadev do we need a whole proposal for that? It sounds like there's just one category of issue there. Can you describe why you'd change the nullability? Can you also specify which fields?

[vincevargadev]

This is what I'd propose:

class TextAccessibility {
    const TextAccessibility({/*...*/});

    /// This could either default to `speechAdjustedPitch = 1`,
    /// or we "do nothing" by default with a `speechAdjustedPitch = null`.
    final double speechAdjustedPitch;
    
    /// Punctuation needs to handle three states:
    /// * "default" punctuation with `null` to let VoiceOver decide based on context
    /// * on and off with `true` and `false
    final bool? speechAlwaysIncludesPunctuation;

    /// Doesn't need to be nullable as the default behavior matches the
    /// `speechSpellsOutCharacters = false` case.
    final bool speechSpellsOutCharacters;

    /// Make it nullable, as it's optional and not needed in most cases.
    final AccessibilityHeading? accessibilityHeading;

    /// Make it nullable, as it's optional and not needed in most cases.
    final Set<AccessibilityTrait>? accessibilityTraits;

    /// Make it nullable, as by default, the text content is spoken by VoiceOver,
    /// and `accessibilityLabel` is only needed if the text content needs to be overridden.
    final String? accessibilityLabel;
    
    // DIRECTION: Include equality override to avoid needless widget rebuilds
}

[vincevargadev]

I opened a PR #20 tldr: Text accessibility labels can be localized, and we should handle that case, too.

Do you have any suggestions, @Maatteogekko, about how to handle this case?

If I see it right, we need to handle two cases for the accessibility label (either translated or not):

class TextAccessibility {
    /// Make it nullable, as by default, the text content is spoken by VoiceOver,
    /// and `accessibilityLabel` is only needed if the text content needs to be overridden.
    final AccessibilityLabel? accessibilityLabel;
}

// A couple of ways to represent it internally, so I only specify the constructors for clarity.
class AccessibilityLabel {
  AccessibilityLabel.verbatim(String value);
  AccessibilityLabel.localized(String value);
  /// ...
}

[Maatteogekko]

@vincevargadev the most important thing is to keep it consistent with the Text specification.

AccessibilityLabel(this.localizedAccessibilityLabelKey);
AccessibilityLabel.verbatim(String text)

I admit that localizedAccessibilityLabelKey is a bit too verbose.

[matthew-carroll]

As mentioned, consistency with existing Swift UI APIs is one of the most important things. We want to avoid developers needing to remember the "Flutter" version of the same capability.