@swiftbrowser/swift 0.1.0 → 0.2.0

package/Sources/SwiftUI/Charts/AxisFormatsAndRanges.swift

@@ -0,0 +1,68 @@
+// `AxisValueLabel(format:)` and the scale ranges of `.chartXScale(range:)`.
+//
+// A formatted label is the tick's value converted to the format's input
+// type and formatted with it (the default text when the value is of
+// another type). A scale range (`.plotDimension(startPadding:endPadding:)`,
+// a range of points) is accepted: the page maps the domain to the whole plot.
+
+import Foundation
+
+extension AxisValueLabel {
+    /// The value formatted with `format` (`.dateTime.month().day()`, `.number`…).
+    public init<F: FormatStyle>(format: F, centered: Bool? = nil, anchor: UnitPoint? = nil,
+                                multiLabelAlignment: Alignment? = nil, collisionResolution: AxisValueLabelCollisionResolution = .automatic,
+                                offsetsMarks: Bool? = nil, orientation: AxisValueLabelOrientation = .automatic,
+                                horizontalSpacing: CGFloat? = nil, verticalSpacing: CGFloat? = nil)
+    where F.FormatInput: Plottable, F.FormatOutput == String {
+        self.init(_label: .formatted { value in F.FormatInput(_plottableValue: value).map { format.format($0) } })
+    }
+}
+
+/// How overlapping axis labels are resolved; accepted.
+public struct AxisValueLabelCollisionResolution: Hashable, Sendable {
+    let name: String
+    public static let automatic = AxisValueLabelCollisionResolution(name: "automatic")
+    public static let greedy = AxisValueLabelCollisionResolution(name: "greedy")
+    public static let truncate = AxisValueLabelCollisionResolution(name: "truncate")
+    public static let disabled = AxisValueLabelCollisionResolution(name: "disabled")
+}
+
+/// Which way axis labels run; accepted (labels are horizontal).
+public struct AxisValueLabelOrientation: Hashable, Sendable {
+    let name: String
+    public static let automatic = AxisValueLabelOrientation(name: "automatic")
+    public static let horizontal = AxisValueLabelOrientation(name: "horizontal")
+    public static let vertical = AxisValueLabelOrientation(name: "vertical")
+    public static let verticalReversed = AxisValueLabelOrientation(name: "verticalReversed")
+}
+
+/// The points a scale maps its domain to; accepted.
+public protocol ScaleRange {}
+
+/// The plot's length along the axis, less the paddings.
+public struct PlotDimensionScaleRange: ScaleRange, Hashable, Sendable {}
+
+extension ScaleRange where Self == PlotDimensionScaleRange {
+    public static var plotDimension: PlotDimensionScaleRange { PlotDimensionScaleRange() }
+    public static func plotDimension(padding: CGFloat) -> PlotDimensionScaleRange { PlotDimensionScaleRange() }
+    public static func plotDimension(startPadding: CGFloat = 0, endPadding: CGFloat = 0) -> PlotDimensionScaleRange {
+        PlotDimensionScaleRange()
+    }
+}
+
+extension ClosedRange: ScaleRange where Bound == CGFloat {}
+
+nonisolated extension View {
+    /// Accepted (see the file comment).
+    public func chartXScale<R: ScaleRange>(range: R) -> some View { self }
+    public func chartYScale<R: ScaleRange>(range: R) -> some View { self }
+
+    /// The domain, as `chartXScale(domain:)`; the range is accepted.
+    public func chartXScale<D: ScaleDomain, R: ScaleRange>(domain: D, range: R) -> some View {
+        chartXScale(domain: domain)
+    }
+
+    public func chartYScale<D: ScaleDomain, R: ScaleRange>(domain: D, range: R) -> some View {
+        chartYScale(domain: domain)
+    }
+}

package/Sources/SwiftUI/Charts/Chart.swift

@@ -535,8 +535,20 @@ private struct _ChartResolver {
         for set in axis.ticks {
             let count = set.values.count
             for (index, value) in set.values.enumerated() {
-                let unit = axis.scale.unit(value) ?? 0
+                let scaled = axis.scale.unit(value)
+                // A value outside the scale's domain (a date bin that starts
+                // before the data) has no mark, as in Swift Charts.
+                if let scaled, scaled < -1e-9 || scaled > 1 + 1e-9 { continue }
+                let unit = scaled ?? 0
                 let at = _unit(isX ? unit : 1 - unit)
+                // A date's label starts at its tick, as Swift Charts places it;
+                // other values are centered on theirs.
+                func label(_ text: String) -> _JSON {
+                    if isX, case .date = value {
+                        return .object(["at": .number(at), "text": .string(text), "anchor": .string("leading")])
+                    }
+                    return .object(["at": .number(at), "text": .string(text)])
+                }
                 let marks = set.marks.content?(AxisValue(index: index, count: count, value: value))._items
                     ?? [.gridLine, .tick, .label(.automatic)]
                 for item in marks {
@@ -546,9 +558,11 @@ private struct _ChartResolver {
                     case .tick:
                         ticks.append(.number(at))
                     case .label(.automatic):
-                        labels.append(.object(["at": .number(at), "text": .string(defaultLabel(value, axis: axis))]))
+                        labels.append(label(defaultLabel(value, axis: axis)))
                     case .label(.text(let text)):
-                        labels.append(.object(["at": .number(at), "text": .string(text)]))
+                        labels.append(label(text))
+                    case .label(.formatted(let format)):
+                        labels.append(label(format(value) ?? defaultLabel(value, axis: axis)))
                     case .label(.view(let view)):
                         let edge: Double = position == "top" || position == "leading" ? 0 : 1
                         views.append(_ChartItemView(

package/Sources/SwiftUI/Charts/ChartProxy.swift

@@ -0,0 +1,57 @@
+/// `ChartProxy`, `.chartOverlay`, `.chartBackground` and the selection
+/// modifiers. The page lays charts out and draws their marks (Phase 7), so
+/// the Swift side knows no plot geometry: a proxy maps no value to a
+/// position or back (nil), and its plot frame is unknown (nil). An overlay
+/// or background is drawn over or under the chart with that proxy. The
+/// page reports no taps or drags on a chart, so a selection binding is
+/// never set by the viewer.
+
+/// Positions in a chart's plot, for overlays: unknown in the browser.
+public struct ChartProxy {
+    init() {}
+
+    /// Nil: the plot's geometry is the page's.
+    public func position<P: Plottable>(forX value: P) -> CGFloat? { nil }
+    public func position<P: Plottable>(forY value: P) -> CGFloat? { nil }
+    public func position<X: Plottable, Y: Plottable>(for value: (x: X, y: Y)) -> CGPoint? { nil }
+    public func value<P: Plottable>(atX position: CGFloat, as type: P.Type = P.self) -> P? { nil }
+    public func value<P: Plottable>(atY position: CGFloat, as type: P.Type = P.self) -> P? { nil }
+    public func value<X: Plottable, Y: Plottable>(at location: CGPoint, as type: (X, Y).Type = (X, Y).self) -> (X, Y)? { nil }
+    /// Nil: the plot's frame is the page's.
+    public var plotFrame: Anchor<CGRect>? { nil }
+    /// Zero.
+    public var plotSize: CGSize { .zero }
+}
+
+nonisolated extension View {
+    /// Draws `content` over the chart with a proxy (see the file comment).
+    public func chartOverlay<V: View>(alignment: Alignment = .center,
+                                      @ViewBuilder content: @escaping (ChartProxy) -> V) -> some View {
+        overlay(alignment: alignment) { content(ChartProxy()) }
+    }
+
+    /// Draws `content` under the chart with a proxy (see the file comment).
+    public func chartBackground<V: View>(alignment: Alignment = .center,
+                                         @ViewBuilder content: @escaping (ChartProxy) -> V) -> some View {
+        background(alignment: alignment) { content(ChartProxy()) }
+    }
+
+    /// Styles the chart's plot area with `content`. The page lays the plot
+    /// out inside the chart, so the plot is not a view of its own here:
+    /// `content` gets the whole chart (an overlay covers the axes too).
+    public func chartPlotStyle<Content: View>(@ViewBuilder content: @escaping (ChartPlotContent) -> Content) -> some View {
+        content(ChartPlotContent(content: AnyView(self)))
+    }
+
+    /// Accepted: the viewer cannot select a value on the page.
+    public func chartXSelection<P: Plottable>(value: Binding<P?>) -> some View { self }
+    public func chartXSelection<P: Plottable & Comparable>(range: Binding<ClosedRange<P>?>) -> some View { self }
+    public func chartYSelection<P: Plottable>(value: Binding<P?>) -> some View { self }
+    public func chartYSelection<P: Plottable & Comparable>(range: Binding<ClosedRange<P>?>) -> some View { self }
+}
+
+/// The plot area `chartPlotStyle` styles: here, the whole chart (see there).
+public struct ChartPlotContent: View {
+    let content: AnyView
+    public var body: some View { content }
+}

package/Sources/SwiftUI/Localization/Localization.swift

@@ -0,0 +1,498 @@
+// Localized strings, as `Text("key")`, `String(localized:)` and
+// `Bundle.localizedString(forKey:value:table:)` find them: the app's string
+// tables are `<language>.lproj/<Table>.strings` and `.stringsdict` files in its
+// bundle, which the CLI compiles from the Xcode target's string catalogs
+// (`.xcstrings`) and classic `.strings` files, as Xcode does (packages/cli,
+// strings.ts). Both are XML property lists: a `.strings` table maps keys to
+// format strings, a `.stringsdict` maps keys to an `NSStringLocalizedFormatKey`
+// whose `%#@name@` tokens a variable resolves (a plural rule).
+//
+// A key is looked up in the table of the language the app runs in (the
+// viewer's, among the bundle's `.lproj` folders), then in the development
+// language's; a key found in neither is its own text. Formatting follows
+// `String(format:)` for the specifiers Xcode puts in keys (`%@`, `%lld`, `%lf`,
+// `%d`, positional `%1$@`…), with each argument in the slot its specifier names.
+// The engine lives in SwiftUI so that `Text` uses it; FoundationBridge's
+// `Bundle` and `String(localized:)` call it too.
+
+import Foundation
+
+/// A value interpolated into a localized string: what its specifier formats.
+public enum _LocalizationArgument: Hashable, Sendable, Codable {
+    case string(String)
+    case int(Int64)
+    case uint(UInt64)
+    case double(Double)
+
+    /// The number a plural rule counts (nil for a string that is no number).
+    var number: Double? {
+        switch self {
+        case .int(let value): Double(value)
+        case .uint(let value): Double(value)
+        case .double(let value): value
+        case .string(let value): Double(value)
+        }
+    }
+
+    var text: String {
+        switch self {
+        case .string(let value): value
+        case .int(let value): String(value)
+        case .uint(let value): String(value)
+        case .double(let value): value.rounded() == value && abs(value) < 1e15 ? String(Int64(value)) : String(value)
+        }
+    }
+}
+
+/// A number type and the specifier SwiftUI and Foundation write for it in a
+/// localization key (`%lld` for `Int`): one generic interpolation takes them
+/// all, as SwiftUI's does, which keeps type checking fast.
+public protocol _FormatSpecifiable {
+    static var _specifier: String { get }
+    var _localizationArgument: _LocalizationArgument { get }
+}
+
+extension Int: _FormatSpecifiable {
+    public static var _specifier: String { "%lld" }
+    public var _localizationArgument: _LocalizationArgument { .int(Int64(self)) }
+}
+extension Int64: _FormatSpecifiable {
+    public static var _specifier: String { "%lld" }
+    public var _localizationArgument: _LocalizationArgument { .int(self) }
+}
+extension Int32: _FormatSpecifiable {
+    public static var _specifier: String { "%d" }
+    public var _localizationArgument: _LocalizationArgument { .int(Int64(self)) }
+}
+extension Int16: _FormatSpecifiable {
+    public static var _specifier: String { "%d" }
+    public var _localizationArgument: _LocalizationArgument { .int(Int64(self)) }
+}
+extension Int8: _FormatSpecifiable {
+    public static var _specifier: String { "%d" }
+    public var _localizationArgument: _LocalizationArgument { .int(Int64(self)) }
+}
+extension UInt: _FormatSpecifiable {
+    public static var _specifier: String { "%llu" }
+    public var _localizationArgument: _LocalizationArgument { .uint(UInt64(self)) }
+}
+extension UInt64: _FormatSpecifiable {
+    public static var _specifier: String { "%llu" }
+    public var _localizationArgument: _LocalizationArgument { .uint(self) }
+}
+extension UInt32: _FormatSpecifiable {
+    public static var _specifier: String { "%u" }
+    public var _localizationArgument: _LocalizationArgument { .uint(UInt64(self)) }
+}
+extension UInt16: _FormatSpecifiable {
+    public static var _specifier: String { "%u" }
+    public var _localizationArgument: _LocalizationArgument { .uint(UInt64(self)) }
+}
+extension UInt8: _FormatSpecifiable {
+    public static var _specifier: String { "%u" }
+    public var _localizationArgument: _LocalizationArgument { .uint(UInt64(self)) }
+}
+extension Double: _FormatSpecifiable {
+    public static var _specifier: String { "%lf" }
+    public var _localizationArgument: _LocalizationArgument { .double(self) }
+}
+extension Float: _FormatSpecifiable {
+    public static var _specifier: String { "%f" }
+    public var _localizationArgument: _LocalizationArgument { .double(Double(self)) }
+}
+
+/// A piece of a formatted localized string: text, or the argument (by index)
+/// that a view takes the place of (an `Image` or `Text` in `Text("…\(image)")`).
+public enum _LocalizedPiece: Equatable, Sendable {
+    case text(String)
+    case argument(Int)
+}
+
+/// A table entry: a format string, or a `.stringsdict` rule.
+enum _LocalizedEntry: Equatable {
+    case format(String)
+    case rule(formatKey: String, variables: [String: [String: String]])
+}
+
+public enum _Localization {
+    /// Where the app's resources are mounted (`SB_BUNDLE_PATH`), as `Bundle.main` reads them.
+    public static var mainBundlePath: String { _environment("SB_BUNDLE_PATH") ?? "/bundle" }
+
+    // MARK: Languages
+
+    /// The `<language>.lproj` folders of a bundle (without `Base`), sorted;
+    /// read once per bundle (an app's bundle does not change while it runs).
+    public static func localizations(bundlePath: String) -> [String] {
+        cacheLock.lock()
+        defer { cacheLock.unlock() }
+        if let cached = languagesByBundle[bundlePath] { return cached }
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: bundlePath)) ?? []
+        let found = names.filter { $0.hasSuffix(".lproj") }.map { String($0.dropLast(6)) }.filter { $0 != "Base" }.sorted()
+        languagesByBundle[bundlePath] = found
+        return found
+    }
+
+    /// The localization the app runs in: the viewer's language (`SB_LOCALE`)
+    /// matched against `available`, else the development localization.
+    public static func preferredLocalization(from available: [String]) -> String? {
+        preferredLocalizations(from: available, forPreferences: _environment("SB_LOCALE").map { [$0] }).first
+    }
+
+    /// The first of `available` that matches a preference, by whole tag
+    /// (`pt-BR`, case and `_` / `-` aside), then by script (`zh-Hant` for
+    /// `zh-TW`), then by language (`pt`); without a match, `en` when listed,
+    /// else the first.
+    public static func preferredLocalizations(from available: [String], forPreferences preferences: [String]?) -> [String] {
+        guard !available.isEmpty else { return [] }
+        func normalized(_ tag: String) -> String { tag.replacingOccurrences(of: "_", with: "-").lowercased() }
+        func language(_ tag: String) -> Substring { normalized(tag).split(separator: "-").first ?? "" }
+        for preference in preferences ?? [] {
+            if let exact = available.first(where: { normalized($0) == normalized(preference) }) { return [exact] }
+            if let script = chineseScript(preference), let match = available.first(where: { normalized($0) == "zh-\(script)" }) { return [match] }
+            if let close = available.first(where: { language($0) == language(preference) && !normalized($0).contains("-") }) { return [close] }
+            if let close = available.first(where: { language($0) == language(preference) }) { return [close] }
+        }
+        if available.contains("en") { return ["en"] }
+        return [available[0]]
+    }
+
+    /// `hant` for traditional Chinese (`zh-TW`, `zh-HK`, `zh-MO`, `zh-Hant…`), `hans` for the rest of `zh`.
+    private static func chineseScript(_ tag: String) -> String? {
+        let parts = tag.replacingOccurrences(of: "_", with: "-").lowercased().split(separator: "-")
+        guard parts.first == "zh" else { return nil }
+        if parts.contains("hant") || parts.contains("tw") || parts.contains("hk") || parts.contains("mo") { return "hant" }
+        return "hans"
+    }
+
+    /// The language the app's strings are written in. Xcode records it in the
+    /// app's Info.plist; the CLI ships its tables, and English is the default.
+    static func developmentLocalization(among available: [String]) -> String? {
+        available.contains("en") ? "en" : available.first
+    }
+
+    // MARK: Tables
+
+    /// Loaded tables and bundles' languages, behind a lock: views on any
+    /// thread look strings up (tests run in parallel on the host).
+    private static let cacheLock = NSLock()
+    nonisolated(unsafe) private static var tables: [String: [String: _LocalizedEntry]] = [:]
+    nonisolated(unsafe) private static var languagesByBundle: [String: [String]] = [:]
+
+    /// The entries of `<bundle>/<language>.lproj/<table>.strings` and `.stringsdict` (empty when absent).
+    static func table(_ name: String, language: String, bundlePath: String) -> [String: _LocalizedEntry] {
+        let base = "\(bundlePath)/\(language).lproj/\(name)"
+        cacheLock.lock()
+        defer { cacheLock.unlock() }
+        if let cached = tables[base] { return cached }
+        var entries: [String: _LocalizedEntry] = [:]
+        if let data = FileManager.default.contents(atPath: "\(base).strings"),
+           let strings = try? PropertyListDecoder().decode([String: String].self, from: data) {
+            for (key, value) in strings { entries[key] = .format(value) }
+        }
+        if let data = FileManager.default.contents(atPath: "\(base).stringsdict"),
+           let rules = try? PropertyListDecoder().decode([String: [String: _PlistValue]].self, from: data) {
+            for (key, rule) in rules {
+                guard case .string(let formatKey)? = rule["NSStringLocalizedFormatKey"] else { continue }
+                var variables: [String: [String: String]] = [:]
+                for (name, value) in rule where name != "NSStringLocalizedFormatKey" {
+                    if case .dictionary(let cases) = value { variables[name] = cases }
+                }
+                entries[key] = .rule(formatKey: formatKey, variables: variables)
+            }
+        }
+        tables[base] = entries
+        return entries
+    }
+
+    /// Forgets the loaded tables and languages (tests write new ones).
+    public static func _resetTables() {
+        cacheLock.lock()
+        defer { cacheLock.unlock() }
+        tables = [:]
+        languagesByBundle = [:]
+    }
+
+    /// The entry for `key`: the running language's table, then the development language's.
+    /// `language` overrides the viewer's (a test's, or a resource's locale).
+    static func entry(forKey key: String, table: String?, bundlePath: String, language: String? = nil) -> (entry: _LocalizedEntry, language: String)? {
+        let available = localizations(bundlePath: bundlePath)
+        guard !available.isEmpty else { return nil }
+        let name = (table?.isEmpty ?? true) ? "Localizable" : table!
+        var languages: [String] = []
+        let preferred = language.flatMap { preferredLocalizations(from: available, forPreferences: [$0]).first } ?? preferredLocalization(from: available)
+        if let preferred { languages.append(preferred) }
+        if let development = developmentLocalization(among: available), !languages.contains(development) { languages.append(development) }
+        for language in languages {
+            if let entry = self.table(name, language: language, bundlePath: bundlePath)[key] { return (entry, language) }
+        }
+        return nil
+    }
+
+    /// The language plural rules follow: the one the app runs in.
+    static func runningLanguage(bundlePath: String) -> String {
+        preferredLocalization(from: localizations(bundlePath: bundlePath)) ?? _environment("SB_LOCALE") ?? "en"
+    }
+
+    // MARK: Resolving
+
+    /// `Bundle.localizedString(forKey:value:table:)`: the key's format string
+    /// (a rule's, with its tokens resolved for no particular count, as
+    /// `other`), else `value` when it is not empty, else the key.
+    public static func localizedString(forKey key: String, value: String?, table: String?, bundlePath: String) -> String {
+        switch entry(forKey: key, table: table, bundlePath: bundlePath) {
+        case (.format(let format), _)?: return format
+        case (.rule(let formatKey, let variables), let language)?:
+            return expand(formatKey, variables: variables, arguments: [], language: language)
+        case nil:
+            if let value, !value.isEmpty { return value }
+            return key
+        }
+    }
+
+    /// `key` localized and formatted with `arguments`: the pieces of text, and
+    /// the indices of the arguments (nil entries: views) that go between them.
+    /// A key with no arguments is not formatted (`"100%"` stays as it is).
+    /// `defaultValue` is the format when the tables lack the key (else the key itself).
+    public static func resolve(key: String, arguments: [_LocalizationArgument?], table: String? = nil,
+                               bundlePath: String? = nil, defaultValue: String? = nil, language: String? = nil) -> [_LocalizedPiece] {
+        let path = bundlePath ?? mainBundlePath
+        let found = entry(forKey: key, table: table, bundlePath: path, language: language)
+        let format: String
+        switch found {
+        case (.format(let text), _)?: format = text
+        case (.rule(let formatKey, let variables), let language)?:
+            format = expand(formatKey, variables: variables, arguments: arguments, language: language)
+        case nil: format = defaultValue ?? key
+        }
+        if arguments.isEmpty { return [.text(format)] }
+        return _LocalizedFormat.format(format, arguments: arguments)
+    }
+
+    /// `resolve` as one string, views left out.
+    public static func string(key: String, arguments: [_LocalizationArgument?], table: String? = nil, bundlePath: String? = nil,
+                              defaultValue: String? = nil, language: String? = nil) -> String {
+        resolve(key: key, arguments: arguments, table: table, bundlePath: bundlePath, defaultValue: defaultValue, language: language).map { piece in
+            if case .text(let text) = piece { text } else { "" }
+        }.joined()
+    }
+
+    /// `key` formatted with `arguments`, not looked up (a key with no arguments is its own text).
+    public static func formatted(key: String, arguments: [_LocalizationArgument]) -> String {
+        if arguments.isEmpty { return key }
+        return _LocalizedFormat.format(key, arguments: arguments).map { piece in
+            if case .text(let text) = piece { text } else { "" }
+        }.joined()
+    }
+
+    /// A rule's format key with each `%#@name@` token replaced by the case its
+    /// variable picks for the token's argument (plural rules), repeatedly, as
+    /// cases may hold tokens. Every specifier is numbered first, so a case's
+    /// own unnumbered specifiers take its token's argument and the others keep theirs.
+    static func expand(_ formatKey: String, variables: [String: [String: String]], arguments: [_LocalizationArgument?], language: String) -> String {
+        var format = _LocalizedFormat.numbered(formatKey)
+        for _ in 0..<8 {
+            guard let token = _LocalizedFormat.firstToken(in: format) else { break }
+            let variable = variables[token.name] ?? [:]
+            let argument = token.position - 1 < arguments.count ? arguments[token.position - 1] : nil
+            let chosen: String
+            if variable["NSStringFormatSpecTypeKey"] == "NSStringPluralRuleType" {
+                let number = argument?.number
+                let category = number.map { _PluralRules.category(for: $0, language: language) } ?? "other"
+                if number == 0, let zero = variable["zero"] {
+                    chosen = zero
+                } else {
+                    chosen = variable[category] ?? variable["other"] ?? ""
+                }
+            } else {
+                // A device rule (settled at compile time) or one the browser has no use for.
+                chosen = variable["iphone"] ?? variable["other"] ?? ""
+            }
+            let replacement = _LocalizedFormat.numbered(chosen, defaultPosition: token.position)
+            format.replaceSubrange(token.range, with: replacement)
+        }
+        return format
+    }
+}
+
+/// A property list value of a `.stringsdict`: a string or a dictionary of strings.
+enum _PlistValue: Decodable {
+    case string(String)
+    case dictionary([String: String])
+    case other
+
+    init(from decoder: any Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        if let string = try? container.decode(String.self) {
+            self = .string(string)
+        } else if let dictionary = try? container.decode([String: String].self) {
+            self = .dictionary(dictionary)
+        } else {
+            self = .other
+        }
+    }
+}
+
+// MARK: - Formatting
+
+enum _LocalizedFormat {
+    /// One `%` specifier: its range, explicit position (`%2$@`), the rest of
+    /// the spec without the position (`-5`, `.2`, `ll`) and its conversion.
+    struct Specifier {
+        let range: Range<String.Index>
+        let position: Int?
+        let spec: String
+        let conversion: Character
+        /// `%#@name@`: a stringsdict token.
+        let token: String?
+    }
+
+    /// The specifiers of a format string, in order (`%%` left out).
+    static func specifiers(in format: String) -> [Specifier] {
+        var out: [Specifier] = []
+        var index = format.startIndex
+        while let percent = format[index...].firstIndex(of: "%") {
+            var cursor = format.index(after: percent)
+            guard cursor < format.endIndex else { break }
+            if format[cursor] == "%" {
+                index = format.index(after: cursor)
+                continue
+            }
+            // Position: digits followed by `$`.
+            var position: Int?
+            var digits = cursor
+            while digits < format.endIndex, format[digits].isASCII, format[digits].isNumber { digits = format.index(after: digits) }
+            if digits > cursor, digits < format.endIndex, format[digits] == "$" {
+                position = Int(format[cursor..<digits])
+                cursor = format.index(after: digits)
+            }
+            let specStart = cursor
+            if cursor < format.endIndex, format[cursor] == "#", format.index(after: cursor) < format.endIndex, format[format.index(after: cursor)] == "@" {
+                // `%#@name@`
+                let nameStart = format.index(cursor, offsetBy: 2)
+                if let end = format[nameStart...].firstIndex(of: "@") {
+                    out.append(Specifier(range: percent..<format.index(after: end), position: position, spec: "",
+                                         conversion: "@", token: String(format[nameStart..<end])))
+                    index = format.index(after: end)
+                    continue
+                }
+            }
+            while cursor < format.endIndex, "-+ #0'".contains(format[cursor]) { cursor = format.index(after: cursor) }
+            while cursor < format.endIndex, format[cursor].isASCII, format[cursor].isNumber || format[cursor] == "*" { cursor = format.index(after: cursor) }
+            if cursor < format.endIndex, format[cursor] == "." {
+                cursor = format.index(after: cursor)
+                while cursor < format.endIndex, format[cursor].isASCII, format[cursor].isNumber { cursor = format.index(after: cursor) }
+            }
+            while cursor < format.endIndex, "hlqLztj".contains(format[cursor]) { cursor = format.index(after: cursor) }
+            guard cursor < format.endIndex else { break }
+            let conversion = format[cursor]
+            guard "@dDiuUxXoOfFeEgGaAcCsSp".contains(conversion) else {
+                index = format.index(after: cursor)
+                continue
+            }
+            out.append(Specifier(range: percent..<format.index(after: cursor), position: position,
+                                 spec: String(format[specStart..<cursor]), conversion: conversion, token: nil))
+            index = format.index(after: cursor)
+        }
+        return out
+    }
+
+    /// `format` with every unnumbered specifier numbered: in order from 1, or
+    /// all `defaultPosition` (a plural case's specifiers are its token's argument).
+    static func numbered(_ format: String, defaultPosition: Int? = nil) -> String {
+        var result = ""
+        var last = format.startIndex
+        var next = 1
+        for specifier in specifiers(in: format) {
+            result += format[last..<specifier.range.lowerBound]
+            let position = specifier.position ?? defaultPosition ?? next
+            if specifier.position == nil, defaultPosition == nil { next += 1 }
+            if let token = specifier.token {
+                result += "%\(position)$#@\(token)@"
+            } else {
+                result += "%\(position)$\(specifier.spec)\(specifier.conversion)"
+            }
+            last = specifier.range.upperBound
+        }
+        result += format[last...]
+        return result
+    }
+
+    static func firstToken(in format: String) -> (name: String, position: Int, range: Range<String.Index>)? {
+        for specifier in specifiers(in: format) {
+            if let token = specifier.token { return (token, specifier.position ?? 1, specifier.range) }
+        }
+        return nil
+    }
+
+    /// The pieces of `format` with its specifiers filled: unnumbered ones take
+    /// the arguments in order, numbered ones theirs; a view argument (nil)
+    /// becomes an `.argument` piece; `%%` is `%`.
+    static func format(_ format: String, arguments: [_LocalizationArgument?]) -> [_LocalizedPiece] {
+        var pieces: [_LocalizedPiece] = []
+        var text = ""
+        var last = format.startIndex
+        var next = 0
+        func literal(_ part: Substring) { text += part.replacingOccurrences(of: "%%", with: "%") }
+        for specifier in specifiers(in: format) {
+            literal(format[last..<specifier.range.lowerBound])
+            last = specifier.range.upperBound
+            let index: Int
+            if let position = specifier.position {
+                index = position - 1
+            } else {
+                index = next
+                next += 1
+            }
+            guard index >= 0, index < arguments.count else { continue }
+            guard let argument = arguments[index] else {
+                if !text.isEmpty { pieces.append(.text(text)); text = "" }
+                pieces.append(.argument(index))
+                continue
+            }
+            text += render(argument, spec: specifier.spec, conversion: specifier.conversion)
+        }
+        literal(format[last...])
+        if !text.isEmpty || pieces.isEmpty { pieces.append(.text(text)) }
+        return pieces
+    }
+
+    /// One argument as its specifier formats it.
+    static func render(_ argument: _LocalizationArgument, spec: String, conversion: Character) -> String {
+        let flags = spec.filter { !"hlqLztj".contains($0) }
+        switch conversion {
+        case "@", "s", "S":
+            return argument.text
+        case "d", "D", "i":
+            let value: Int64 = switch argument {
+            case .int(let v): v
+            case .uint(let v): Int64(truncatingIfNeeded: v)
+            case .double(let v): v.isFinite ? Int64(v) : 0
+            case .string(let v): Int64(v) ?? 0
+            }
+            return flags.isEmpty ? String(value) : String(format: "%\(flags)lld", value)
+        case "u", "U", "x", "X", "o", "O":
+            let value: UInt64 = switch argument {
+            case .int(let v): UInt64(bitPattern: v)
+            case .uint(let v): v
+            case .double(let v): v.isFinite && v >= 0 ? UInt64(v) : 0
+            case .string(let v): UInt64(v) ?? 0
+            }
+            let lower = Character(conversion.lowercased())
+            let code = lower == "u" ? "u" : String(conversion)
+            return String(format: "%\(flags)ll\(code)", value)
+        case "f", "F", "e", "E", "g", "G", "a", "A":
+            let value: Double = switch argument {
+            case .int(let v): Double(v)
+            case .uint(let v): Double(v)
+            case .double(let v): v
+            case .string(let v): Double(v) ?? 0
+            }
+            return String(format: "%\(flags)\(conversion)", value)
+        case "c", "C":
+            if case .int(let v) = argument, let scalar = Unicode.Scalar(UInt32(truncatingIfNeeded: v)) { return String(Character(scalar)) }
+            return argument.text
+        default:
+            return argument.text
+        }
+    }
+}