@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-formatstyle/SKILL.md

@@ -1,341 +1,365 @@
 ---
 name: swift-formatstyle
-description: "Format values for display using the FormatStyle protocol and its concrete types. Use when formatting numbers (integers, floating-point, decimals), currencies, percentages, dates, date ranges, relative dates, durations (Duration.TimeFormatStyle, Duration.UnitsFormatStyle), measurements, person names (PersonNameComponents.FormatStyle), byte counts (ByteCountFormatStyle), lists (ListFormatStyle), and URLs (URL.FormatStyle). Also covers creating custom FormatStyle conformances and replacing legacy Formatter subclasses. FormatStyle is available iOS 15+; Duration styles require iOS 16+."
+description: "Display formatting with FormatStyle (iOS 15+): integers, floating point, decimals, currency, percentages, dates, date ranges, relative and anchored relative dates, durations (Duration.TimeFormatStyle, Duration.UnitsFormatStyle, iOS 16+), measurements, person names, byte counts, lists, URLs (iOS 16+), parsing, custom FormatStyle conformances. Use when formatting values for display, replacing legacy Formatter subclasses, or writing a custom format style. String Catalogs, plurals and RTL review belong to ios-localization."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Swift FormatStyle
 
-Format values for human-readable display using the `FormatStyle` protocol
-and Foundation's concrete format styles. Replaces legacy `Formatter` subclasses
-with a type-safe, composable, cacheable API.
-
-Locale-aware display is an i18n concern even when the app is not adding new languages. For user-facing formatted output, always recommend previewing or testing representative locales such as `en_US`, `de_DE`, `ar_SA`, and `ja_JP`; check separators, numbering systems, calendars, currency and unit conventions, text direction, and layout-sensitive output. Keep this skill focused on `FormatStyle`, `ParseableFormatStyle`, parsing, and reusable formatter API design; route broader localization work such as String Catalogs, bundles, plurals, localized copy, and RTL layout review to `ios-localization`. Do not use "not adding languages" as the reason to skip `ios-localization`; locale-sensitive formatting can be a localization review issue without translation work.
-
-Docs: [FormatStyle](https://sosumi.ai/documentation/foundation/formatstyle)
-
-## Contents
-
-- [Quick Reference](#quick-reference)
-- [Numbers](#numbers)
-- [Currency](#currency)
-- [Percentages](#percentages)
-- [Dates](#dates)
-- [Durations](#durations)
-- [Measurements](#measurements)
-- [Person Names](#person-names)
-- [Lists](#lists)
-- [Byte Counts](#byte-counts)
-- [URLs](#urls)
-- [SwiftUI Integration](#swiftui-integration)
-- [Custom FormatStyle](#custom-formatstyle)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-
-## Quick Reference
-
-| Type | Style Access | Example |
-|------|-------------|---------|
-| `Int`, `Double` | `.number` | `42.formatted(.number.precision(.fractionLength(2)))` → `"42.00"` |
-| Currency | `.currency(code:)` | `29.99.formatted(.currency(code: "USD"))` → `"$29.99"` |
-| Percent | `.percent` | `0.85.formatted(.percent)` → `"85%"` |
-| `Date` | `.dateTime` | `Date.now.formatted(.dateTime.month().day().year())` |
-| Date range | `.interval` | `(date1..<date2).formatted(.interval)` |
-| Relative date | `.relative(presentation:unitsStyle:)` | `date.formatted(.relative(presentation: .named))` → `"yesterday"` |
-| `Duration` | `.time(pattern:)` | `Duration.seconds(3661).formatted(.time(pattern: .hourMinuteSecond))` → `"1:01:01"` |
-| `Duration` | `.units(allowed:width:)` | `Duration.seconds(90).formatted(.units(allowed: [.minutes, .seconds]))` → `"1 min, 30 sec"` |
-| `Measurement` | `.measurement(width:)` | `Measurement(value: 72, unit: UnitTemperature.fahrenheit).formatted(.measurement(width: .abbreviated))` |
-| `PersonNameComponents` | `.name(style:)` | `name.formatted(.name(style: .short))` → `"Tom"` |
-| `[String]` | `.list(type:width:)` | `["A","B","C"].formatted(.list(type: .and))` → `"A, B, and C"` |
-| Byte count | `.byteCount(style:)` | `Int64(1_048_576).formatted(.byteCount(style: .memory))` → `"1 MB"` |
-| `URL` | `.url` | `url.formatted(.url.scheme(.never).host().path())` |
+`FormatStyle` describes how one kind of value becomes text, as a small typed
+value you can chain and reuse, instead of configured `Formatter` objects. Foundation caches the
+expensive machinery behind them, so a style can be written inline wherever a
+value is shown. Availability: iOS 15 for the protocol and most styles, iOS 16
+for the `Duration` and `URL` styles, iOS 18 for `Date.AnchoredRelativeFormatStyle`.
+
+## Locale review is part of the job
+
+Formatting output changes with the user's region even in an app that ships one
+language. Whenever this skill is used, recommend previewing or testing at least
+`en_US`, `de_DE`, `ar_SA` and `ja_JP`, and check:
+
+- decimal and grouping separators,
+- the numbering system (Arabic-Indic digits in `ar_SA`),
+- calendar and date order,
+- where the currency sign goes and which units people expect,
+- right-to-left output, and any layout that depends on the string's length.
+
+Work on String Catalogs, bundles, plural rules, translated copy and RTL layout
+review belongs to `ios-localization`. "We are not adding languages" is not a
+reason to skip that review.
+
+## Quick reference
+
+| Value | Style | Example output (en_US) |
+| --- | --- | --- |
+| `Int`, `Double` | `.number` | `9.formatted(.number.precision(.fractionLength(2)))` gives "9.00" |
+| Currency | `.currency(code:)` | 12.5 with `"USD"` gives "$12.50" |
+| Percent | `.percent` | 0.4 gives "40%" |
+| `Date` | `.dateTime` | `.dateTime.month().day().year()` gives "Mar 3, 2026" |
+| Date range | `.interval` | `(opening..<closing).formatted(.interval)` |
+| Relative date | `.relative(presentation:unitsStyle:)` | `.named` gives "yesterday" |
+| `Duration` | `.time(pattern:)` | 3661 seconds as `.hourMinuteSecond` is "1:01:01" |
+| `Duration` | `.units(allowed:width:)` | 90 seconds is "1 min, 30 sec" |
+| `Measurement` | `.measurement(width:)` | "72°F" |
+| `PersonNameComponents` | `.name(style:)` | "Ada Lovelace" |
+| `[String]` | `.list(type:width:)` | three names with `.and` read "Mina, Omar, and Lea" |
+| Byte count | `.byteCount(style:)` | one mebibyte (1,048,576 bytes) with `.memory` is "1 MB" |
+| `URL` | `.url` | `.url.scheme(.never).host().path()` drops "https://" and the query |
 
 ## Numbers
 
-```swift
-// Default locale-aware formatting
-let n = 1234567.formatted()  // "1,234,567" (en_US)
-
-// Precision
-1234.5.formatted(.number.precision(.fractionLength(0...2)))  // "1,234.5"
-1234.5.formatted(.number.precision(.significantDigits(3)))    // "1,230"
+Plain `formatted()` already follows the user's locale: 2500000 shows as
+"2,500,000" in `en_US` and "2.500.000" in `de_DE`.
 
-// Rounding
-1234.formatted(.number.rounded(rule: .down, increment: 100)) // "1,200"
+```swift
+let upToTwo = FloatingPointFormatStyle<Double>.number.precision(.fractionLength(0...2))
+let threeSignificant = FloatingPointFormatStyle<Double>.number.precision(.significantDigits(3))
+(7.0 / 3.0).formatted(upToTwo)            // "2.33"
+(7.0 / 3.0).formatted(threeSignificant)   // "2.33"
+
+let seats = 1834
+seats.formatted(.number.rounded(rule: .down, increment: 100))   // "1,800"
+seats.formatted(.number.grouping(.never))                       // "1834"
+seats.formatted(.number.sign(strategy: .always()))              // "+1,834"
+seats.formatted(.number.locale(Locale(identifier: "fr_FR")))    // "1 834"
+
+let audience = 3_400_000
+audience.formatted(.number.notation(.compactName))              // "3.4M"
+0.00042.formatted(.number.notation(.scientific))                // "4.2E-4"
+```
 
-// Grouping
-1234567.formatted(.number.grouping(.never))                   // "1234567"
+The styles behind these are `IntegerFormatStyle` and
+`FloatingPointFormatStyle` (and `Decimal.FormatStyle`).
 
-// Notation
-1_200_000.formatted(.number.notation(.compactName))           // "1.2M"
-42.formatted(.number.notation(.scientific))                    // "4.2E1"
+## Currency
 
-// Sign display
-(-42).formatted(.number.sign(strategy: .always()))            // "+42" / "-42"
+The ISO 4217 code decides the symbol and the usual number of fraction digits,
+so yen shows no decimals:
 
-// Locale override
-42.formatted(.number.locale(Locale(identifier: "de_DE")))     // "42"
+```swift
+18.75.formatted(.currency(code: "EUR"))   // "€18.75" in en_US
+30.0.formatted(.currency(code: "JPY"))    // "¥30"
 ```
 
-Docs: [IntegerFormatStyle](https://sosumi.ai/documentation/foundation/integerformatstyle),
-[FloatingPointFormatStyle](https://sosumi.ai/documentation/foundation/floatingpointformatstyle)
-
-## Currency
+To override precision, build the style explicitly:
 
 ```swift
-29.99.formatted(.currency(code: "USD"))   // "$29.99"
-29.99.formatted(.currency(code: "EUR"))   // "€29.99"
-29.99.formatted(.currency(code: "JPY"))   // "¥30"
-
-// Customize precision
-let style = FloatingPointFormatStyle<Double>.Currency(code: "USD")
+let noCents = FloatingPointFormatStyle<Double>.Currency(code: "USD")
     .precision(.fractionLength(0))
-1234.56.formatted(style)  // "$1,235"
+let price = 1299.99
+price.formatted(noCents)                  // "$1,300"
 ```
 
 ## Percentages
 
+A floating-point value is a fraction; an integer is already a percentage.
+
 ```swift
-0.85.formatted(.percent)                                      // "85%"
-0.8567.formatted(.percent.precision(.fractionLength(1)))       // "85.7%"
-42.formatted(.percent)                                         // "42%"  (integer)
+let completion = 0.8567
+completion.formatted(.percent)                                   // "85.67%"
+completion.formatted(.percent.precision(.fractionLength(1)))     // "85.7%"
+let passRate = 42
+passRate.formatted(.percent)                                     // "42%"
 ```
 
 ## Dates
 
+Build exactly the fields you want; the locale decides order and punctuation.
+
 ```swift
-let now = Date.now
+let launch = Date.now
+launch.formatted(.dateTime.day().month().year())            // "Mar 3, 2026" (order comes from the locale)
+launch.formatted(.dateTime.minute().hour())                 // "4:05 PM"
+let spelledOut = Date.FormatStyle.dateTime.day().month(.wide).weekday(.wide)
+launch.formatted(spelledOut)                                // "Tuesday, March 3"
+```
+
+Predefined combinations:
 
-// Components
-now.formatted(.dateTime.year().month().day())           // "Apr 22, 2026"
-now.formatted(.dateTime.hour().minute())                // "4:30 PM"
-now.formatted(.dateTime.weekday(.wide).month(.wide).day()) // "Wednesday, April 22"
+```swift
+launch.formatted(date: .long, time: .shortened)     // "March 3, 2026 at 4:05 PM"
+launch.formatted(date: .abbreviated, time: .omitted) // "Mar 3, 2026"
+launch.formatted(.iso8601)                           // "2026-03-03T13:05:00Z"
+```
 
-// Predefined styles
-now.formatted(date: .long, time: .shortened)            // "April 22, 2026 at 4:30 PM"
-now.formatted(date: .abbreviated, time: .omitted)       // "Apr 22, 2026"
+Relative to now:
 
-// ISO 8601
-now.formatted(.iso8601)                                 // "2026-04-22T16:30:00Z"
+```swift
+let dayBefore = Date.now.addingTimeInterval(-86_400)
+dayBefore.formatted(.relative(presentation: .named))    // "yesterday"
+let numericAgo = Date.RelativeFormatStyle(presentation: .numeric)
+dayBefore.formatted(numericAgo)                         // "1 day ago"
+```
 
-// Relative
-let yesterday = Calendar.current.date(byAdding: .day, value: -1, to: .now)!
-yesterday.formatted(.relative(presentation: .named))    // "yesterday"
-yesterday.formatted(.relative(presentation: .numeric))  // "1 day ago"
+Ranges and countdowns:
 
-// Interval
-(date1..<date2).formatted(.interval.month().day().hour().minute())
+```swift
+let slot = launch..<launch.addingTimeInterval(5_400)
+let meetingSpan = Date.IntervalFormatStyle().day().month().minute().hour()
+slot.formatted(meetingSpan)   // "Mar 3, 4:05 - 5:35 PM" (ICU prints an en dash)
 
-// Components (countdown-style)
-(date1..<date2).formatted(.components(style: .wide, fields: [.day, .hour]))
-// "2 days, 5 hours"
+let untilDeparture = Date.now..<Date.now.addingTimeInterval(190_800)
+let countdown = Date.ComponentsFormatStyle(style: .wide, fields: [.hour, .day])
+untilDeparture.formatted(countdown)   // "2 days, 5 hours"
 ```
 
-Docs: [Date.FormatStyle](https://sosumi.ai/documentation/foundation/date/formatstyle),
-[Date.RelativeFormatStyle](https://sosumi.ai/documentation/foundation/date/relativeformatstyle),
-[Date.IntervalFormatStyle](https://sosumi.ai/documentation/foundation/date/intervalformatstyle)
+Related types: `Date.FormatStyle`, `Date.RelativeFormatStyle`,
+`Date.IntervalFormatStyle`, `Date.ComponentsFormatStyle`.
 
-### Anchored Relative Dates (iOS 18+)
+### Relative to a chosen reference (iOS 18+)
 
-`Date.AnchoredRelativeFormatStyle` formats relative to a fixed anchor date
-rather than the current moment.
+`Date.AnchoredRelativeFormatStyle` describes one fixed date, the anchor,
+relative to whatever moment you format. Plain `.relative` always measures from
+the real current time; the anchored style lets you choose the reference, which
+suits timelines, widgets and tests.
 
-Docs: [Date.AnchoredRelativeFormatStyle](https://sosumi.ai/documentation/foundation/date/anchoredrelativeformatstyle)
+```swift
+let meetup = Date(timeIntervalSince1970: 1_800_000_000)
+let style = Date.AnchoredRelativeFormatStyle(anchor: meetup, presentation: .named)
+style.format(meetup.addingTimeInterval(86_400))   // "yesterday": the anchor was a day before the reference
+style.format(meetup.addingTimeInterval(-3_600))   // "in 1 hour"
+```
 
 ## Durations
 
-`Duration` (iOS 16+) has two format styles:
+A `Duration` (iOS 16+) can be shown as a clock reading with
+`Duration.TimeFormatStyle` or as labeled units with `Duration.UnitsFormatStyle`.
 
-Docs: [Duration.TimeFormatStyle](https://sosumi.ai/documentation/swift/duration/timeformatstyle),
-[Duration.UnitsFormatStyle](https://sosumi.ai/documentation/swift/duration/unitsformatstyle)
+```swift
+let ride = Duration.seconds(7_384)                  // 2 h 3 min 4 s
+ride.formatted(.time(pattern: .hourMinuteSecond))   // "2:03:04"
+ride.formatted(.time(pattern: .hourMinute))         // "2:03"
+ride.formatted(.time(pattern: .minuteSecond))       // "123:04" (minutes are not wrapped into hours)
 
-### TimeFormatStyle  -  compact separator-based
+let stopwatch = Duration.TimeFormatStyle.Pattern.minuteSecond(padMinuteToLength: 2, fractionalSecondsLength: 2)
+Duration.milliseconds(3_750).formatted(.time(pattern: stopwatch))   // "00:03.75"
+```
 
 ```swift
-let d = Duration.seconds(3661)
-
-d.formatted(.time(pattern: .hourMinuteSecond))       // "1:01:01"
-d.formatted(.time(pattern: .hourMinute))             // "1:01"
-d.formatted(.time(pattern: .minuteSecond))           // "61:01"
+let clock: Set<Duration.UnitsFormatStyle.Unit> = [.hours, .minutes, .seconds]
+ride.formatted(.units(allowed: clock, width: .abbreviated))                      // "2 hr, 3 min, 4 sec"
+ride.formatted(.units(allowed: clock, width: .wide, maximumUnitCount: 1))        // "2 hours"
 
-// Fractional seconds
-Duration.seconds(3.75).formatted(
-    .time(pattern: .minuteSecond(padMinuteToLength: 2, fractionalSecondsLength: 2))
-)  // "00:03.75"
+let rest = Duration.seconds(150)
+rest.formatted(.units(allowed: [.minutes, .seconds], width: .wide))     // "2 minutes, 30 seconds"
+rest.formatted(.units(allowed: [.minutes, .seconds], width: .narrow))   // "2m 30s"
 ```
 
-### UnitsFormatStyle  -  labeled units
+`maximumUnitCount` caps how many units appear.
+
+## Measurements
 
 ```swift
-Duration.seconds(3661).formatted(
-    .units(allowed: [.hours, .minutes, .seconds], width: .abbreviated)
-)  // "1 hr, 1 min, 1 sec"
-
-Duration.seconds(90).formatted(
-    .units(allowed: [.minutes, .seconds], width: .wide)
-)  // "1 minute, 30 seconds"
-
-Duration.seconds(90).formatted(
-    .units(allowed: [.minutes, .seconds], width: .narrow)
-)  // "1m 30s"
-
-// Limit unit count
-Duration.seconds(3661).formatted(
-    .units(allowed: [.hours, .minutes, .seconds], width: .abbreviated, maximumUnitCount: 2)
-)  // "1 hr, 1 min"
+let poolWater = Measurement<UnitTemperature>(value: 81, unit: .fahrenheit)
+poolWater.formatted(.measurement(width: .wide))         // "81 degrees Fahrenheit"
+poolWater.formatted(.measurement(width: .abbreviated))  // "81°F"
+poolWater.formatted(.measurement(width: .narrow))       // "81°"
 ```
 
-## Measurements
+`usage:` lets the style convert to what the locale expects for that context:
 
 ```swift
-let temp = Measurement(value: 72, unit: UnitTemperature.fahrenheit)
-temp.formatted(.measurement(width: .wide))        // "72 degrees Fahrenheit"
-temp.formatted(.measurement(width: .abbreviated))  // "72°F"
-temp.formatted(.measurement(width: .narrow))       // "72°"
-
-let dist = Measurement(value: 5, unit: UnitLength.kilometers)
-dist.formatted(.measurement(width: .abbreviated, usage: .road))  // "3.1 mi" (en_US)
+let hike = Measurement<UnitLength>(value: 8, unit: .kilometers)
+let roadSign = Measurement<UnitLength>.FormatStyle(width: .abbreviated, usage: .road)
+hike.formatted(roadSign)   // "5 mi" in en_US, "8 km" in de_DE
 ```
 
-Docs: [Measurement.FormatStyle](https://sosumi.ai/documentation/foundation/measurement/formatstyle)
+The type is `Measurement<Unit>.FormatStyle`.
+
+## Person names
 
-## Person Names
+`PersonNameComponents` holds `givenName`, `familyName`, `middleName`,
+`namePrefix`, `nickname` and `nameSuffix`.
 
 ```swift
-var name = PersonNameComponents()
-name.givenName = "Thomas"
-name.familyName = "Clark"
-name.middleName = "Louis"
-name.namePrefix = "Dr."
-name.nickname = "Tom"
-name.nameSuffix = "Esq."
-
-name.formatted(.name(style: .long))        // "Dr. Thomas Louis Clark Esq."
-name.formatted(.name(style: .medium))      // "Thomas Clark"
-name.formatted(.name(style: .short))       // "Tom"
-name.formatted(.name(style: .abbreviated)) // "TC"
+var person = PersonNameComponents()
+person.namePrefix = "Dr."
+person.givenName = "Ada"
+person.familyName = "Lovelace"
+person.nickname = "Addie"
+
+person.formatted(.name(style: .long))         // "Dr. Ada Lovelace"
+person.formatted(.name(style: .medium))       // "Ada Lovelace"
+person.formatted(.name(style: .short))        // "Addie"
+person.formatted(.name(style: .abbreviated))  // "AL"
 ```
 
-Style resolution follows priority: script → user preferences → locale → developer setting.
-
-Docs: [PersonNameComponents.FormatStyle](https://sosumi.ai/documentation/foundation/personnamecomponents/formatstyle)
+The final order and form depend, in priority order, on the script of the name,
+the user's preferences, the locale, and only then the style you asked for.
 
 ## Lists
 
 ```swift
-["Alice", "Bob", "Charlie"].formatted(.list(type: .and))
-// "Alice, Bob, and Charlie"
-
-["Alice", "Bob", "Charlie"].formatted(.list(type: .or))
-// "Alice, Bob, or Charlie"
+let crew = ["Mina", "Omar", "Lea"]
+crew.formatted(.list(type: .and))                     // "Mina, Omar, and Lea"
+crew.formatted(.list(type: .or))                      // "Mina, Omar, or Lea"
+crew.formatted(.list(type: .and, width: .narrow))     // "Mina, Omar, Lea"
 
-// With member formatting
-[1, 2, 3].formatted(.list(memberStyle: .number, type: .and))
-// "1, 2, and 3"
-
-// Narrow width
-["A", "B", "C"].formatted(.list(type: .and, width: .narrow))
-// "A, B, C"
+let lanes = [3, 5, 8]
+lanes.formatted(.list(memberStyle: IntegerFormatStyle<Int>(), type: .and))  // "3, 5, and 8"
 ```
 
-Docs: [ListFormatStyle](https://sosumi.ai/documentation/foundation/listformatstyle)
+The type is `ListFormatStyle`.
 
-## Byte Counts
+## Byte counts
 
 ```swift
-Int64(1_048_576).formatted(.byteCount(style: .memory))   // "1 MB"
-Int64(1_048_576).formatted(.byteCount(style: .file))      // "1 MB"
-Int64(1_048_576).formatted(.byteCount(style: .binary))    // "1 MiB"
+let attachment: Int64 = 1_048_576
+var labels: [String] = []
+for style in [ByteCountFormatStyle.Style.memory, .file, .binary] {
+    labels.append(attachment.formatted(.byteCount(style: style)))   // "1 MB" each time
+}
 ```
 
-Docs: [ByteCountFormatStyle](https://sosumi.ai/documentation/foundation/bytecountformatstyle)
+`.memory` and `.binary` count in powers of 1024; `.file` and `.decimal` count
+in powers of 1000. All four use the same unit labels ("KB", "MB"), never
+"KiB" or "MiB", so a different base only shows once the value is large enough
+for the rounding to differ.
 
 ## URLs
 
 ```swift
-let url = URL(string: "https://example.com/path?q=1")!
-url.formatted()
-// "https://example.com/path?q=1"
+let guide = URL(string: "https://help.example.org/guides/setup?ref=home")!
+guide.formatted()                                           // the full string
+guide.formatted(.url.scheme(.never).host().path())          // "help.example.org/guides/setup"
+guide.formatted(.url.scheme(.always).host().path(.never))   // "https://help.example.org"
+guide.formatted(.url.scheme(.never).host(.never).path())    // "/guides/setup"
+```
 
-url.formatted(.url.scheme(.never).host().path())
-// "example.com/path"
+(Unwrap the literal URL with `guard let` in real code.)
 
-url.formatted(.url.scheme(.always).host(.never).path())
-// "https:///path"
-```
+## SwiftUI integration
 
-Docs: [URL.FormatStyle](https://sosumi.ai/documentation/foundation/url/formatstyle)
+Pass the value and the style to `Text` instead of building a string first:
 
-## SwiftUI Integration
+```swift
+Text(order.total, format: .currency(code: order.currencyCode))
+Text(order.placedAt, format: .dateTime.day().month().hour().minute())
+Text(workout.elapsed, format: .units(allowed: [.hours, .minutes], width: .abbreviated))
+```
 
-`Text` accepts a `format:` parameter, keeping formatting out of the view model.
+`Text` then formats with the view's `\.locale` environment value, so previews
+and in-app locale overrides are respected, and the value stays typed until the
+moment it is drawn. For live values:
 
 ```swift
-// Inline format style
-Text(price, format: .currency(code: "USD"))
-Text(date, format: .dateTime.month().day().year())
-Text(duration, format: .units(allowed: [.minutes, .seconds]))
-
-// Timer-style (live updating)
-Text(.now, style: .timer)
-Text(.now, style: .relative)
-Text(timerInterval: start...end)
+Text(.now, style: .timer)                        // counts up from the date
+Text(sessionStart, style: .relative)             // "2 min"
+Text(timerInterval: sessionStart...sessionEnd)   // counts down across the range
 ```
 
-**Prefer `Text(_:format:)` over string interpolation**  -  it allows SwiftUI to
-re-render only the formatted value and supports accessibility scaling.
+`Text(timerInterval:)` needs iOS 16.
 
 ## Custom FormatStyle
 
-Conform to `FormatStyle` for domain-specific formatting. Conform to
-`ParseableFormatStyle` if you also need parsing.
+Conform to `FormatStyle` and implement `format(_:)`. Add `ParseableFormatStyle`
+if the text must also be read back. `FormatStyle` inherits `Codable` and
+`Hashable`, so keep stored properties simple value types.
 
 ```swift
-struct AbbreviatedCountStyle: FormatStyle {
-    func format(_ value: Int) -> String {
-        switch value {
-        case ..<1_000:
-            return "\(value)"
-        case 1_000..<1_000_000:
-            return String(format: "%.1fK", Double(value) / 1_000)
-        default:
-            return String(format: "%.1fM", Double(value) / 1_000_000)
+struct CompactCountStyle: FormatStyle {
+    func format(_ count: Int) -> String {
+        switch abs(count) {
+        case 1_000_000...: scaled(count, by: 1_000_000) + "M"
+        case 1_000...:     scaled(count, by: 1_000) + "K"
+        default:           count.formatted()
         }
     }
+
+    private func scaled(_ count: Int, by divisor: Double) -> String {
+        (Double(count) / divisor).formatted(.number.precision(.fractionLength(0...1)))
+    }
 }
 
-extension FormatStyle where Self == AbbreviatedCountStyle {
-    static var abbreviatedCount: AbbreviatedCountStyle { .init() }
+extension FormatStyle where Self == CompactCountStyle {
+    static var compactCount: CompactCountStyle { CompactCountStyle() }
 }
 
-// Usage
-let followers = 12_500
-Text(followers, format: .abbreviatedCount)  // "12.5K"
+let followers = 48_700.formatted(.compactCount)   // "48.7K"
 ```
 
-## Common Mistakes
+The static member in the constrained extension is what enables the
+`.compactCount` dot syntax at call sites. (For real apps, `.notation(.compactName)`
+already does this with localized suffixes; a custom style earns its place when
+the rule is your own.)
+
+## Common mistakes
 
 | Mistake | Fix |
-|---------|-----|
-| Using legacy `NumberFormatter` / `DateFormatter` in new code | Use `FormatStyle` (iOS 15+). Foundation caches format style instances automatically. |
-| String interpolation for formatted numbers in `Text` | Use `Text(value, format:)` for locale correctness and accessibility |
-| Hardcoding locale in format styles | Omit `.locale()` to inherit the user's current locale by default |
-| Using `.time(pattern:)` for labeled duration display | Use `.units(allowed:width:)` for "1 hr, 30 min" style output |
-| Creating `Formatter` instances in `body` or tight loops | FormatStyle instances are value types cached by Foundation; safe to create inline |
-| Formatting `Duration` with `DateComponentsFormatter` | Use `Duration.TimeFormatStyle` or `Duration.UnitsFormatStyle` directly |
-| Ignoring `usage:` parameter for measurements | Specify `.road`, `.asProvided`, etc. for locale-aware unit conversion |
-
-## Review Checklist
-
-- [ ] `FormatStyle` used instead of legacy `Formatter` subclasses for iOS 15+ targets
-- [ ] `Text(_:format:)` used instead of pre-formatting strings for SwiftUI text
-- [ ] No hardcoded locale unless explicitly needed (e.g., server communication)
-- [ ] Duration formatting uses `Duration.TimeFormatStyle` or `Duration.UnitsFormatStyle`
-- [ ] Currency codes are ISO 4217 strings, not hardcoded symbols
-- [ ] Measurement formatting includes `usage:` for user-facing display
-- [ ] Custom FormatStyle types conform to `Codable` + `Hashable` for caching
+| --- | --- |
+| `NumberFormatter` or `DateFormatter` in new code | `FormatStyle` (iOS 15+); Foundation caches the underlying formatters |
+| String interpolation of a value inside `Text` | `Text(value, format:)` |
+| Hardcoded `.locale(...)` for display | Leave it out so the user's locale applies |
+| `.time(pattern:)` where labels are wanted | `.units(allowed:width:)` |
+| A `Formatter` created in `body` or inside a loop | An inline style; it is cheap and cached |
+| `DateComponentsFormatter` for a `Duration` | `Duration.TimeFormatStyle` or `Duration.UnitsFormatStyle` |
+| Measurements formatted without `usage:` | Pass `.road`, `.person`, `.asProvided` or another usage that fits |
+
+## Review checklist
+
+- [ ] `FormatStyle` rather than `Formatter` subclasses when targeting iOS 15+
+- [ ] `Text(_:format:)` rather than preformatted strings
+- [ ] No hardcoded locale unless the output is machine-facing (for example, sent to a server)
+- [ ] `Duration` values go through the time or units duration style
+- [ ] Currencies are identified by ISO 4217 code ("EUR"), never by symbol ("€")
+- [ ] Measurement display passes `usage:`
+- [ ] Custom styles keep the `Codable` and `Hashable` conformance that `FormatStyle` requires working (value-type properties only)
+- [ ] Output checked in `en_US`, `de_DE`, `ar_SA` and `ja_JP`
 
 ## References
 
-- Apple docs: [FormatStyle](https://sosumi.ai/documentation/foundation/formatstyle) | [Date.FormatStyle](https://sosumi.ai/documentation/foundation/date/formatstyle) | [Duration.TimeFormatStyle](https://sosumi.ai/documentation/swift/duration/timeformatstyle)
+- [FormatStyle](https://developer.apple.com/documentation/foundation/formatstyle)
+- [IntegerFormatStyle](https://developer.apple.com/documentation/foundation/integerformatstyle)
+- [FloatingPointFormatStyle](https://developer.apple.com/documentation/foundation/floatingpointformatstyle)
+- [Date.FormatStyle](https://developer.apple.com/documentation/foundation/date/formatstyle)
+- [Date.RelativeFormatStyle](https://developer.apple.com/documentation/foundation/date/relativeformatstyle)
+- [Date.IntervalFormatStyle](https://developer.apple.com/documentation/foundation/date/intervalformatstyle)
+- [Date.AnchoredRelativeFormatStyle](https://developer.apple.com/documentation/foundation/date/anchoredrelativeformatstyle)
+- [Duration.TimeFormatStyle](https://developer.apple.com/documentation/swift/duration/timeformatstyle)
+- [Duration.UnitsFormatStyle](https://developer.apple.com/documentation/swift/duration/unitsformatstyle)
+- [Measurement.FormatStyle](https://developer.apple.com/documentation/foundation/measurement/formatstyle)
+- [PersonNameComponents.FormatStyle](https://developer.apple.com/documentation/foundation/personnamecomponents/formatstyle)
+- [ListFormatStyle](https://developer.apple.com/documentation/foundation/listformatstyle)
+- [ByteCountFormatStyle](https://developer.apple.com/documentation/foundation/bytecountformatstyle)
+- [URL.FormatStyle](https://developer.apple.com/documentation/foundation/url/formatstyle)