@astryxdesign/native 0.7.5-canary.577e8ca → 0.7.5-canary.58fa49d

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/apple/Package.swift +7 -1
  2. package/apple/README.md +20 -7
  3. package/apple/Sources/Astryx/Avatar/Avatar.spec.md +219 -0
  4. package/apple/Sources/Astryx/Avatar/Avatar.swift +495 -0
  5. package/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md +162 -0
  6. package/apple/Sources/Astryx/Avatar/AvatarStatusDot.swift +181 -0
  7. package/apple/Sources/Astryx/Banner/Banner.swift +2 -2
  8. package/apple/Sources/Astryx/Base/BaseProps.swift +16 -0
  9. package/apple/Sources/Astryx/Button/Button.swift +3 -2
  10. package/apple/Sources/Astryx/Card/Card.swift +95 -19
  11. package/apple/Sources/Astryx/Heading/Heading.swift +90 -19
  12. package/apple/Sources/Astryx/Icon/Icon.spec.md +189 -0
  13. package/apple/Sources/Astryx/Icon/Icon.swift +160 -0
  14. package/apple/Sources/Astryx/Localization/AstryxStrings.swift +36 -0
  15. package/apple/Sources/Astryx/Resources/af.lproj/Localizable.strings +15 -0
  16. package/apple/Sources/Astryx/Resources/ar.lproj/Localizable.strings +15 -0
  17. package/apple/Sources/Astryx/Resources/ca.lproj/Localizable.strings +15 -0
  18. package/apple/Sources/Astryx/Resources/cs.lproj/Localizable.strings +15 -0
  19. package/apple/Sources/Astryx/Resources/da.lproj/Localizable.strings +15 -0
  20. package/apple/Sources/Astryx/Resources/de.lproj/Localizable.strings +15 -0
  21. package/apple/Sources/Astryx/Resources/el.lproj/Localizable.strings +15 -0
  22. package/apple/Sources/Astryx/Resources/en.lproj/Localizable.strings +15 -0
  23. package/apple/Sources/Astryx/Resources/es.lproj/Localizable.strings +15 -0
  24. package/apple/Sources/Astryx/Resources/fi.lproj/Localizable.strings +15 -0
  25. package/apple/Sources/Astryx/Resources/fr.lproj/Localizable.strings +15 -0
  26. package/apple/Sources/Astryx/Resources/he.lproj/Localizable.strings +15 -0
  27. package/apple/Sources/Astryx/Resources/hu.lproj/Localizable.strings +15 -0
  28. package/apple/Sources/Astryx/Resources/it.lproj/Localizable.strings +15 -0
  29. package/apple/Sources/Astryx/Resources/ja.lproj/Localizable.strings +15 -0
  30. package/apple/Sources/Astryx/Resources/ko.lproj/Localizable.strings +15 -0
  31. package/apple/Sources/Astryx/Resources/nb.lproj/Localizable.strings +15 -0
  32. package/apple/Sources/Astryx/Resources/nl.lproj/Localizable.strings +15 -0
  33. package/apple/Sources/Astryx/Resources/pl.lproj/Localizable.strings +15 -0
  34. package/apple/Sources/Astryx/Resources/pt-BR.lproj/Localizable.strings +15 -0
  35. package/apple/Sources/Astryx/Resources/pt-PT.lproj/Localizable.strings +15 -0
  36. package/apple/Sources/Astryx/Resources/ro.lproj/Localizable.strings +15 -0
  37. package/apple/Sources/Astryx/Resources/ru.lproj/Localizable.strings +15 -0
  38. package/apple/Sources/Astryx/Resources/sr.lproj/Localizable.strings +15 -0
  39. package/apple/Sources/Astryx/Resources/sv.lproj/Localizable.strings +15 -0
  40. package/apple/Sources/Astryx/Resources/tr.lproj/Localizable.strings +15 -0
  41. package/apple/Sources/Astryx/Resources/uk.lproj/Localizable.strings +15 -0
  42. package/apple/Sources/Astryx/Resources/vi.lproj/Localizable.strings +15 -0
  43. package/apple/Sources/Astryx/Resources/zh-Hans.lproj/Localizable.strings +15 -0
  44. package/apple/Sources/Astryx/Resources/zh-Hant.lproj/Localizable.strings +15 -0
  45. package/apple/Sources/Astryx/Text/Text.swift +89 -70
  46. package/apple/Sources/Astryx/Text/TypeStyle.swift +143 -0
  47. package/apple/Sources/Astryx/Theme/AstryxIcons.swift +72 -1
  48. package/apple/Sources/Astryx/Theme/Generated/ButterTheme.swift +390 -406
  49. package/apple/Sources/Astryx/Theme/Generated/ChocolateTheme.swift +390 -406
  50. package/apple/Sources/Astryx/Theme/Generated/DefaultTheme.swift +390 -406
  51. package/apple/Sources/Astryx/Theme/Generated/GothicTheme.swift +390 -406
  52. package/apple/Sources/Astryx/Theme/Generated/MatchaTheme.swift +390 -406
  53. package/apple/Sources/Astryx/Theme/Generated/NeutralTheme.swift +390 -406
  54. package/apple/Sources/Astryx/Theme/Generated/StoneTheme.swift +390 -406
  55. package/apple/Sources/Astryx/Theme/Generated/Tokens.swift +391 -238
  56. package/apple/Sources/Astryx/Theme/Generated/Y2kTheme.swift +390 -406
  57. package/apple/Sources/Astryx/Theme/Shadow.swift +41 -0
  58. package/apple/Sources/Astryx/Theme/Theme.swift +93 -45
  59. package/apple/Sources/Astryx/Thumbnail/Thumbnail.spec.md +191 -0
  60. package/apple/Sources/Astryx/Thumbnail/Thumbnail.swift +357 -0
  61. package/apple/Sources/Astryx/Tooltip/TooltipPresenter.swift +564 -0
  62. package/apple/Sources/Astryx/Wire/AstryxNodeView.swift +82 -0
  63. package/apple/Sources/AstryxNative/Generated/AstryxNode.swift +12 -0
  64. package/apple/Sources/AstryxNative/Generated/Avatar.swift +165 -0
  65. package/apple/Sources/AstryxNative/Generated/AvatarStatusDot.swift +78 -0
  66. package/apple/Sources/AstryxNative/Generated/Icon.swift +107 -0
  67. package/apple/Sources/AstryxNative/Generated/IconName.swift +47 -0
  68. package/apple/Sources/AstryxNative/Generated/Switch.swift +2 -26
  69. package/apple/Sources/AstryxNative/Generated/Thumbnail.swift +123 -0
  70. package/apple/Tests/AstryxTests/AvatarStatusDotTests.swift +255 -0
  71. package/apple/Tests/AstryxTests/AvatarTests.swift +263 -0
  72. package/apple/Tests/AstryxTests/BannerTests.swift +1 -1
  73. package/apple/Tests/AstryxTests/CardTests.swift +143 -3
  74. package/apple/Tests/AstryxTests/EnvironmentTests.swift +92 -2
  75. package/apple/Tests/AstryxTests/HeadingTests.swift +41 -13
  76. package/apple/Tests/AstryxTests/IconTests.swift +189 -0
  77. package/apple/Tests/AstryxTests/Resources/astryx-test-icon.png +0 -0
  78. package/apple/Tests/AstryxTests/TextInputTests.swift +1 -1
  79. package/apple/Tests/AstryxTests/TextTests.swift +90 -6
  80. package/apple/Tests/AstryxTests/ThemeTests.swift +4 -10
  81. package/apple/Tests/AstryxTests/ThumbnailTests.swift +204 -0
  82. package/apple/Tests/AstryxTests/TooltipPresenterTests.swift +220 -0
  83. package/apple/Tests/AstryxTests/TwoThemeTests.swift +5 -5
  84. package/dist/components/Avatar.d.ts +10 -0
  85. package/dist/components/Avatar.d.ts.map +1 -0
  86. package/dist/components/Avatar.js +17 -0
  87. package/dist/components/AvatarStatusDot.d.ts +10 -0
  88. package/dist/components/AvatarStatusDot.d.ts.map +1 -0
  89. package/dist/components/AvatarStatusDot.js +9 -0
  90. package/dist/components/Icon.d.ts +10 -0
  91. package/dist/components/Icon.d.ts.map +1 -0
  92. package/dist/components/Icon.js +7 -0
  93. package/dist/components/Switch.d.ts.map +1 -1
  94. package/dist/components/Switch.js +13 -0
  95. package/dist/components/Thumbnail.d.ts +10 -0
  96. package/dist/components/Thumbnail.d.ts.map +1 -0
  97. package/dist/components/Thumbnail.js +10 -0
  98. package/dist/components/index.d.ts.map +1 -1
  99. package/dist/components/index.js +8 -0
  100. package/dist/contract/fromComponentDoc.d.ts +14 -3
  101. package/dist/contract/fromComponentDoc.d.ts.map +1 -1
  102. package/dist/contract/fromComponentDoc.js +16 -1
  103. package/dist/contract/generateSwift.d.ts.map +1 -1
  104. package/dist/contract/generateSwift.js +61 -0
  105. package/dist/contract/generateTypeScript.d.ts.map +1 -1
  106. package/dist/contract/generateTypeScript.js +13 -2
  107. package/dist/contract/parseDocType.d.ts +2 -2
  108. package/dist/contract/parseDocType.d.ts.map +1 -1
  109. package/dist/contract/parseDocType.js +7 -2
  110. package/dist/contract/types.d.ts +11 -0
  111. package/dist/contract/types.d.ts.map +1 -1
  112. package/dist/types/android.d.ts +54 -4
  113. package/dist/types/core.d.ts +38 -2
  114. package/dist/types/ios.d.ts +51 -4
  115. package/dist/types/macos.d.ts +51 -4
  116. package/dist/types/shared.d.ts +51 -4
  117. package/dist/types/windows.d.ts +54 -4
  118. package/package.json +4 -4
  119. package/src/components/Avatar.ts +28 -0
  120. package/src/components/AvatarStatusDot.ts +20 -0
  121. package/src/components/Icon.ts +18 -0
  122. package/src/components/Switch.ts +13 -0
  123. package/src/components/Thumbnail.ts +21 -0
  124. package/src/components/index.ts +8 -0
  125. package/src/contract/contracts.test.ts +112 -0
  126. package/src/contract/fromComponentDoc.ts +40 -4
  127. package/src/contract/generateSwift.ts +68 -0
  128. package/src/contract/generateTypeScript.ts +13 -2
  129. package/src/contract/parseDocType.test.ts +12 -0
  130. package/src/contract/parseDocType.ts +9 -2
  131. package/src/contract/types.ts +7 -0
  132. package/src/theme/swiftIOSTheme.test.ts +78 -12
@@ -0,0 +1,495 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ import AstryxNative
4
+ import SwiftUI
5
+ import os
6
+
7
+ /// A person's or an entity's picture: the image at `src`, else `fallbackSrc`,
8
+ /// else initials from `name`, else a person symbol (core `Avatar`).
9
+ ///
10
+ /// ```swift
11
+ /// Avatar("Ada Lovelace", src: "https://example.com/ada.jpg")
12
+ /// Avatar("Ada Lovelace", size: .lg, shape: .rounded)
13
+ /// Avatar("Ada Lovelace", href: "https://example.com/ada")
14
+ /// Avatar("Ada Lovelace") { AvatarStatusDot(variant: .success, label: "Online") }
15
+ /// Avatar("Ada Lovelace", onClick: showProfile)
16
+ /// ```
17
+ public struct Avatar<Status: View>: View {
18
+ /// The contract the view draws, the same for both initializers.
19
+ public let props: AvatarProps
20
+ let status: Status
21
+ @Environment(\.astryx) private var astryx
22
+ @State private var statusLabel: String?
23
+
24
+ /// An avatar from its labeled props.
25
+ /// - Parameters:
26
+ /// - name: The person's or entity's name, for initials and the accessible name (core `name`).
27
+ /// - src: The image URL (core `src`).
28
+ /// - fallbackSrc: The image URL to try when `src` fails (core `fallbackSrc`).
29
+ /// - alt: The accessible name, when it differs from `name` (core `alt`).
30
+ /// - size: `xsm` 20, `sm` 24, `md` 36, `lg` 48, or `xl` 128 points; `nil` is `md` (core `size`).
31
+ /// - shape: `circle`, `rounded`, or `square`; `nil` is `circle` (core `shape`).
32
+ /// - tooltip: Words shown where there is a pointer: `nil` or `true` the name, a string those words, `false` none (core `tooltip`).
33
+ /// - href: A URL the system opens when the avatar is tapped; the avatar becomes a link (core `href`).
34
+ /// - status: An `AvatarStatusDot` in the bottom trailing corner; a single trailing closure is this (core `status`).
35
+ /// - onClick: Runs when the avatar is tapped; without `href` the avatar becomes a button (core `onClick`).
36
+ public init(
37
+ _ name: String? = nil,
38
+ src: String? = nil,
39
+ fallbackSrc: String? = nil,
40
+ alt: String? = nil,
41
+ size: AvatarSize? = nil,
42
+ shape: AvatarShape? = nil,
43
+ tooltip: AvatarTooltip? = nil,
44
+ href: String? = nil,
45
+ @ViewBuilder status: () -> Status = { EmptyView() },
46
+ onClick: (() -> Void)? = nil
47
+ ) {
48
+ self.init(
49
+ AvatarProps(
50
+ src: src, fallbackSrc: fallbackSrc, name: name, alt: alt, size: size, shape: shape, tooltip: tooltip, href: href,
51
+ onClick: onClick
52
+ ),
53
+ status: status)
54
+ }
55
+
56
+ /// An avatar from its generated contract, for generated and wire-driven callers.
57
+ public init(_ props: AvatarProps, @ViewBuilder status: () -> Status = { EmptyView() }) {
58
+ self.props = props
59
+ self.status = status()
60
+ }
61
+
62
+ public var body: some View {
63
+ if props.base.isHidden != true {
64
+ control
65
+ // The Astryx tooltip (library/tooltip.spec.md), as core's Avatar uses
66
+ // core's tooltip: a static avatar is a tab stop and opens on a tap;
67
+ // a link or button keeps its focus and its tap.
68
+ // Touch is core's `auto`: a static avatar opens on a tap; a control's
69
+ // tap belongs to its action.
70
+ .astryxTooltip(tooltipText, hint: tooltipHint, focus: Avatar.tooltipFocus(tap))
71
+ .modifier(AvatarIdentifier(id: props.base.id))
72
+ .onAppear(perform: checkInDevelopment)
73
+ }
74
+ }
75
+
76
+ /// Development checks core makes too: an `href` an app cannot open stops
77
+ /// the build with its value, and an unnamed link or button is flagged.
78
+ private func checkInDevelopment() {
79
+ #if DEBUG
80
+ if Avatar.isUnusableHref(props.href) {
81
+ assertionFailure(
82
+ "Avatar href \"\(props.href ?? "")\" is not an absolute URL an app can open; it draws without a link.")
83
+ }
84
+ // The avatar's own name: a status label alone does not name a person.
85
+ let ownName = Avatar.meaningful(props.alt) ?? Avatar.meaningful(props.name)
86
+ if Avatar.needsNameWarning(tap: tap, isNamed: ownName != nil) {
87
+ Logger(subsystem: "Astryx", category: "Avatar").warning(
88
+ "An Avatar with href or onClick has no alt or name, so VoiceOver reads it without a name.")
89
+ }
90
+ #endif
91
+ }
92
+
93
+ /// The tooltip's words: the name for `nil` or `true`, the given words, or
94
+ /// none for `false` or blank words, as core resolves it.
95
+ var tooltipText: String? {
96
+ switch props.tooltip ?? .on {
97
+ case .on: Avatar.meaningful(props.name).map(Avatar.trimmed)
98
+ case .off: nil
99
+ case .text(let words): Avatar.meaningful(words).map(Avatar.trimmed)
100
+ }
101
+ }
102
+
103
+ /// The VoiceOver hint: given tooltip words, as core puts them in the
104
+ /// description; the default name is the avatar's own name, not repeated.
105
+ var tooltipHint: String? {
106
+ guard case .text = props.tooltip else { return nil }
107
+ return tooltipText
108
+ }
109
+
110
+ /// A non-empty `href` that is not an absolute URL, such as a web path.
111
+ nonisolated static func isUnusableHref(_ href: String?) -> Bool {
112
+ guard let href, !href.isEmpty else { return false }
113
+ guard let url = URL(string: href) else { return true }
114
+ return url.scheme == nil
115
+ }
116
+
117
+ /// The picture as a link with `href`, a button with only `onClick`, or a
118
+ /// static image (Swift component API, A4). All three draw the same.
119
+ @ViewBuilder private var control: some View {
120
+ if let url = linkURL {
121
+ SwiftUI.Link(destination: url) { picture }
122
+ .buttonStyle(.plain)
123
+ .modifier(AvatarRunsBeforeOpening(onClick: props.onClick))
124
+ .modifier(AvatarTarget(side: side))
125
+ .modifier(AvatarName(label: accessibilityLabel, tap: .link))
126
+ } else if let onClick = props.onClick {
127
+ SwiftUI.Button(action: onClick) { picture }
128
+ .buttonStyle(.plain)
129
+ .modifier(AvatarTarget(side: side))
130
+ .modifier(AvatarName(label: accessibilityLabel, tap: .button))
131
+ } else {
132
+ picture
133
+ // A static avatar whose tap opens its tooltip answers taps across
134
+ // 44 points too.
135
+ .modifier(AvatarTarget(side: Avatar.tapTargetSide(side, takesTaps: tooltipText != nil)))
136
+ .modifier(AvatarName(label: accessibilityLabel, tap: .none))
137
+ }
138
+ }
139
+
140
+ /// How the avatar takes a tap: a link with a usable `href`, else a button
141
+ /// with `onClick`, else none.
142
+ enum Tap: Equatable { case link, button, none }
143
+
144
+ /// How far a tappable avatar's tap area reaches past its side: to 44
145
+ /// points (Swift accessibility, X7).
146
+ nonisolated static func tapOutset(side: CGFloat) -> CGFloat { max(0, (44 - side) / 2) }
147
+
148
+ /// The side a static avatar's tap area grows from: its own when a tap
149
+ /// opens its tooltip, and 44, which adds nothing, when it takes no taps.
150
+ nonisolated static func tapTargetSide(_ side: CGFloat, takesTaps: Bool) -> CGFloat { takesTaps ? side : 44 }
151
+
152
+ /// How keyboard focus reaches the tooltip: a static avatar is made a tab
153
+ /// stop, as core gives it one; a link or button takes focus already.
154
+ nonisolated static func tooltipFocus(_ tap: Tap) -> TooltipFocus { tap == .none ? .tabStop : .control }
155
+
156
+
157
+ var tap: Tap {
158
+ if linkURL != nil { return .link }
159
+ if props.onClick != nil { return .button }
160
+ return .none
161
+ }
162
+
163
+ /// The traits the avatar adds: a named static avatar is an image; a link or
164
+ /// button keeps its own trait and adds none (Swift accessibility, X1).
165
+ nonisolated static func addedTraits(tap: Tap, isNamed: Bool) -> AccessibilityTraits {
166
+ guard isNamed else { return [] }
167
+ switch tap {
168
+ case .none: return .isImage
169
+ case .link: return .isLink
170
+ case .button: return []
171
+ }
172
+ }
173
+
174
+ /// Traits a named avatar drops: a link avatar is a link, not the button
175
+ /// SwiftUI reports for `Link`.
176
+ nonisolated static func removedTraits(tap: Tap, isNamed: Bool) -> AccessibilityTraits {
177
+ isNamed && tap == .link ? .isButton : []
178
+ }
179
+
180
+ /// A link or button avatar needs a name, as core warns in development.
181
+ nonisolated static func needsNameWarning(tap: Tap, isNamed: Bool) -> Bool {
182
+ tap != .none && !isNamed
183
+ }
184
+
185
+ /// The photo; the fallback photo only after it fails or when there is
186
+ /// none, as core does; initials or the symbol while either loads and
187
+ /// after both fail.
188
+ private var picture: some View {
189
+ AvatarImage(url: url(props.src)) {
190
+ plate
191
+ } failure: {
192
+ AvatarImage(url: url(props.fallbackSrc)) { plate } failure: { plate }
193
+ }
194
+ .frame(width: side, height: side)
195
+ .clipShape(AvatarShapeOutline(shape: resolvedShape, radius: cornerRadius))
196
+ .overlay {
197
+ // Outside the clip, so the status is never cut off. The layout places
198
+ // it from its own size; SwiftUI mirrors the placement in right-to-left
199
+ // layouts, so it sits on the bottom leading corner there.
200
+ AvatarStatusPlacement(side: side, shape: resolvedShape) {
201
+ status
202
+ .environment(\.astryxAvatarSide, side)
203
+ // The owner sizes what it holds (slots S4): status content never
204
+ // grows with text faster than the avatar does.
205
+ .dynamicTypeSize(...Avatar<EmptyView>.statusTypeSizeCap)
206
+ }
207
+ }
208
+ .onPreferenceChange(AvatarStatusLabelKey.self) { label in
209
+ statusLabel = label?.text
210
+ }
211
+ }
212
+
213
+ /// How far the status content's bottom trailing corner moves out from the
214
+ /// avatar's, sized from the content itself, as core places any status: on a
215
+ /// circle its center sits on the edge at the bottom trailing 45° point; on a
216
+ /// rounded or square avatar it overhangs the corner by a quarter of its size.
217
+ nonisolated static func statusOffset(content: CGSize, side: CGFloat, shape: AvatarShape) -> CGSize {
218
+ switch shape {
219
+ case .circle:
220
+ return CGSize(width: content.width / 2 - side * circleEdgeInset, height: content.height / 2 - side * circleEdgeInset)
221
+ case .rounded, .square:
222
+ return CGSize(width: content.width / 4, height: content.height / 4)
223
+ }
224
+ }
225
+
226
+ /// Where a 45-degree line meets a circle, as a fraction of its side from
227
+ /// the square's corner: (1 − 1/√2) / 2.
228
+ nonisolated static var circleEdgeInset: CGFloat { (1 - 1 / 2.squareRoot()) / 2 }
229
+
230
+ /// The fallback: initials on the neutral plate, else a person symbol.
231
+ private var plate: some View {
232
+ ZStack {
233
+ astryx.tokens.color.neutral
234
+ if let initials {
235
+ // Drawn, not laid out as a Text view, so the initials are never an
236
+ // accessibility element of their own; the name names the avatar.
237
+ let font = initialsFont
238
+ let color = astryx.tokens.color.textSecondary
239
+ Canvas { context, size in
240
+ let text = context.resolve(SwiftUI.Text(initials).font(font).foregroundColor(color))
241
+ context.draw(text, at: CGPoint(x: size.width / 2, y: size.height / 2), anchor: .center)
242
+ }
243
+ .accessibilityHidden(true)
244
+ } else {
245
+ Image(systemName: "person.fill")
246
+ .resizable()
247
+ .scaledToFit()
248
+ .frame(width: side * 0.6, height: side * 0.6)
249
+ .foregroundStyle(astryx.tokens.color.textSecondary)
250
+ .accessibilityHidden(true)
251
+ }
252
+ }
253
+ }
254
+
255
+ /// The side of the avatar in points.
256
+ /// The side of the avatar in points: core's size grown with Dynamic Type,
257
+ /// as the name beside it grows, up to 1.6 times so it never swallows a row.
258
+ var side: CGFloat { Avatar.side(for: props.size ?? .md, textScale: astryx.textScale) }
259
+
260
+ /// The most an avatar grows with Dynamic Type.
261
+ nonisolated static var maximumTextScale: CGFloat { 1.6 }
262
+
263
+ /// The largest text size status content grows to: the largest whose text
264
+ /// scale stays within the avatar's own growth (`maximumTextScale`).
265
+ nonisolated static var statusTypeSizeCap: DynamicTypeSize {
266
+ DynamicTypeSize.allCases.last { astryxTextScale(for: $0) <= maximumTextScale } ?? .large
267
+ }
268
+
269
+ nonisolated static func side(for size: AvatarSize, textScale: CGFloat) -> CGFloat {
270
+ (points(for: size) * min(max(textScale, 1), maximumTextScale)).rounded()
271
+ }
272
+
273
+ var resolvedShape: AvatarShape { props.shape ?? .circle }
274
+
275
+ /// The corner radius for `rounded`, from the theme's element radius.
276
+ private var cornerRadius: CGFloat { astryx.tokens.radius.element }
277
+
278
+ /// Initials drawn at 40% of the side in the theme's body family, medium weight.
279
+ private var initialsFont: Font {
280
+ astryxFont(
281
+ families: astryx.tokens.font.family.body,
282
+ size: side * 0.4,
283
+ weight: astryx.fontWeight(astryx.tokens.font.weight.medium),
284
+ isBoldText: astryx.isBoldText
285
+ )
286
+ }
287
+
288
+ /// The initials the plate shows, or `nil` for the person symbol.
289
+ var initials: String? {
290
+ guard let name = Avatar.meaningful(props.name) else { return nil }
291
+ let initials = Avatar.initials(from: name)
292
+ return initials.isEmpty ? nil : initials
293
+ }
294
+
295
+ /// The name VoiceOver reads: `alt`, else `name`; `nil` when neither
296
+ /// carries anything, and then a static avatar is decorative.
297
+ var accessibilityLabel: String? {
298
+ Avatar.accessibleName(name: Avatar.meaningful(props.alt) ?? Avatar.meaningful(props.name), status: statusLabel)
299
+ }
300
+
301
+ /// The name with the status dot's label: "Ada Lovelace, Online" in the
302
+ /// person's language; either alone when the other is absent.
303
+ nonisolated static func accessibleName(name: String?, status: String?) -> String? {
304
+ switch (name, status) {
305
+ case let (name?, status?): AstryxStrings.avatarNameWithStatus(name: name, status: status)
306
+ case let (name, status): name ?? status
307
+ }
308
+ }
309
+
310
+ /// The URL the avatar opens, or `nil` when it has no usable `href`.
311
+ var linkURL: URL? {
312
+ // Only an absolute URL the system can open; a malformed or relative
313
+ // `href` leaves the avatar static or a button.
314
+ guard let url = url(props.href), url.scheme != nil else { return nil }
315
+ return url
316
+ }
317
+
318
+ private func url(_ string: String?) -> URL? {
319
+ guard let string, !string.isEmpty else { return nil }
320
+ return URL(string: string)
321
+ }
322
+
323
+ /// Core's named sizes in points.
324
+ nonisolated static func points(for size: AvatarSize) -> CGFloat {
325
+ switch size {
326
+ case .xsm: 20
327
+ case .sm: 24
328
+ case .md: 36
329
+ case .lg: 48
330
+ case .xl: 128
331
+ }
332
+ }
333
+
334
+ /// The string when it carries something, `nil` when it is absent or blank.
335
+ /// Words without their leading and trailing space, as core trims the
336
+ /// tooltip it shows.
337
+ nonisolated static func trimmed(_ value: String) -> String {
338
+ value.trimmingCharacters(in: .whitespacesAndNewlines)
339
+ }
340
+
341
+ nonisolated static func meaningful(_ value: String?) -> String? {
342
+ guard let value, !value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return nil }
343
+ return value
344
+ }
345
+
346
+ /// Core's initials: the first letter, digit, or emoji of the first and last
347
+ /// words that have one, uppercased. Leading punctuation in a word is skipped.
348
+ nonisolated static func initials(from name: String) -> String {
349
+ let letters = name.split(whereSeparator: { $0.isWhitespace }).compactMap { word in
350
+ word.first(where: avatarCanStandForAWord)
351
+ }
352
+ guard let first = letters.first else { return "" }
353
+ guard letters.count > 1, let last = letters.last else { return String(first).uppercased() }
354
+ return (String(first) + String(last)).uppercased()
355
+ }
356
+ }
357
+
358
+ /// A letter, a digit, or an emoji, as core's `\p{L}`, `\p{N}`,
359
+ /// `\p{Extended_Pictographic}`, and `\p{Regional_Indicator}`.
360
+ func avatarCanStandForAWord(_ character: Character) -> Bool {
361
+ if character.isLetter || character.isNumber { return true }
362
+ guard let scalar = character.unicodeScalars.first else { return false }
363
+ // `isEmoji` also covers `#`, `*`, and the digits, which are ASCII.
364
+ return scalar.value > 0x7F && scalar.properties.isEmoji
365
+ }
366
+
367
+ /// Draws the image at a URL: `loading` while it loads, `failure` when it
368
+ /// fails or there is no URL.
369
+ private struct AvatarImage<Loading: View, Failure: View>: View {
370
+ let url: URL?
371
+ @ViewBuilder let loading: () -> Loading
372
+ @ViewBuilder let failure: () -> Failure
373
+
374
+ var body: some View {
375
+ if let url {
376
+ AsyncImage(url: url) { phase in
377
+ if let image = phase.image {
378
+ image.resizable().scaledToFill()
379
+ } else if phase.error != nil {
380
+ failure()
381
+ } else {
382
+ loading()
383
+ }
384
+ }
385
+ } else {
386
+ failure()
387
+ }
388
+ }
389
+ }
390
+
391
+ /// Runs `onClick` as a link opens, then hands the URL to whatever opens URLs
392
+ /// above the avatar, so an app's own handler still applies. Without
393
+ /// `onClick` it changes nothing.
394
+ private struct AvatarRunsBeforeOpening: ViewModifier {
395
+ let onClick: (() -> Void)?
396
+ @Environment(\.openURL) private var inheritedOpenURL
397
+
398
+ func body(content: Content) -> some View {
399
+ if let onClick {
400
+ content.environment(\.openURL, OpenURLAction { url in
401
+ onClick()
402
+ inheritedOpenURL(url)
403
+ return .handled
404
+ })
405
+ } else {
406
+ content
407
+ }
408
+ }
409
+ }
410
+
411
+ /// The outline each shape clips to: a circle, the element radius, or square.
412
+ private struct AvatarShapeOutline: Shape {
413
+ let shape: AvatarShape
414
+ let radius: CGFloat
415
+
416
+ func path(in rect: CGRect) -> Path {
417
+ switch shape {
418
+ case .circle: Circle().path(in: rect)
419
+ case .rounded: RoundedRectangle(cornerRadius: radius, style: .continuous).path(in: rect)
420
+ case .square: Rectangle().path(in: rect)
421
+ }
422
+ }
423
+ }
424
+
425
+ /// Places the status content at the avatar's bottom trailing corner from the
426
+ /// content's own size (`Avatar.statusOffset`), in the same layout pass, so it
427
+ /// is in place from the first frame whatever it holds.
428
+ private struct AvatarStatusPlacement: Layout {
429
+ let side: CGFloat
430
+ let shape: AvatarShape
431
+
432
+ func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
433
+ proposal.replacingUnspecifiedDimensions(by: CGSize(width: side, height: side))
434
+ }
435
+
436
+ func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
437
+ for subview in subviews {
438
+ let size = subview.sizeThatFits(.unspecified)
439
+ let offset = Avatar<EmptyView>.statusOffset(content: size, side: side, shape: shape)
440
+ let origin = CGPoint(x: bounds.maxX - size.width + offset.width, y: bounds.maxY - size.height + offset.height)
441
+ subview.place(at: origin, anchor: .topLeading, proposal: ProposedViewSize(size))
442
+ }
443
+ }
444
+ }
445
+
446
+ /// One element named by the avatar's label. A static avatar without a label
447
+ /// is hidden; an interactive one keeps its link or button trait.
448
+ private struct AvatarName: ViewModifier {
449
+ let label: String?
450
+ let tap: Avatar<EmptyView>.Tap
451
+
452
+ func body(content: Content) -> some View {
453
+ let isNamed = label != nil
454
+ let added = Avatar<EmptyView>.addedTraits(tap: tap, isNamed: isNamed)
455
+ let removed = Avatar<EmptyView>.removedTraits(tap: tap, isNamed: isNamed)
456
+ if let label {
457
+ if tap == .none {
458
+ // One image element named by the name.
459
+ content.accessibilityElement(children: .ignore).accessibilityLabel(label)
460
+ .accessibilityAddTraits(added)
461
+ } else {
462
+ // The link or button itself carries the name, so VoiceOver reads
463
+ // "Grace Hopper, button", not the initials inside it.
464
+ content.accessibilityLabel(label).accessibilityAddTraits(added).accessibilityRemoveTraits(removed)
465
+ }
466
+ } else if tap != .none {
467
+ content
468
+ } else {
469
+ content.accessibilityHidden(true)
470
+ }
471
+ }
472
+ }
473
+
474
+ /// A tappable avatar answers taps across at least 44 by 44 points without
475
+ /// changing its drawn size or its layout (Swift accessibility, X7).
476
+ private struct AvatarTarget: ViewModifier {
477
+ let side: CGFloat
478
+
479
+ func body(content: Content) -> some View {
480
+ content.contentShape(.interaction, Rectangle().inset(by: -Avatar<EmptyView>.tapOutset(side: side)))
481
+ }
482
+ }
483
+
484
+ /// The base `id` becomes the accessibility identifier (AST-082 FR7).
485
+ private struct AvatarIdentifier: ViewModifier {
486
+ let id: String?
487
+
488
+ func body(content: Content) -> some View {
489
+ if let id {
490
+ content.accessibilityIdentifier(id)
491
+ } else {
492
+ content
493
+ }
494
+ }
495
+ }
@@ -0,0 +1,162 @@
1
+ ---
2
+ schema_version: 3
3
+ template_version: 7
4
+ kind: component
5
+ id: component:swift/AvatarStatusDot
6
+ platform_of: component:AvatarStatusDot
7
+ authority: draft
8
+ archive_reason: null
9
+ superseded_by: null
10
+ approved_by: null
11
+ approved_at: null
12
+ owners: [cixzhang]
13
+ review_triggers: [public-api, behavior, theming, accessibility]
14
+ verified_by:
15
+ [
16
+ packages/native/apple/Tests/AstryxTests/AvatarStatusDotTests.swift,
17
+ packages/native/src/contract/contracts.test.ts,
18
+ ]
19
+ modules: []
20
+ families: []
21
+ design_specs: []
22
+ architecture: []
23
+ contributing: []
24
+ system_specs: [spec:AST-082, spec:AST-093]
25
+ ---
26
+
27
+ # AvatarStatusDot (Swift) component contract
28
+
29
+ ## Contract at a glance
30
+
31
+ | Area | Contract |
32
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33
+ | Public contract | `AvatarStatusDot(variant: AvatarStatusDotVariant? = nil, label: String? = nil)` and `AvatarStatusDot(_ props: AvatarStatusDotProps)`, a SwiftUI `View`, placed in `Avatar`'s `status` slot. |
34
+ | Behavior | Draws core's dot at the tier for its avatar's size: `success` filled, `neutral` a ring, `error` a minus bar, each in theme tokens with a surface border. Its label joins the avatar's name. |
35
+ | End-user impact | A person sees who is online, away, or busy by shape as well as color, and VoiceOver reads it with the person's name ("Ada Lovelace, Online"). |
36
+ | Builder impact | An app puts the dot in the avatar's trailing closure with a label. A custom icon inside the dot has no Swift form. |
37
+ | Compatibility/readiness | Additive: a new view, generated `AvatarStatusDotProps`, and core's name-with-status message in the Swift string catalogs. Draft; built and tested on macOS and the iOS Simulator; device captures are attached. |
38
+ | Review checks | Reject a status shown by color alone, a dot that resizes or moves the avatar, a dot that VoiceOver reads separately inside an avatar, or a color that is not a theme token. |
39
+ | Governing rules | `spec:AST-082` FR4, FR7; `spec:AST-093` FR1–FR5; the Swift component API, slots (S4), theme environment, and accessibility (X1, X6) records under `packages/native/specs/swift/library/`. |
40
+
41
+ This table is a review projection; the body below is authoritative.
42
+
43
+ ## Intent
44
+
45
+ AvatarStatusDot on Apple platforms shows a person's status on their avatar by
46
+ shape and color, sized from the avatar, and gives the avatar its words.
47
+
48
+ ## Compatibility and migration
49
+
50
+ - Released default preserved: `not yet released`
51
+ - Compatibility class: additive
52
+ - Controlled/uncontrolled behavior: not applicable
53
+ - Migration decision: none
54
+
55
+ Consumer migration instructions belong in consumer docs and release notes.
56
+
57
+ ## Ownership boundary
58
+
59
+ **Owns**
60
+
61
+ - The dot's size tier, fill, border, and shape glyph per variant.
62
+ - Reporting its label to the avatar that holds it.
63
+
64
+ **Does not own / non-goals**
65
+
66
+ - Where the dot sits and how the name is composed — owned by
67
+ `component:swift/Avatar` (FR7, AR6).
68
+ - The meaning of the variants — owned by `component:AvatarStatusDot`.
69
+
70
+ ## Public concepts
71
+
72
+ | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
73
+ | ------- | ----------------------------- | -------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------- | ------------ | ---------------------- |
74
+ | variant | `success`, `neutral`, `error` | filled dot, ring, minus bar | always | `success` | `component:AvatarStatusDot` | experimental | none |
75
+ | tier | small, medium, large | 10, 20, 32 point dot for avatars up to 36, 72, and above | from the avatar; small alone | small | `component:AvatarStatusDot` | experimental | none |
76
+
77
+ ## Behavioral and layout contract
78
+
79
+ | ID | Candidate invariant | Basis | Draft review state |
80
+ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------ |
81
+ | FR1 | The dot MUST take core's tier for its avatar's side: up to 36 points a 10-point dot with a 1-point border and 1-point glyph stroke; up to 72 a 20-point dot, 2-point border, 1.5-point stroke; larger a 32-point dot, 4-point border, 2-point stroke. Outside an avatar it is small. | core `AvatarStatusDot` size tiers | verify |
82
+ | FR2 | `success` MUST fill with `color.success` and draw no glyph; `neutral` MUST fill with `color.backgroundSurface` and draw a ring in `color.textSecondary` on the inner field; `error` MUST fill with `color.error` and draw a round-capped bar in `color.onError` across three quarters of the inner field. Every dot has a `color.backgroundSurface` border. The plates are the strong status fills, `color.success` and `color.error`, and their ink is the matching content role, `color.onSuccess` and `color.onError`, as core's are (`architecture:theme-tokens` INV11). | core `AvatarStatusDot` styles | verify |
83
+ | FR3 | Both initializers MUST build the same `AvatarStatusDotProps`. Base props come through `AvatarStatusDotProps`: with `isHidden` the view draws nothing; `id` becomes the accessibility identifier. | Swift component API A2, A3, A7 | verify |
84
+
85
+ ### Allowed variation
86
+
87
+ - **AV1 — Glyph drawing.** The ring and bar are SwiftUI shapes at core's stroke
88
+ widths, not core's SVG.
89
+
90
+ ### Representative states
91
+
92
+ | State | Required invariant | Allowed variation |
93
+ | -------------------------- | ---------------------------------- | ----------------- |
94
+ | each variant | its fill, glyph, and border | AV1 |
95
+ | each tier | its dot, border, and stroke | none |
96
+ | on a circle and a square | placed by `component:swift/Avatar` | none |
97
+ | light and dark, two themes | each theme's colors | none |
98
+
99
+ ### Transformation and precedence order
100
+
101
+ - **ORD1 — Tier.** The avatar's side → small outside an avatar.
102
+
103
+ ### Performance and resources
104
+
105
+ - **PR1 — Shapes only.** The dot draws SwiftUI shapes and loads nothing.
106
+
107
+ ## Accessibility contract
108
+
109
+ - **AR1 — Inside an avatar.** The dot's label reaches VoiceOver through the
110
+ avatar's name, and the dot is not a separate element (Swift accessibility
111
+ X5).
112
+ - **AR2 — Alone.** A labeled dot outside an avatar is one image element named
113
+ by its label; an unlabeled one is hidden (X1).
114
+ - **AR3 — Not by color alone.** Each variant has its own shape (X6, Differentiate
115
+ Without Color).
116
+ - **AR4 — Rendered tree not measured.** Tests assert what the view sets; the
117
+ rendered accessibility tree is not measured until an app-hosted target
118
+ exists.
119
+
120
+ ## Design relationships
121
+
122
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
123
+ | ---------------- | ----------------------------------------------- | ------------------------ | -------------- | ------------------ |
124
+ | Dot and glyph | Apple Human Interface Guidelines, Accessibility | prescribed by core | supporting | FR1, FR2 |
125
+
126
+ The component implements design requirements without copying their rationale.
127
+
128
+ Platform control: SwiftUI has no status badge control for an image, so the dot
129
+ is drawn from SwiftUI shapes (`spec:AST-093` FR2). Guideline page:
130
+ Accessibility in the Apple Human Interface Guidelines.
131
+
132
+ Theme values read: `color.success`, `color.error`, `color.onSuccess`, `color.onError`, `color.backgroundSurface`,
133
+ `color.textSecondary`.
134
+
135
+ ## Family and system relationships
136
+
137
+ - `component:AvatarStatusDot` owns the variants and tiers; this record states
138
+ only how Swift draws them.
139
+ - `component:swift/Avatar` owns the dot's placement and the composed name.
140
+
141
+ ## Verification map
142
+
143
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
144
+ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------- |
145
+ | FR1 | `AvatarStatusDotTests.swift` tier test | 36, 48, 128 points; no avatar | a wrong dot, border, or stroke fails | `audit:swift/AvatarStatusDot/tier` |
146
+ | FR2 | `AvatarStatusDotTests.swift` variant render, ring sides, and the busy bar in Y2K | each variant at the large tier; neutral, butter, dark; Y2K light, where on-error and the surface differ | a wrong fill, a missing ring side or glyph, a bar not in on-error, or a glyph on success fails | `audit:swift/AvatarStatusDot/look` |
147
+ | FR3 | `AvatarStatusDotTests.swift` initializer test; `contracts.test.ts` | both initializers | differing props fail | `audit:swift/AvatarStatusDot/api` |
148
+ | AR1, AR2 | `AvatarStatusDotTests.swift` composed-name, standalone-trait, and hidden tests; the label the dot reports to its avatar in a rendered tree is not measured (`component:swift/Avatar` AR3) | name with and without a status; a dot alone with and without a label | a composed name without the status label, or a standalone dot without its label and image trait, fails | `audit:swift/AvatarStatusDot/a11y` |
149
+
150
+ ## Decision log
151
+
152
+ No component-local decision is recorded.
153
+
154
+ ## Open questions
155
+
156
+ - **OQ1 — A custom icon in the dot.** (`human-api`) Core's `icon` is free-form
157
+ content; it reaches Swift once the contract has the shared icon-name slot.
158
+
159
+ ## Content boundary
160
+
161
+ This file does not duplicate consumer prop tables/examples, current audit
162
+ results, implementation steps, or family/system rules. It links to their owners.