@astryxdesign/native 0.7.5-canary.c85932b → 0.7.5-canary.c86dc62

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 (139) hide show
  1. package/apple/Package.swift +7 -1
  2. package/apple/README.md +38 -21
  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/{AstryxBanner.swift → Banner.swift} +6 -6
  8. package/apple/Sources/Astryx/Base/BaseProps.swift +16 -0
  9. package/apple/Sources/Astryx/Button/{AstryxButton.swift → Button.swift} +8 -7
  10. package/apple/Sources/Astryx/Card/Card.swift +109 -0
  11. package/apple/Sources/Astryx/Exports.swift +8 -0
  12. package/apple/Sources/Astryx/Heading/Heading.swift +117 -0
  13. package/apple/Sources/Astryx/Icon/Icon.spec.md +189 -0
  14. package/apple/Sources/Astryx/Icon/Icon.swift +160 -0
  15. package/apple/Sources/Astryx/Localization/AstryxStrings.swift +36 -0
  16. package/apple/Sources/Astryx/Resources/af.lproj/Localizable.strings +15 -0
  17. package/apple/Sources/Astryx/Resources/ar.lproj/Localizable.strings +15 -0
  18. package/apple/Sources/Astryx/Resources/ca.lproj/Localizable.strings +15 -0
  19. package/apple/Sources/Astryx/Resources/cs.lproj/Localizable.strings +15 -0
  20. package/apple/Sources/Astryx/Resources/da.lproj/Localizable.strings +15 -0
  21. package/apple/Sources/Astryx/Resources/de.lproj/Localizable.strings +15 -0
  22. package/apple/Sources/Astryx/Resources/el.lproj/Localizable.strings +15 -0
  23. package/apple/Sources/Astryx/Resources/en.lproj/Localizable.strings +15 -0
  24. package/apple/Sources/Astryx/Resources/es.lproj/Localizable.strings +15 -0
  25. package/apple/Sources/Astryx/Resources/fi.lproj/Localizable.strings +15 -0
  26. package/apple/Sources/Astryx/Resources/fr.lproj/Localizable.strings +15 -0
  27. package/apple/Sources/Astryx/Resources/he.lproj/Localizable.strings +15 -0
  28. package/apple/Sources/Astryx/Resources/hu.lproj/Localizable.strings +15 -0
  29. package/apple/Sources/Astryx/Resources/it.lproj/Localizable.strings +15 -0
  30. package/apple/Sources/Astryx/Resources/ja.lproj/Localizable.strings +15 -0
  31. package/apple/Sources/Astryx/Resources/ko.lproj/Localizable.strings +15 -0
  32. package/apple/Sources/Astryx/Resources/nb.lproj/Localizable.strings +15 -0
  33. package/apple/Sources/Astryx/Resources/nl.lproj/Localizable.strings +15 -0
  34. package/apple/Sources/Astryx/Resources/pl.lproj/Localizable.strings +15 -0
  35. package/apple/Sources/Astryx/Resources/pt-BR.lproj/Localizable.strings +15 -0
  36. package/apple/Sources/Astryx/Resources/pt-PT.lproj/Localizable.strings +15 -0
  37. package/apple/Sources/Astryx/Resources/ro.lproj/Localizable.strings +15 -0
  38. package/apple/Sources/Astryx/Resources/ru.lproj/Localizable.strings +15 -0
  39. package/apple/Sources/Astryx/Resources/sr.lproj/Localizable.strings +15 -0
  40. package/apple/Sources/Astryx/Resources/sv.lproj/Localizable.strings +15 -0
  41. package/apple/Sources/Astryx/Resources/tr.lproj/Localizable.strings +15 -0
  42. package/apple/Sources/Astryx/Resources/uk.lproj/Localizable.strings +15 -0
  43. package/apple/Sources/Astryx/Resources/vi.lproj/Localizable.strings +15 -0
  44. package/apple/Sources/Astryx/Resources/zh-Hans.lproj/Localizable.strings +15 -0
  45. package/apple/Sources/Astryx/Resources/zh-Hant.lproj/Localizable.strings +15 -0
  46. package/apple/Sources/Astryx/Text/Text.swift +102 -0
  47. package/apple/Sources/Astryx/Text/TypeStyle.swift +143 -0
  48. package/apple/Sources/Astryx/TextInput/{AstryxTextInput.swift → TextInput.swift} +4 -4
  49. package/apple/Sources/Astryx/Theme/AstryxIcons.swift +72 -1
  50. package/apple/Sources/Astryx/Theme/Generated/ButterTheme.swift +390 -406
  51. package/apple/Sources/Astryx/Theme/Generated/ChocolateTheme.swift +390 -406
  52. package/apple/Sources/Astryx/Theme/Generated/DefaultTheme.swift +390 -406
  53. package/apple/Sources/Astryx/Theme/Generated/GothicTheme.swift +390 -406
  54. package/apple/Sources/Astryx/Theme/Generated/MatchaTheme.swift +390 -406
  55. package/apple/Sources/Astryx/Theme/Generated/NeutralTheme.swift +390 -406
  56. package/apple/Sources/Astryx/Theme/Generated/StoneTheme.swift +390 -406
  57. package/apple/Sources/Astryx/Theme/Generated/Tokens.swift +391 -238
  58. package/apple/Sources/Astryx/Theme/Generated/Y2kTheme.swift +390 -406
  59. package/apple/Sources/Astryx/Theme/Shadow.swift +41 -0
  60. package/apple/Sources/Astryx/Theme/Theme.swift +93 -45
  61. package/apple/Sources/Astryx/Thumbnail/Thumbnail.spec.md +191 -0
  62. package/apple/Sources/Astryx/Thumbnail/Thumbnail.swift +357 -0
  63. package/apple/Sources/Astryx/Tooltip/TooltipPresenter.swift +564 -0
  64. package/apple/Sources/Astryx/Wire/AstryxNodeView.swift +82 -0
  65. package/apple/Sources/AstryxNative/Generated/AstryxNode.swift +12 -0
  66. package/apple/Sources/AstryxNative/Generated/Avatar.swift +165 -0
  67. package/apple/Sources/AstryxNative/Generated/AvatarStatusDot.swift +78 -0
  68. package/apple/Sources/AstryxNative/Generated/Icon.swift +107 -0
  69. package/apple/Sources/AstryxNative/Generated/IconName.swift +47 -0
  70. package/apple/Sources/AstryxNative/Generated/Switch.swift +2 -26
  71. package/apple/Sources/AstryxNative/Generated/Thumbnail.swift +123 -0
  72. package/apple/Tests/AstryxTests/AvatarStatusDotTests.swift +255 -0
  73. package/apple/Tests/AstryxTests/AvatarTests.swift +263 -0
  74. package/apple/Tests/AstryxTests/BannerTests.swift +5 -5
  75. package/apple/Tests/AstryxTests/ButtonTests.swift +13 -13
  76. package/apple/Tests/AstryxTests/CardTests.swift +143 -3
  77. package/apple/Tests/AstryxTests/EnvironmentTests.swift +95 -5
  78. package/apple/Tests/AstryxTests/HeadingTests.swift +42 -14
  79. package/apple/Tests/AstryxTests/IconTests.swift +189 -0
  80. package/apple/Tests/AstryxTests/NamesTests.swift +28 -0
  81. package/apple/Tests/AstryxTests/Resources/astryx-test-icon.png +0 -0
  82. package/apple/Tests/AstryxTests/TextInputTests.swift +4 -4
  83. package/apple/Tests/AstryxTests/TextTests.swift +92 -8
  84. package/apple/Tests/AstryxTests/ThemeTests.swift +4 -10
  85. package/apple/Tests/AstryxTests/ThumbnailTests.swift +204 -0
  86. package/apple/Tests/AstryxTests/TooltipPresenterTests.swift +220 -0
  87. package/apple/Tests/AstryxTests/TwoThemeTests.swift +8 -8
  88. package/dist/components/Avatar.d.ts +10 -0
  89. package/dist/components/Avatar.d.ts.map +1 -0
  90. package/dist/components/Avatar.js +17 -0
  91. package/dist/components/AvatarStatusDot.d.ts +10 -0
  92. package/dist/components/AvatarStatusDot.d.ts.map +1 -0
  93. package/dist/components/AvatarStatusDot.js +9 -0
  94. package/dist/components/Icon.d.ts +10 -0
  95. package/dist/components/Icon.d.ts.map +1 -0
  96. package/dist/components/Icon.js +7 -0
  97. package/dist/components/Switch.d.ts.map +1 -1
  98. package/dist/components/Switch.js +13 -0
  99. package/dist/components/Thumbnail.d.ts +10 -0
  100. package/dist/components/Thumbnail.d.ts.map +1 -0
  101. package/dist/components/Thumbnail.js +10 -0
  102. package/dist/components/index.d.ts.map +1 -1
  103. package/dist/components/index.js +8 -0
  104. package/dist/contract/fromComponentDoc.d.ts +14 -3
  105. package/dist/contract/fromComponentDoc.d.ts.map +1 -1
  106. package/dist/contract/fromComponentDoc.js +16 -1
  107. package/dist/contract/generateSwift.d.ts.map +1 -1
  108. package/dist/contract/generateSwift.js +61 -0
  109. package/dist/contract/generateTypeScript.d.ts.map +1 -1
  110. package/dist/contract/generateTypeScript.js +13 -2
  111. package/dist/contract/parseDocType.d.ts +2 -2
  112. package/dist/contract/parseDocType.d.ts.map +1 -1
  113. package/dist/contract/parseDocType.js +7 -2
  114. package/dist/contract/types.d.ts +11 -0
  115. package/dist/contract/types.d.ts.map +1 -1
  116. package/dist/types/android.d.ts +54 -4
  117. package/dist/types/core.d.ts +38 -2
  118. package/dist/types/ios.d.ts +51 -4
  119. package/dist/types/macos.d.ts +51 -4
  120. package/dist/types/shared.d.ts +51 -4
  121. package/dist/types/windows.d.ts +54 -4
  122. package/package.json +4 -4
  123. package/src/components/Avatar.ts +28 -0
  124. package/src/components/AvatarStatusDot.ts +20 -0
  125. package/src/components/Icon.ts +18 -0
  126. package/src/components/Switch.ts +13 -0
  127. package/src/components/Thumbnail.ts +21 -0
  128. package/src/components/index.ts +8 -0
  129. package/src/contract/contracts.test.ts +104 -0
  130. package/src/contract/fromComponentDoc.ts +40 -4
  131. package/src/contract/generateSwift.ts +68 -0
  132. package/src/contract/generateTypeScript.ts +13 -2
  133. package/src/contract/parseDocType.test.ts +12 -0
  134. package/src/contract/parseDocType.ts +9 -2
  135. package/src/contract/types.ts +7 -0
  136. package/src/theme/swiftIOSTheme.test.ts +78 -12
  137. package/apple/Sources/Astryx/Card/AstryxCard.swift +0 -33
  138. package/apple/Sources/Astryx/Heading/AstryxHeading.swift +0 -46
  139. package/apple/Sources/Astryx/Text/AstryxText.swift +0 -83
@@ -27,9 +27,15 @@ let package = Package(
27
27
  name: "Astryx",
28
28
  dependencies: ["AstryxNative"],
29
29
  path: "Sources/Astryx",
30
+ // Each component's spec lives beside its view (AST-093 FR1).
31
+ exclude: ["Avatar/Avatar.spec.md", "Avatar/AvatarStatusDot.spec.md", "Icon/Icon.spec.md", "Thumbnail/Thumbnail.spec.md"],
30
32
  resources: [.process("Resources")]
31
33
  ),
32
34
  .testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
33
- .testTarget(name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests"),
35
+ .testTarget(
36
+ name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests",
37
+ // A tiny image that stands in for an app-shipped icon asset.
38
+ resources: [.process("Resources")]
39
+ ),
34
40
  ]
35
41
  )
package/apple/README.md CHANGED
@@ -26,12 +26,15 @@ apple/
26
26
  │ │ │ └── Generated/ # typed tokens and every published theme, generated; do not edit
27
27
  │ │ ├── Resources/ # core's messages per locale, generated; do not edit
28
28
  │ │ ├── Localization/
29
- │ │ ├── Text/ # AstryxText
30
- │ │ ├── Heading/ # AstryxHeading
31
- │ │ ├── Button/ # AstryxButton
32
- │ │ ├── TextInput/ # AstryxTextInput
33
- │ │ ├── Card/ # AstryxCard
34
- │ │ └── Banner/ # AstryxBanner
29
+ │ │ ├── Icon/ # Icon, Icon.spec.md
30
+ │ │ ├── Avatar/ # Avatar, Avatar.spec.md
31
+ │ │ ├── Text/ # Text
32
+ │ │ ├── Heading/ # Heading
33
+ │ │ ├── Button/ # Button
34
+ │ │ ├── TextInput/ # TextInput
35
+ │ │ ├── Thumbnail/ # Thumbnail, Thumbnail.spec.md
36
+ │ │ ├── Card/ # Card
37
+ │ │ └── Banner/ # Banner
35
38
  │ └── AstryxNative/ # contracts, wire, logic host (module AstryxNative)
36
39
  │ └── Generated/ # generated; do not edit
37
40
  ├── Tests/
@@ -44,18 +47,21 @@ apple/
44
47
  ```
45
48
 
46
49
  - **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
47
- `packages/core/src/<Name>/`. A component's parameters use core's prop names
50
+ `packages/core/src/<Name>/`. Each view has core's component name in the
51
+ `Astryx` module (`Button`, `Text`), which re-exports SwiftUI and the
52
+ generated contracts, so an app file writes `import Astryx` alone. In a file
53
+ that also imports SwiftUI, write `Astryx.Button` and `SwiftUI.Button`. A
54
+ component's parameters use core's prop names
48
55
  and values (`variant: .primary`, `size: .lg`, `isLoading`), so code reads
49
- the same across web and native, with six exceptions, the interim shape
50
- AST-093 FR5 exempts until the components move onto the generated contracts:
51
- - `AstryxButton` takes `action` where core has `onClick`.
52
- - `AstryxButton` takes `fillsWidth` where core has `width="100%"`.
53
- - `AstryxButton` takes `icon` as a shared icon name (`"search"`), which the
56
+ the same across web and native. `Text`, `Heading`, and `Card` take the
57
+ generated `TextProps`, `HeadingProps`, and `CardProps`, as AST-093 FR5 asks;
58
+ the others keep four exceptions, the interim shape FR5 exempts until they move onto the generated
59
+ contracts:
60
+ - `Button` takes `action` where core has `onClick`.
61
+ - `Button` takes `fillsWidth` where core has `width="100%"`.
62
+ - `Button` takes `icon` as a shared icon name (`"search"`), which the
54
63
  generated `ButtonProps` does not carry yet.
55
- - `AstryxTextInput` takes a `Binding` where core has `value` and `onChange`.
56
- - `AstryxHeading`'s `level` is optional where core requires it.
57
- - `AstryxCard` takes `padding` as a whole spacing step, so it cannot spell
58
- core's `0.5` and `1.5` steps.
64
+ - `TextInput` takes a `Binding` where core has `value` and `onChange`.
59
65
  - **`Templates/`** holds one folder per page template, named after the
60
66
  `astryx template` id. Templates are clone-only, as on the web: you copy a
61
67
  template's folder into your app and own it from then on. They are a
@@ -74,7 +80,6 @@ app.
74
80
 
75
81
  ```swift
76
82
  import Astryx
77
- import SwiftUI
78
83
 
79
84
  @main
80
85
  struct DemoApp: App {
@@ -95,11 +100,22 @@ size.
95
100
  Components read every color, size, and font from the `astryx` environment
96
101
  value, never from a constant of their own. `astryx.tokens` holds the theme's
97
102
  tokens in the current mode as typed members (`tokens.color.textPrimary`,
98
- `tokens.space.s4`, `tokens.font.bodySize`), so a misspelled token fails to
99
- compile. Text sizes grow with Dynamic Type. The components still read some
103
+ `tokens.space.s4`, `tokens.font.body.size`), so a misspelled token fails to
104
+ compile. Font tokens come grouped: each type style (`tokens.font.body`,
105
+ `tokens.font.heading1`) holds its `size`, `weight`, and `leading`, and
106
+ `tokens.font.family`, `.size`, and `.weight` hold the scales. Text sizes grow with Dynamic Type. The components still read some
100
107
  tokens by core's name (`astryx.color("color-accent")`); moving them onto the
101
108
  typed members comes next.
102
109
 
110
+ `Icon(.search)` draws a shared icon name as the platform's SF Symbol, at
111
+ core's icon size and color, hidden from VoiceOver unless it has a `label`.
112
+ `IconName` holds every built-in name as a static member; a theme maps a name
113
+ to another symbol or to an image the app ships, or registers a
114
+ `<library>:<name>` name, with
115
+ `Theme(…, icons: ["acme:rocket": "airplane", "close": .assetName("brand.close")])`.
116
+ An asset the app does not ship stops a development build with a message that
117
+ names it, and draws nothing in a release build.
118
+
103
119
  Font families come from the theme's `font-family-*` stacks: the first family
104
120
  the device has wins, and a system family such as `-apple-system` or
105
121
  `sans-serif` is the system font. Icons use core's shared icon names
@@ -173,8 +189,9 @@ Both packages also declare macOS 14 so they build and test on a Mac without a
173
189
  simulator; iOS 17 is the target. Open `Templates/Package.swift` in Xcode to
174
190
  run `LoginTemplate` in an iOS simulator through its preview.
175
191
 
176
- To add a component, create `Sources/Astryx/<Name>/Astryx<Name>.swift` with
177
- core's prop names, read its tokens from `astryx`, and add tests under
192
+ To add a component, create `Sources/Astryx/<Name>/<Name>.swift` declaring
193
+ `<Name>` with core's prop names, writing `SwiftUI.<Name>` wherever it means the
194
+ system type, read its tokens from `astryx`, and add tests under
178
195
  `Tests/AstryxTests/`. To add a template, create
179
196
  `Templates/<Name>/<Name>Template.swift` from the output of
180
197
  `astryx template <id>`, with tests under `Templates/Tests/`.
@@ -0,0 +1,219 @@
1
+ ---
2
+ schema_version: 3
3
+ template_version: 7
4
+ kind: component
5
+ id: component:swift/Avatar
6
+ platform_of: component:Avatar
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, layout, theming, accessibility]
14
+ verified_by:
15
+ [
16
+ packages/native/apple/Tests/AstryxTests/AvatarTests.swift,
17
+ packages/native/apple/Tests/AstryxTests/AvatarStatusDotTests.swift,
18
+ packages/native/src/contract/contracts.test.ts,
19
+ packages/native/src/contract/parseDocType.test.ts,
20
+ ]
21
+ modules: []
22
+ families: []
23
+ design_specs: []
24
+ architecture: []
25
+ contributing: []
26
+ system_specs: [spec:AST-082, spec:AST-093]
27
+ ---
28
+
29
+ # Avatar (Swift) component contract
30
+
31
+ ## Contract at a glance
32
+
33
+ | Area | Contract |
34
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35
+ | Public contract | `Avatar(_ name: String? = nil, src:, fallbackSrc:, alt:, size: AvatarSize?, shape: AvatarShape?, tooltip: AvatarTooltip?, href:, status:, onClick:)` and `Avatar(_ props: AvatarProps, status:)`, a SwiftUI `View` in module `Astryx`. `size` is the named sizes `xsm` to `xl`. |
36
+ | Behavior | Draws the image at `src`, else `fallbackSrc`, else initials from `name` on the theme's neutral plate, else a person symbol, clipped to its shape. With `href` it is a SwiftUI `Link`; with only `onClick` it is a button; it draws the same either way. |
37
+ | End-user impact | A person sees the same picture, initials, and shape as on the web, and VoiceOver reads the avatar's name, or skips a decorative one. |
38
+ | Builder impact | An app passes a name and an image URL, and optionally tooltip words and an `AvatarStatusDot`. Pixel sizes, `target`, and `rel` have no Swift form; an `href` must be an absolute URL. |
39
+ | Compatibility/readiness | Additive: a new view and generated `AvatarProps`. Draft; built and tested on macOS and the iOS Simulator; device captures are attached to the change. |
40
+ | Review checks | Reject a size or shape beyond the contract, a disabled state, a link or button that draws differently from the static avatar, a layout that grows for the touch target, or a static avatar VoiceOver reads without a name. |
41
+ | Governing rules | `spec:AST-082` FR3, FR4, FR7; `spec:AST-093` FR1–FR5; the Swift component API (A1–A9), theme environment, and accessibility records under `packages/native/specs/swift/library/`. |
42
+
43
+ This table is a review projection; the body below is authoritative.
44
+
45
+ ## Intent
46
+
47
+ Avatar on Apple platforms shows a person's or an entity's picture with core's
48
+ fallback order, sizes, shapes, and naming, drawn with SwiftUI's own image
49
+ loading and link and button controls.
50
+
51
+ ## Compatibility and migration
52
+
53
+ - Released default preserved: `not yet released`
54
+ - Compatibility class: additive
55
+ - Controlled/uncontrolled behavior: not applicable
56
+ - Migration decision: none
57
+
58
+ Consumer migration instructions belong in consumer docs and release notes.
59
+
60
+ ## Ownership boundary
61
+
62
+ **Owns**
63
+
64
+ - Loading `src`, then `fallbackSrc`, with SwiftUI `AsyncImage`.
65
+ - Initials, the person symbol, the plate color, and the shape clip.
66
+ - Switching to a SwiftUI `Link` or `Button` for `href` or `onClick` without
67
+ changing the drawing.
68
+ - The avatar's VoiceOver name and its touch target.
69
+
70
+ **Does not own / non-goals**
71
+
72
+ - The meaning of the props, the initials rule, and the size scale — owned by
73
+ `component:Avatar`.
74
+ - Avatar groups, which have no Swift view.
75
+
76
+ ## Public concepts
77
+
78
+ | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
79
+ | ------- | ---------------------------------------------- | --------------------------------------------------- | ----------------------------------------- | -------- | ------------------------ | ------------ | -------------------------------------------------------------------------- |
80
+ | size | `xsm`, `sm`, `md`, `lg`, `xl` | 20, 24, 36, 48, 128 points at the default text size | always | `md` | `component:Avatar` | experimental | core's pixel sizes have no Swift form |
81
+ | shape | `circle`, `rounded`, `square` | full round, the theme's element radius, no radius | always | `circle` | `component:Avatar` | experimental | none |
82
+ | picture | image, fallback image, initials, person symbol | the first that is available, in that order | always | — | `component:Avatar` | experimental | an empty or unloadable URL moves to the next |
83
+ | control | static, link (`href`), button (`onClick`) | how a tap behaves; the drawing is the same | always | static | `component:swift/Avatar` | experimental | an `href` that is not an absolute URL leaves the avatar static or a button |
84
+
85
+ ## Behavioral and layout contract
86
+
87
+ | ID | Candidate invariant | Basis | Draft review state |
88
+ | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
89
+ | FR1 | The view MUST show the image at `src`; when it is absent or fails, the image at `fallbackSrc`; then initials from a `name` that is not blank; then a person symbol. The fallback image loads only after `src` fails or when there is no `src`; while an image loads, the initials or the person symbol show. | core `Avatar` fallback order; `spec:AST-093` FR2 | verify |
90
+ | FR2 | Initials MUST follow core's rule: the first letter, digit, or emoji of the first and last words that have one, uppercased, skipping leading punctuation, keeping a whole emoji, flag, or joined emoji sequence. A name with none shows the person symbol and still names the avatar. | core `Avatar` initials | verify |
91
+ | FR3 | The avatar MUST be a square of 20, 24, 36, 48, or 128 points for `xsm` to `xl` at the default text size, grown with Dynamic Type up to 1.6 times and never shrunk, so it and its initials grow with the name beside them without swallowing a row (`spec:AST-082` FR11). It is clipped to a circle, to the theme's `radius.element`, or to a square. | core `Avatar` sizes and shapes | verify |
92
+ | FR4 | Initials and the person symbol MUST draw in `color.textSecondary` on `color.neutral`; initials use the theme's body family at medium weight and 40% of the side. | core `Avatar` fallback styles; `spec:AST-093` FR4 | verify |
93
+ | FR5 | With an `href` that is an absolute URL (it has a scheme), the avatar MUST be a SwiftUI `Link`; with `onClick` too, `onClick` runs as it opens and the URL then goes to the app's own URL handler, or the system's. An `href` that is not an absolute URL, such as a web path, MUST stop a development build with a message naming it; a release build draws the avatar without a link, as a button with `onClick` or static. With only `onClick`, a SwiftUI `Button`. Either draws exactly as the static avatar, and the avatar has no disabled state. | Swift component API A4 | verify |
94
+ | FR6 | Both initializers MUST build the same `AvatarProps`; `name` is the unlabeled first parameter, a single trailing closure is the status, and `onClick` comes last. Base props come through `AvatarProps`: with `isHidden` the view draws nothing; `id` becomes the accessibility identifier. | Swift component API A2–A4, A7; `spec:AST-082` FR7 | verify |
95
+ | FR7 | The `status` slot MUST draw its content, usually one `AvatarStatusDot`, outside the avatar's clip, placed from the content's own size, in the same layout pass, as core places any status: on a circle centered on the circle's edge at the bottom trailing 45° point, on a rounded or square avatar overhanging the bottom trailing corner by a quarter of its size, mirrored in right-to-left layouts. It MUST NOT change the avatar's size or layout, gives a dot the avatar's side for its size tier, and lets other content grow with Dynamic Type no faster than the avatar, up to the text size at its 1.6 times growth: the content still grows with Dynamic Type (`spec:AST-082` FR11), up to its owner's growth, since the owner sizes what it holds (Swift slots S4). | core `Avatar` status position; Swift slots S4 | verify |
96
+ | FR8 | `tooltip` MUST resolve, as core does, to the name for `nil` or `true`, the given words for a string, and nothing for `false` or blank words, and MUST show through the Astryx tooltip (`architecture:native-swift-library-tooltip`), with the focus and touch the Tooltip by input table below states: a static avatar is a tab stop and opens on a tap; a link or button keeps its focus and its tap. Given words are the VoiceOver hint. On the wire it is the web value, a string or a Bool. | core `Avatar` `tooltip`; core `Tooltip`; `spec:AST-082` FR3 | verify |
97
+
98
+ **Tooltip by input (FR8).** The Astryx tooltip's rules apply; this table
99
+ states Avatar's choices.
100
+
101
+ | Input | Default name | Given words | Off (`false` or blank) |
102
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------ |
103
+ | Pointer | the bubble shows the name above the avatar after 200 ms, stays while the pointer is on it, and a press hides it | the same, with the words | nothing |
104
+ | Keyboard focus | the bubble shows the name at once and Escape hides it; a static avatar is a tab stop | the same, with the words | nothing; a static avatar is not a tab stop |
105
+ | Touch tap | a direct tap on a static avatar opens the bubble with the name; another tap on it, or a tap anywhere else, closes it, and that tap still reaches what it lands on; the tap is shared with an enclosing row; a link or button keeps its tap | the same, with the words | nothing |
106
+ | VoiceOver | the name is read once, as the avatar's own; the bubble is hidden and the tap is left alone | the words are the hint, as core puts them in the description | nothing |
107
+
108
+ ### Allowed variation
109
+
110
+ - **AV1 — Loading.** While an image loads, the initials or the person symbol
111
+ show instead of an empty plate.
112
+ - **AV2 — Glyph.** The person symbol is the SF Symbol `person.fill`, not core's
113
+ SVG.
114
+
115
+ - **AV3 — Tooltip surface.** The tooltip is the Astryx tooltip's bubble in
116
+ core's tooltip colors on every input. SwiftUI's `.help` does not fit: it is
117
+ also the VoiceOver hint, so it would read the name twice, and it shows with
118
+ the system's look and delay, never on keyboard focus or a tap.
119
+
120
+ ### Representative states
121
+
122
+ | State | Required invariant | Allowed variation |
123
+ | ------------------------------ | -------------------------------------- | ----------------- |
124
+ | image | the image fills the shape | image content |
125
+ | failed image with a fallback | the fallback image | none |
126
+ | initials, every size and shape | initials centered on the neutral plate | glyph metrics |
127
+ | no name | the person symbol at 60% of the side | none |
128
+ | link and button | the same drawing as static | none |
129
+ | light and dark, two themes | each theme's plate and text color | none |
130
+
131
+ ### Transformation and precedence order
132
+
133
+ - **ORD1 — Picture.** `src` → `fallbackSrc` → initials → person symbol.
134
+ - **ORD2 — Name.** `alt` → `name`, where a blank string is none; then
135
+ compose with the status label (AR6), a dot's label before another
136
+ element's.
137
+ - **ORD3 — Control.** `href` (link) → `onClick` (button) → static.
138
+
139
+ ### Performance and resources
140
+
141
+ - **PR1 — System loading.** Images load through `AsyncImage` and the system
142
+ URL cache; the view keeps no image cache of its own.
143
+
144
+ ## Accessibility contract
145
+
146
+ - **AR1 — Named or decorative.** A static avatar with a name is one image
147
+ element named by `alt`, else `name`, composed with its status label (AR6);
148
+ without a name and without a status label it is hidden from VoiceOver.
149
+ A link or button avatar is one element with the link or button trait and the
150
+ same name; the initials are never an element of their own (Swift
151
+ accessibility X1, X5).
152
+ - **AR2 — Touch target.** A link or button avatar, and a static avatar whose
153
+ tap opens its tooltip, answers taps across at least 44 by 44 points without
154
+ changing its drawn size or layout (X7).
155
+ - **AR3 — Rendered tree not measured.** Tests assert what the view sets; the
156
+ rendered accessibility tree and the hit region are not measured until an
157
+ app-hosted target exists.
158
+ - **AR4 — Unnamed taps are flagged.** A link or button avatar without `alt`
159
+ or `name` logs a development warning, as core warns.
160
+ - **AR5 — Initials contrast.** The initials draw in core's tokens,
161
+ `color.textSecondary` on `color.neutral`, as core's Avatar does. In the
162
+ default and neutral themes' dark appearance that pair is below 4.5:1, in
163
+ core as well; the fix belongs to the theme tokens.
164
+ - **AR6 — Status in the name.** The status label joins the avatar's name as
165
+ core's message composes it ("Ada Lovelace, Online"); a status label alone
166
+ names an otherwise unnamed avatar. The label comes from an `AvatarStatusDot` or a labeled `Icon` in the slot, at any depth, as core reads the `label` of the element passed as `status`, and a dot's label wins, as core's reported dot label does; SwiftUI cannot read a label from other
167
+ views, so theirs does not join.
168
+
169
+ ## Design relationships
170
+
171
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
172
+ | ---------------- | ---------------------------------------- | ------------------------ | -------------- | ------------------ |
173
+ | Photo, initials | Apple Human Interface Guidelines, Images | prescribed by core | prominent | FR1–FR4 |
174
+
175
+ The component implements design requirements without copying their rationale.
176
+
177
+ Platform controls: SwiftUI `AsyncImage` for the images, SwiftUI `Link` for
178
+ `href`, and SwiftUI `Button` for `onClick` (`spec:AST-093` FR2). SwiftUI has no
179
+ avatar control, so the plate, initials, and clip are drawn here. Guideline
180
+ pages: Images, Buttons, and Accessibility in the Apple Human Interface
181
+ Guidelines.
182
+
183
+ Theme values read: `color.neutral`, `color.textSecondary`, `radius.element`,
184
+ `font.family.body`, `font.weight.medium`, and Bold Text; for the tooltip bubble,
185
+ `color.textPrimary`, `color.backgroundSurface`, `space.s1`, `space.s2`,
186
+ `radius.container`, and the body text size and weight.
187
+
188
+ ## Family and system relationships
189
+
190
+ - `component:Avatar` owns the props, the sizes, the initials rule, and the
191
+ fallback order; this record states only how Swift draws them.
192
+ - An owner that holds an Avatar in a slot leaves an unsized Avatar at `md`
193
+ (Swift slots S4).
194
+
195
+ ## Verification map
196
+
197
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
198
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
199
+ | FR1, FR2 | `AvatarTests.swift` initials and fallback tests | core's initials cases; blank and symbol names | a wrong initial or a missing person symbol fails | `audit:swift/Avatar/picture` |
200
+ | FR3, FR4 | `AvatarTests.swift` size, text-size growth, shape, and two-theme renders | each size; xx-large and the largest text size; circle and square; light, dark, butter | a wrong side, no growth or growth past 1.6 times, an unclipped corner, or a color of its own fails | `audit:swift/Avatar/look` |
201
+ | FR5, AR2, AR4 | `AvatarTests.swift` link and button renders; tap, trait, tap-area, warning, `linkURL`, and web-path tests | static, link, button; malformed, relative, and empty `href` | a link or button that draws differently, a malformed `href` made a link, a web path not flagged, or an unflagged unnamed tap fails | `audit:swift/Avatar/control` |
202
+ | FR8 | `AvatarTests.swift` tooltip words, focus and touch, VoiceOver hint, and wire tests; `TooltipPresenterTests.swift` for each input; `contracts.test.ts`; `parseDocType.test.ts` | name, `true`, words, `false`, blank, no name; static, link, button | a wrong tooltip, a static avatar that is not a tab stop or does not open on a tap, a control that loses its tap, or a wire value that is not the web's fails | `audit:swift/Avatar/tooltip` |
203
+ | FR6 | `AvatarTests.swift` initializer and hidden tests; `contracts.test.ts` | both initializers; `isHidden`; named sizes | differing props, a drawn hidden avatar, or a pixel size in Swift fails | `audit:swift/Avatar/api` |
204
+ | FR7, AR6 | `AvatarStatusDotTests.swift` placement renders of a dot and of other content at its measured place, size, an icon's growth at the largest text size, dot-label-wins, and name tests; the label preference that carries a label into the rendered name is not measured (AR3) | circle and square at `lg`; name with and without a status | a dot that changes the avatar's size, sits off the edge, or leaves the name without its label fails | `audit:swift/Avatar/status` |
205
+ | AR1 | `AvatarTests.swift` naming and trait tests | `alt`, `name`, blank, none | a wrong name or a named decorative avatar fails | `audit:swift/Avatar/a11y` |
206
+ | AR5 | `AvatarTests.swift` two-theme renders draw the initials in core's tokens | default and neutral, light and dark | initials in tokens other than core's fail | `audit:swift/Avatar/look` |
207
+
208
+ ## Decision log
209
+
210
+ No component-local decision is recorded.
211
+
212
+ ## Open questions
213
+
214
+ None.
215
+
216
+ ## Content boundary
217
+
218
+ This file does not duplicate consumer prop tables/examples, current audit
219
+ results, implementation steps, or family/system rules. It links to their owners.